From bfeb1693d691d7e3e60da1fc1c81b3ccf113c42f Mon Sep 17 00:00:00 2001 From: diegosouzapw Date: Wed, 1 Apr 2026 12:34:37 -0300 Subject: [PATCH] chore: documents --- .agents/workflows/update-docs.md | 105 - ...001-proxy-registry-limit-generalization.md | 46 - ...api-error-contract-management-endpoints.md | 32 - .../0003-security-checklist-proxy-limits.md | 16 - docs/i18n/README.md | 1 + docs/i18n/ar/CHANGELOG.md | 84 +- docs/i18n/ar/CONTRIBUTING.md | 299 ++ docs/i18n/ar/FEATURES.md | 147 - docs/i18n/ar/README.md | 49 +- docs/i18n/ar/RELEASE_CHECKLIST.md | 37 - docs/i18n/ar/SECURITY.md | 179 ++ docs/i18n/ar/VM_DEPLOYMENT_GUIDE.md | 401 --- docs/i18n/ar/docs/A2A-SERVER.md | 200 ++ docs/i18n/ar/docs/API_REFERENCE.md | 465 +++ docs/i18n/ar/docs/ARCHITECTURE.md | 814 +++++ docs/i18n/ar/docs/AUTO-COMBO.md | 67 + docs/i18n/ar/docs/CLI-TOOLS.md | 348 +++ .../ar/{ => docs}/CODEBASE_DOCUMENTATION.md | 10 +- docs/i18n/ar/docs/COVERAGE_PLAN.md | 170 ++ docs/i18n/ar/docs/FEATURES.md | 4 +- docs/i18n/ar/docs/MCP-SERVER.md | 87 + docs/i18n/ar/docs/RELEASE_CHECKLIST.md | 37 + docs/i18n/{da => ar/docs}/TROUBLESHOOTING.md | 8 +- docs/i18n/ar/{ => docs}/USER_GUIDE.md | 69 +- docs/i18n/ar/docs/VM_DEPLOYMENT_GUIDE.md | 403 +++ docs/i18n/ar/src/lib/a2a/README.md | 752 +++++ docs/i18n/bg/CHANGELOG.md | 84 +- docs/i18n/bg/CONTRIBUTING.md | 299 ++ docs/i18n/bg/FEATURES.md | 147 - docs/i18n/bg/README.md | 49 +- docs/i18n/bg/RELEASE_CHECKLIST.md | 37 - docs/i18n/bg/SECURITY.md | 179 ++ docs/i18n/bg/VM_DEPLOYMENT_GUIDE.md | 401 --- docs/i18n/bg/docs/A2A-SERVER.md | 200 ++ docs/i18n/bg/docs/API_REFERENCE.md | 465 +++ docs/i18n/bg/docs/ARCHITECTURE.md | 814 +++++ docs/i18n/bg/docs/AUTO-COMBO.md | 67 + docs/i18n/bg/docs/CLI-TOOLS.md | 348 +++ .../bg/{ => docs}/CODEBASE_DOCUMENTATION.md | 10 +- docs/i18n/bg/docs/COVERAGE_PLAN.md | 170 ++ docs/i18n/bg/docs/FEATURES.md | 4 +- docs/i18n/bg/docs/MCP-SERVER.md | 87 + docs/i18n/bg/docs/RELEASE_CHECKLIST.md | 37 + docs/i18n/bg/{ => docs}/TROUBLESHOOTING.md | 8 +- docs/i18n/bg/{ => docs}/USER_GUIDE.md | 69 +- docs/i18n/bg/docs/VM_DEPLOYMENT_GUIDE.md | 403 +++ docs/i18n/bg/src/lib/a2a/README.md | 752 +++++ docs/i18n/cs/A2A-SERVER.md | 196 -- docs/i18n/cs/API_REFERENCE.md | 453 --- docs/i18n/cs/ARCHITECTURE.md | 782 ----- docs/i18n/cs/AUTO-COMBO.md | 63 - docs/i18n/cs/CHANGELOG.md | 2622 ++++++++++++++--- docs/i18n/cs/CLI-TOOLS.md | 344 --- docs/i18n/cs/CODEBASE_DOCUMENTATION.md | 589 ---- docs/i18n/cs/CONTRIBUTING.md | 304 +- docs/i18n/cs/FEATURES.md | 143 - docs/i18n/cs/MCP-SERVER.md | 83 - docs/i18n/cs/README.md | 2369 +++++++++------ docs/i18n/cs/RELEASE_CHECKLIST.md | 33 - docs/i18n/cs/SECURITY.md | 196 +- docs/i18n/cs/TROUBLESHOOTING.md | 254 -- docs/i18n/cs/USER_GUIDE.md | 808 ----- docs/i18n/cs/VM_DEPLOYMENT_GUIDE.md | 401 --- ...001-proxy-registry-limit-generalization.md | 45 - ...api-error-contract-management-endpoints.md | 31 - .../0003-security-checklist-proxy-limits.md | 15 - docs/i18n/cs/docs/A2A-SERVER.md | 200 ++ docs/i18n/cs/docs/API_REFERENCE.md | 465 +++ docs/i18n/cs/docs/ARCHITECTURE.md | 814 +++++ docs/i18n/cs/docs/AUTO-COMBO.md | 67 + docs/i18n/cs/docs/CLI-TOOLS.md | 348 +++ .../{de => cs/docs}/CODEBASE_DOCUMENTATION.md | 10 +- docs/i18n/cs/docs/COVERAGE_PLAN.md | 170 ++ docs/i18n/{de => cs/docs}/FEATURES.md | 12 +- docs/i18n/cs/docs/MCP-SERVER.md | 87 + docs/i18n/cs/docs/RELEASE_CHECKLIST.md | 37 + docs/i18n/{de => cs/docs}/TROUBLESHOOTING.md | 8 +- docs/i18n/cs/docs/USER_GUIDE.md | 944 ++++++ docs/i18n/cs/docs/VM_DEPLOYMENT_GUIDE.md | 403 +++ docs/i18n/cs/electron/README.md | 254 -- docs/i18n/cs/i18n/README.md | 26 - docs/i18n/cs/open-sse/mcp-server/README.md | 587 ---- docs/i18n/cs/src/lib/a2a/README.md | 752 +++++ docs/i18n/da/CHANGELOG.md | 84 +- docs/i18n/da/CONTRIBUTING.md | 299 ++ docs/i18n/da/FEATURES.md | 147 - docs/i18n/da/README.md | 49 +- docs/i18n/da/RELEASE_CHECKLIST.md | 37 - docs/i18n/da/SECURITY.md | 179 ++ docs/i18n/{de => da/docs}/A2A-SERVER.md | 6 +- docs/i18n/{ar => da/docs}/API_REFERENCE.md | 82 +- docs/i18n/{ar => da/docs}/ARCHITECTURE.md | 81 +- docs/i18n/{bg => da/docs}/AUTO-COMBO.md | 6 +- docs/i18n/{de => da/docs}/CLI-TOOLS.md | 81 +- docs/i18n/da/docs/CODEBASE_DOCUMENTATION.md | 591 ++++ docs/i18n/da/docs/COVERAGE_PLAN.md | 170 ++ docs/i18n/da/docs/FEATURES.md | 4 +- docs/i18n/da/{ => docs}/MCP-SERVER.md | 28 +- docs/i18n/da/docs/RELEASE_CHECKLIST.md | 37 + docs/i18n/{ar => da/docs}/TROUBLESHOOTING.md | 8 +- docs/i18n/da/{ => docs}/USER_GUIDE.md | 69 +- docs/i18n/da/docs/VM_DEPLOYMENT_GUIDE.md | 403 +++ docs/i18n/da/src/lib/a2a/README.md | 752 +++++ docs/i18n/de/CHANGELOG.md | 84 +- docs/i18n/de/CONTRIBUTING.md | 299 ++ docs/i18n/de/README.md | 49 +- docs/i18n/de/RELEASE_CHECKLIST.md | 37 - docs/i18n/de/SECURITY.md | 179 ++ docs/i18n/de/VM_DEPLOYMENT_GUIDE.md | 401 --- docs/i18n/de/docs/A2A-SERVER.md | 200 ++ docs/i18n/de/docs/API_REFERENCE.md | 465 +++ docs/i18n/de/docs/ARCHITECTURE.md | 814 +++++ docs/i18n/de/docs/AUTO-COMBO.md | 67 + docs/i18n/de/docs/CLI-TOOLS.md | 348 +++ docs/i18n/de/docs/CODEBASE_DOCUMENTATION.md | 591 ++++ docs/i18n/de/docs/COVERAGE_PLAN.md | 170 ++ docs/i18n/de/docs/FEATURES.md | 4 +- docs/i18n/de/docs/MCP-SERVER.md | 87 + docs/i18n/de/docs/RELEASE_CHECKLIST.md | 37 + docs/i18n/de/docs/TROUBLESHOOTING.md | 256 ++ docs/i18n/de/{ => docs}/USER_GUIDE.md | 69 +- docs/i18n/de/docs/VM_DEPLOYMENT_GUIDE.md | 403 +++ docs/i18n/de/src/lib/a2a/README.md | 752 +++++ docs/i18n/es/A2A-SERVER.md | 200 -- docs/i18n/es/API_REFERENCE.md | 455 --- docs/i18n/es/ARCHITECTURE.md | 787 ----- docs/i18n/es/AUTO-COMBO.md | 67 - docs/i18n/es/CHANGELOG.md | 84 +- docs/i18n/es/CLI-TOOLS.md | 351 --- docs/i18n/es/CODEBASE_DOCUMENTATION.md | 593 ---- docs/i18n/es/CONTRIBUTING.md | 299 ++ docs/i18n/es/FEATURES.md | 147 - docs/i18n/es/MCP-SERVER.md | 87 - docs/i18n/es/README.md | 49 +- docs/i18n/es/RELEASE_CHECKLIST.md | 37 - docs/i18n/es/SECURITY.md | 179 ++ docs/i18n/es/TROUBLESHOOTING.md | 258 -- docs/i18n/es/VM_DEPLOYMENT_GUIDE.md | 401 --- docs/i18n/es/docs/A2A-SERVER.md | 200 ++ docs/i18n/es/docs/API_REFERENCE.md | 465 +++ docs/i18n/es/docs/ARCHITECTURE.md | 814 +++++ docs/i18n/es/docs/AUTO-COMBO.md | 67 + docs/i18n/es/docs/CLI-TOOLS.md | 348 +++ docs/i18n/es/docs/CODEBASE_DOCUMENTATION.md | 591 ++++ docs/i18n/es/docs/COVERAGE_PLAN.md | 170 ++ docs/i18n/es/docs/FEATURES.md | 4 +- docs/i18n/es/docs/MCP-SERVER.md | 87 + docs/i18n/es/docs/RELEASE_CHECKLIST.md | 37 + docs/i18n/es/docs/TROUBLESHOOTING.md | 256 ++ docs/i18n/es/{ => docs}/USER_GUIDE.md | 69 +- .../{no => es/docs}/VM_DEPLOYMENT_GUIDE.md | 138 +- docs/i18n/es/src/lib/a2a/README.md | 752 +++++ docs/i18n/fi/A2A-SERVER.md | 200 -- docs/i18n/fi/API_REFERENCE.md | 455 --- docs/i18n/fi/ARCHITECTURE.md | 787 ----- docs/i18n/fi/AUTO-COMBO.md | 67 - docs/i18n/fi/CHANGELOG.md | 84 +- docs/i18n/fi/CLI-TOOLS.md | 351 --- docs/i18n/fi/CODEBASE_DOCUMENTATION.md | 593 ---- docs/i18n/fi/CONTRIBUTING.md | 299 ++ docs/i18n/fi/FEATURES.md | 147 - docs/i18n/fi/MCP-SERVER.md | 87 - docs/i18n/fi/README.md | 49 +- docs/i18n/fi/RELEASE_CHECKLIST.md | 37 - docs/i18n/fi/SECURITY.md | 179 ++ docs/i18n/fi/TROUBLESHOOTING.md | 258 -- docs/i18n/fi/VM_DEPLOYMENT_GUIDE.md | 401 --- docs/i18n/{ar => fi/docs}/A2A-SERVER.md | 6 +- docs/i18n/{bg => fi/docs}/API_REFERENCE.md | 82 +- docs/i18n/{de => fi/docs}/ARCHITECTURE.md | 81 +- docs/i18n/{de => fi/docs}/AUTO-COMBO.md | 6 +- docs/i18n/fi/docs/CLI-TOOLS.md | 348 +++ docs/i18n/fi/docs/CODEBASE_DOCUMENTATION.md | 591 ++++ docs/i18n/fi/docs/COVERAGE_PLAN.md | 170 ++ docs/i18n/fi/docs/FEATURES.md | 4 +- docs/i18n/{ar => fi/docs}/MCP-SERVER.md | 28 +- docs/i18n/fi/docs/RELEASE_CHECKLIST.md | 37 + docs/i18n/fi/docs/TROUBLESHOOTING.md | 256 ++ docs/i18n/fi/{ => docs}/USER_GUIDE.md | 69 +- docs/i18n/fi/docs/VM_DEPLOYMENT_GUIDE.md | 403 +++ docs/i18n/fi/src/lib/a2a/README.md | 752 +++++ docs/i18n/fr/A2A-SERVER.md | 200 -- docs/i18n/fr/API_REFERENCE.md | 455 --- docs/i18n/fr/ARCHITECTURE.md | 787 ----- docs/i18n/fr/AUTO-COMBO.md | 67 - docs/i18n/fr/CHANGELOG.md | 84 +- docs/i18n/fr/CLI-TOOLS.md | 351 --- docs/i18n/fr/CODEBASE_DOCUMENTATION.md | 593 ---- docs/i18n/fr/CONTRIBUTING.md | 299 ++ docs/i18n/fr/FEATURES.md | 147 - docs/i18n/fr/MCP-SERVER.md | 87 - docs/i18n/fr/README.md | 49 +- docs/i18n/fr/RELEASE_CHECKLIST.md | 37 - docs/i18n/fr/SECURITY.md | 179 ++ docs/i18n/fr/TROUBLESHOOTING.md | 258 -- docs/i18n/fr/VM_DEPLOYMENT_GUIDE.md | 401 --- docs/i18n/fr/docs/A2A-SERVER.md | 200 ++ docs/i18n/fr/docs/API_REFERENCE.md | 465 +++ docs/i18n/fr/docs/ARCHITECTURE.md | 814 +++++ docs/i18n/fr/docs/AUTO-COMBO.md | 67 + docs/i18n/fr/docs/CLI-TOOLS.md | 348 +++ .../{da => fr/docs}/CODEBASE_DOCUMENTATION.md | 8 +- docs/i18n/fr/docs/COVERAGE_PLAN.md | 170 ++ docs/i18n/fr/docs/FEATURES.md | 4 +- docs/i18n/fr/docs/MCP-SERVER.md | 87 + docs/i18n/fr/docs/RELEASE_CHECKLIST.md | 37 + docs/i18n/fr/docs/TROUBLESHOOTING.md | 256 ++ docs/i18n/fr/{ => docs}/USER_GUIDE.md | 69 +- docs/i18n/fr/docs/VM_DEPLOYMENT_GUIDE.md | 403 +++ docs/i18n/fr/src/lib/a2a/README.md | 752 +++++ docs/i18n/he/A2A-SERVER.md | 200 -- docs/i18n/he/API_REFERENCE.md | 455 --- docs/i18n/he/ARCHITECTURE.md | 787 ----- docs/i18n/he/AUTO-COMBO.md | 67 - docs/i18n/he/CHANGELOG.md | 84 +- docs/i18n/he/CLI-TOOLS.md | 351 --- docs/i18n/he/CODEBASE_DOCUMENTATION.md | 593 ---- docs/i18n/he/CONTRIBUTING.md | 299 ++ docs/i18n/he/FEATURES.md | 147 - docs/i18n/he/MCP-SERVER.md | 87 - docs/i18n/he/README.md | 49 +- docs/i18n/he/RELEASE_CHECKLIST.md | 37 - docs/i18n/he/SECURITY.md | 179 ++ docs/i18n/he/TROUBLESHOOTING.md | 258 -- docs/i18n/he/VM_DEPLOYMENT_GUIDE.md | 401 --- docs/i18n/he/docs/A2A-SERVER.md | 200 ++ docs/i18n/he/docs/API_REFERENCE.md | 465 +++ docs/i18n/he/docs/ARCHITECTURE.md | 814 +++++ docs/i18n/he/docs/AUTO-COMBO.md | 67 + docs/i18n/he/docs/CLI-TOOLS.md | 348 +++ docs/i18n/he/docs/CODEBASE_DOCUMENTATION.md | 591 ++++ docs/i18n/he/docs/COVERAGE_PLAN.md | 170 ++ docs/i18n/he/docs/FEATURES.md | 4 +- docs/i18n/he/docs/MCP-SERVER.md | 87 + docs/i18n/he/docs/RELEASE_CHECKLIST.md | 37 + docs/i18n/he/docs/TROUBLESHOOTING.md | 256 ++ docs/i18n/he/{ => docs}/USER_GUIDE.md | 69 +- docs/i18n/he/docs/VM_DEPLOYMENT_GUIDE.md | 403 +++ docs/i18n/he/src/lib/a2a/README.md | 752 +++++ docs/i18n/hu/A2A-SERVER.md | 200 -- docs/i18n/hu/API_REFERENCE.md | 455 --- docs/i18n/hu/ARCHITECTURE.md | 787 ----- docs/i18n/hu/AUTO-COMBO.md | 67 - docs/i18n/hu/CHANGELOG.md | 84 +- docs/i18n/hu/CLI-TOOLS.md | 351 --- docs/i18n/hu/CODEBASE_DOCUMENTATION.md | 593 ---- docs/i18n/hu/CONTRIBUTING.md | 299 ++ docs/i18n/hu/FEATURES.md | 147 - docs/i18n/hu/MCP-SERVER.md | 87 - docs/i18n/hu/README.md | 49 +- docs/i18n/hu/RELEASE_CHECKLIST.md | 37 - docs/i18n/hu/SECURITY.md | 179 ++ docs/i18n/hu/TROUBLESHOOTING.md | 258 -- docs/i18n/hu/VM_DEPLOYMENT_GUIDE.md | 401 --- docs/i18n/{da => hu/docs}/A2A-SERVER.md | 6 +- docs/i18n/{da => hu/docs}/API_REFERENCE.md | 82 +- docs/i18n/{bg => hu/docs}/ARCHITECTURE.md | 81 +- docs/i18n/{da => hu/docs}/AUTO-COMBO.md | 6 +- docs/i18n/hu/docs/CLI-TOOLS.md | 348 +++ docs/i18n/hu/docs/CODEBASE_DOCUMENTATION.md | 591 ++++ docs/i18n/hu/docs/COVERAGE_PLAN.md | 170 ++ docs/i18n/hu/docs/FEATURES.md | 4 +- docs/i18n/hu/docs/MCP-SERVER.md | 87 + docs/i18n/hu/docs/RELEASE_CHECKLIST.md | 37 + docs/i18n/hu/docs/TROUBLESHOOTING.md | 256 ++ docs/i18n/hu/{ => docs}/USER_GUIDE.md | 69 +- docs/i18n/hu/docs/VM_DEPLOYMENT_GUIDE.md | 403 +++ docs/i18n/hu/src/lib/a2a/README.md | 752 +++++ docs/i18n/id/A2A-SERVER.md | 200 -- docs/i18n/id/API_REFERENCE.md | 455 --- docs/i18n/id/ARCHITECTURE.md | 787 ----- docs/i18n/id/AUTO-COMBO.md | 67 - docs/i18n/id/CHANGELOG.md | 84 +- docs/i18n/id/CLI-TOOLS.md | 351 --- docs/i18n/id/CODEBASE_DOCUMENTATION.md | 593 ---- docs/i18n/id/CONTRIBUTING.md | 299 ++ docs/i18n/id/FEATURES.md | 147 - docs/i18n/id/MCP-SERVER.md | 87 - docs/i18n/id/README.md | 49 +- docs/i18n/id/RELEASE_CHECKLIST.md | 37 - docs/i18n/id/SECURITY.md | 179 ++ docs/i18n/id/TROUBLESHOOTING.md | 258 -- docs/i18n/id/VM_DEPLOYMENT_GUIDE.md | 401 --- docs/i18n/id/docs/A2A-SERVER.md | 200 ++ docs/i18n/id/docs/API_REFERENCE.md | 465 +++ docs/i18n/id/docs/ARCHITECTURE.md | 814 +++++ docs/i18n/id/docs/AUTO-COMBO.md | 67 + docs/i18n/id/docs/CLI-TOOLS.md | 348 +++ docs/i18n/id/docs/CODEBASE_DOCUMENTATION.md | 591 ++++ docs/i18n/id/docs/COVERAGE_PLAN.md | 170 ++ docs/i18n/id/docs/FEATURES.md | 4 +- docs/i18n/id/docs/MCP-SERVER.md | 87 + docs/i18n/id/docs/RELEASE_CHECKLIST.md | 37 + docs/i18n/id/docs/TROUBLESHOOTING.md | 256 ++ docs/i18n/id/{ => docs}/USER_GUIDE.md | 69 +- docs/i18n/id/docs/VM_DEPLOYMENT_GUIDE.md | 403 +++ docs/i18n/id/src/lib/a2a/README.md | 752 +++++ docs/i18n/in/A2A-SERVER.md | 200 -- docs/i18n/in/API_REFERENCE.md | 455 --- docs/i18n/in/ARCHITECTURE.md | 787 ----- docs/i18n/in/AUTO-COMBO.md | 67 - docs/i18n/in/CHANGELOG.md | 84 +- docs/i18n/in/CLI-TOOLS.md | 351 --- docs/i18n/in/CODEBASE_DOCUMENTATION.md | 593 ---- docs/i18n/in/CONTRIBUTING.md | 299 ++ docs/i18n/in/FEATURES.md | 147 - docs/i18n/in/MCP-SERVER.md | 87 - docs/i18n/in/README.md | 49 +- docs/i18n/in/RELEASE_CHECKLIST.md | 37 - docs/i18n/in/SECURITY.md | 179 ++ docs/i18n/in/TROUBLESHOOTING.md | 258 -- docs/i18n/in/VM_DEPLOYMENT_GUIDE.md | 295 -- docs/i18n/in/docs/A2A-SERVER.md | 200 ++ docs/i18n/in/docs/API_REFERENCE.md | 465 +++ docs/i18n/in/docs/ARCHITECTURE.md | 814 +++++ docs/i18n/in/docs/AUTO-COMBO.md | 67 + docs/i18n/in/docs/CLI-TOOLS.md | 348 +++ docs/i18n/in/docs/CODEBASE_DOCUMENTATION.md | 591 ++++ docs/i18n/in/docs/COVERAGE_PLAN.md | 170 ++ docs/i18n/in/docs/FEATURES.md | 4 +- docs/i18n/in/docs/MCP-SERVER.md | 87 + docs/i18n/in/docs/RELEASE_CHECKLIST.md | 37 + docs/i18n/in/docs/TROUBLESHOOTING.md | 256 ++ docs/i18n/in/{ => docs}/USER_GUIDE.md | 69 +- docs/i18n/in/docs/VM_DEPLOYMENT_GUIDE.md | 403 +++ docs/i18n/in/src/lib/a2a/README.md | 752 +++++ docs/i18n/it/A2A-SERVER.md | 200 -- docs/i18n/it/API_REFERENCE.md | 455 --- docs/i18n/it/ARCHITECTURE.md | 787 ----- docs/i18n/it/AUTO-COMBO.md | 67 - docs/i18n/it/CHANGELOG.md | 84 +- docs/i18n/it/CLI-TOOLS.md | 351 --- docs/i18n/it/CODEBASE_DOCUMENTATION.md | 593 ---- docs/i18n/it/CONTRIBUTING.md | 299 ++ docs/i18n/it/FEATURES.md | 147 - docs/i18n/it/MCP-SERVER.md | 87 - docs/i18n/it/README.md | 49 +- docs/i18n/it/RELEASE_CHECKLIST.md | 37 - docs/i18n/it/SECURITY.md | 179 ++ docs/i18n/it/TROUBLESHOOTING.md | 258 -- docs/i18n/it/VM_DEPLOYMENT_GUIDE.md | 401 --- docs/i18n/it/docs/A2A-SERVER.md | 200 ++ docs/i18n/it/docs/API_REFERENCE.md | 465 +++ docs/i18n/it/docs/ARCHITECTURE.md | 814 +++++ docs/i18n/it/docs/AUTO-COMBO.md | 67 + docs/i18n/it/docs/CLI-TOOLS.md | 348 +++ docs/i18n/it/docs/CODEBASE_DOCUMENTATION.md | 591 ++++ docs/i18n/it/docs/COVERAGE_PLAN.md | 170 ++ docs/i18n/it/docs/FEATURES.md | 4 +- docs/i18n/it/docs/MCP-SERVER.md | 87 + docs/i18n/it/docs/RELEASE_CHECKLIST.md | 37 + docs/i18n/it/docs/TROUBLESHOOTING.md | 256 ++ docs/i18n/it/{ => docs}/USER_GUIDE.md | 69 +- .../{da => it/docs}/VM_DEPLOYMENT_GUIDE.md | 160 +- docs/i18n/it/src/lib/a2a/README.md | 752 +++++ docs/i18n/ja/A2A-SERVER.md | 200 -- docs/i18n/ja/API_REFERENCE.md | 455 --- docs/i18n/ja/ARCHITECTURE.md | 787 ----- docs/i18n/ja/AUTO-COMBO.md | 67 - docs/i18n/ja/CHANGELOG.md | 84 +- docs/i18n/ja/CLI-TOOLS.md | 351 --- docs/i18n/ja/CODEBASE_DOCUMENTATION.md | 593 ---- docs/i18n/ja/CONTRIBUTING.md | 299 ++ docs/i18n/ja/FEATURES.md | 147 - docs/i18n/ja/MCP-SERVER.md | 87 - docs/i18n/ja/README.md | 49 +- docs/i18n/ja/RELEASE_CHECKLIST.md | 37 - docs/i18n/ja/SECURITY.md | 179 ++ docs/i18n/ja/TROUBLESHOOTING.md | 258 -- docs/i18n/ja/VM_DEPLOYMENT_GUIDE.md | 401 --- docs/i18n/ja/docs/A2A-SERVER.md | 200 ++ docs/i18n/ja/docs/API_REFERENCE.md | 465 +++ docs/i18n/ja/docs/ARCHITECTURE.md | 814 +++++ docs/i18n/ja/docs/AUTO-COMBO.md | 67 + docs/i18n/ja/docs/CLI-TOOLS.md | 348 +++ docs/i18n/ja/docs/CODEBASE_DOCUMENTATION.md | 591 ++++ docs/i18n/ja/docs/COVERAGE_PLAN.md | 170 ++ docs/i18n/ja/docs/FEATURES.md | 4 +- docs/i18n/ja/docs/MCP-SERVER.md | 87 + docs/i18n/ja/docs/RELEASE_CHECKLIST.md | 37 + docs/i18n/ja/docs/TROUBLESHOOTING.md | 256 ++ docs/i18n/ja/{ => docs}/USER_GUIDE.md | 69 +- docs/i18n/ja/docs/VM_DEPLOYMENT_GUIDE.md | 403 +++ docs/i18n/ja/src/lib/a2a/README.md | 752 +++++ docs/i18n/ko/A2A-SERVER.md | 200 -- docs/i18n/ko/API_REFERENCE.md | 455 --- docs/i18n/ko/ARCHITECTURE.md | 787 ----- docs/i18n/ko/AUTO-COMBO.md | 67 - docs/i18n/ko/CHANGELOG.md | 84 +- docs/i18n/ko/CLI-TOOLS.md | 351 --- docs/i18n/ko/CODEBASE_DOCUMENTATION.md | 593 ---- docs/i18n/ko/CONTRIBUTING.md | 299 ++ docs/i18n/ko/FEATURES.md | 147 - docs/i18n/ko/MCP-SERVER.md | 87 - docs/i18n/ko/README.md | 49 +- docs/i18n/ko/RELEASE_CHECKLIST.md | 37 - docs/i18n/ko/SECURITY.md | 179 ++ docs/i18n/ko/TROUBLESHOOTING.md | 258 -- docs/i18n/ko/VM_DEPLOYMENT_GUIDE.md | 401 --- docs/i18n/ko/docs/A2A-SERVER.md | 200 ++ docs/i18n/ko/docs/API_REFERENCE.md | 465 +++ docs/i18n/ko/docs/ARCHITECTURE.md | 814 +++++ docs/i18n/ko/docs/AUTO-COMBO.md | 67 + docs/i18n/ko/docs/CLI-TOOLS.md | 348 +++ docs/i18n/ko/docs/CODEBASE_DOCUMENTATION.md | 591 ++++ docs/i18n/ko/docs/COVERAGE_PLAN.md | 170 ++ docs/i18n/ko/docs/FEATURES.md | 4 +- docs/i18n/{bg => ko/docs}/MCP-SERVER.md | 28 +- docs/i18n/ko/docs/RELEASE_CHECKLIST.md | 37 + docs/i18n/ko/docs/TROUBLESHOOTING.md | 256 ++ docs/i18n/ko/{ => docs}/USER_GUIDE.md | 69 +- docs/i18n/ko/docs/VM_DEPLOYMENT_GUIDE.md | 403 +++ docs/i18n/ko/src/lib/a2a/README.md | 752 +++++ docs/i18n/ms/A2A-SERVER.md | 200 -- docs/i18n/ms/API_REFERENCE.md | 455 --- docs/i18n/ms/ARCHITECTURE.md | 787 ----- docs/i18n/ms/AUTO-COMBO.md | 67 - docs/i18n/ms/CHANGELOG.md | 84 +- docs/i18n/ms/CLI-TOOLS.md | 351 --- docs/i18n/ms/CODEBASE_DOCUMENTATION.md | 593 ---- docs/i18n/ms/CONTRIBUTING.md | 299 ++ docs/i18n/ms/FEATURES.md | 147 - docs/i18n/ms/MCP-SERVER.md | 87 - docs/i18n/ms/README.md | 49 +- docs/i18n/ms/RELEASE_CHECKLIST.md | 37 - docs/i18n/ms/SECURITY.md | 179 ++ docs/i18n/ms/TROUBLESHOOTING.md | 258 -- docs/i18n/ms/docs/A2A-SERVER.md | 200 ++ docs/i18n/ms/docs/API_REFERENCE.md | 465 +++ docs/i18n/ms/docs/ARCHITECTURE.md | 814 +++++ docs/i18n/ms/docs/AUTO-COMBO.md | 67 + docs/i18n/ms/docs/CLI-TOOLS.md | 348 +++ docs/i18n/ms/docs/CODEBASE_DOCUMENTATION.md | 591 ++++ docs/i18n/ms/docs/COVERAGE_PLAN.md | 170 ++ docs/i18n/ms/docs/FEATURES.md | 4 +- docs/i18n/ms/docs/MCP-SERVER.md | 87 + docs/i18n/ms/docs/RELEASE_CHECKLIST.md | 37 + docs/i18n/ms/docs/TROUBLESHOOTING.md | 256 ++ docs/i18n/ms/{ => docs}/USER_GUIDE.md | 69 +- docs/i18n/ms/docs/VM_DEPLOYMENT_GUIDE.md | 403 +++ docs/i18n/ms/src/lib/a2a/README.md | 752 +++++ docs/i18n/nl/A2A-SERVER.md | 200 -- docs/i18n/nl/API_REFERENCE.md | 455 --- docs/i18n/nl/ARCHITECTURE.md | 787 ----- docs/i18n/nl/AUTO-COMBO.md | 67 - docs/i18n/nl/CHANGELOG.md | 84 +- docs/i18n/nl/CLI-TOOLS.md | 351 --- docs/i18n/nl/CODEBASE_DOCUMENTATION.md | 593 ---- docs/i18n/nl/CONTRIBUTING.md | 299 ++ docs/i18n/nl/FEATURES.md | 147 - docs/i18n/nl/MCP-SERVER.md | 87 - docs/i18n/nl/README.md | 49 +- docs/i18n/nl/RELEASE_CHECKLIST.md | 37 - docs/i18n/nl/SECURITY.md | 179 ++ docs/i18n/nl/TROUBLESHOOTING.md | 258 -- docs/i18n/nl/VM_DEPLOYMENT_GUIDE.md | 401 --- docs/i18n/nl/docs/A2A-SERVER.md | 200 ++ docs/i18n/nl/docs/API_REFERENCE.md | 465 +++ docs/i18n/nl/docs/ARCHITECTURE.md | 814 +++++ docs/i18n/nl/docs/AUTO-COMBO.md | 67 + docs/i18n/nl/docs/CLI-TOOLS.md | 348 +++ docs/i18n/nl/docs/CODEBASE_DOCUMENTATION.md | 591 ++++ docs/i18n/nl/docs/COVERAGE_PLAN.md | 170 ++ docs/i18n/nl/docs/FEATURES.md | 4 +- docs/i18n/nl/docs/MCP-SERVER.md | 87 + docs/i18n/nl/docs/RELEASE_CHECKLIST.md | 37 + docs/i18n/nl/docs/TROUBLESHOOTING.md | 256 ++ docs/i18n/nl/{ => docs}/USER_GUIDE.md | 69 +- docs/i18n/nl/docs/VM_DEPLOYMENT_GUIDE.md | 403 +++ docs/i18n/nl/src/lib/a2a/README.md | 752 +++++ docs/i18n/no/A2A-SERVER.md | 200 -- docs/i18n/no/API_REFERENCE.md | 455 --- docs/i18n/no/ARCHITECTURE.md | 787 ----- docs/i18n/no/AUTO-COMBO.md | 67 - docs/i18n/no/CHANGELOG.md | 84 +- docs/i18n/no/CLI-TOOLS.md | 351 --- docs/i18n/no/CODEBASE_DOCUMENTATION.md | 593 ---- docs/i18n/no/CONTRIBUTING.md | 299 ++ docs/i18n/no/FEATURES.md | 147 - docs/i18n/no/MCP-SERVER.md | 87 - docs/i18n/no/README.md | 49 +- docs/i18n/no/RELEASE_CHECKLIST.md | 37 - docs/i18n/no/SECURITY.md | 179 ++ docs/i18n/no/TROUBLESHOOTING.md | 258 -- docs/i18n/{bg => no/docs}/A2A-SERVER.md | 6 +- docs/i18n/{de => no/docs}/API_REFERENCE.md | 82 +- docs/i18n/{da => no/docs}/ARCHITECTURE.md | 81 +- docs/i18n/{ar => no/docs}/AUTO-COMBO.md | 6 +- docs/i18n/{bg => no/docs}/CLI-TOOLS.md | 81 +- docs/i18n/no/docs/CODEBASE_DOCUMENTATION.md | 591 ++++ docs/i18n/no/docs/COVERAGE_PLAN.md | 170 ++ docs/i18n/no/docs/FEATURES.md | 4 +- docs/i18n/{de => no/docs}/MCP-SERVER.md | 28 +- docs/i18n/no/docs/RELEASE_CHECKLIST.md | 37 + docs/i18n/no/docs/TROUBLESHOOTING.md | 256 ++ docs/i18n/no/{ => docs}/USER_GUIDE.md | 69 +- docs/i18n/no/docs/VM_DEPLOYMENT_GUIDE.md | 403 +++ docs/i18n/no/src/lib/a2a/README.md | 752 +++++ docs/i18n/phi/A2A-SERVER.md | 200 -- docs/i18n/phi/API_REFERENCE.md | 455 --- docs/i18n/phi/ARCHITECTURE.md | 787 ----- docs/i18n/phi/AUTO-COMBO.md | 67 - docs/i18n/phi/CHANGELOG.md | 84 +- docs/i18n/phi/CLI-TOOLS.md | 351 --- docs/i18n/phi/CODEBASE_DOCUMENTATION.md | 593 ---- docs/i18n/phi/CONTRIBUTING.md | 299 ++ docs/i18n/phi/FEATURES.md | 147 - docs/i18n/phi/MCP-SERVER.md | 87 - docs/i18n/phi/README.md | 49 +- docs/i18n/phi/RELEASE_CHECKLIST.md | 37 - docs/i18n/phi/SECURITY.md | 179 ++ docs/i18n/phi/TROUBLESHOOTING.md | 258 -- docs/i18n/phi/VM_DEPLOYMENT_GUIDE.md | 401 --- docs/i18n/phi/docs/A2A-SERVER.md | 200 ++ docs/i18n/phi/docs/API_REFERENCE.md | 465 +++ docs/i18n/phi/docs/ARCHITECTURE.md | 814 +++++ docs/i18n/phi/docs/AUTO-COMBO.md | 67 + docs/i18n/phi/docs/CLI-TOOLS.md | 348 +++ docs/i18n/phi/docs/CODEBASE_DOCUMENTATION.md | 591 ++++ docs/i18n/phi/docs/COVERAGE_PLAN.md | 170 ++ docs/i18n/phi/docs/FEATURES.md | 4 +- docs/i18n/phi/docs/MCP-SERVER.md | 87 + docs/i18n/phi/docs/RELEASE_CHECKLIST.md | 37 + docs/i18n/phi/docs/TROUBLESHOOTING.md | 256 ++ docs/i18n/phi/{ => docs}/USER_GUIDE.md | 69 +- .../{ms => phi/docs}/VM_DEPLOYMENT_GUIDE.md | 160 +- docs/i18n/phi/src/lib/a2a/README.md | 752 +++++ docs/i18n/pl/A2A-SERVER.md | 200 -- docs/i18n/pl/API_REFERENCE.md | 455 --- docs/i18n/pl/ARCHITECTURE.md | 787 ----- docs/i18n/pl/AUTO-COMBO.md | 67 - docs/i18n/pl/CHANGELOG.md | 84 +- docs/i18n/pl/CLI-TOOLS.md | 351 --- docs/i18n/pl/CODEBASE_DOCUMENTATION.md | 593 ---- docs/i18n/pl/CONTRIBUTING.md | 299 ++ docs/i18n/pl/FEATURES.md | 147 - docs/i18n/pl/MCP-SERVER.md | 87 - docs/i18n/pl/README.md | 49 +- docs/i18n/pl/RELEASE_CHECKLIST.md | 37 - docs/i18n/pl/SECURITY.md | 179 ++ docs/i18n/pl/TROUBLESHOOTING.md | 258 -- docs/i18n/pl/VM_DEPLOYMENT_GUIDE.md | 401 --- docs/i18n/pl/docs/A2A-SERVER.md | 200 ++ docs/i18n/pl/docs/API_REFERENCE.md | 465 +++ docs/i18n/pl/docs/ARCHITECTURE.md | 814 +++++ docs/i18n/pl/docs/AUTO-COMBO.md | 67 + docs/i18n/pl/docs/CLI-TOOLS.md | 348 +++ docs/i18n/pl/docs/CODEBASE_DOCUMENTATION.md | 591 ++++ docs/i18n/pl/docs/COVERAGE_PLAN.md | 170 ++ docs/i18n/pl/docs/FEATURES.md | 4 +- docs/i18n/pl/docs/MCP-SERVER.md | 87 + docs/i18n/pl/docs/RELEASE_CHECKLIST.md | 37 + docs/i18n/pl/docs/TROUBLESHOOTING.md | 256 ++ docs/i18n/pl/{ => docs}/USER_GUIDE.md | 69 +- docs/i18n/pl/docs/VM_DEPLOYMENT_GUIDE.md | 403 +++ docs/i18n/pl/src/lib/a2a/README.md | 752 +++++ docs/i18n/pt-BR/A2A-SERVER.md | 200 -- docs/i18n/pt-BR/API_REFERENCE.md | 455 --- docs/i18n/pt-BR/ARCHITECTURE.md | 787 ----- docs/i18n/pt-BR/AUTO-COMBO.md | 67 - docs/i18n/pt-BR/CHANGELOG.md | 84 +- docs/i18n/pt-BR/CLI-TOOLS.md | 351 --- docs/i18n/pt-BR/CODEBASE_DOCUMENTATION.md | 593 ---- docs/i18n/pt-BR/CONTRIBUTING.md | 299 ++ docs/i18n/pt-BR/FEATURES.md | 148 - docs/i18n/pt-BR/MCP-SERVER.md | 87 - docs/i18n/pt-BR/README.md | 49 +- docs/i18n/pt-BR/RELEASE_CHECKLIST.md | 37 - docs/i18n/pt-BR/SECURITY.md | 179 ++ docs/i18n/pt-BR/TROUBLESHOOTING.md | 258 -- docs/i18n/pt-BR/USER_GUIDE.md | 913 ------ docs/i18n/pt-BR/docs/A2A-SERVER.md | 200 ++ docs/i18n/pt-BR/docs/API_REFERENCE.md | 465 +++ docs/i18n/pt-BR/docs/ARCHITECTURE.md | 814 +++++ docs/i18n/pt-BR/docs/AUTO-COMBO.md | 67 + docs/i18n/pt-BR/docs/CLI-TOOLS.md | 348 +++ .../i18n/pt-BR/docs/CODEBASE_DOCUMENTATION.md | 591 ++++ docs/i18n/pt-BR/docs/COVERAGE_PLAN.md | 170 ++ docs/i18n/pt-BR/docs/FEATURES.md | 4 +- docs/i18n/pt-BR/docs/MCP-SERVER.md | 87 + docs/i18n/pt-BR/docs/RELEASE_CHECKLIST.md | 37 + docs/i18n/pt-BR/docs/TROUBLESHOOTING.md | 256 ++ docs/i18n/pt-BR/docs/USER_GUIDE.md | 944 ++++++ docs/i18n/pt-BR/docs/VM_DEPLOYMENT_GUIDE.md | 403 +++ docs/i18n/pt-BR/src/lib/a2a/README.md | 752 +++++ docs/i18n/pt/A2A-SERVER.md | 200 -- docs/i18n/pt/API_REFERENCE.md | 455 --- docs/i18n/pt/ARCHITECTURE.md | 787 ----- docs/i18n/pt/AUTO-COMBO.md | 67 - docs/i18n/pt/CHANGELOG.md | 84 +- docs/i18n/pt/CLI-TOOLS.md | 351 --- docs/i18n/pt/CODEBASE_DOCUMENTATION.md | 593 ---- docs/i18n/pt/CONTRIBUTING.md | 299 ++ docs/i18n/pt/FEATURES.md | 147 - docs/i18n/pt/MCP-SERVER.md | 87 - docs/i18n/pt/README.md | 49 +- docs/i18n/pt/RELEASE_CHECKLIST.md | 37 - docs/i18n/pt/SECURITY.md | 179 ++ docs/i18n/pt/TROUBLESHOOTING.md | 258 -- docs/i18n/pt/VM_DEPLOYMENT_GUIDE.md | 401 --- docs/i18n/pt/docs/A2A-SERVER.md | 200 ++ docs/i18n/pt/docs/API_REFERENCE.md | 465 +++ docs/i18n/pt/docs/ARCHITECTURE.md | 814 +++++ docs/i18n/pt/docs/AUTO-COMBO.md | 67 + docs/i18n/pt/docs/CLI-TOOLS.md | 348 +++ docs/i18n/pt/docs/CODEBASE_DOCUMENTATION.md | 591 ++++ docs/i18n/pt/docs/COVERAGE_PLAN.md | 170 ++ docs/i18n/pt/docs/FEATURES.md | 4 +- docs/i18n/pt/docs/MCP-SERVER.md | 87 + docs/i18n/pt/docs/RELEASE_CHECKLIST.md | 37 + docs/i18n/pt/docs/TROUBLESHOOTING.md | 256 ++ docs/i18n/pt/{ => docs}/USER_GUIDE.md | 69 +- docs/i18n/pt/docs/VM_DEPLOYMENT_GUIDE.md | 403 +++ docs/i18n/pt/src/lib/a2a/README.md | 752 +++++ docs/i18n/ro/A2A-SERVER.md | 200 -- docs/i18n/ro/API_REFERENCE.md | 455 --- docs/i18n/ro/ARCHITECTURE.md | 787 ----- docs/i18n/ro/AUTO-COMBO.md | 67 - docs/i18n/ro/CHANGELOG.md | 84 +- docs/i18n/ro/CLI-TOOLS.md | 351 --- docs/i18n/ro/CODEBASE_DOCUMENTATION.md | 593 ---- docs/i18n/ro/CONTRIBUTING.md | 299 ++ docs/i18n/ro/FEATURES.md | 147 - docs/i18n/ro/MCP-SERVER.md | 87 - docs/i18n/ro/README.md | 49 +- docs/i18n/ro/RELEASE_CHECKLIST.md | 37 - docs/i18n/ro/SECURITY.md | 179 ++ docs/i18n/ro/TROUBLESHOOTING.md | 258 -- docs/i18n/ro/VM_DEPLOYMENT_GUIDE.md | 401 --- docs/i18n/ro/docs/A2A-SERVER.md | 200 ++ docs/i18n/ro/docs/API_REFERENCE.md | 465 +++ docs/i18n/ro/docs/ARCHITECTURE.md | 814 +++++ docs/i18n/ro/docs/AUTO-COMBO.md | 67 + docs/i18n/{ar => ro/docs}/CLI-TOOLS.md | 81 +- docs/i18n/ro/docs/CODEBASE_DOCUMENTATION.md | 591 ++++ docs/i18n/ro/docs/COVERAGE_PLAN.md | 170 ++ docs/i18n/ro/docs/FEATURES.md | 4 +- docs/i18n/ro/docs/MCP-SERVER.md | 87 + docs/i18n/ro/docs/RELEASE_CHECKLIST.md | 37 + docs/i18n/ro/docs/TROUBLESHOOTING.md | 256 ++ docs/i18n/ro/{ => docs}/USER_GUIDE.md | 69 +- .../{pt-BR => ro/docs}/VM_DEPLOYMENT_GUIDE.md | 160 +- docs/i18n/ro/src/lib/a2a/README.md | 752 +++++ docs/i18n/ru/A2A-SERVER.md | 200 -- docs/i18n/ru/API_REFERENCE.md | 455 --- docs/i18n/ru/ARCHITECTURE.md | 787 ----- docs/i18n/ru/AUTO-COMBO.md | 67 - docs/i18n/ru/CHANGELOG.md | 84 +- docs/i18n/ru/CLI-TOOLS.md | 351 --- docs/i18n/ru/CODEBASE_DOCUMENTATION.md | 593 ---- docs/i18n/ru/CONTRIBUTING.md | 299 ++ docs/i18n/ru/FEATURES.md | 147 - docs/i18n/ru/MCP-SERVER.md | 87 - docs/i18n/ru/README.md | 49 +- docs/i18n/ru/RELEASE_CHECKLIST.md | 37 - docs/i18n/ru/SECURITY.md | 179 ++ docs/i18n/ru/TROUBLESHOOTING.md | 258 -- docs/i18n/ru/VM_DEPLOYMENT_GUIDE.md | 401 --- docs/i18n/ru/docs/A2A-SERVER.md | 200 ++ docs/i18n/ru/docs/API_REFERENCE.md | 465 +++ docs/i18n/ru/docs/ARCHITECTURE.md | 814 +++++ docs/i18n/ru/docs/AUTO-COMBO.md | 67 + docs/i18n/ru/docs/CLI-TOOLS.md | 348 +++ docs/i18n/ru/docs/CODEBASE_DOCUMENTATION.md | 591 ++++ docs/i18n/ru/docs/COVERAGE_PLAN.md | 170 ++ docs/i18n/ru/docs/FEATURES.md | 4 +- docs/i18n/ru/docs/MCP-SERVER.md | 87 + docs/i18n/ru/docs/RELEASE_CHECKLIST.md | 37 + docs/i18n/ru/docs/TROUBLESHOOTING.md | 256 ++ docs/i18n/ru/{ => docs}/USER_GUIDE.md | 69 +- docs/i18n/ru/docs/VM_DEPLOYMENT_GUIDE.md | 403 +++ docs/i18n/ru/src/lib/a2a/README.md | 752 +++++ docs/i18n/sk/A2A-SERVER.md | 200 -- docs/i18n/sk/API_REFERENCE.md | 455 --- docs/i18n/sk/ARCHITECTURE.md | 787 ----- docs/i18n/sk/AUTO-COMBO.md | 67 - docs/i18n/sk/CHANGELOG.md | 84 +- docs/i18n/sk/CLI-TOOLS.md | 351 --- docs/i18n/sk/CODEBASE_DOCUMENTATION.md | 593 ---- docs/i18n/sk/CONTRIBUTING.md | 299 ++ docs/i18n/sk/FEATURES.md | 147 - docs/i18n/sk/MCP-SERVER.md | 87 - docs/i18n/sk/README.md | 49 +- docs/i18n/sk/RELEASE_CHECKLIST.md | 37 - docs/i18n/sk/SECURITY.md | 179 ++ docs/i18n/sk/TROUBLESHOOTING.md | 258 -- docs/i18n/sk/VM_DEPLOYMENT_GUIDE.md | 401 --- docs/i18n/sk/docs/A2A-SERVER.md | 200 ++ docs/i18n/sk/docs/API_REFERENCE.md | 465 +++ docs/i18n/sk/docs/ARCHITECTURE.md | 814 +++++ docs/i18n/sk/docs/AUTO-COMBO.md | 67 + docs/i18n/sk/docs/CLI-TOOLS.md | 348 +++ docs/i18n/sk/docs/CODEBASE_DOCUMENTATION.md | 591 ++++ docs/i18n/sk/docs/COVERAGE_PLAN.md | 170 ++ docs/i18n/sk/docs/FEATURES.md | 4 +- docs/i18n/sk/docs/MCP-SERVER.md | 87 + docs/i18n/sk/docs/RELEASE_CHECKLIST.md | 37 + docs/i18n/sk/docs/TROUBLESHOOTING.md | 256 ++ docs/i18n/sk/{ => docs}/USER_GUIDE.md | 69 +- docs/i18n/sk/docs/VM_DEPLOYMENT_GUIDE.md | 403 +++ docs/i18n/sk/src/lib/a2a/README.md | 752 +++++ docs/i18n/sv/A2A-SERVER.md | 200 -- docs/i18n/sv/API_REFERENCE.md | 455 --- docs/i18n/sv/ARCHITECTURE.md | 787 ----- docs/i18n/sv/AUTO-COMBO.md | 67 - docs/i18n/sv/CHANGELOG.md | 84 +- docs/i18n/sv/CLI-TOOLS.md | 351 --- docs/i18n/sv/CODEBASE_DOCUMENTATION.md | 593 ---- docs/i18n/sv/CONTRIBUTING.md | 299 ++ docs/i18n/sv/FEATURES.md | 147 - docs/i18n/sv/MCP-SERVER.md | 87 - docs/i18n/sv/README.md | 49 +- docs/i18n/sv/RELEASE_CHECKLIST.md | 37 - docs/i18n/sv/SECURITY.md | 179 ++ docs/i18n/sv/TROUBLESHOOTING.md | 258 -- docs/i18n/sv/VM_DEPLOYMENT_GUIDE.md | 401 --- docs/i18n/sv/docs/A2A-SERVER.md | 200 ++ docs/i18n/sv/docs/API_REFERENCE.md | 465 +++ docs/i18n/sv/docs/ARCHITECTURE.md | 814 +++++ docs/i18n/sv/docs/AUTO-COMBO.md | 67 + docs/i18n/{da => sv/docs}/CLI-TOOLS.md | 81 +- docs/i18n/sv/docs/CODEBASE_DOCUMENTATION.md | 591 ++++ docs/i18n/sv/docs/COVERAGE_PLAN.md | 170 ++ docs/i18n/sv/docs/FEATURES.md | 4 +- docs/i18n/sv/docs/MCP-SERVER.md | 87 + docs/i18n/sv/docs/RELEASE_CHECKLIST.md | 37 + docs/i18n/sv/docs/TROUBLESHOOTING.md | 256 ++ docs/i18n/sv/{ => docs}/USER_GUIDE.md | 69 +- docs/i18n/sv/docs/VM_DEPLOYMENT_GUIDE.md | 403 +++ docs/i18n/sv/src/lib/a2a/README.md | 752 +++++ docs/i18n/th/A2A-SERVER.md | 200 -- docs/i18n/th/API_REFERENCE.md | 455 --- docs/i18n/th/ARCHITECTURE.md | 787 ----- docs/i18n/th/AUTO-COMBO.md | 67 - docs/i18n/th/CHANGELOG.md | 84 +- docs/i18n/th/CLI-TOOLS.md | 351 --- docs/i18n/th/CODEBASE_DOCUMENTATION.md | 593 ---- docs/i18n/th/CONTRIBUTING.md | 299 ++ docs/i18n/th/FEATURES.md | 147 - docs/i18n/th/MCP-SERVER.md | 87 - docs/i18n/th/README.md | 49 +- docs/i18n/th/RELEASE_CHECKLIST.md | 37 - docs/i18n/th/SECURITY.md | 179 ++ docs/i18n/th/TROUBLESHOOTING.md | 258 -- docs/i18n/th/VM_DEPLOYMENT_GUIDE.md | 401 --- docs/i18n/th/docs/A2A-SERVER.md | 200 ++ docs/i18n/th/docs/API_REFERENCE.md | 465 +++ docs/i18n/th/docs/ARCHITECTURE.md | 814 +++++ docs/i18n/th/docs/AUTO-COMBO.md | 67 + docs/i18n/th/docs/CLI-TOOLS.md | 348 +++ docs/i18n/th/docs/CODEBASE_DOCUMENTATION.md | 591 ++++ docs/i18n/th/docs/COVERAGE_PLAN.md | 170 ++ docs/i18n/th/docs/FEATURES.md | 4 +- docs/i18n/th/docs/MCP-SERVER.md | 87 + docs/i18n/th/docs/RELEASE_CHECKLIST.md | 37 + docs/i18n/th/docs/TROUBLESHOOTING.md | 256 ++ docs/i18n/th/{ => docs}/USER_GUIDE.md | 69 +- docs/i18n/th/docs/VM_DEPLOYMENT_GUIDE.md | 403 +++ docs/i18n/th/src/lib/a2a/README.md | 752 +++++ docs/i18n/uk-UA/A2A-SERVER.md | 200 -- docs/i18n/uk-UA/API_REFERENCE.md | 455 --- docs/i18n/uk-UA/ARCHITECTURE.md | 787 ----- docs/i18n/uk-UA/AUTO-COMBO.md | 67 - docs/i18n/uk-UA/CHANGELOG.md | 84 +- docs/i18n/uk-UA/CLI-TOOLS.md | 351 --- docs/i18n/uk-UA/CODEBASE_DOCUMENTATION.md | 593 ---- docs/i18n/uk-UA/CONTRIBUTING.md | 299 ++ docs/i18n/uk-UA/FEATURES.md | 147 - docs/i18n/uk-UA/MCP-SERVER.md | 87 - docs/i18n/uk-UA/README.md | 49 +- docs/i18n/uk-UA/RELEASE_CHECKLIST.md | 37 - docs/i18n/uk-UA/SECURITY.md | 179 ++ docs/i18n/uk-UA/TROUBLESHOOTING.md | 258 -- docs/i18n/uk-UA/VM_DEPLOYMENT_GUIDE.md | 401 --- docs/i18n/uk-UA/docs/A2A-SERVER.md | 200 ++ docs/i18n/uk-UA/docs/API_REFERENCE.md | 465 +++ docs/i18n/uk-UA/docs/ARCHITECTURE.md | 814 +++++ docs/i18n/uk-UA/docs/AUTO-COMBO.md | 67 + docs/i18n/uk-UA/docs/CLI-TOOLS.md | 348 +++ .../i18n/uk-UA/docs/CODEBASE_DOCUMENTATION.md | 591 ++++ docs/i18n/uk-UA/docs/COVERAGE_PLAN.md | 170 ++ docs/i18n/uk-UA/docs/FEATURES.md | 4 +- docs/i18n/uk-UA/docs/MCP-SERVER.md | 87 + docs/i18n/uk-UA/docs/RELEASE_CHECKLIST.md | 37 + docs/i18n/uk-UA/docs/TROUBLESHOOTING.md | 256 ++ docs/i18n/uk-UA/{ => docs}/USER_GUIDE.md | 69 +- docs/i18n/uk-UA/docs/VM_DEPLOYMENT_GUIDE.md | 403 +++ docs/i18n/uk-UA/src/lib/a2a/README.md | 752 +++++ docs/i18n/vi/A2A-SERVER.md | 200 -- docs/i18n/vi/API_REFERENCE.md | 455 --- docs/i18n/vi/ARCHITECTURE.md | 787 ----- docs/i18n/vi/AUTO-COMBO.md | 67 - docs/i18n/vi/CHANGELOG.md | 84 +- docs/i18n/vi/CLI-TOOLS.md | 351 --- docs/i18n/vi/CODEBASE_DOCUMENTATION.md | 593 ---- docs/i18n/vi/CONTRIBUTING.md | 299 ++ docs/i18n/vi/FEATURES.md | 147 - docs/i18n/vi/MCP-SERVER.md | 87 - docs/i18n/vi/README.md | 49 +- docs/i18n/vi/RELEASE_CHECKLIST.md | 37 - docs/i18n/vi/SECURITY.md | 179 ++ docs/i18n/vi/TROUBLESHOOTING.md | 258 -- docs/i18n/vi/VM_DEPLOYMENT_GUIDE.md | 401 --- docs/i18n/vi/docs/A2A-SERVER.md | 200 ++ docs/i18n/vi/docs/API_REFERENCE.md | 465 +++ docs/i18n/vi/docs/ARCHITECTURE.md | 814 +++++ docs/i18n/vi/docs/AUTO-COMBO.md | 67 + docs/i18n/vi/docs/CLI-TOOLS.md | 348 +++ docs/i18n/vi/docs/CODEBASE_DOCUMENTATION.md | 591 ++++ docs/i18n/vi/docs/COVERAGE_PLAN.md | 170 ++ docs/i18n/vi/docs/FEATURES.md | 4 +- docs/i18n/vi/docs/MCP-SERVER.md | 87 + docs/i18n/vi/docs/RELEASE_CHECKLIST.md | 37 + docs/i18n/vi/docs/TROUBLESHOOTING.md | 256 ++ docs/i18n/vi/{ => docs}/USER_GUIDE.md | 69 +- docs/i18n/vi/docs/VM_DEPLOYMENT_GUIDE.md | 403 +++ docs/i18n/vi/src/lib/a2a/README.md | 752 +++++ docs/i18n/zh-CN/A2A-SERVER.md | 198 -- docs/i18n/zh-CN/API_REFERENCE.md | 463 --- docs/i18n/zh-CN/ARCHITECTURE.md | 812 ----- docs/i18n/zh-CN/AUTO-COMBO.md | 67 - docs/i18n/zh-CN/CHANGELOG.md | 2566 ++++++++-------- docs/i18n/zh-CN/CLI-TOOLS.md | 344 --- docs/i18n/zh-CN/CODEBASE_DOCUMENTATION.md | 589 ---- docs/i18n/zh-CN/CONTRIBUTING.md | 299 ++ docs/i18n/zh-CN/FEATURES.md | 143 - docs/i18n/zh-CN/MCP-SERVER.md | 87 - docs/i18n/zh-CN/README.md | 2116 ++++++------- docs/i18n/zh-CN/RELEASE_CHECKLIST.md | 37 - docs/i18n/zh-CN/SECURITY.md | 179 ++ docs/i18n/zh-CN/TROUBLESHOOTING.md | 256 -- docs/i18n/zh-CN/USER_GUIDE.md | 942 ------ docs/i18n/zh-CN/VM_DEPLOYMENT_GUIDE.md | 401 --- docs/i18n/zh-CN/docs/A2A-SERVER.md | 200 ++ docs/i18n/zh-CN/docs/API_REFERENCE.md | 465 +++ docs/i18n/zh-CN/docs/ARCHITECTURE.md | 814 +++++ docs/i18n/zh-CN/docs/AUTO-COMBO.md | 67 + docs/i18n/zh-CN/docs/CLI-TOOLS.md | 348 +++ .../i18n/zh-CN/docs/CODEBASE_DOCUMENTATION.md | 591 ++++ docs/i18n/zh-CN/docs/COVERAGE_PLAN.md | 170 ++ docs/i18n/zh-CN/docs/FEATURES.md | 104 +- docs/i18n/zh-CN/docs/MCP-SERVER.md | 87 + docs/i18n/zh-CN/docs/RELEASE_CHECKLIST.md | 37 + docs/i18n/zh-CN/docs/TROUBLESHOOTING.md | 256 ++ docs/i18n/zh-CN/docs/USER_GUIDE.md | 944 ++++++ docs/i18n/zh-CN/docs/VM_DEPLOYMENT_GUIDE.md | 403 +++ docs/i18n/zh-CN/src/lib/a2a/README.md | 752 +++++ typescript | 0 848 files changed, 140984 insertions(+), 98533 deletions(-) delete mode 100644 .agents/workflows/update-docs.md delete mode 100644 docs/adr/0001-proxy-registry-limit-generalization.md delete mode 100644 docs/adr/0002-api-error-contract-management-endpoints.md delete mode 100644 docs/adr/0003-security-checklist-proxy-limits.md create mode 100644 docs/i18n/ar/CONTRIBUTING.md delete mode 100644 docs/i18n/ar/FEATURES.md delete mode 100644 docs/i18n/ar/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/ar/SECURITY.md delete mode 100644 docs/i18n/ar/VM_DEPLOYMENT_GUIDE.md create mode 100644 docs/i18n/ar/docs/A2A-SERVER.md create mode 100644 docs/i18n/ar/docs/API_REFERENCE.md create mode 100644 docs/i18n/ar/docs/ARCHITECTURE.md create mode 100644 docs/i18n/ar/docs/AUTO-COMBO.md create mode 100644 docs/i18n/ar/docs/CLI-TOOLS.md rename docs/i18n/ar/{ => docs}/CODEBASE_DOCUMENTATION.md (91%) create mode 100644 docs/i18n/ar/docs/COVERAGE_PLAN.md create mode 100644 docs/i18n/ar/docs/MCP-SERVER.md create mode 100644 docs/i18n/ar/docs/RELEASE_CHECKLIST.md rename docs/i18n/{da => ar/docs}/TROUBLESHOOTING.md (77%) rename docs/i18n/ar/{ => docs}/USER_GUIDE.md (82%) create mode 100644 docs/i18n/ar/docs/VM_DEPLOYMENT_GUIDE.md create mode 100644 docs/i18n/ar/src/lib/a2a/README.md create mode 100644 docs/i18n/bg/CONTRIBUTING.md delete mode 100644 docs/i18n/bg/FEATURES.md delete mode 100644 docs/i18n/bg/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/bg/SECURITY.md delete mode 100644 docs/i18n/bg/VM_DEPLOYMENT_GUIDE.md create mode 100644 docs/i18n/bg/docs/A2A-SERVER.md create mode 100644 docs/i18n/bg/docs/API_REFERENCE.md create mode 100644 docs/i18n/bg/docs/ARCHITECTURE.md create mode 100644 docs/i18n/bg/docs/AUTO-COMBO.md create mode 100644 docs/i18n/bg/docs/CLI-TOOLS.md rename docs/i18n/bg/{ => docs}/CODEBASE_DOCUMENTATION.md (91%) create mode 100644 docs/i18n/bg/docs/COVERAGE_PLAN.md create mode 100644 docs/i18n/bg/docs/MCP-SERVER.md create mode 100644 docs/i18n/bg/docs/RELEASE_CHECKLIST.md rename docs/i18n/bg/{ => docs}/TROUBLESHOOTING.md (77%) rename docs/i18n/bg/{ => docs}/USER_GUIDE.md (82%) create mode 100644 docs/i18n/bg/docs/VM_DEPLOYMENT_GUIDE.md create mode 100644 docs/i18n/bg/src/lib/a2a/README.md delete mode 100644 docs/i18n/cs/A2A-SERVER.md delete mode 100644 docs/i18n/cs/API_REFERENCE.md delete mode 100644 docs/i18n/cs/ARCHITECTURE.md delete mode 100644 docs/i18n/cs/AUTO-COMBO.md delete mode 100644 docs/i18n/cs/CLI-TOOLS.md delete mode 100644 docs/i18n/cs/CODEBASE_DOCUMENTATION.md delete mode 100644 docs/i18n/cs/FEATURES.md delete mode 100644 docs/i18n/cs/MCP-SERVER.md delete mode 100644 docs/i18n/cs/RELEASE_CHECKLIST.md delete mode 100644 docs/i18n/cs/TROUBLESHOOTING.md delete mode 100644 docs/i18n/cs/USER_GUIDE.md delete mode 100644 docs/i18n/cs/VM_DEPLOYMENT_GUIDE.md delete mode 100644 docs/i18n/cs/adr/0001-proxy-registry-limit-generalization.md delete mode 100644 docs/i18n/cs/adr/0002-api-error-contract-management-endpoints.md delete mode 100644 docs/i18n/cs/adr/0003-security-checklist-proxy-limits.md create mode 100644 docs/i18n/cs/docs/A2A-SERVER.md create mode 100644 docs/i18n/cs/docs/API_REFERENCE.md create mode 100644 docs/i18n/cs/docs/ARCHITECTURE.md create mode 100644 docs/i18n/cs/docs/AUTO-COMBO.md create mode 100644 docs/i18n/cs/docs/CLI-TOOLS.md rename docs/i18n/{de => cs/docs}/CODEBASE_DOCUMENTATION.md (91%) create mode 100644 docs/i18n/cs/docs/COVERAGE_PLAN.md rename docs/i18n/{de => cs/docs}/FEATURES.md (75%) create mode 100644 docs/i18n/cs/docs/MCP-SERVER.md create mode 100644 docs/i18n/cs/docs/RELEASE_CHECKLIST.md rename docs/i18n/{de => cs/docs}/TROUBLESHOOTING.md (77%) create mode 100644 docs/i18n/cs/docs/USER_GUIDE.md create mode 100644 docs/i18n/cs/docs/VM_DEPLOYMENT_GUIDE.md delete mode 100644 docs/i18n/cs/electron/README.md delete mode 100644 docs/i18n/cs/i18n/README.md delete mode 100644 docs/i18n/cs/open-sse/mcp-server/README.md create mode 100644 docs/i18n/cs/src/lib/a2a/README.md create mode 100644 docs/i18n/da/CONTRIBUTING.md delete mode 100644 docs/i18n/da/FEATURES.md delete mode 100644 docs/i18n/da/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/da/SECURITY.md rename docs/i18n/{de => da/docs}/A2A-SERVER.md (77%) rename docs/i18n/{ar => da/docs}/API_REFERENCE.md (74%) rename docs/i18n/{ar => da/docs}/ARCHITECTURE.md (89%) rename docs/i18n/{bg => da/docs}/AUTO-COMBO.md (65%) rename docs/i18n/{de => da/docs}/CLI-TOOLS.md (66%) create mode 100644 docs/i18n/da/docs/CODEBASE_DOCUMENTATION.md create mode 100644 docs/i18n/da/docs/COVERAGE_PLAN.md rename docs/i18n/da/{ => docs}/MCP-SERVER.md (65%) create mode 100644 docs/i18n/da/docs/RELEASE_CHECKLIST.md rename docs/i18n/{ar => da/docs}/TROUBLESHOOTING.md (77%) rename docs/i18n/da/{ => docs}/USER_GUIDE.md (82%) create mode 100644 docs/i18n/da/docs/VM_DEPLOYMENT_GUIDE.md create mode 100644 docs/i18n/da/src/lib/a2a/README.md create mode 100644 docs/i18n/de/CONTRIBUTING.md delete mode 100644 docs/i18n/de/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/de/SECURITY.md delete mode 100644 docs/i18n/de/VM_DEPLOYMENT_GUIDE.md create mode 100644 docs/i18n/de/docs/A2A-SERVER.md create mode 100644 docs/i18n/de/docs/API_REFERENCE.md create mode 100644 docs/i18n/de/docs/ARCHITECTURE.md create mode 100644 docs/i18n/de/docs/AUTO-COMBO.md create mode 100644 docs/i18n/de/docs/CLI-TOOLS.md create mode 100644 docs/i18n/de/docs/CODEBASE_DOCUMENTATION.md create mode 100644 docs/i18n/de/docs/COVERAGE_PLAN.md create mode 100644 docs/i18n/de/docs/MCP-SERVER.md create mode 100644 docs/i18n/de/docs/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/de/docs/TROUBLESHOOTING.md rename docs/i18n/de/{ => docs}/USER_GUIDE.md (82%) create mode 100644 docs/i18n/de/docs/VM_DEPLOYMENT_GUIDE.md create mode 100644 docs/i18n/de/src/lib/a2a/README.md delete mode 100644 docs/i18n/es/A2A-SERVER.md delete mode 100644 docs/i18n/es/API_REFERENCE.md delete mode 100644 docs/i18n/es/ARCHITECTURE.md delete mode 100644 docs/i18n/es/AUTO-COMBO.md delete mode 100644 docs/i18n/es/CLI-TOOLS.md delete mode 100644 docs/i18n/es/CODEBASE_DOCUMENTATION.md create mode 100644 docs/i18n/es/CONTRIBUTING.md delete mode 100644 docs/i18n/es/FEATURES.md delete mode 100644 docs/i18n/es/MCP-SERVER.md delete mode 100644 docs/i18n/es/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/es/SECURITY.md delete mode 100644 docs/i18n/es/TROUBLESHOOTING.md delete mode 100644 docs/i18n/es/VM_DEPLOYMENT_GUIDE.md create mode 100644 docs/i18n/es/docs/A2A-SERVER.md create mode 100644 docs/i18n/es/docs/API_REFERENCE.md create mode 100644 docs/i18n/es/docs/ARCHITECTURE.md create mode 100644 docs/i18n/es/docs/AUTO-COMBO.md create mode 100644 docs/i18n/es/docs/CLI-TOOLS.md create mode 100644 docs/i18n/es/docs/CODEBASE_DOCUMENTATION.md create mode 100644 docs/i18n/es/docs/COVERAGE_PLAN.md create mode 100644 docs/i18n/es/docs/MCP-SERVER.md create mode 100644 docs/i18n/es/docs/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/es/docs/TROUBLESHOOTING.md rename docs/i18n/es/{ => docs}/USER_GUIDE.md (82%) rename docs/i18n/{no => es/docs}/VM_DEPLOYMENT_GUIDE.md (58%) create mode 100644 docs/i18n/es/src/lib/a2a/README.md delete mode 100644 docs/i18n/fi/A2A-SERVER.md delete mode 100644 docs/i18n/fi/API_REFERENCE.md delete mode 100644 docs/i18n/fi/ARCHITECTURE.md delete mode 100644 docs/i18n/fi/AUTO-COMBO.md delete mode 100644 docs/i18n/fi/CLI-TOOLS.md delete mode 100644 docs/i18n/fi/CODEBASE_DOCUMENTATION.md create mode 100644 docs/i18n/fi/CONTRIBUTING.md delete mode 100644 docs/i18n/fi/FEATURES.md delete mode 100644 docs/i18n/fi/MCP-SERVER.md delete mode 100644 docs/i18n/fi/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/fi/SECURITY.md delete mode 100644 docs/i18n/fi/TROUBLESHOOTING.md delete mode 100644 docs/i18n/fi/VM_DEPLOYMENT_GUIDE.md rename docs/i18n/{ar => fi/docs}/A2A-SERVER.md (77%) rename docs/i18n/{bg => fi/docs}/API_REFERENCE.md (74%) rename docs/i18n/{de => fi/docs}/ARCHITECTURE.md (89%) rename docs/i18n/{de => fi/docs}/AUTO-COMBO.md (65%) create mode 100644 docs/i18n/fi/docs/CLI-TOOLS.md create mode 100644 docs/i18n/fi/docs/CODEBASE_DOCUMENTATION.md create mode 100644 docs/i18n/fi/docs/COVERAGE_PLAN.md rename docs/i18n/{ar => fi/docs}/MCP-SERVER.md (65%) create mode 100644 docs/i18n/fi/docs/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/fi/docs/TROUBLESHOOTING.md rename docs/i18n/fi/{ => docs}/USER_GUIDE.md (82%) create mode 100644 docs/i18n/fi/docs/VM_DEPLOYMENT_GUIDE.md create mode 100644 docs/i18n/fi/src/lib/a2a/README.md delete mode 100644 docs/i18n/fr/A2A-SERVER.md delete mode 100644 docs/i18n/fr/API_REFERENCE.md delete mode 100644 docs/i18n/fr/ARCHITECTURE.md delete mode 100644 docs/i18n/fr/AUTO-COMBO.md delete mode 100644 docs/i18n/fr/CLI-TOOLS.md delete mode 100644 docs/i18n/fr/CODEBASE_DOCUMENTATION.md create mode 100644 docs/i18n/fr/CONTRIBUTING.md delete mode 100644 docs/i18n/fr/FEATURES.md delete mode 100644 docs/i18n/fr/MCP-SERVER.md delete mode 100644 docs/i18n/fr/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/fr/SECURITY.md delete mode 100644 docs/i18n/fr/TROUBLESHOOTING.md delete mode 100644 docs/i18n/fr/VM_DEPLOYMENT_GUIDE.md create mode 100644 docs/i18n/fr/docs/A2A-SERVER.md create mode 100644 docs/i18n/fr/docs/API_REFERENCE.md create mode 100644 docs/i18n/fr/docs/ARCHITECTURE.md create mode 100644 docs/i18n/fr/docs/AUTO-COMBO.md create mode 100644 docs/i18n/fr/docs/CLI-TOOLS.md rename docs/i18n/{da => fr/docs}/CODEBASE_DOCUMENTATION.md (91%) create mode 100644 docs/i18n/fr/docs/COVERAGE_PLAN.md create mode 100644 docs/i18n/fr/docs/MCP-SERVER.md create mode 100644 docs/i18n/fr/docs/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/fr/docs/TROUBLESHOOTING.md rename docs/i18n/fr/{ => docs}/USER_GUIDE.md (82%) create mode 100644 docs/i18n/fr/docs/VM_DEPLOYMENT_GUIDE.md create mode 100644 docs/i18n/fr/src/lib/a2a/README.md delete mode 100644 docs/i18n/he/A2A-SERVER.md delete mode 100644 docs/i18n/he/API_REFERENCE.md delete mode 100644 docs/i18n/he/ARCHITECTURE.md delete mode 100644 docs/i18n/he/AUTO-COMBO.md delete mode 100644 docs/i18n/he/CLI-TOOLS.md delete mode 100644 docs/i18n/he/CODEBASE_DOCUMENTATION.md create mode 100644 docs/i18n/he/CONTRIBUTING.md delete mode 100644 docs/i18n/he/FEATURES.md delete mode 100644 docs/i18n/he/MCP-SERVER.md delete mode 100644 docs/i18n/he/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/he/SECURITY.md delete mode 100644 docs/i18n/he/TROUBLESHOOTING.md delete mode 100644 docs/i18n/he/VM_DEPLOYMENT_GUIDE.md create mode 100644 docs/i18n/he/docs/A2A-SERVER.md create mode 100644 docs/i18n/he/docs/API_REFERENCE.md create mode 100644 docs/i18n/he/docs/ARCHITECTURE.md create mode 100644 docs/i18n/he/docs/AUTO-COMBO.md create mode 100644 docs/i18n/he/docs/CLI-TOOLS.md create mode 100644 docs/i18n/he/docs/CODEBASE_DOCUMENTATION.md create mode 100644 docs/i18n/he/docs/COVERAGE_PLAN.md create mode 100644 docs/i18n/he/docs/MCP-SERVER.md create mode 100644 docs/i18n/he/docs/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/he/docs/TROUBLESHOOTING.md rename docs/i18n/he/{ => docs}/USER_GUIDE.md (82%) create mode 100644 docs/i18n/he/docs/VM_DEPLOYMENT_GUIDE.md create mode 100644 docs/i18n/he/src/lib/a2a/README.md delete mode 100644 docs/i18n/hu/A2A-SERVER.md delete mode 100644 docs/i18n/hu/API_REFERENCE.md delete mode 100644 docs/i18n/hu/ARCHITECTURE.md delete mode 100644 docs/i18n/hu/AUTO-COMBO.md delete mode 100644 docs/i18n/hu/CLI-TOOLS.md delete mode 100644 docs/i18n/hu/CODEBASE_DOCUMENTATION.md create mode 100644 docs/i18n/hu/CONTRIBUTING.md delete mode 100644 docs/i18n/hu/FEATURES.md delete mode 100644 docs/i18n/hu/MCP-SERVER.md delete mode 100644 docs/i18n/hu/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/hu/SECURITY.md delete mode 100644 docs/i18n/hu/TROUBLESHOOTING.md delete mode 100644 docs/i18n/hu/VM_DEPLOYMENT_GUIDE.md rename docs/i18n/{da => hu/docs}/A2A-SERVER.md (77%) rename docs/i18n/{da => hu/docs}/API_REFERENCE.md (74%) rename docs/i18n/{bg => hu/docs}/ARCHITECTURE.md (89%) rename docs/i18n/{da => hu/docs}/AUTO-COMBO.md (65%) create mode 100644 docs/i18n/hu/docs/CLI-TOOLS.md create mode 100644 docs/i18n/hu/docs/CODEBASE_DOCUMENTATION.md create mode 100644 docs/i18n/hu/docs/COVERAGE_PLAN.md create mode 100644 docs/i18n/hu/docs/MCP-SERVER.md create mode 100644 docs/i18n/hu/docs/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/hu/docs/TROUBLESHOOTING.md rename docs/i18n/hu/{ => docs}/USER_GUIDE.md (82%) create mode 100644 docs/i18n/hu/docs/VM_DEPLOYMENT_GUIDE.md create mode 100644 docs/i18n/hu/src/lib/a2a/README.md delete mode 100644 docs/i18n/id/A2A-SERVER.md delete mode 100644 docs/i18n/id/API_REFERENCE.md delete mode 100644 docs/i18n/id/ARCHITECTURE.md delete mode 100644 docs/i18n/id/AUTO-COMBO.md delete mode 100644 docs/i18n/id/CLI-TOOLS.md delete mode 100644 docs/i18n/id/CODEBASE_DOCUMENTATION.md create mode 100644 docs/i18n/id/CONTRIBUTING.md delete mode 100644 docs/i18n/id/FEATURES.md delete mode 100644 docs/i18n/id/MCP-SERVER.md delete mode 100644 docs/i18n/id/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/id/SECURITY.md delete mode 100644 docs/i18n/id/TROUBLESHOOTING.md delete mode 100644 docs/i18n/id/VM_DEPLOYMENT_GUIDE.md create mode 100644 docs/i18n/id/docs/A2A-SERVER.md create mode 100644 docs/i18n/id/docs/API_REFERENCE.md create mode 100644 docs/i18n/id/docs/ARCHITECTURE.md create mode 100644 docs/i18n/id/docs/AUTO-COMBO.md create mode 100644 docs/i18n/id/docs/CLI-TOOLS.md create mode 100644 docs/i18n/id/docs/CODEBASE_DOCUMENTATION.md create mode 100644 docs/i18n/id/docs/COVERAGE_PLAN.md create mode 100644 docs/i18n/id/docs/MCP-SERVER.md create mode 100644 docs/i18n/id/docs/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/id/docs/TROUBLESHOOTING.md rename docs/i18n/id/{ => docs}/USER_GUIDE.md (82%) create mode 100644 docs/i18n/id/docs/VM_DEPLOYMENT_GUIDE.md create mode 100644 docs/i18n/id/src/lib/a2a/README.md delete mode 100644 docs/i18n/in/A2A-SERVER.md delete mode 100644 docs/i18n/in/API_REFERENCE.md delete mode 100644 docs/i18n/in/ARCHITECTURE.md delete mode 100644 docs/i18n/in/AUTO-COMBO.md delete mode 100644 docs/i18n/in/CLI-TOOLS.md delete mode 100644 docs/i18n/in/CODEBASE_DOCUMENTATION.md create mode 100644 docs/i18n/in/CONTRIBUTING.md delete mode 100644 docs/i18n/in/FEATURES.md delete mode 100644 docs/i18n/in/MCP-SERVER.md delete mode 100644 docs/i18n/in/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/in/SECURITY.md delete mode 100644 docs/i18n/in/TROUBLESHOOTING.md delete mode 100644 docs/i18n/in/VM_DEPLOYMENT_GUIDE.md create mode 100644 docs/i18n/in/docs/A2A-SERVER.md create mode 100644 docs/i18n/in/docs/API_REFERENCE.md create mode 100644 docs/i18n/in/docs/ARCHITECTURE.md create mode 100644 docs/i18n/in/docs/AUTO-COMBO.md create mode 100644 docs/i18n/in/docs/CLI-TOOLS.md create mode 100644 docs/i18n/in/docs/CODEBASE_DOCUMENTATION.md create mode 100644 docs/i18n/in/docs/COVERAGE_PLAN.md create mode 100644 docs/i18n/in/docs/MCP-SERVER.md create mode 100644 docs/i18n/in/docs/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/in/docs/TROUBLESHOOTING.md rename docs/i18n/in/{ => docs}/USER_GUIDE.md (82%) create mode 100644 docs/i18n/in/docs/VM_DEPLOYMENT_GUIDE.md create mode 100644 docs/i18n/in/src/lib/a2a/README.md delete mode 100644 docs/i18n/it/A2A-SERVER.md delete mode 100644 docs/i18n/it/API_REFERENCE.md delete mode 100644 docs/i18n/it/ARCHITECTURE.md delete mode 100644 docs/i18n/it/AUTO-COMBO.md delete mode 100644 docs/i18n/it/CLI-TOOLS.md delete mode 100644 docs/i18n/it/CODEBASE_DOCUMENTATION.md create mode 100644 docs/i18n/it/CONTRIBUTING.md delete mode 100644 docs/i18n/it/FEATURES.md delete mode 100644 docs/i18n/it/MCP-SERVER.md delete mode 100644 docs/i18n/it/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/it/SECURITY.md delete mode 100644 docs/i18n/it/TROUBLESHOOTING.md delete mode 100644 docs/i18n/it/VM_DEPLOYMENT_GUIDE.md create mode 100644 docs/i18n/it/docs/A2A-SERVER.md create mode 100644 docs/i18n/it/docs/API_REFERENCE.md create mode 100644 docs/i18n/it/docs/ARCHITECTURE.md create mode 100644 docs/i18n/it/docs/AUTO-COMBO.md create mode 100644 docs/i18n/it/docs/CLI-TOOLS.md create mode 100644 docs/i18n/it/docs/CODEBASE_DOCUMENTATION.md create mode 100644 docs/i18n/it/docs/COVERAGE_PLAN.md create mode 100644 docs/i18n/it/docs/MCP-SERVER.md create mode 100644 docs/i18n/it/docs/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/it/docs/TROUBLESHOOTING.md rename docs/i18n/it/{ => docs}/USER_GUIDE.md (82%) rename docs/i18n/{da => it/docs}/VM_DEPLOYMENT_GUIDE.md (55%) create mode 100644 docs/i18n/it/src/lib/a2a/README.md delete mode 100644 docs/i18n/ja/A2A-SERVER.md delete mode 100644 docs/i18n/ja/API_REFERENCE.md delete mode 100644 docs/i18n/ja/ARCHITECTURE.md delete mode 100644 docs/i18n/ja/AUTO-COMBO.md delete mode 100644 docs/i18n/ja/CLI-TOOLS.md delete mode 100644 docs/i18n/ja/CODEBASE_DOCUMENTATION.md create mode 100644 docs/i18n/ja/CONTRIBUTING.md delete mode 100644 docs/i18n/ja/FEATURES.md delete mode 100644 docs/i18n/ja/MCP-SERVER.md delete mode 100644 docs/i18n/ja/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/ja/SECURITY.md delete mode 100644 docs/i18n/ja/TROUBLESHOOTING.md delete mode 100644 docs/i18n/ja/VM_DEPLOYMENT_GUIDE.md create mode 100644 docs/i18n/ja/docs/A2A-SERVER.md create mode 100644 docs/i18n/ja/docs/API_REFERENCE.md create mode 100644 docs/i18n/ja/docs/ARCHITECTURE.md create mode 100644 docs/i18n/ja/docs/AUTO-COMBO.md create mode 100644 docs/i18n/ja/docs/CLI-TOOLS.md create mode 100644 docs/i18n/ja/docs/CODEBASE_DOCUMENTATION.md create mode 100644 docs/i18n/ja/docs/COVERAGE_PLAN.md create mode 100644 docs/i18n/ja/docs/MCP-SERVER.md create mode 100644 docs/i18n/ja/docs/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/ja/docs/TROUBLESHOOTING.md rename docs/i18n/ja/{ => docs}/USER_GUIDE.md (82%) create mode 100644 docs/i18n/ja/docs/VM_DEPLOYMENT_GUIDE.md create mode 100644 docs/i18n/ja/src/lib/a2a/README.md delete mode 100644 docs/i18n/ko/A2A-SERVER.md delete mode 100644 docs/i18n/ko/API_REFERENCE.md delete mode 100644 docs/i18n/ko/ARCHITECTURE.md delete mode 100644 docs/i18n/ko/AUTO-COMBO.md delete mode 100644 docs/i18n/ko/CLI-TOOLS.md delete mode 100644 docs/i18n/ko/CODEBASE_DOCUMENTATION.md create mode 100644 docs/i18n/ko/CONTRIBUTING.md delete mode 100644 docs/i18n/ko/FEATURES.md delete mode 100644 docs/i18n/ko/MCP-SERVER.md delete mode 100644 docs/i18n/ko/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/ko/SECURITY.md delete mode 100644 docs/i18n/ko/TROUBLESHOOTING.md delete mode 100644 docs/i18n/ko/VM_DEPLOYMENT_GUIDE.md create mode 100644 docs/i18n/ko/docs/A2A-SERVER.md create mode 100644 docs/i18n/ko/docs/API_REFERENCE.md create mode 100644 docs/i18n/ko/docs/ARCHITECTURE.md create mode 100644 docs/i18n/ko/docs/AUTO-COMBO.md create mode 100644 docs/i18n/ko/docs/CLI-TOOLS.md create mode 100644 docs/i18n/ko/docs/CODEBASE_DOCUMENTATION.md create mode 100644 docs/i18n/ko/docs/COVERAGE_PLAN.md rename docs/i18n/{bg => ko/docs}/MCP-SERVER.md (65%) create mode 100644 docs/i18n/ko/docs/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/ko/docs/TROUBLESHOOTING.md rename docs/i18n/ko/{ => docs}/USER_GUIDE.md (82%) create mode 100644 docs/i18n/ko/docs/VM_DEPLOYMENT_GUIDE.md create mode 100644 docs/i18n/ko/src/lib/a2a/README.md delete mode 100644 docs/i18n/ms/A2A-SERVER.md delete mode 100644 docs/i18n/ms/API_REFERENCE.md delete mode 100644 docs/i18n/ms/ARCHITECTURE.md delete mode 100644 docs/i18n/ms/AUTO-COMBO.md delete mode 100644 docs/i18n/ms/CLI-TOOLS.md delete mode 100644 docs/i18n/ms/CODEBASE_DOCUMENTATION.md create mode 100644 docs/i18n/ms/CONTRIBUTING.md delete mode 100644 docs/i18n/ms/FEATURES.md delete mode 100644 docs/i18n/ms/MCP-SERVER.md delete mode 100644 docs/i18n/ms/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/ms/SECURITY.md delete mode 100644 docs/i18n/ms/TROUBLESHOOTING.md create mode 100644 docs/i18n/ms/docs/A2A-SERVER.md create mode 100644 docs/i18n/ms/docs/API_REFERENCE.md create mode 100644 docs/i18n/ms/docs/ARCHITECTURE.md create mode 100644 docs/i18n/ms/docs/AUTO-COMBO.md create mode 100644 docs/i18n/ms/docs/CLI-TOOLS.md create mode 100644 docs/i18n/ms/docs/CODEBASE_DOCUMENTATION.md create mode 100644 docs/i18n/ms/docs/COVERAGE_PLAN.md create mode 100644 docs/i18n/ms/docs/MCP-SERVER.md create mode 100644 docs/i18n/ms/docs/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/ms/docs/TROUBLESHOOTING.md rename docs/i18n/ms/{ => docs}/USER_GUIDE.md (82%) create mode 100644 docs/i18n/ms/docs/VM_DEPLOYMENT_GUIDE.md create mode 100644 docs/i18n/ms/src/lib/a2a/README.md delete mode 100644 docs/i18n/nl/A2A-SERVER.md delete mode 100644 docs/i18n/nl/API_REFERENCE.md delete mode 100644 docs/i18n/nl/ARCHITECTURE.md delete mode 100644 docs/i18n/nl/AUTO-COMBO.md delete mode 100644 docs/i18n/nl/CLI-TOOLS.md delete mode 100644 docs/i18n/nl/CODEBASE_DOCUMENTATION.md create mode 100644 docs/i18n/nl/CONTRIBUTING.md delete mode 100644 docs/i18n/nl/FEATURES.md delete mode 100644 docs/i18n/nl/MCP-SERVER.md delete mode 100644 docs/i18n/nl/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/nl/SECURITY.md delete mode 100644 docs/i18n/nl/TROUBLESHOOTING.md delete mode 100644 docs/i18n/nl/VM_DEPLOYMENT_GUIDE.md create mode 100644 docs/i18n/nl/docs/A2A-SERVER.md create mode 100644 docs/i18n/nl/docs/API_REFERENCE.md create mode 100644 docs/i18n/nl/docs/ARCHITECTURE.md create mode 100644 docs/i18n/nl/docs/AUTO-COMBO.md create mode 100644 docs/i18n/nl/docs/CLI-TOOLS.md create mode 100644 docs/i18n/nl/docs/CODEBASE_DOCUMENTATION.md create mode 100644 docs/i18n/nl/docs/COVERAGE_PLAN.md create mode 100644 docs/i18n/nl/docs/MCP-SERVER.md create mode 100644 docs/i18n/nl/docs/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/nl/docs/TROUBLESHOOTING.md rename docs/i18n/nl/{ => docs}/USER_GUIDE.md (82%) create mode 100644 docs/i18n/nl/docs/VM_DEPLOYMENT_GUIDE.md create mode 100644 docs/i18n/nl/src/lib/a2a/README.md delete mode 100644 docs/i18n/no/A2A-SERVER.md delete mode 100644 docs/i18n/no/API_REFERENCE.md delete mode 100644 docs/i18n/no/ARCHITECTURE.md delete mode 100644 docs/i18n/no/AUTO-COMBO.md delete mode 100644 docs/i18n/no/CLI-TOOLS.md delete mode 100644 docs/i18n/no/CODEBASE_DOCUMENTATION.md create mode 100644 docs/i18n/no/CONTRIBUTING.md delete mode 100644 docs/i18n/no/FEATURES.md delete mode 100644 docs/i18n/no/MCP-SERVER.md delete mode 100644 docs/i18n/no/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/no/SECURITY.md delete mode 100644 docs/i18n/no/TROUBLESHOOTING.md rename docs/i18n/{bg => no/docs}/A2A-SERVER.md (77%) rename docs/i18n/{de => no/docs}/API_REFERENCE.md (74%) rename docs/i18n/{da => no/docs}/ARCHITECTURE.md (89%) rename docs/i18n/{ar => no/docs}/AUTO-COMBO.md (65%) rename docs/i18n/{bg => no/docs}/CLI-TOOLS.md (66%) create mode 100644 docs/i18n/no/docs/CODEBASE_DOCUMENTATION.md create mode 100644 docs/i18n/no/docs/COVERAGE_PLAN.md rename docs/i18n/{de => no/docs}/MCP-SERVER.md (65%) create mode 100644 docs/i18n/no/docs/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/no/docs/TROUBLESHOOTING.md rename docs/i18n/no/{ => docs}/USER_GUIDE.md (82%) create mode 100644 docs/i18n/no/docs/VM_DEPLOYMENT_GUIDE.md create mode 100644 docs/i18n/no/src/lib/a2a/README.md delete mode 100644 docs/i18n/phi/A2A-SERVER.md delete mode 100644 docs/i18n/phi/API_REFERENCE.md delete mode 100644 docs/i18n/phi/ARCHITECTURE.md delete mode 100644 docs/i18n/phi/AUTO-COMBO.md delete mode 100644 docs/i18n/phi/CLI-TOOLS.md delete mode 100644 docs/i18n/phi/CODEBASE_DOCUMENTATION.md create mode 100644 docs/i18n/phi/CONTRIBUTING.md delete mode 100644 docs/i18n/phi/FEATURES.md delete mode 100644 docs/i18n/phi/MCP-SERVER.md delete mode 100644 docs/i18n/phi/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/phi/SECURITY.md delete mode 100644 docs/i18n/phi/TROUBLESHOOTING.md delete mode 100644 docs/i18n/phi/VM_DEPLOYMENT_GUIDE.md create mode 100644 docs/i18n/phi/docs/A2A-SERVER.md create mode 100644 docs/i18n/phi/docs/API_REFERENCE.md create mode 100644 docs/i18n/phi/docs/ARCHITECTURE.md create mode 100644 docs/i18n/phi/docs/AUTO-COMBO.md create mode 100644 docs/i18n/phi/docs/CLI-TOOLS.md create mode 100644 docs/i18n/phi/docs/CODEBASE_DOCUMENTATION.md create mode 100644 docs/i18n/phi/docs/COVERAGE_PLAN.md create mode 100644 docs/i18n/phi/docs/MCP-SERVER.md create mode 100644 docs/i18n/phi/docs/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/phi/docs/TROUBLESHOOTING.md rename docs/i18n/phi/{ => docs}/USER_GUIDE.md (82%) rename docs/i18n/{ms => phi/docs}/VM_DEPLOYMENT_GUIDE.md (54%) create mode 100644 docs/i18n/phi/src/lib/a2a/README.md delete mode 100644 docs/i18n/pl/A2A-SERVER.md delete mode 100644 docs/i18n/pl/API_REFERENCE.md delete mode 100644 docs/i18n/pl/ARCHITECTURE.md delete mode 100644 docs/i18n/pl/AUTO-COMBO.md delete mode 100644 docs/i18n/pl/CLI-TOOLS.md delete mode 100644 docs/i18n/pl/CODEBASE_DOCUMENTATION.md create mode 100644 docs/i18n/pl/CONTRIBUTING.md delete mode 100644 docs/i18n/pl/FEATURES.md delete mode 100644 docs/i18n/pl/MCP-SERVER.md delete mode 100644 docs/i18n/pl/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/pl/SECURITY.md delete mode 100644 docs/i18n/pl/TROUBLESHOOTING.md delete mode 100644 docs/i18n/pl/VM_DEPLOYMENT_GUIDE.md create mode 100644 docs/i18n/pl/docs/A2A-SERVER.md create mode 100644 docs/i18n/pl/docs/API_REFERENCE.md create mode 100644 docs/i18n/pl/docs/ARCHITECTURE.md create mode 100644 docs/i18n/pl/docs/AUTO-COMBO.md create mode 100644 docs/i18n/pl/docs/CLI-TOOLS.md create mode 100644 docs/i18n/pl/docs/CODEBASE_DOCUMENTATION.md create mode 100644 docs/i18n/pl/docs/COVERAGE_PLAN.md create mode 100644 docs/i18n/pl/docs/MCP-SERVER.md create mode 100644 docs/i18n/pl/docs/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/pl/docs/TROUBLESHOOTING.md rename docs/i18n/pl/{ => docs}/USER_GUIDE.md (82%) create mode 100644 docs/i18n/pl/docs/VM_DEPLOYMENT_GUIDE.md create mode 100644 docs/i18n/pl/src/lib/a2a/README.md delete mode 100644 docs/i18n/pt-BR/A2A-SERVER.md delete mode 100644 docs/i18n/pt-BR/API_REFERENCE.md delete mode 100644 docs/i18n/pt-BR/ARCHITECTURE.md delete mode 100644 docs/i18n/pt-BR/AUTO-COMBO.md delete mode 100644 docs/i18n/pt-BR/CLI-TOOLS.md delete mode 100644 docs/i18n/pt-BR/CODEBASE_DOCUMENTATION.md create mode 100644 docs/i18n/pt-BR/CONTRIBUTING.md delete mode 100644 docs/i18n/pt-BR/FEATURES.md delete mode 100644 docs/i18n/pt-BR/MCP-SERVER.md delete mode 100644 docs/i18n/pt-BR/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/pt-BR/SECURITY.md delete mode 100644 docs/i18n/pt-BR/TROUBLESHOOTING.md delete mode 100644 docs/i18n/pt-BR/USER_GUIDE.md create mode 100644 docs/i18n/pt-BR/docs/A2A-SERVER.md create mode 100644 docs/i18n/pt-BR/docs/API_REFERENCE.md create mode 100644 docs/i18n/pt-BR/docs/ARCHITECTURE.md create mode 100644 docs/i18n/pt-BR/docs/AUTO-COMBO.md create mode 100644 docs/i18n/pt-BR/docs/CLI-TOOLS.md create mode 100644 docs/i18n/pt-BR/docs/CODEBASE_DOCUMENTATION.md create mode 100644 docs/i18n/pt-BR/docs/COVERAGE_PLAN.md create mode 100644 docs/i18n/pt-BR/docs/MCP-SERVER.md create mode 100644 docs/i18n/pt-BR/docs/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/pt-BR/docs/TROUBLESHOOTING.md create mode 100644 docs/i18n/pt-BR/docs/USER_GUIDE.md create mode 100644 docs/i18n/pt-BR/docs/VM_DEPLOYMENT_GUIDE.md create mode 100644 docs/i18n/pt-BR/src/lib/a2a/README.md delete mode 100644 docs/i18n/pt/A2A-SERVER.md delete mode 100644 docs/i18n/pt/API_REFERENCE.md delete mode 100644 docs/i18n/pt/ARCHITECTURE.md delete mode 100644 docs/i18n/pt/AUTO-COMBO.md delete mode 100644 docs/i18n/pt/CLI-TOOLS.md delete mode 100644 docs/i18n/pt/CODEBASE_DOCUMENTATION.md create mode 100644 docs/i18n/pt/CONTRIBUTING.md delete mode 100644 docs/i18n/pt/FEATURES.md delete mode 100644 docs/i18n/pt/MCP-SERVER.md delete mode 100644 docs/i18n/pt/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/pt/SECURITY.md delete mode 100644 docs/i18n/pt/TROUBLESHOOTING.md delete mode 100644 docs/i18n/pt/VM_DEPLOYMENT_GUIDE.md create mode 100644 docs/i18n/pt/docs/A2A-SERVER.md create mode 100644 docs/i18n/pt/docs/API_REFERENCE.md create mode 100644 docs/i18n/pt/docs/ARCHITECTURE.md create mode 100644 docs/i18n/pt/docs/AUTO-COMBO.md create mode 100644 docs/i18n/pt/docs/CLI-TOOLS.md create mode 100644 docs/i18n/pt/docs/CODEBASE_DOCUMENTATION.md create mode 100644 docs/i18n/pt/docs/COVERAGE_PLAN.md create mode 100644 docs/i18n/pt/docs/MCP-SERVER.md create mode 100644 docs/i18n/pt/docs/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/pt/docs/TROUBLESHOOTING.md rename docs/i18n/pt/{ => docs}/USER_GUIDE.md (82%) create mode 100644 docs/i18n/pt/docs/VM_DEPLOYMENT_GUIDE.md create mode 100644 docs/i18n/pt/src/lib/a2a/README.md delete mode 100644 docs/i18n/ro/A2A-SERVER.md delete mode 100644 docs/i18n/ro/API_REFERENCE.md delete mode 100644 docs/i18n/ro/ARCHITECTURE.md delete mode 100644 docs/i18n/ro/AUTO-COMBO.md delete mode 100644 docs/i18n/ro/CLI-TOOLS.md delete mode 100644 docs/i18n/ro/CODEBASE_DOCUMENTATION.md create mode 100644 docs/i18n/ro/CONTRIBUTING.md delete mode 100644 docs/i18n/ro/FEATURES.md delete mode 100644 docs/i18n/ro/MCP-SERVER.md delete mode 100644 docs/i18n/ro/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/ro/SECURITY.md delete mode 100644 docs/i18n/ro/TROUBLESHOOTING.md delete mode 100644 docs/i18n/ro/VM_DEPLOYMENT_GUIDE.md create mode 100644 docs/i18n/ro/docs/A2A-SERVER.md create mode 100644 docs/i18n/ro/docs/API_REFERENCE.md create mode 100644 docs/i18n/ro/docs/ARCHITECTURE.md create mode 100644 docs/i18n/ro/docs/AUTO-COMBO.md rename docs/i18n/{ar => ro/docs}/CLI-TOOLS.md (66%) create mode 100644 docs/i18n/ro/docs/CODEBASE_DOCUMENTATION.md create mode 100644 docs/i18n/ro/docs/COVERAGE_PLAN.md create mode 100644 docs/i18n/ro/docs/MCP-SERVER.md create mode 100644 docs/i18n/ro/docs/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/ro/docs/TROUBLESHOOTING.md rename docs/i18n/ro/{ => docs}/USER_GUIDE.md (82%) rename docs/i18n/{pt-BR => ro/docs}/VM_DEPLOYMENT_GUIDE.md (54%) create mode 100644 docs/i18n/ro/src/lib/a2a/README.md delete mode 100644 docs/i18n/ru/A2A-SERVER.md delete mode 100644 docs/i18n/ru/API_REFERENCE.md delete mode 100644 docs/i18n/ru/ARCHITECTURE.md delete mode 100644 docs/i18n/ru/AUTO-COMBO.md delete mode 100644 docs/i18n/ru/CLI-TOOLS.md delete mode 100644 docs/i18n/ru/CODEBASE_DOCUMENTATION.md create mode 100644 docs/i18n/ru/CONTRIBUTING.md delete mode 100644 docs/i18n/ru/FEATURES.md delete mode 100644 docs/i18n/ru/MCP-SERVER.md delete mode 100644 docs/i18n/ru/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/ru/SECURITY.md delete mode 100644 docs/i18n/ru/TROUBLESHOOTING.md delete mode 100644 docs/i18n/ru/VM_DEPLOYMENT_GUIDE.md create mode 100644 docs/i18n/ru/docs/A2A-SERVER.md create mode 100644 docs/i18n/ru/docs/API_REFERENCE.md create mode 100644 docs/i18n/ru/docs/ARCHITECTURE.md create mode 100644 docs/i18n/ru/docs/AUTO-COMBO.md create mode 100644 docs/i18n/ru/docs/CLI-TOOLS.md create mode 100644 docs/i18n/ru/docs/CODEBASE_DOCUMENTATION.md create mode 100644 docs/i18n/ru/docs/COVERAGE_PLAN.md create mode 100644 docs/i18n/ru/docs/MCP-SERVER.md create mode 100644 docs/i18n/ru/docs/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/ru/docs/TROUBLESHOOTING.md rename docs/i18n/ru/{ => docs}/USER_GUIDE.md (82%) create mode 100644 docs/i18n/ru/docs/VM_DEPLOYMENT_GUIDE.md create mode 100644 docs/i18n/ru/src/lib/a2a/README.md delete mode 100644 docs/i18n/sk/A2A-SERVER.md delete mode 100644 docs/i18n/sk/API_REFERENCE.md delete mode 100644 docs/i18n/sk/ARCHITECTURE.md delete mode 100644 docs/i18n/sk/AUTO-COMBO.md delete mode 100644 docs/i18n/sk/CLI-TOOLS.md delete mode 100644 docs/i18n/sk/CODEBASE_DOCUMENTATION.md create mode 100644 docs/i18n/sk/CONTRIBUTING.md delete mode 100644 docs/i18n/sk/FEATURES.md delete mode 100644 docs/i18n/sk/MCP-SERVER.md delete mode 100644 docs/i18n/sk/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/sk/SECURITY.md delete mode 100644 docs/i18n/sk/TROUBLESHOOTING.md delete mode 100644 docs/i18n/sk/VM_DEPLOYMENT_GUIDE.md create mode 100644 docs/i18n/sk/docs/A2A-SERVER.md create mode 100644 docs/i18n/sk/docs/API_REFERENCE.md create mode 100644 docs/i18n/sk/docs/ARCHITECTURE.md create mode 100644 docs/i18n/sk/docs/AUTO-COMBO.md create mode 100644 docs/i18n/sk/docs/CLI-TOOLS.md create mode 100644 docs/i18n/sk/docs/CODEBASE_DOCUMENTATION.md create mode 100644 docs/i18n/sk/docs/COVERAGE_PLAN.md create mode 100644 docs/i18n/sk/docs/MCP-SERVER.md create mode 100644 docs/i18n/sk/docs/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/sk/docs/TROUBLESHOOTING.md rename docs/i18n/sk/{ => docs}/USER_GUIDE.md (82%) create mode 100644 docs/i18n/sk/docs/VM_DEPLOYMENT_GUIDE.md create mode 100644 docs/i18n/sk/src/lib/a2a/README.md delete mode 100644 docs/i18n/sv/A2A-SERVER.md delete mode 100644 docs/i18n/sv/API_REFERENCE.md delete mode 100644 docs/i18n/sv/ARCHITECTURE.md delete mode 100644 docs/i18n/sv/AUTO-COMBO.md delete mode 100644 docs/i18n/sv/CLI-TOOLS.md delete mode 100644 docs/i18n/sv/CODEBASE_DOCUMENTATION.md create mode 100644 docs/i18n/sv/CONTRIBUTING.md delete mode 100644 docs/i18n/sv/FEATURES.md delete mode 100644 docs/i18n/sv/MCP-SERVER.md delete mode 100644 docs/i18n/sv/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/sv/SECURITY.md delete mode 100644 docs/i18n/sv/TROUBLESHOOTING.md delete mode 100644 docs/i18n/sv/VM_DEPLOYMENT_GUIDE.md create mode 100644 docs/i18n/sv/docs/A2A-SERVER.md create mode 100644 docs/i18n/sv/docs/API_REFERENCE.md create mode 100644 docs/i18n/sv/docs/ARCHITECTURE.md create mode 100644 docs/i18n/sv/docs/AUTO-COMBO.md rename docs/i18n/{da => sv/docs}/CLI-TOOLS.md (66%) create mode 100644 docs/i18n/sv/docs/CODEBASE_DOCUMENTATION.md create mode 100644 docs/i18n/sv/docs/COVERAGE_PLAN.md create mode 100644 docs/i18n/sv/docs/MCP-SERVER.md create mode 100644 docs/i18n/sv/docs/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/sv/docs/TROUBLESHOOTING.md rename docs/i18n/sv/{ => docs}/USER_GUIDE.md (82%) create mode 100644 docs/i18n/sv/docs/VM_DEPLOYMENT_GUIDE.md create mode 100644 docs/i18n/sv/src/lib/a2a/README.md delete mode 100644 docs/i18n/th/A2A-SERVER.md delete mode 100644 docs/i18n/th/API_REFERENCE.md delete mode 100644 docs/i18n/th/ARCHITECTURE.md delete mode 100644 docs/i18n/th/AUTO-COMBO.md delete mode 100644 docs/i18n/th/CLI-TOOLS.md delete mode 100644 docs/i18n/th/CODEBASE_DOCUMENTATION.md create mode 100644 docs/i18n/th/CONTRIBUTING.md delete mode 100644 docs/i18n/th/FEATURES.md delete mode 100644 docs/i18n/th/MCP-SERVER.md delete mode 100644 docs/i18n/th/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/th/SECURITY.md delete mode 100644 docs/i18n/th/TROUBLESHOOTING.md delete mode 100644 docs/i18n/th/VM_DEPLOYMENT_GUIDE.md create mode 100644 docs/i18n/th/docs/A2A-SERVER.md create mode 100644 docs/i18n/th/docs/API_REFERENCE.md create mode 100644 docs/i18n/th/docs/ARCHITECTURE.md create mode 100644 docs/i18n/th/docs/AUTO-COMBO.md create mode 100644 docs/i18n/th/docs/CLI-TOOLS.md create mode 100644 docs/i18n/th/docs/CODEBASE_DOCUMENTATION.md create mode 100644 docs/i18n/th/docs/COVERAGE_PLAN.md create mode 100644 docs/i18n/th/docs/MCP-SERVER.md create mode 100644 docs/i18n/th/docs/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/th/docs/TROUBLESHOOTING.md rename docs/i18n/th/{ => docs}/USER_GUIDE.md (82%) create mode 100644 docs/i18n/th/docs/VM_DEPLOYMENT_GUIDE.md create mode 100644 docs/i18n/th/src/lib/a2a/README.md delete mode 100644 docs/i18n/uk-UA/A2A-SERVER.md delete mode 100644 docs/i18n/uk-UA/API_REFERENCE.md delete mode 100644 docs/i18n/uk-UA/ARCHITECTURE.md delete mode 100644 docs/i18n/uk-UA/AUTO-COMBO.md delete mode 100644 docs/i18n/uk-UA/CLI-TOOLS.md delete mode 100644 docs/i18n/uk-UA/CODEBASE_DOCUMENTATION.md create mode 100644 docs/i18n/uk-UA/CONTRIBUTING.md delete mode 100644 docs/i18n/uk-UA/FEATURES.md delete mode 100644 docs/i18n/uk-UA/MCP-SERVER.md delete mode 100644 docs/i18n/uk-UA/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/uk-UA/SECURITY.md delete mode 100644 docs/i18n/uk-UA/TROUBLESHOOTING.md delete mode 100644 docs/i18n/uk-UA/VM_DEPLOYMENT_GUIDE.md create mode 100644 docs/i18n/uk-UA/docs/A2A-SERVER.md create mode 100644 docs/i18n/uk-UA/docs/API_REFERENCE.md create mode 100644 docs/i18n/uk-UA/docs/ARCHITECTURE.md create mode 100644 docs/i18n/uk-UA/docs/AUTO-COMBO.md create mode 100644 docs/i18n/uk-UA/docs/CLI-TOOLS.md create mode 100644 docs/i18n/uk-UA/docs/CODEBASE_DOCUMENTATION.md create mode 100644 docs/i18n/uk-UA/docs/COVERAGE_PLAN.md create mode 100644 docs/i18n/uk-UA/docs/MCP-SERVER.md create mode 100644 docs/i18n/uk-UA/docs/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/uk-UA/docs/TROUBLESHOOTING.md rename docs/i18n/uk-UA/{ => docs}/USER_GUIDE.md (82%) create mode 100644 docs/i18n/uk-UA/docs/VM_DEPLOYMENT_GUIDE.md create mode 100644 docs/i18n/uk-UA/src/lib/a2a/README.md delete mode 100644 docs/i18n/vi/A2A-SERVER.md delete mode 100644 docs/i18n/vi/API_REFERENCE.md delete mode 100644 docs/i18n/vi/ARCHITECTURE.md delete mode 100644 docs/i18n/vi/AUTO-COMBO.md delete mode 100644 docs/i18n/vi/CLI-TOOLS.md delete mode 100644 docs/i18n/vi/CODEBASE_DOCUMENTATION.md create mode 100644 docs/i18n/vi/CONTRIBUTING.md delete mode 100644 docs/i18n/vi/FEATURES.md delete mode 100644 docs/i18n/vi/MCP-SERVER.md delete mode 100644 docs/i18n/vi/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/vi/SECURITY.md delete mode 100644 docs/i18n/vi/TROUBLESHOOTING.md delete mode 100644 docs/i18n/vi/VM_DEPLOYMENT_GUIDE.md create mode 100644 docs/i18n/vi/docs/A2A-SERVER.md create mode 100644 docs/i18n/vi/docs/API_REFERENCE.md create mode 100644 docs/i18n/vi/docs/ARCHITECTURE.md create mode 100644 docs/i18n/vi/docs/AUTO-COMBO.md create mode 100644 docs/i18n/vi/docs/CLI-TOOLS.md create mode 100644 docs/i18n/vi/docs/CODEBASE_DOCUMENTATION.md create mode 100644 docs/i18n/vi/docs/COVERAGE_PLAN.md create mode 100644 docs/i18n/vi/docs/MCP-SERVER.md create mode 100644 docs/i18n/vi/docs/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/vi/docs/TROUBLESHOOTING.md rename docs/i18n/vi/{ => docs}/USER_GUIDE.md (82%) create mode 100644 docs/i18n/vi/docs/VM_DEPLOYMENT_GUIDE.md create mode 100644 docs/i18n/vi/src/lib/a2a/README.md delete mode 100644 docs/i18n/zh-CN/A2A-SERVER.md delete mode 100644 docs/i18n/zh-CN/API_REFERENCE.md delete mode 100644 docs/i18n/zh-CN/ARCHITECTURE.md delete mode 100644 docs/i18n/zh-CN/AUTO-COMBO.md delete mode 100644 docs/i18n/zh-CN/CLI-TOOLS.md delete mode 100644 docs/i18n/zh-CN/CODEBASE_DOCUMENTATION.md create mode 100644 docs/i18n/zh-CN/CONTRIBUTING.md delete mode 100644 docs/i18n/zh-CN/FEATURES.md delete mode 100644 docs/i18n/zh-CN/MCP-SERVER.md delete mode 100644 docs/i18n/zh-CN/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/zh-CN/SECURITY.md delete mode 100644 docs/i18n/zh-CN/TROUBLESHOOTING.md delete mode 100644 docs/i18n/zh-CN/USER_GUIDE.md delete mode 100644 docs/i18n/zh-CN/VM_DEPLOYMENT_GUIDE.md create mode 100644 docs/i18n/zh-CN/docs/A2A-SERVER.md create mode 100644 docs/i18n/zh-CN/docs/API_REFERENCE.md create mode 100644 docs/i18n/zh-CN/docs/ARCHITECTURE.md create mode 100644 docs/i18n/zh-CN/docs/AUTO-COMBO.md create mode 100644 docs/i18n/zh-CN/docs/CLI-TOOLS.md create mode 100644 docs/i18n/zh-CN/docs/CODEBASE_DOCUMENTATION.md create mode 100644 docs/i18n/zh-CN/docs/COVERAGE_PLAN.md create mode 100644 docs/i18n/zh-CN/docs/MCP-SERVER.md create mode 100644 docs/i18n/zh-CN/docs/RELEASE_CHECKLIST.md create mode 100644 docs/i18n/zh-CN/docs/TROUBLESHOOTING.md create mode 100644 docs/i18n/zh-CN/docs/USER_GUIDE.md create mode 100644 docs/i18n/zh-CN/docs/VM_DEPLOYMENT_GUIDE.md create mode 100644 docs/i18n/zh-CN/src/lib/a2a/README.md delete mode 100644 typescript diff --git a/.agents/workflows/update-docs.md b/.agents/workflows/update-docs.md deleted file mode 100644 index ab3bd26a2d..0000000000 --- a/.agents/workflows/update-docs.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -description: How to automatically summarize recent changes and update README and CHANGELOG ---- - -# Update Documentation Workflow - -Update CHANGELOG.md, README.md, docs/ files, and all multi-language translations whenever features are added or changed. - -## Steps - -### 1. Summarize recent changes - -Review git log and identify new features, fixes, or changes since the last release tag: - -```bash -git log $(git describe --tags --abbrev=0)..HEAD --oneline -``` - -### 2. Update English CHANGELOG.md - -Add an `[Unreleased]` section (or version header if releasing) with: - -- `### โœจ New Features` โ€” each feature as a bullet point -- `### ๐Ÿ› Bug Fixes` โ€” if applicable -- `### ๐Ÿงช Tests` โ€” test count changes -- `### ๐Ÿ“ New Files` โ€” table of new files with purpose - -### 3. Update English README.md - -Update the feature tables in these sections: - -- **๐Ÿง  Routing & Intelligence** โ€” for routing/model features -- **๐Ÿ›ก๏ธ Resilience & Security** โ€” for security/resilience features -- **๐Ÿ“Š Observability & Analytics** โ€” for monitoring features -- **โ˜๏ธ Deploy & Sync** โ€” for deployment features - -### 4. Update docs/ files - -- `docs/FEATURES.md` โ€” update the Settings section description -- `docs/API_REFERENCE.md` โ€” add new API routes if any -- `docs/ARCHITECTURE.md` โ€” update architecture if structural changes - -### 5. ๐ŸŒ Sync Multi-Language Documentation (CRITICAL) - -// turbo-all - -**This step MUST be run after every README or docs update.** - -The project has **30 language versions** of documentation: - -**README files (root directory):** - -``` -README.md (English - source of truth) -README.pt-BR.md README.pt.md README.es.md README.fr.md README.it.md -README.de.md README.nl.md README.sv.md README.no.md README.da.md README.fi.md -README.ru.md README.uk-UA.md README.bg.md README.sk.md README.pl.md README.ro.md README.hu.md -README.ar.md README.he.md README.th.md README.in.md README.id.md README.ms.md README.vi.md -README.ja.md README.ko.md README.zh-CN.md README.phi.md README.cs.md -``` - -**docs/i18n/ directories (29 languages):** - -``` -docs/i18n/{ar,bg,cs,da,de,es,fi,fr,he,hu,id,in,it,ja,ko,ms,nl,no,phi,pl,pt,pt-BR,ro,ru,sk,sv,th,uk-UA,vi,zh-CN}/ -Each contains: API_REFERENCE.md, ARCHITECTURE.md, CODEBASE_DOCUMENTATION.md, FEATURES.md, TROUBLESHOOTING.md, USER_GUIDE.md -``` - -**Sync approach for feature table updates:** - -a. Identify which feature table rows were added to English README.md -b. For each translated README, find the corresponding anchor lines: - -- **Routing section:** Find the `๐Ÿ’ฌ` (System Prompt) table row โ€” the line before it is always the last routing feature. Insert new routing features before System Prompt. -- **Resilience section:** Find the `๐Ÿ“Š` Rate Limits table row (the one in lines 590-600, NOT the quota tracking one in lines 560-570). Insert new resilience features after it. - c. The new feature entries can stay in English for technical features, matching the pattern used in the existing translations. - d. Use `sed` or similar tool to batch-insert across all 29 translated READMEs. - -**Verification:** - -```bash -# Verify all READMEs have the new features -grep -l "NEW_FEATURE_NAME" README.*.md | wc -l -# Should return 30 (all language versions) -``` - -**FEATURES.md sync:** - -```bash -# Update Settings description in all docs/i18n/*/FEATURES.md -for dir in docs/i18n/*/; do - # Update the Settings section description to mention new features - # Check FEATURES.md in each directory -done -``` - -### 6. Verify documentation changes - -```bash -# Check all modified files -git status --short - -# Verify no broken markdown -# Optional: run markdownlint if available -``` diff --git a/docs/adr/0001-proxy-registry-limit-generalization.md b/docs/adr/0001-proxy-registry-limit-generalization.md deleted file mode 100644 index bb7d766e14..0000000000 --- a/docs/adr/0001-proxy-registry-limit-generalization.md +++ /dev/null @@ -1,46 +0,0 @@ -# ADR-0001: Proxy Registry + Usage Control Generalization - -Date: 2026-03-17 -Status: Accepted - -## Context - -OmniRoute sudah punya: - -- Proxy assignment berbasis config-map (`global`, `providers`, `combos`, `keys`). -- Quota-aware selection khusus provider tertentu (notably `codex`). - -Gap utama: - -- Proxy belum menjadi aset reusable yang bisa di-manage sebagai entitas (metadata, where-used, safe delete). -- Usage policy belum konsisten lintas provider. -- Error contract API belum seragam untuk endpoint manajemen. - -## Decision - -1. Tambah **Proxy Registry** sebagai domain baru di DB (`proxy_registry`, `proxy_assignments`). -2. Pertahankan kompatibilitas assignment lama (fallback ke `proxyConfig` lama). -3. Resolver runtime pakai prioritas: - - account -> provider -> global (registry) - - fallback ke legacy resolver jika registry belum ada assignment -4. Wajib redaction kredensial di output list registry default. -5. Standarkan error JSON untuk endpoint manajemen proxy agar konsisten dan punya `requestId`. - -## Consequences - -Positif: - -- Proxy reusable dan bisa dilacak pemakaiannya. -- Safe delete bisa ditegakkan (409 saat masih dipakai). -- Migrasi bertahap tanpa breaking change runtime. - -Negatif: - -- Ada dual-source sementara (registry + legacy config) sampai migrasi selesai. -- Butuh endpoint assignment tambahan dan pemetaan scope yang konsisten. - -## Follow-up - -- Migrasi UI provider/account dari input raw proxy ke selector registry. -- Tambah health telemetry per proxy dan alerting. -- Generalisasi usage control ke provider lain melalui interface policy yang sama. diff --git a/docs/adr/0002-api-error-contract-management-endpoints.md b/docs/adr/0002-api-error-contract-management-endpoints.md deleted file mode 100644 index fced830c61..0000000000 --- a/docs/adr/0002-api-error-contract-management-endpoints.md +++ /dev/null @@ -1,32 +0,0 @@ -# ADR-0002: Error Contract for Management Endpoints - -Date: 2026-03-17 -Status: Accepted - -## Decision - -Management endpoints (proxy config, proxy registry, and proxy assignments) return a uniform error body: - -```json -{ - "error": { - "message": "Human-readable summary", - "type": "invalid_request | not_found | conflict | server_error", - "details": {} - }, - "requestId": "uuid" -} -``` - -## Status Mapping - -- 400: invalid request / validation failure -- 404: resource not found -- 409: resource conflict (for example, proxy still assigned) -- 500: unexpected server error - -## Notes - -- `requestId` is mandatory for log correlation. -- `details` is optional and only used for safe validation details. -- Sensitive secrets (proxy credentials, tokens) must never appear in `message` or `details`. diff --git a/docs/adr/0003-security-checklist-proxy-limits.md b/docs/adr/0003-security-checklist-proxy-limits.md deleted file mode 100644 index 5ff89da6a0..0000000000 --- a/docs/adr/0003-security-checklist-proxy-limits.md +++ /dev/null @@ -1,16 +0,0 @@ -# ADR-0003: Security Checklist for Proxy Registry and Usage Controls - -Date: 2026-03-17 -Status: Accepted - -## Checklist - -- Validate all management payloads with Zod. -- Reject malformed scope assignment updates with status 400. -- Reject deleting an in-use proxy with status 409 unless forced. -- Never expose proxy username/password in list responses by default. -- Never log raw credentials or token values. -- Keep error responses free from internal stack traces. -- Protect management endpoints with existing auth middleware policy. -- Audit mutating operations: create/update/delete/assign/migrate. -- Ensure resolver fallback to legacy config while migration is in transition. diff --git a/docs/i18n/README.md b/docs/i18n/README.md index bb250f5ee4..8c8a0369bd 100644 --- a/docs/i18n/README.md +++ b/docs/i18n/README.md @@ -33,3 +33,4 @@ Translations of documentation into 30 languages. Code blocks remain in English. - ๐Ÿ‡ฎ๐Ÿ‡ฑ **ืขื‘ืจื™ืช** (`he`): [Docs Root](./he/README.md) - ๐Ÿ‡ต๐Ÿ‡ญ **Filipino** (`phi`): [Docs Root](./phi/README.md) - ๐Ÿ‡ง๐Ÿ‡ท **Portuguรชs (Brasil)** (`pt-BR`): [Docs Root](./pt-BR/README.md) +- ๐Ÿ‡จ๐Ÿ‡ฟ **ฤŒeลกtina** (`cs`): [Docs Root](./cs/README.md) diff --git a/docs/i18n/ar/CHANGELOG.md b/docs/i18n/ar/CHANGELOG.md index 15b3637d59..1cba534503 100644 --- a/docs/i18n/ar/CHANGELOG.md +++ b/docs/i18n/ar/CHANGELOG.md @@ -1,12 +1,92 @@ # Changelog (ุงู„ุนุฑุจูŠุฉ) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CHANGELOG.md) --- - ## [Unreleased] +### ๐Ÿ› ๏ธ Maintenance + +- **AGENTS.md rewrite:** Condensed from 297โ†’153 lines. Added build/lint/test commands (including single-test execution), code style guidelines (Prettier, TypeScript, ESLint, naming, imports, error handling, security), and trimmed verbose architecture tables for AI agent consumption. + +## [3.4.2] - 2026-04-01 + +### ๐Ÿ› Bug Fixes + +- **CI Stabilization:** Fixed failing analytics/settings Playwright selectors and request assertions so GitHub Actions E2E runs pass reliably across localized UIs and switch-based controls. +- **Deterministic Tests:** Removed date-sensitive quota fixtures from Copilot usage tests and aligned idempotency/model catalog tests with the merged runtime behavior. +- **MCP Type Hardening:** Removed zero-budget explicit `any` regressions from the MCP server tool registration path, restoring the `check:any-budget:t11` workflow gate. + +### ๐Ÿ› ๏ธ Maintenance + +- **Release Branch Integration:** Consolidated the active feature branches into `release/v3.4.2` on top of current `main` and validated the branch with lint, unit, coverage, build, and CI-mode E2E runs. + +## [3.4.1] - 2026-03-31 + +> [!WARNING] +> **BREAKING CHANGE: request logging, retention, and logging environment variables have been redesigned.** +> On the first startup after upgrading, OmniRoute archives legacy request logs from `DATA_DIR/logs/`, legacy `DATA_DIR/call_logs/`, and `DATA_DIR/log.txt` into `DATA_DIR/log_archives/*.zip`, then removes the deprecated layout and switches to the new unified artifact format under `DATA_DIR/call_logs/`. + +### โœจ New Features + +- **.ENV Migration Utility:** Included `scripts/migrate-env.mjs` to seamlessly migrate `= 18 < 24 (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` | `20128` | Server port | +| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | Base URL for frontend | +| `JWT_SECRET` | (generate above) | JWT signing secret | +| `INITIAL_PASSWORD` | `CHANGEME` | First login password | +| `APP_LOG_LEVEL` | `info` | Log verbosity level | + +### Dashboard Settings + +The dashboard provides UI toggles for features that can also be configured via environment variables: + +| Setting Location | Toggle | Description | +| ------------------- | ------------------ | ------------------------------ | +| Settings โ†’ Advanced | Debug Mode | Enable debug request logs (UI) | +| Settings โ†’ General | Sidebar Visibility | Show/hide sidebar sections | + +These settings are stored in the database and persist across restarts, overriding env var defaults when set. + +### 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:20128/dashboard` +- **API**: `http://localhost:20128/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`, `mcp`, `a2a`, `memory`, `skills`. + +--- + +## Running Tests + +```bash +# All tests (unit + vitest + ecosystem + e2e) +npm run test:all + +# Single test file (Node.js native test runner โ€” most tests use this) +node --import tsx/esm --test tests/unit/your-file.test.mjs + +# Vitest (MCP server, autoCombo, cache) +npm run test:vitest + +# E2E tests (requires Playwright) +npm run test:e2e + +# Protocol clients E2E (MCP transports, A2A) +npm run test:protocols:e2e + +# Ecosystem compatibility tests +npm run test:ecosystem + +# Coverage (55% min statements/lines/functions; 60% branches) +npm run test:coverage +npm run coverage:report + +# Lint + format check +npm run lint +npm run check +``` + +Coverage notes: + +- `npm run test:coverage` measures source coverage for the main unit test suite, excludes `tests/**`, and includes `open-sse/**` +- `npm run coverage:report` prints the detailed file-by-file report from the latest coverage run +- `npm run test:coverage:legacy` preserves the older metric for historical comparison +- See `docs/COVERAGE_PLAN.md` for the phased coverage improvement roadmap + +Current test status: **122 unit test files** covering: + +- Provider translators and format conversion +- Rate limiting, circuit breaker, and resilience +- Semantic cache, idempotency, progress tracking +- Database operations and schema (21 DB modules) +- OAuth flows and authentication +- API endpoint validation (Zod v4) +- MCP server tools and scope enforcement +- Memory and Skills systems + +--- + +## Code Style + +- **ESLint** โ€” Run `npm run lint` before committing +- **Prettier** โ€” Auto-formatted via `lint-staged` on commit (2 spaces, semicolons, double quotes, 100 char width, es5 trailing commas) +- **TypeScript** โ€” All `src/` code uses `.ts`/`.tsx`; `open-sse/` uses `.ts`/`.js`; document with TSDoc (`@param`, `@returns`, `@throws`) +- **No `eval()`** โ€” ESLint enforces `no-eval`, `no-implied-eval`, `no-new-func` +- **Zod validation** โ€” Use Zod v4 schemas for all API input validation +- **Naming**: Files = camelCase/kebab-case, components = PascalCase, constants = UPPER_SNAKE + +--- + +## Project Structure + +``` +src/ # TypeScript (.ts / .tsx) +โ”œโ”€โ”€ app/ # Next.js 16 App Router +โ”‚ โ”œโ”€โ”€ (dashboard)/ # Dashboard pages (23 sections) +โ”‚ โ”œโ”€โ”€ api/ # API routes (51 directories) +โ”‚ โ””โ”€โ”€ login/ # Auth pages (.tsx) +โ”œโ”€โ”€ domain/ # Policy engine (policyEngine, comboResolver, costRules, etc.) +โ”œโ”€โ”€ lib/ # Core business logic (.ts) +โ”‚ โ”œโ”€โ”€ a2a/ # Agent-to-Agent v0.3 protocol server +โ”‚ โ”œโ”€โ”€ acp/ # Agent Communication Protocol registry +โ”‚ โ”œโ”€โ”€ compliance/ # Compliance policy engine +โ”‚ โ”œโ”€โ”€ db/ # SQLite database layer (21 modules + 16 migrations) +โ”‚ โ”œโ”€โ”€ memory/ # Persistent conversational memory +โ”‚ โ”œโ”€โ”€ oauth/ # OAuth providers, services, and utilities +โ”‚ โ”œโ”€โ”€ skills/ # Extensible skill framework +โ”‚ โ”œโ”€โ”€ usage/ # Usage tracking and cost calculation +โ”‚ โ””โ”€โ”€ localDb.ts # Re-export layer only โ€” never add logic here +โ”œโ”€โ”€ middleware/ # Request middleware (promptInjectionGuard) +โ”œโ”€โ”€ mitm/ # MITM proxy (cert, DNS, target routing) +โ”œโ”€โ”€ shared/ +โ”‚ โ”œโ”€โ”€ components/ # React components (.tsx) +โ”‚ โ”œโ”€โ”€ constants/ # Provider definitions (60+), MCP scopes, routing strategies +โ”‚ โ”œโ”€โ”€ utils/ # Circuit breaker, sanitizer, auth helpers +โ”‚ โ””โ”€โ”€ validation/ # Zod v4 schemas +โ””โ”€โ”€ sse/ # SSE proxy pipeline + +open-sse/ # @omniroute/open-sse workspace +โ”œโ”€โ”€ executors/ # 14 provider-specific request executors +โ”œโ”€โ”€ handlers/ # 11 request handlers (chat, responses, embeddings, images, etc.) +โ”œโ”€โ”€ mcp-server/ # MCP server (25 tools, 3 transports, 10 scopes) +โ”œโ”€โ”€ services/ # 36+ services (combo, autoCombo, rateLimitManager, etc.) +โ”œโ”€โ”€ translator/ # Format translators (OpenAI โ†” Claude โ†” Gemini โ†” Responses โ†” Ollama) +โ”œโ”€โ”€ transformer/ # Responses API transformer +โ””โ”€โ”€ utils/ # 22 utility modules (stream, TLS, proxy, logging) + +electron/ # Electron desktop app (cross-platform) + +tests/ +โ”œโ”€โ”€ unit/ # Node.js test runner (122 test files) +โ”œโ”€โ”€ integration/ # Integration tests +โ”œโ”€โ”€ e2e/ # Playwright tests +โ”œโ”€โ”€ security/ # Security tests +โ”œโ”€โ”€ translator/ # Translator-specific tests +โ””โ”€โ”€ load/ # Load tests + +docs/ # Documentation +โ”œโ”€โ”€ ARCHITECTURE.md # System architecture +โ”œโ”€โ”€ API_REFERENCE.md # All endpoints +โ”œโ”€โ”€ USER_GUIDE.md # Provider setup, CLI integration +โ”œโ”€โ”€ TROUBLESHOOTING.md # Common issues +โ”œโ”€โ”€ MCP-SERVER.md # MCP server (25 tools) +โ”œโ”€โ”€ A2A-SERVER.md # A2A agent protocol +โ”œโ”€โ”€ AUTO-COMBO.md # Auto-combo engine +โ”œโ”€โ”€ CLI-TOOLS.md # CLI tools integration +โ”œโ”€โ”€ COVERAGE_PLAN.md # Test coverage improvement plan +โ”œโ”€โ”€ openapi.yaml # OpenAPI specification +โ””โ”€โ”€ adr/ # Architecture Decision Records +``` + +--- + +## Adding a New Provider + +### Step 1: Register Provider Constants + +Add to `src/shared/constants/providers.ts` โ€” Zod-validated at module load. + +### Step 2: Add Executor (if custom logic needed) + +Create executor in `open-sse/executors/your-provider.ts` extending the base executor. + +### Step 3: Add Translator (if non-OpenAI format) + +Create request/response translators in `open-sse/translator/`. + +### Step 4: Add OAuth Config (if OAuth-based) + +Add OAuth credentials in `src/lib/oauth/constants/oauth.ts` and service in `src/lib/oauth/services/`. + +### Step 5: Register Models + +Add model definitions in `open-sse/config/providerRegistry.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 +- [ ] All inputs validated with Zod schemas +- [ ] CHANGELOG updated (if user-facing change) +- [ ] Documentation updated (if applicable) + +--- + +## Releasing + +Releases are managed via the `/generate-release` workflow. When a new GitHub Release is created, the package is **automatically published to npm** via GitHub Actions. + +--- + +## Getting Help + +- **Architecture**: See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) +- **API Reference**: See [`docs/API_REFERENCE.md`](docs/API_REFERENCE.md) +- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **ADRs**: See `docs/adr/` for architectural decision records diff --git a/docs/i18n/ar/FEATURES.md b/docs/i18n/ar/FEATURES.md deleted file mode 100644 index 020be4ff72..0000000000 --- a/docs/i18n/ar/FEATURES.md +++ /dev/null @@ -1,147 +0,0 @@ -# OmniRoute โ€” Dashboard Features Gallery (ุงู„ุนุฑุจูŠุฉ) - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) - -> ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../docs/FEATURES.md) - ---- - -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 (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. - -![Providers Dashboard](screenshots/01-providers.png) - ---- - -## ๐ŸŽจ Combos - -Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. - -![Combos Dashboard](screenshots/02-combos.png) - ---- - -## ๐Ÿ“Š Analytics - -Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. - -![Analytics Dashboard](screenshots/03-analytics.png) - ---- - -## ๐Ÿฅ System Health - -Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. - -![Health Dashboard](screenshots/04-health.png) - ---- - -## ๐Ÿ”ง Translator Playground - -Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). - -![Translator Playground](screenshots/05-translator.png) - ---- - -## ๐ŸŽฎ Model Playground _(v2.0.9+)_ - -Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. - ---- - -## ๐ŸŽจ Themes _(v2.0.5+)_ - -Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. - ---- - -## โš™๏ธ Settings - -Comprehensive settings panel with tabs: - -- **General** โ€” System storage, backup management (export/import database) -- **Appearance** โ€” Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls -- **Security** โ€” API endpoint protection, custom provider blocking, IP filtering, session info -- **Routing** โ€” Model aliases, background task degradation -- **Resilience** โ€” Rate limit persistence, circuit breaker tuning -- **Advanced** โ€” Configuration overrides - -![Settings Dashboard](screenshots/06-settings.png) - ---- - -## ๐Ÿ”ง CLI Tools - -One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. - -![CLI Tools Dashboard](screenshots/07-cli-tools.png) - ---- - -## ๐Ÿค– CLI Agents _(v2.0.11+)_ - -Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: - -- **Installation status** โ€” Installed / Not Found with version detection -- **Protocol badges** โ€” stdio, HTTP, etc. -- **Custom agents** โ€” Register any CLI tool via form (name, binary, version command, spawn args) -- **CLI Fingerprint Matching** โ€” Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP - ---- - -## ๐Ÿ–ผ๏ธ Media _(v2.0.3+)_ - -Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. - ---- - -## ๐Ÿ“ Request Logs - -Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. - -![Usage Logs](screenshots/08-usage.png) - ---- - -## ๐ŸŒ API Endpoint - -Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. - -![Endpoint Dashboard](screenshots/09-endpoint.png) - ---- - -## ๐Ÿ”‘ API Key Management - -Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. - ---- - -## ๐Ÿ“‹ Audit Log - -Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. - ---- - -## ๐Ÿ–ฅ๏ธ Desktop Application - -Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. - -Key features: - -- Server readiness polling (no blank screen on cold start) -- System tray with port management -- Content Security Policy -- Single-instance lock -- Auto-update on restart -- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) -- Hardened Electron build packaging โ€” symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+) - -๐Ÿ“– See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/ar/README.md b/docs/i18n/ar/README.md index 8ca74e0201..12773d778f 100644 --- a/docs/i18n/ar/README.md +++ b/docs/i18n/ar/README.md @@ -1,12 +1,12 @@ # ๐Ÿš€ OmniRoute โ€” The Free AI Gateway (ุงู„ุนุฑุจูŠุฉ) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/README.md) --- ### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback. -_Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._ +_Your universal API proxy โ€” one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._ **Chat Completions โ€ข Embeddings โ€ข Image Generation โ€ข Video โ€ข Music โ€ข Audio โ€ข Reranking โ€ข **Web Search** โ€ข MCP Server โ€ข A2A Protocol โ€ข 100% TypeScript** @@ -46,15 +46,17 @@ _Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now wi > - `APP_LOG_FILE_PATH` > - `APP_LOG_MAX_FILE_SIZE` > - `APP_LOG_RETENTION_DAYS` +> - `APP_LOG_MAX_FILES` > - `APP_LOG_LEVEL` > - `APP_LOG_FORMAT` > - `CALL_LOG_RETENTION_DAYS` +> - `CALL_LOG_MAX_ENTRIES` > > For release details and upgrade notes, see the [CHANGELOG](CHANGELOG.md). --- -## ๐Ÿ†• What's New in v3.0.0 +## ๐Ÿ†• What's New > **Upgrading from v2.9.5?** โ€” See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes. @@ -274,7 +276,7 @@ Developers pay $20โ€“200/month for Claude Pro, Codex Pro, or GitHub Copilot. Eve - **Smart 4-Tier Fallback** โ€” If subscription quota runs out, automatically redirects to API Key โ†’ Cheap โ†’ Free with zero manual intervention - **Real-Time Quota Tracking** โ€” Shows token consumption in real-time with reset countdown (5h, daily, weekly) - **Multi-Account Support** โ€” Multiple accounts per provider with auto round-robin โ€” when one runs out, switches to the next -- **Custom Combos** โ€” Customizable fallback chains with 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Custom Combos** โ€” Customizable fallback chains with 9 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random) - **Codex Business Quotas** โ€” Business/Team workspace quota monitoring directly in the dashboard @@ -286,7 +288,7 @@ OpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If **How OmniRoute solves it:** -- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 67+ providers +- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 60+ providers - **Format Translation** โ€” Automatic and transparent: OpenAI โ†” Claude โ†” Gemini โ†” Responses API - **Response Sanitization** โ€” Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+ - **Role Normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI providers; `system` โ†’ `user` for GLM/ERNIE @@ -372,7 +374,7 @@ Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code.. - **CLI Tools Dashboard** โ€” Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline - **GitHub Copilot Config Generator** โ€” Generates `chatLanguageModels.json` for VS Code with bulk model selection - **Onboarding Wizard** โ€” Guided 4-step setup for first-time users -- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 67+ providers +- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 60+ providers @@ -419,7 +421,7 @@ When a call fails, the dev doesn't know if it was a rate limit, expired token, w - **SQLite Proxy Logs** โ€” Persistent logs that survive server restarts - **Translator Playground** โ€” 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time) - **Request Telemetry** โ€” p50/p95/p99 latency + X-Request-Id tracing -- **File-Based Logging with Rotation** โ€” Console interceptor captures everything to JSON log with size-based rotation +- **File-Based Logging with Rotation** โ€” App logs rotate by size, retention days, and archive count; call log artifacts rotate by retention days and file count - **System Info Report** โ€” `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage. @@ -514,7 +516,7 @@ Developers who want all responses in a specific language, with a specific tone, - **System Prompt Injection** โ€” Global prompt applied to all requests - **Thinking Budget Validation** โ€” Reasoning token allocation control per request (passthrough, auto, custom, adaptive) -- **6 Routing Strategies** โ€” Global strategies that determine how requests are distributed +- **9 Routing Strategies** โ€” Global strategies that determine how requests are distributed - **Wildcard Router** โ€” `provider/*` patterns route dynamically to any provider - **Combo Enable/Disable Toggle** โ€” Toggle combos directly from the dashboard - **Provider Toggle** โ€” Enable/disable all connections for a provider with one click @@ -581,7 +583,7 @@ Different clients should have least-privilege access to tool categories. **How OmniRoute solves it:** -- 9 granular MCP scopes for controlled tool access +- 10 granular MCP scopes for controlled tool access - Scope enforcement and visibility in MCP management UI - Safe default posture for operational tooling @@ -1325,19 +1327,19 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. ### ๐Ÿค– Agent & Protocol Operations (v2.0) -| Feature | What It Does | -| ------------------------------------- | -------------------------------------------------------------------------------------------------- | -| ๐Ÿ”ง **MCP Server (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) | -| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | -| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | -| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | -| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | -| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | -| ๐Ÿ” **MCP Scope Enforcement** | 9 granular scope permissions for controlled tool access | -| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | -| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | -| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | -| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | +| Feature | What It Does | +| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| ๐Ÿ”ง **MCP Server (25 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools | +| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | +| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | +| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | +| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | +| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | +| ๐Ÿ” **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access | +| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | +| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | +| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | +| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | ### ๐Ÿง  Routing & Intelligence @@ -1348,7 +1350,7 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. | ๐Ÿ”„ **Format Translation** | OpenAI โ†” Claude โ†” Gemini โ†” Responses with schema-safe conversions | | ๐Ÿ‘ฅ **Multi-Account Support** | Multiple accounts per provider with intelligent selection | | ๐Ÿ”„ **Auto Token Refresh** | OAuth tokens refresh automatically with retry | -| ๐ŸŽจ **Custom Combos** | 6 balancing strategies + fallback chain control | +| ๐ŸŽจ **Custom Combos** | 9 balancing strategies + fallback chain control | | ๐ŸŒ **Wildcard Router** | `provider/*` dynamic routing | | ๐Ÿง  **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits | | ๐Ÿ”€ **Model Aliases** | Built-in + custom model aliasing and migration safety | @@ -1949,6 +1951,7 @@ opencode - Request artifacts are written to `DATA_DIR/call_logs/` as one JSON file per request - Enable pipeline capture from Dashboard โ†’ Logs โ†’ Request Logs if you need detailed per-stage payloads - Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log` +- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed **Connection test shows "Invalid" for OpenAI-compatible providers** diff --git a/docs/i18n/ar/RELEASE_CHECKLIST.md b/docs/i18n/ar/RELEASE_CHECKLIST.md deleted file mode 100644 index 903e812c3f..0000000000 --- a/docs/i18n/ar/RELEASE_CHECKLIST.md +++ /dev/null @@ -1,37 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/RELEASE_CHECKLIST.md) - ---- - -# Release Checklist - -Use this checklist before tagging or publishing a new OmniRoute release. - -## Version and Changelog - -1. Bump `package.json` version (`x.y.z`) in the release branch. -2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: - - `## [x.y.z] โ€” YYYY-MM-DD` -3. Keep `## [Unreleased]` as the first changelog section for upcoming work. -4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. - -## API Docs - -1. Update `docs/openapi.yaml`: - - `info.version` must equal `package.json` version. -2. Validate endpoint examples if API contracts changed. - -## Runtime Docs - -1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. -2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. -3. Update localized docs if source docs changed significantly. - -## Automated Check - -Run the sync guard locally before opening PR: - -```bash -npm run check:docs-sync -``` - -CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/ar/SECURITY.md b/docs/i18n/ar/SECURITY.md new file mode 100644 index 0000000000..bee390b97c --- /dev/null +++ b/docs/i18n/ar/SECURITY.md @@ -0,0 +1,179 @@ +# Security Policy (ุงู„ุนุฑุจูŠุฉ) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../SECURITY.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/SECURITY.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/SECURITY.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/SECURITY.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/SECURITY.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/SECURITY.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/SECURITY.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/SECURITY.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/SECURITY.md) + +--- + +## 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 | +| ------- | -------------- | +| 3.4.x | โœ… Active | +| 3.0.x | โœ… Security | +| < 3.0.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 | +| **MCP Scopes** | 10 granular scopes for MCP tool access control | + +### ๐Ÿ›ก๏ธ 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:::` +- 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** | Allowlist/blocklist IP ranges in dashboard | +| **Rate Limiting** | Per-provider rate limits with automatic backoff | +| **Anti-Thundering Herd** | Mutex + per-connection locking prevents cascading 502s | +| **TLS Fingerprint** | Browser-like TLS fingerprint spoofing to reduce bot detection | +| **CLI Fingerprint** | Per-provider header/body ordering to match native CLI signatures | + +### ๐Ÿ”Œ Resilience & Availability + +| 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 `CALL_LOG_RETENTION_DAYS` | +| **No-Log Opt-out** | Per API key `noLog` flag disables request logging | +| **Audit Log** | Administrative actions tracked in `audit_log` table | +| **MCP Audit** | SQLite-backed audit logging for all MCP tool calls | +| **Zod Validation** | All API inputs validated with Zod v4 schemas at module load | + +--- + +## 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 +- Provider constants validated at module load via Zod (`src/shared/validation/providerSchema.ts`) diff --git a/docs/i18n/ar/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/ar/VM_DEPLOYMENT_GUIDE.md deleted file mode 100644 index c9bd2d844f..0000000000 --- a/docs/i18n/ar/VM_DEPLOYMENT_GUIDE.md +++ /dev/null @@ -1,401 +0,0 @@ -# OmniRoute โ€” ุฏู„ูŠู„ ุงู„ู†ุดุฑ ุนู„ู‰ VM ุจุงุณุชุฎุฏุงู… Cloudflare - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](../pt-BR/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](../es/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](../fr/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](../it/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](../ru/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](../zh-CN/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](../de/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](../in/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](../th/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](../uk-UA/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](../ar/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](../ja/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](../vi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](../bg/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](../da/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](../fi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](../he/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](../hu/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](../id/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](../ko/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](../ms/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](../nl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](../no/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](../pt/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](../ro/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](../pl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](../sk/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](../sv/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](../phi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](../cs/VM_DEPLOYMENT_GUIDE.md) - -ุงู„ุฏู„ูŠู„ ุงู„ูƒุงู…ู„ ู„ุชุซุจูŠุช OmniRoute ูˆุชูƒูˆูŠู†ู‡ ุนู„ู‰ VM (VPS) ู…ุน ุงู„ู…ุฌุงู„ ุงู„ู…ูุฏุงุฑ ุนุจุฑ Cloudflare. - ---- - -## ุงู„ู…ุชุทู„ุจุงุช ุงู„ุฃุณุงุณูŠุฉ - -| ุงู„ุนู†ุตุฑ | ุงู„ุญุฏ ุงู„ุฃุฏู†ู‰ | ู…ูˆุตู‰ ุจู‡ | -| ---------------------------- | ----------------------------------- | ----------------------------------- | -| ** ูˆุญุฏุฉ ุงู„ู…ุนุงู„ุฌุฉ ุงู„ู…ุฑูƒุฒูŠุฉ ** | 1 ูˆุญุฏุฉ ุงู„ู…ุนุงู„ุฌุฉ ุงู„ู…ุฑูƒุฒูŠุฉ ุงู„ุงูุชุฑุงุถูŠุฉ | 2 ูˆุญุฏุฉ ุงู„ู…ุนุงู„ุฌุฉ ุงู„ู…ุฑูƒุฒูŠุฉ ุงู„ุงูุชุฑุงุถูŠุฉ | -| **ุฐุงูƒุฑุฉ ุงู„ูˆุตูˆู„ ุงู„ุนุดูˆุงุฆูŠ** | 1 ุฌูŠุฌุง | 2 ุฌูŠุฌุง | -| **ุงู„ู‚ุฑุต** | 10 ุฌูŠุฌุง ุงุณ ุงุณ ุฏูŠ | 25 ุฌูŠุฌุง ุงุณ ุงุณ ุฏูŠ | -| **ู†ุธุงู… ุงู„ุชุดุบูŠู„** | ุฃูˆุจูˆู†ุชูˆ 22.04 LTS | ุฃูˆุจูˆู†ุชูˆ 24.04 LTS | -| **ุงู„ู…ุฌุงู„** | ู…ุณุฌู„ ููŠ Cloudflare | โ€” | -| ** ุนุงู…ู„ ุงู„ู…ูŠู†ุงุก ** | ู…ุญุฑูƒ ุฏูˆูƒุฑ 24+ | ุนุงู…ู„ ุงู„ู…ูŠู†ุงุก 27+ | - -**ุงู„ู…ุฒูˆุฏูˆู† ุงู„ุฐูŠู† ุชู… ุงุฎุชุจุงุฑู‡ู…**: Akamai (Linode)ุŒ DigitalOceanุŒ VultrุŒ HetznerุŒ AWS Lightsail. - ---- - -## 1. ู‚ู… ุจุชูƒูˆูŠู† ุงู„ุฌู‡ุงุฒ ุงู„ุงูุชุฑุงุถูŠ - -### 1.1 ุฅู†ุดุงุก ุงู„ู…ุซูŠู„ - -ุนู„ู‰ ู…ูˆูุฑ VPS ุงู„ู…ูุถู„ ู„ุฏูŠูƒ: - -- ุงุฎุชุฑ Ubuntu 24.04 LTS -- ุญุฏุฏ ุงู„ุญุฏ ุงู„ุฃุฏู†ู‰ ู„ู„ุฎุทุฉ (1 vCPU / 1 ุฌูŠุฌุงุจุงูŠุช ู…ู† ุฐุงูƒุฑุฉ ุงู„ูˆุตูˆู„ ุงู„ุนุดูˆุงุฆูŠ) -- ู‚ู… ุจุชุนูŠูŠู† ูƒู„ู…ุฉ ู…ุฑูˆุฑ ุฌุฐุฑ ู‚ูˆูŠุฉ ุฃูˆ ู‚ู… ุจุชูƒูˆูŠู† ู…ูุชุงุญ SSH -- ู„ุงุญุธ **ุนู†ูˆุงู† IP ุงู„ุนุงู…** (ุนู„ู‰ ุณุจูŠู„ ุงู„ู…ุซุงู„ุŒ `203.0.113.10`) - -### 1.2 ุงู„ุงุชุตุงู„ ุนุจุฑ SSH - -```bash -ssh root@203.0.113.10 -``` - -### 1.3 ุชุญุฏูŠุซ ุงู„ู†ุธุงู… - -```bash -apt update && apt upgrade -y -``` - -### 1.4 ุชุซุจูŠุช ุนุงู…ู„ ุงู„ู…ูŠู†ุงุก - -```bash -# Install dependencies -apt install -y ca-certificates curl gnupg - -# Add official Docker repository -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 ุชุซุจูŠุช nginx - -```bash -apt install -y nginx -``` - -### 1.6 ุชูƒูˆูŠู† ุฌุฏุงุฑ ุงู„ุญู…ุงูŠุฉ (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 -``` - -> **ู†ุตูŠุญุฉ**: ู„ู„ุญุตูˆู„ ุนู„ู‰ ุงู„ุญุฏ ุงู„ุฃู‚ุตู‰ ู…ู† ุงู„ุฃู…ุงู†ุŒ ู‚ู… ุจุชู‚ูŠูŠุฏ ุงู„ู…ู†ูุฐูŠู† 80 ูˆ443 ุจุนู†ุงูˆูŠู† Cloudflare IP ูู‚ุท. ุฑุงุฌุน ู‚ุณู… [Advanced Security](#advanced-security). - ---- - -## 2. ู‚ู… ุจุชุซุจูŠุช OmniRoute - -### 2.1 ุฅู†ุดุงุก ุฏู„ูŠู„ ุงู„ุชูƒูˆูŠู† - -```bash -mkdir -p /opt/omniroute -``` - -### 2.2 ุฅู†ุดุงุก ู…ู„ู ู…ุชุบูŠุฑุงุช ุงู„ุจูŠุฆุฉ - -```bash -cat > /opt/omniroute/.env << โ€˜EOFโ€™ -# === Security === -JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY -INITIAL_PASSWORD=YourSecurePassword123! -API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY -STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY -STORAGE_ENCRYPTION_KEY_VERSION=v1 -MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT - -# === 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 (change to your domain) === -BASE_URL=https://llms.seudominio.com -NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com - -# === Cloud Sync (optional) === -# CLOUD_URL=https://cloud.omniroute.online -# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online -EOF -``` - -> โš ๏ธ **ู‡ุงู…**: ุฃู†ุดุฆ ู…ูุงุชูŠุญ ุณุฑูŠุฉ ูุฑูŠุฏุฉ! ุงุณุชุฎุฏู… `openssl rand -hex 32` ู„ูƒู„ ู…ูุชุงุญ. - -### 2.3 ุงุจุฏุฃ ุงู„ุญุงูˆูŠุฉ - -```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 ุงู„ุชุญู‚ู‚ ู…ู† ุฃู†ู‡ ู‚ูŠุฏ ุงู„ุชุดุบูŠู„ - -```bash -docker ps | grep omniroute -docker logs omniroute --tail 20 -``` - -ูŠุฌุจ ุฃู† ูŠุนุฑุถ: `[DB] SQLite database ready` ูˆ`listening on port 20128`. - ---- - -## 3. ุชูƒูˆูŠู† nginx (ุงู„ูˆูƒูŠู„ ุงู„ุนูƒุณูŠ) - -### 3.1 ุฅู†ุดุงุก ุดู‡ุงุฏุฉ SSL (ุฃุตู„ Cloudflare) - -ููŠ ู„ูˆุญุฉ ู…ุนู„ูˆู…ุงุช Cloudflare: - -1. ุงู†ุชู‚ู„ ุฅู„ู‰ **SSL/TLS โ†’ ุฎุงุฏู… ุงู„ุฃุตู„** -2. ุงู†ู‚ุฑ **ุฅู†ุดุงุก ุดู‡ุงุฏุฉ** -3. ุงุญุชูุธ ุจุงู„ุฅุนุฏุงุฏุงุช ุงู„ุงูุชุฑุงุถูŠุฉ (15 ุนุงู…ู‹ุงุŒ \*.yourdomain.com) -4. ุงู†ุณุฎ **ุดู‡ุงุฏุฉ ุงู„ู…ู†ุดุฃ** ูˆ**ุงู„ู…ูุชุงุญ ุงู„ุฎุงุต** - -```bash -mkdir -p /etc/nginx/ssl - -# Paste the certificate -nano /etc/nginx/ssl/origin.crt - -# Paste the private key -nano /etc/nginx/ssl/origin.key - -chmod 600 /etc/nginx/ssl/origin.key -``` - -### 3.2 ุชูƒูˆูŠู† ุฅู†ุฌูŠู†ูƒุณ - -```bash -cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ -# Default server โ€” blocks direct access via 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.yourdomain.com; # Change to your domain - - 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.yourdomain.com; - return 301 https://$server_name$request_uri; -} -NGINX -``` - -### 3.3 ุชู…ูƒูŠู† ูˆุงุฎุชุจุงุฑ - -```bash -# Remove default configuration -rm -f /etc/nginx/sites-enabled/default - -# Enable OmniRoute -ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute - -# Test and reload -nginx -t && systemctl reload nginx -``` - ---- - -## 4. ุชูƒูˆูŠู† Cloudflare DNS - -### 4.1 ุฅุถุงูุฉ ุณุฌู„ DNS - -ููŠ ู„ูˆุญุฉ ู…ุนู„ูˆู…ุงุช Cloudflare โ†’ DNS: - -| ุงูƒุชุจ | ุงู„ุงุณู… | ุงู„ู…ุญุชูˆู‰ | ุงู„ูˆูƒูŠู„ | -| ---- | ------ | ---------------------- | -------- | -| ุฃ | `llms` | `203.0.113.10` (VM IP) | โœ… ุชูˆูƒูŠู„ | - -### 4.2 ุชูƒูˆูŠู† SSL - -ุถู…ู† **SSL/TLS โ†’ ู†ุธุฑุฉ ุนุงู…ุฉ**: - -- ุงู„ูˆุถุน: **ูƒุงู…ู„ (ุตุงุฑู…)** - -ุถู…ู† **SSL/TLS โ†’ ุดู‡ุงุฏุงุช ุงู„ุญุงูุฉ**: - -- ุงุณุชุฎุฏู… HTTPS ุฏุงุฆู…ู‹ุง: โœ… ู‚ูŠุฏ ุงู„ุชุดุบูŠู„ -- ุงู„ุญุฏ ุงู„ุฃุฏู†ู‰ ู„ุฅุตุฏุงุฑ TLS: TLS 1.2 -- ุฅุนุงุฏุฉ ูƒุชุงุจุฉ HTTPS ุชู„ู‚ุงุฆูŠู‹ุง: โœ… ุชุดุบูŠู„ - -### 4.3 ุงู„ุงุฎุชุจุงุฑ - -```bash -curl -sI https://llms.seudominio.com/health -# Should return HTTP/2 200 -``` - ---- - -## 5. ุงู„ุนู…ู„ูŠุงุช ูˆุงู„ุตูŠุงู†ุฉ - -### ุงู„ุชุฑู‚ูŠุฉ ุฅู„ู‰ ุงู„ุฅุตุฏุงุฑ ุงู„ุฌุฏูŠุฏ - -```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 -``` - -### ุนุฑุถ ุงู„ุณุฌู„ุงุช - -```bash -docker logs -f omniroute # Real-time stream -docker logs omniroute --tail 50 # Last 50 lines -``` - -### ุงู„ู†ุณุฎ ุงู„ุงุญุชูŠุงุทูŠ ู„ู‚ุงุนุฏุฉ ุงู„ุจูŠุงู†ุงุช ูŠุฏูˆูŠุง - -```bash -# Copy data from the volume to the host -docker cp omniroute:/app/data ./backup-$(date +%F) - -# Or compress the entire volume -docker run --rm -v omniroute-data:/data -v $(pwd):/backup \ - alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data -``` - -### ุงู„ุงุณุชุนุงุฏุฉ ู…ู† ุงู„ู†ุณุฎุฉ ุงู„ุงุญุชูŠุงุทูŠุฉ - -```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. ุงู„ุฃู…ุงู† ุงู„ู…ุชู‚ุฏู… - -### ุชู‚ูŠูŠุฏ nginx ุนู„ู‰ ุนู†ุงูˆูŠู† IP ุงู„ุฎุงุตุฉ ุจู€ Cloudflare - -```bash -cat > /etc/nginx/cloudflare-ips.conf << โ€˜CFโ€™ -# Cloudflare IPv4 ranges โ€” update periodically -# 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 -``` - -ุฃุถู ู…ุง ูŠู„ูŠ ุฅู„ู‰ `nginx.conf` ุฏุงุฎู„ ุงู„ูƒุชู„ุฉ `http {}`: - -```nginx -include /etc/nginx/cloudflare-ips.conf; -``` - -### ุชุซุจูŠุช Fail2ban - -```bash -apt install -y fail2ban -systemctl enable fail2ban -systemctl start fail2ban - -# Check status -fail2ban-client status sshd -``` - -### ู…ู†ุน ุงู„ูˆุตูˆู„ ุงู„ู…ุจุงุดุฑ ุฅู„ู‰ ู…ู†ูุฐ Docker - -```bash -# Prevent direct external access to port 20128 -iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP -iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT - -# Persist the rules -apt install -y iptables-persistent -netfilter-persistent save -``` - ---- - -## 7. ุงู„ู†ุดุฑ ุฅู„ู‰ ุนู…ุงู„ Cloudflare (ุงุฎุชูŠุงุฑูŠ) - -ู„ู„ูˆุตูˆู„ ุนู† ุจุนุฏ ุนุจุฑ Cloudflare Workers (ุฏูˆู† ุงู„ูƒุดู ุนู† ุงู„ุฌู‡ุงุฒ ุงู„ุงูุชุฑุงุถูŠ ู…ุจุงุดุฑุฉ): - -```bash -# In the local repository -cd omnirouteCloud -npm install -npx wrangler login -npx wrangler deploy -``` - -ุฑุงุฌุน ุงู„ูˆุซุงุฆู‚ ุงู„ูƒุงู…ู„ุฉ ุนู„ู‰ [omnirouteCloud/README.md](../omnirouteCloud/README.md). - ---- - -## ู…ู„ุฎุต ุงู„ู…ู†ูุฐ - -| ู…ูŠู†ุงุก | ุงู„ุฎุฏู…ุฉ | ุงู„ูˆุตูˆู„ | -| ----- | ------------- | ----------------------------- | -| 22 | ุณุด | ุนุงู… (ู…ุน Fail2ban) | -| 80 | ุฅู†ุฌูŠู†ูƒุณ HTTP | ุฅุนุงุฏุฉ ุงู„ุชูˆุฌูŠู‡ โ†’ HTTPS | -| 443 | ุฅู†ุฌูŠู†ูƒุณ HTTPS | ุนุจุฑ ูˆูƒูŠู„ Cloudflare | -| 20128 | ุฃูˆู…ู†ูŠุฑูˆุชูŠ | ุงู„ู…ุถูŠู ุงู„ู…ุญู„ูŠ ูู‚ุท (ุนุจุฑ nginx) | diff --git a/docs/i18n/ar/docs/A2A-SERVER.md b/docs/i18n/ar/docs/A2A-SERVER.md new file mode 100644 index 0000000000..58c345a0b5 --- /dev/null +++ b/docs/i18n/ar/docs/A2A-SERVER.md @@ -0,0 +1,200 @@ +# OmniRoute A2A Server Documentation (ุงู„ุนุฑุจูŠุฉ) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/A2A-SERVER.md) + +--- + +> Agent-to-Agent Protocol v0.3 โ€” OmniRoute as an intelligent routing agent + +## Agent Discovery + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements. + +--- + +## Authentication + +All `/a2a` requests require an API key via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server, authentication is bypassed. + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Sends a message to a skill and waits for the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a hello world in Python"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "uuid", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "..." }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}} + +: heartbeat 2026-03-03T17:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Available Skills + +| Skill | Description | +| :----------------- | :------------------------------------------------------------------------------------------------------------------------------ | +| `smart-routing` | Routes prompts through OmniRoute's intelligent pipeline. Returns response with routing explanation, cost, and resilience trace. | +| `quota-management` | Answers natural-language queries about provider quotas, suggests free combos, and provides quota rankings. | + +--- + +## Task Lifecycle + +``` +submitted โ†’ working โ†’ completed + โ†’ failed + โ†’ cancelled +``` + +- Tasks expire after 5 minutes (configurable) +- Terminal states: `completed`, `failed`, `cancelled` +- Event log tracks every state transition + +--- + +## Error Codes + +| Code | Meaning | +| :----- | :----------------------------- | +| -32700 | Parse error (invalid JSON) | +| -32600 | Invalid request / Unauthorized | +| -32601 | Method or skill not found | +| -32602 | Invalid params | +| -32603 | Internal error | + +--- + +## Integration Examples + +### Python (requests) + +```python +import requests + +resp = requests.post("http://localhost:20128/a2a", json={ + "jsonrpc": "2.0", "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Hello"}] + } +}, headers={"Authorization": "Bearer YOUR_KEY"}) + +result = resp.json()["result"] +print(result["artifacts"][0]["content"]) +print(result["metadata"]["routing_explanation"]) +``` + +### TypeScript (fetch) + +```typescript +const resp = await fetch("http://localhost:20128/a2a", { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: "Bearer YOUR_KEY", + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "1", + method: "message/send", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Hello" }], + }, + }), +}); +const { result } = await resp.json(); +console.log(result.metadata.routing_explanation); +``` diff --git a/docs/i18n/ar/docs/API_REFERENCE.md b/docs/i18n/ar/docs/API_REFERENCE.md new file mode 100644 index 0000000000..bdfbcb4b40 --- /dev/null +++ b/docs/i18n/ar/docs/API_REFERENCE.md @@ -0,0 +1,465 @@ +# API Reference (ุงู„ุนุฑุจูŠุฉ) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/API_REFERENCE.md) + +--- + +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 | +| `X-Session-Id` | Request | Sticky session key for external session affinity | +| `x_session_id` | Request | Underscore variant also accepted (direct HTTP) | +| `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 | +| `X-OmniRoute-Session-Id` | Response | Effective session ID used by OmniRoute | + +> Nginx note: if you rely on underscore headers (for example `x_session_id`), enable `underscores_in_headers 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/stats + +# Clear all caches +DELETE /api/cache/stats +``` + +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/PATCH | 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 + provider summary (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`) | +| `/api/cache/stats` | 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 | + +### Tunnels + +| Endpoint | Method | Description | +| -------------------------- | ------ | ----------------------------------------------------------------------- | +| `/api/tunnels/cloudflared` | GET | Read Cloudflare Quick Tunnel install/runtime status for the dashboard | +| `/api/tunnels/cloudflared` | POST | Enable or disable the Cloudflare Quick Tunnel (`action=enable/disable`) | + +### 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`. + +### ACP Agents + +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | + +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). + +### Resilience & Rate Limits + +| Endpoint | Method | Description | +| ----------------------- | --------- | ------------------------------- | +| `/api/resilience` | GET/PATCH | 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` diff --git a/docs/i18n/ar/docs/ARCHITECTURE.md b/docs/i18n/ar/docs/ARCHITECTURE.md new file mode 100644 index 0000000000..aedd88fbf8 --- /dev/null +++ b/docs/i18n/ar/docs/ARCHITECTURE.md @@ -0,0 +1,814 @@ +# OmniRoute Architecture (ุงู„ุนุฑุจูŠุฉ) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/ARCHITECTURE.md) + +--- + +_Last updated: 2026-03-28_ + +## 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 (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developerโ†’system, systemโ†’user) for cross-provider compatibility +- Structured output conversion (json_schema โ†’ Gemini responseSchema) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) +- Global system prompt injection +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout โ†’ budget โ†’ fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) + +Primary runtime model: + +- Next.js 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.) + +## Dashboard Surface (Current) + +Main pages under `src/app/(dashboard)/dashboard/`: + +- `/dashboard` โ€” quick start + provider overview +- `/dashboard/endpoint` โ€” endpoint proxy + MCP + A2A + API endpoint tabs +- `/dashboard/providers` โ€” provider connections and credentials +- `/dashboard/combos` โ€” combo strategies, templates, model routing rules +- `/dashboard/costs` โ€” cost aggregation and pricing visibility +- `/dashboard/analytics` โ€” usage analytics and evaluations +- `/dashboard/limits` โ€” quota/rate controls +- `/dashboard/cli-tools` โ€” CLI onboarding, runtime detection, config generation +- `/dashboard/agents` โ€” detected ACP agents + custom agent registration +- `/dashboard/media` โ€” image/video/music playground +- `/dashboard/search-tools` โ€” search provider testing and history +- `/dashboard/health` โ€” uptime, circuit breakers, rate limits +- `/dashboard/logs` โ€” request/proxy/audit/console logs +- `/dashboard/settings` โ€” system settings tabs (general, routing, combo defaults, etc.) +- `/dashboard/api-manager` โ€” API key lifecycle and model permissions + +## 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[(storage.sqlite)] + UDB[(usage tables + log artifacts)] + end + + subgraph Upstreams[Upstream Providers] + P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/Qoder/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/route.ts` (GET) +- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- OAuth: `src/app/api/oauth/*` +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` +- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI tooling helpers: `src/app/api/cli-tools/*` +- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) +- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) โ€” provider profiles, circuit breaker, rate limit state +- Resilience reset: `src/app/api/resilience/reset` (POST) โ€” reset breakers + cooldowns +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) +- Telemetry: `src/app/api/telemetry/summary` (GET) +- Budget: `src/app/api/usage/budget` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Policies: `src/app/api/policies` (GET/POST) + +## 2) SSE + 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` +- Response sanitization: `open-sse/handlers/responseSanitizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.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`, `qoder.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 (SQLite): + +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** + +Usage persistence: + +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present + +Domain State DB (SQLite): + +- `src/lib/db/domainState.ts` โ€” CRUD operations 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`, `src/shared/services/modelSyncScheduler.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Periodic task: `src/shared/services/modelSyncScheduler.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. Combo routing adds one extra guard: provider-scoped 400s such as upstream content-block and role-validation failures are treated as model-local failures so later combo targets can still run. + +## 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: + +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` + +## Deployment Topology + +```mermaid +flowchart LR + 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[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] + end + + subgraph External[External Services] + Providers[AI Providers] + SyncCloud[Cloud Sync Service] + end + + CLI --> Next + Browser --> Next + Next --> Core + Next --> MainDB + Core --> MainDB + Core --> UsageDB + Core --> Providers + Next --> SyncCloud +``` + +## Module Mapping (Decision-Critical) + +### Route and API Modules + +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle +- `src/app/api/models/alias`: alias management +- `src/app/api/combos*`: fallback combo management +- `src/app/api/pricing`: pricing overrides for cost calculation +- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers +- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) +- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) +- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) +- `src/app/api/sessions`: active session listing (GET) +- `src/app/api/rate-limits`: per-account rate limit status (GET) + +### Routing and Execution Core + +- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior + +### Translation Registry and Format Converters + +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` +- Format constants: `open-sse/translator/formats.ts` + +### Persistence + +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables + +## Provider Executor Coverage (Strategy Pattern) + +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. + +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, Qoder, 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 | +| Qoder | openai | OAuth (Basic) | โœ… | โœ… | โœ… | โš ๏ธ Per request | +| OpenRouter | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| GLM/Kimi/MiniMax | claude | API Key | โœ… | โœ… | โŒ | โŒ | +| DeepSeek | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Groq | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| xAI (Grok) | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Mistral | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Perplexity | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Together AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Fireworks AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Cerebras | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Cohere | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| NVIDIA NIM | openai | API Key | โœ… | โœ… | โŒ | โŒ | + +## Format Translation Coverage + +Detected source formats include: + +- `openai` +- `openai-responses` +- `claude` +- `gemini` + +Target formats include: + +- OpenAI chat/Responses +- Claude +- Gemini/Gemini-CLI/Antigravity envelope +- Kiro +- Cursor + +Translations use **OpenAI as the hub format** โ€” all conversions go through OpenAI as intermediate: + +``` +Source Format โ†’ OpenAI (hub) โ†’ Target Format +``` + +Translations are selected dynamically based on source payload shape and provider target format. + +Additional processing layers in the translation pipeline: + +- **Response sanitization** โ€” Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI targets; merges `system` โ†’ `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** โ€” Parses `...` blocks from content into `reasoning_content` field +- **Structured output** โ€” Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` + +## Supported API Endpoints + +| 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` | Provider Models | Provider model metadata backing custom and managed available models | + +## 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 `/logs//` 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 + +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON โ†’ SQLite migration compatibility path + +## Observability and Operational Signals + +Runtime visibility sources: + +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- four-stage detailed payload captures in SQLite (`request_detail_logs`) when `settings.detailed_logs_enabled=true` +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption + +Detailed request payload capture stores up to four JSON payload stages per routed call: + +- raw request received from the client +- translated request actually sent upstream +- provider response reconstructed as JSON; streamed responses are compacted to the final summary plus stream metadata +- final client response returned by OmniRoute; streamed responses are stored in the same compact summary form + +## Security-Sensitive Boundaries + +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics + +## Environment and Runtime Matrix + +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` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). + +## Operational Verification Checklist + +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: +- `GET /api/settings` +- `GET /api/v1/models` +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/ar/docs/AUTO-COMBO.md b/docs/i18n/ar/docs/AUTO-COMBO.md new file mode 100644 index 0000000000..27191bc97e --- /dev/null +++ b/docs/i18n/ar/docs/AUTO-COMBO.md @@ -0,0 +1,67 @@ +# OmniRoute Auto-Combo Engine (ุงู„ุนุฑุจูŠุฉ) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/AUTO-COMBO.md) + +--- + +> Self-managing model chains with adaptive scoring + +## How It Works + +The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**: + +| Factor | Weight | Description | +| :--------- | :----- | :---------------------------------------------- | +| Quota | 0.20 | Remaining capacity [0..1] | +| Health | 0.25 | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 | +| CostInv | 0.20 | Inverse cost (cheaper = higher score) | +| LatencyInv | 0.15 | Inverse p95 latency (faster = higher) | +| TaskFit | 0.10 | Model ร— task type fitness score | +| Stability | 0.10 | Low variance in latency/errors | + +## Mode Packs + +| Pack | Focus | Key Weight | +| :---------------------- | :----------- | :--------------- | +| ๐Ÿš€ **Ship Fast** | Speed | latencyInv: 0.35 | +| ๐Ÿ’ฐ **Cost Saver** | Economy | costInv: 0.40 | +| ๐ŸŽฏ **Quality First** | Best model | taskFit: 0.40 | +| ๐Ÿ“ก **Offline Friendly** | Availability | quota: 0.40 | + +## Self-Healing + +- **Temporary exclusion**: Score < 0.2 โ†’ excluded for 5 min (progressive backoff, max 30 min) +- **Circuit breaker awareness**: OPEN โ†’ auto-excluded; HALF_OPEN โ†’ probe requests +- **Incident mode**: >50% OPEN โ†’ disable exploration, maximize stability +- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout + +## Bandit Exploration + +5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode. + +## API + +```bash +# Create auto-combo +curl -X POST http://localhost:20128/api/combos/auto \ + -H "Content-Type: application/json" \ + -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}' + +# List auto-combos +curl http://localhost:20128/api/combos/auto +``` + +## Task Fitness + +30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` โ†’ high coding score). + +## Files + +| File | Purpose | +| :------------------------------------------- | :------------------------------------ | +| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization | +| `open-sse/services/autoCombo/taskFitness.ts` | Model ร— task fitness lookup | +| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap | +| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode | +| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles | +| `src/app/api/combos/auto/route.ts` | REST API | diff --git a/docs/i18n/ar/docs/CLI-TOOLS.md b/docs/i18n/ar/docs/CLI-TOOLS.md new file mode 100644 index 0000000000..1e01011145 --- /dev/null +++ b/docs/i18n/ar/docs/CLI-TOOLS.md @@ -0,0 +1,348 @@ +# CLI Tools Setup Guide โ€” OmniRoute (ุงู„ุนุฑุจูŠุฉ) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CLI-TOOLS.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CLI-TOOLS.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CLI-TOOLS.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CLI-TOOLS.md) + +--- + +This guide explains how to install and configure all supported AI coding CLI tools +to use **OmniRoute** as the unified backend, giving you centralized key management, +cost tracking, model switching, and request logging across every tool. + +--- + +## How It Works + +``` +Claude / Codex / OpenCode / Cline / KiloCode / Continue / Kiro / Cursor / Copilot + โ”‚ + โ–ผ (all point to OmniRoute) + http://YOUR_SERVER:20128/v1 + โ”‚ + โ–ผ (OmniRoute routes to the right provider) + Anthropic / OpenAI / Gemini / DeepSeek / Groq / Mistral / ... +``` + +**Benefits:** + +- One API key to manage all tools +- Cost tracking across all CLIs in the dashboard +- Model switching without reconfiguring every tool +- Works locally and on remote servers (VPS) + +--- + +## Supported Tools (Dashboard Source of Truth) + +The dashboard cards in `/dashboard/cli-tools` are generated from `src/shared/constants/cliTools.ts`. +Current list (v3.0.0-rc.16): + +| Tool | ID | Command | Setup Mode | Install Method | +| ------------------ | ------------- | ---------- | ---------- | -------------- | +| **Claude Code** | `claude` | `claude` | env | npm | +| **OpenAI Codex** | `codex` | `codex` | custom | npm | +| **Factory Droid** | `droid` | `droid` | custom | bundled/CLI | +| **OpenClaw** | `openclaw` | `openclaw` | custom | bundled/CLI | +| **Cursor** | `cursor` | app | guide | desktop app | +| **Cline** | `cline` | `cline` | custom | npm | +| **Kilo Code** | `kilo` | `kilocode` | custom | npm | +| **Continue** | `continue` | extension | guide | VS Code | +| **Antigravity** | `antigravity` | internal | mitm | OmniRoute | +| **GitHub Copilot** | `copilot` | extension | custom | VS Code | +| **OpenCode** | `opencode` | `opencode` | guide | npm | +| **Kiro AI** | `kiro` | app/cli | mitm | desktop/CLI | + +### CLI fingerprint sync (Agents + Settings) + +`/dashboard/agents` and `Settings > CLI Fingerprint` use `src/shared/constants/cliCompatProviders.ts`. +This keeps provider IDs aligned with CLI cards and legacy IDs. + +| CLI ID | Fingerprint Provider ID | +| ---------------------------------------------------------------------------------------------------- | ----------------------- | +| `kilo` | `kilocode` | +| `copilot` | `github` | +| `claude` / `codex` / `antigravity` / `kiro` / `cursor` / `cline` / `opencode` / `droid` / `openclaw` | same ID | + +Legacy IDs still accepted for compatibility: `copilot`, `kimi-coding`, `qwen`. + +--- + +## Step 1 โ€” Get an OmniRoute API Key + +1. Open the OmniRoute dashboard โ†’ **API Manager** (`/dashboard/api-manager`) +2. Click **Create API Key** +3. Give it a name (e.g. `cli-tools`) and select all permissions +4. Copy the key โ€” you'll need it for every CLI below + +> Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` + +--- + +## Step 2 โ€” Install CLI Tools + +All npm-based tools require Node.js 18+: + +```bash +# Claude Code (Anthropic) +npm install -g @anthropic-ai/claude-code + +# OpenAI Codex +npm install -g @openai/codex + +# OpenCode +npm install -g opencode-ai + +# Cline +npm install -g cline + +# KiloCode +npm install -g kilocode + +# Kiro CLI (Amazon โ€” requires curl + unzip) +apt-get install -y unzip # on Debian/Ubuntu +curl -fsSL https://cli.kiro.dev/install | bash +export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc +``` + +**Verify:** + +```bash +claude --version # 2.x.x +codex --version # 0.x.x +opencode --version # x.x.x +cline --version # 2.x.x +kilocode --version # x.x.x (or: kilo --version) +kiro-cli --version # 1.x.x +``` + +--- + +## Step 3 โ€” Set Global Environment Variables + +Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`: + +```bash +# OmniRoute Universal Endpoint +export OPENAI_BASE_URL="http://localhost:20128/v1" +export OPENAI_API_KEY="sk-your-omniroute-key" +export ANTHROPIC_BASE_URL="http://localhost:20128/v1" +export ANTHROPIC_API_KEY="sk-your-omniroute-key" +export GEMINI_BASE_URL="http://localhost:20128/v1" +export GEMINI_API_KEY="sk-your-omniroute-key" +``` + +> For a **remote server** replace `localhost:20128` with the server IP or domain, +> e.g. `http://192.168.0.15:20128`. + +--- + +## Step 4 โ€” Configure Each Tool + +### Claude Code + +```bash +# Via CLI: +claude config set --global api-base-url http://localhost:20128/v1 + +# Or create ~/.claude/settings.json: +mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF +{ + "apiBaseUrl": "http://localhost:20128/v1", + "apiKey": "sk-your-omniroute-key" +} +EOF +``` + +**Test:** `claude "say hello"` + +--- + +### OpenAI Codex + +```bash +mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF +model: auto +apiKey: sk-your-omniroute-key +apiBaseUrl: http://localhost:20128/v1 +EOF +``` + +**Test:** `codex "what is 2+2?"` + +--- + +### OpenCode + +```bash +mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF +[provider.openai] +base_url = "http://localhost:20128/v1" +api_key = "sk-your-omniroute-key" +EOF +``` + +**Test:** `opencode` + +--- + +### Cline (CLI or VS Code) + +**CLI mode:** + +```bash +mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF +{ + "apiProvider": "openai", + "openAiBaseUrl": "http://localhost:20128/v1", + "openAiApiKey": "sk-your-omniroute-key" +} +EOF +``` + +**VS Code mode:** +Cline extension settings โ†’ API Provider: `OpenAI Compatible` โ†’ Base URL: `http://localhost:20128/v1` + +Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ Cline โ†’ Apply Config**. + +--- + +### KiloCode (CLI or VS Code) + +**CLI mode:** + +```bash +kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key +``` + +**VS Code settings:** + +```json +{ + "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", + "kilo-code.apiKey": "sk-your-omniroute-key" +} +``` + +Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ KiloCode โ†’ Apply Config**. + +--- + +### Continue (VS Code Extension) + +Edit `~/.continue/config.yaml`: + +```yaml +models: + - name: OmniRoute + provider: openai + model: auto + apiBase: http://localhost:20128/v1 + apiKey: sk-your-omniroute-key + default: true +``` + +Restart VS Code after editing. + +--- + +### Kiro CLI (Amazon) + +```bash +# Login to your AWS/Kiro account: +kiro-cli login + +# The CLI uses its own auth โ€” OmniRoute is not needed as backend for Kiro CLI itself. +# Use kiro-cli alongside OmniRoute for other tools. +kiro-cli status +``` + +--- + +### Cursor (Desktop App) + +> **Note:** Cursor routes requests through its cloud. For OmniRoute integration, +> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL. + +Via GUI: **Settings โ†’ Models โ†’ OpenAI API Key** + +- Base URL: `https://your-domain.com/v1` +- API Key: your OmniRoute key + +--- + +## Dashboard Auto-Configuration + +The OmniRoute dashboard automates configuration for most tools: + +1. Go to `http://localhost:20128/dashboard/cli-tools` +2. Expand any tool card +3. Select your API key from the dropdown +4. Click **Apply Config** (if tool is detected as installed) +5. Or copy the generated config snippet manually + +--- + +## Built-in Agents: Droid & OpenClaw + +**Droid** and **OpenClaw** are AI agents built directly into OmniRoute โ€” no installation needed. +They run as internal routes and use OmniRoute's model routing automatically. + +- Access: `http://localhost:20128/dashboard/agents` +- Configure: same combos and providers as all other tools +- No API key or CLI install required + +--- + +## Available API Endpoints + +| Endpoint | Description | Use For | +| -------------------------- | ----------------------------- | --------------------------- | +| `/v1/chat/completions` | Standard chat (all providers) | All modern tools | +| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows | +| `/v1/completions` | Legacy text completions | Older tools using `prompt:` | +| `/v1/embeddings` | Text embeddings | RAG, search | +| `/v1/images/generations` | Image generation | DALL-E, Flux, etc. | +| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS | +| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI | + +--- + +## ุงุณุชูƒุดุงู ุงู„ุฃุฎุทุงุก + +| Error | Cause | Fix | +| ------------------------- | ----------------------- | ------------------------------------------ | +| `Connection refused` | OmniRoute not running | `pm2 start omniroute` | +| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` | +| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` | +| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` | +| CLI shows "not installed" | Binary not in PATH | Check `which ` | +| `kiro-cli: not found` | Not in PATH | `export PATH="$HOME/.local/bin:$PATH"` | + +--- + +## Quick Setup Script (One Command) + +```bash +# Install all CLIs and configure for OmniRoute (replace with your key and server URL) +OMNIROUTE_URL="http://localhost:20128/v1" +OMNIROUTE_KEY="sk-your-omniroute-key" + +npm install -g @anthropic-ai/claude-code @openai/codex opencode-ai cline kilocode + +# Kiro CLI +apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash + +# Write configs +mkdir -p ~/.claude ~/.codex ~/.config/opencode ~/.continue + +cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" +cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" +cat >> ~/.bashrc << EOF +export OPENAI_BASE_URL="$OMNIROUTE_URL" +export OPENAI_API_KEY="$OMNIROUTE_KEY" +export ANTHROPIC_BASE_URL="$OMNIROUTE_URL" +export ANTHROPIC_API_KEY="$OMNIROUTE_KEY" +EOF + +source ~/.bashrc +echo "โœ… All CLIs installed and configured for OmniRoute" +``` diff --git a/docs/i18n/ar/CODEBASE_DOCUMENTATION.md b/docs/i18n/ar/docs/CODEBASE_DOCUMENTATION.md similarity index 91% rename from docs/i18n/ar/CODEBASE_DOCUMENTATION.md rename to docs/i18n/ar/docs/CODEBASE_DOCUMENTATION.md index e2d7950052..a97476043b 100644 --- a/docs/i18n/ar/CODEBASE_DOCUMENTATION.md +++ b/docs/i18n/ar/docs/CODEBASE_DOCUMENTATION.md @@ -1,11 +1,9 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CODEBASE_DOCUMENTATION.md) +# omniroute โ€” Codebase Documentation (ุงู„ุนุฑุจูŠุฉ) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CODEBASE_DOCUMENTATION.md) --- -# omniroute โ€” Codebase Documentation - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) - > A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. --- @@ -352,7 +350,7 @@ flowchart LR The **format translation engine** using a self-registering plugin system. -#### Architecture +#### ุงู„ู‡ู†ุฏุณุฉ ```mermaid graph TD diff --git a/docs/i18n/ar/docs/COVERAGE_PLAN.md b/docs/i18n/ar/docs/COVERAGE_PLAN.md new file mode 100644 index 0000000000..d376b93ddd --- /dev/null +++ b/docs/i18n/ar/docs/COVERAGE_PLAN.md @@ -0,0 +1,170 @@ +# Test Coverage Plan (ุงู„ุนุฑุจูŠุฉ) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/COVERAGE_PLAN.md) + +--- + +Last updated: 2026-03-28 + +## Baseline + +There are multiple coverage numbers depending on how the report is computed. For planning, only one of them is useful. + +| Metric | Scope | Statements / Lines | Branches | Functions | Notes | +| -------------------- | ----------------------------------------------------- | -----------------: | -------: | --------: | --------------------------------------------------- | +| Legacy | Old `npm run test:coverage` | 79.42% | 75.15% | 67.94% | Inflated: counts test files and excludes `open-sse` | +| Diagnostic | Source-only, excluding tests and excluding `open-sse` | 68.16% | 63.55% | 64.06% | Useful only to isolate `src/**` | +| Recommended baseline | Source-only, excluding tests and including `open-sse` | 56.95% | 66.05% | 57.80% | This is the project-wide baseline to improve | + +The recommended baseline is the number to optimize against. + +## Rules + +- Coverage targets apply to source files, not to `tests/**`. +- `open-sse/**` is part of the product and must remain in scope. +- New code should not reduce coverage in touched areas. +- Prefer testing behavior and branch outcomes over implementation details. +- Prefer temp SQLite databases and small fixtures over broad mocks for `src/lib/db/**`. + +## Current command set + +- `npm run test:coverage` + - Main source coverage gate for the unit test suite + - Generates `text-summary`, `html`, `json-summary`, and `lcov` +- `npm run coverage:report` + - Detailed file-by-file report from the latest run +- `npm run test:coverage:legacy` + - Historical comparison only + +## Milestones + +| Phase | Target | Focus | +| ------- | ---------------------: | ------------------------------------------------- | +| Phase 1 | 60% statements / lines | Quick wins and low-risk utility coverage | +| Phase 2 | 65% statements / lines | DB and route foundations | +| Phase 3 | 70% statements / lines | Provider validation and usage analytics | +| Phase 4 | 75% statements / lines | `open-sse` translators and helpers | +| Phase 5 | 80% statements / lines | `open-sse` handlers and executor branches | +| Phase 6 | 85% statements / lines | Harder edge cases, branch debt, regression suites | +| Phase 7 | 90% statements / lines | Final sweep, gap closure, strict ratchet | + +Branches and functions should ratchet upward with each phase, but the primary hard target is statements / lines. + +## Priority hotspots + +These files or areas offer the best return for the next phases: + +1. `open-sse/handlers` + - `chatCore.ts` at 7.57% + - Overall directory at 29.07% +2. `open-sse/translator/request` + - Overall directory at 36.39% + - Many translators are still near single-digit coverage +3. `open-sse/translator/response` + - Overall directory at 8.07% +4. `open-sse/executors` + - Overall directory at 36.62% +5. `src/lib/db` + - `models.ts` at 20.66% + - `registeredKeys.ts` at 34.46% + - `modelComboMappings.ts` at 36.25% + - `settings.ts` at 46.40% + - `webhooks.ts` at 33.33% +6. `src/lib/usage` + - `usageHistory.ts` at 21.12% + - `usageStats.ts` at 9.56% + - `costCalculator.ts` at 30.00% +7. `src/lib/providers` + - `validation.ts` at 41.16% +8. Low-risk utility and API files for early gains + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/api/errorResponse.ts` + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +## Execution checklist + +### Phase 1: 56.95% -> 60% + +- [x] Fix coverage metric so it reflects source code instead of test files +- [x] Keep a legacy coverage script for comparison +- [x] Record the baseline and hotspots in-repo +- [ ] Add focused tests for low-risk utilities: + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/fetchTimeout.ts` + - `src/lib/api/errorResponse.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/display/names.ts` +- [ ] Add route tests for: + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +### Phase 2: 60% -> 65% + +- [ ] Add DB-backed tests for: + - `src/lib/db/modelComboMappings.ts` + - `src/lib/db/settings.ts` + - `src/lib/db/registeredKeys.ts` +- [ ] Cover branch behavior in: + - `src/lib/providers/validation.ts` + - `src/app/api/v1/embeddings/route.ts` + - `src/app/api/v1/moderations/route.ts` + +### Phase 3: 65% -> 70% + +- [ ] Add usage analytics tests for: + - `src/lib/usage/usageHistory.ts` + - `src/lib/usage/usageStats.ts` + - `src/lib/usage/costCalculator.ts` +- [ ] Expand route coverage for proxy management and settings branches + +### Phase 4: 70% -> 75% + +- [ ] Cover translator helpers and central translation paths: + - `open-sse/translator/index.ts` + - `open-sse/translator/helpers/*` + - `open-sse/translator/request/*` + - `open-sse/translator/response/*` + +### Phase 5: 75% -> 80% + +- [ ] Add handler-level tests for: + - `open-sse/handlers/chatCore.ts` + - `open-sse/handlers/responsesHandler.js` + - `open-sse/handlers/imageGeneration.js` + - `open-sse/handlers/embeddings.js` +- [ ] Add executor branch coverage for provider-specific auth, retries, and endpoint overrides + +### Phase 6: 80% -> 85% + +- [ ] Merge more edge-case suites into the main coverage path +- [ ] Increase function coverage for DB modules with weak constructor/helper coverage +- [ ] Close branch gaps in `settings.ts`, `registeredKeys.ts`, `validation.ts`, and translator helpers + +### Phase 7: 85% -> 90% + +- [ ] Treat the remaining low-coverage files as blockers +- [ ] Add regression tests for every uncovered production bug fixed during the push to 90% +- [ ] Raise the coverage gate in CI only after the local baseline is stable for at least two consecutive runs + +## Ratchet policy + +Update `npm run test:coverage` thresholds only after the project actually exceeds the next milestone with a comfortable buffer. + +Recommended ratchet sequence: + +1. 55/60/55 +2. 60/62/58 +3. 65/64/62 +4. 70/66/66 +5. 75/70/72 +6. 80/75/78 +7. 85/80/84 +8. 90/85/88 + +Order is `statements-lines / branches / functions`. + +## Known gap + +The current coverage command measures the main Node unit suite and includes source reached from it, including `open-sse`. It does not yet merge Vitest coverage into a single unified report. That merge is worth doing later, but it is not a blocker for starting the 60% -> 80% climb. diff --git a/docs/i18n/ar/docs/FEATURES.md b/docs/i18n/ar/docs/FEATURES.md index bfcb823b16..9e2f7279ea 100644 --- a/docs/i18n/ar/docs/FEATURES.md +++ b/docs/i18n/ar/docs/FEATURES.md @@ -1,6 +1,6 @@ # OmniRoute โ€” Dashboard Features Gallery (ุงู„ุนุฑุจูŠุฉ) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/FEATURES.md) --- @@ -10,7 +10,7 @@ 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). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. ![Providers Dashboard](screenshots/01-providers.png) diff --git a/docs/i18n/ar/docs/MCP-SERVER.md b/docs/i18n/ar/docs/MCP-SERVER.md new file mode 100644 index 0000000000..ab8c27c157 --- /dev/null +++ b/docs/i18n/ar/docs/MCP-SERVER.md @@ -0,0 +1,87 @@ +# OmniRoute MCP Server Documentation (ุงู„ุนุฑุจูŠุฉ) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/MCP-SERVER.md) + +--- + +> Model Context Protocol server with 16 intelligent tools + +## ุชุซุจูŠุช + +OmniRoute MCP is built-in. Start it with: + +```bash +omniroute --mcp +``` + +Or via the open-sse transport: + +```bash +# HTTP streamable transport (port 20130) +omniroute --dev # MCP auto-starts on /mcp endpoint +``` + +## IDE Configuration + +See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup. + +--- + +## Essential Tools (8) + +| Tool | Description | +| :------------------------------ | :--------------------------------------- | +| `omniroute_get_health` | Gateway health, circuit breakers, uptime | +| `omniroute_list_combos` | All configured combos with models | +| `omniroute_get_combo_metrics` | Performance metrics for a specific combo | +| `omniroute_switch_combo` | Switch active combo by ID/name | +| `omniroute_check_quota` | Quota status per provider or all | +| `omniroute_route_request` | Send a chat completion through OmniRoute | +| `omniroute_cost_report` | Cost analytics for a time period | +| `omniroute_list_models_catalog` | Full model catalog with capabilities | + +## Advanced Tools (8) + +| Tool | Description | +| :--------------------------------- | :---------------------------------------------------------- | +| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | +| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | +| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | +| `omniroute_test_combo` | Live-test all models in a combo via a real upstream request | +| `omniroute_get_provider_metrics` | Detailed metrics for one provider | +| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | +| `omniroute_explain_route` | Explain a past routing decision | +| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | + +## Authentication + +MCP tools are authenticated via API key scopes. Each tool requires specific scopes: + +| Scope | Tools | +| :------------- | :----------------------------------------------- | +| `read:health` | get_health, get_provider_metrics | +| `read:combos` | list_combos, get_combo_metrics | +| `write:combos` | switch_combo | +| `read:quota` | check_quota | +| `write:route` | route_request, simulate_route, test_combo | +| `read:usage` | cost_report, get_session_snapshot, explain_route | +| `write:config` | set_budget_guard, set_resilience_profile | +| `read:models` | list_models_catalog, best_combo_for_task | + +## Audit Logging + +Every tool call is logged to `mcp_tool_audit` with: + +- Tool name, arguments, result +- Duration (ms), success/failure +- API key hash, timestamp + +## Files + +| File | Purpose | +| :------------------------------------------- | :------------------------------------------ | +| `open-sse/mcp-server/server.ts` | MCP server creation + 16 tool registrations | +| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport | +| `open-sse/mcp-server/auth.ts` | API key + scope validation | +| `open-sse/mcp-server/audit.ts` | Tool call audit logging | +| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers | diff --git a/docs/i18n/ar/docs/RELEASE_CHECKLIST.md b/docs/i18n/ar/docs/RELEASE_CHECKLIST.md new file mode 100644 index 0000000000..51d2cb71ed --- /dev/null +++ b/docs/i18n/ar/docs/RELEASE_CHECKLIST.md @@ -0,0 +1,37 @@ +# Release Checklist (ุงู„ุนุฑุจูŠุฉ) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/RELEASE_CHECKLIST.md) + +--- + +Use this checklist before tagging or publishing a new OmniRoute release. + +## Version and Changelog + +1. Bump `package.json` version (`x.y.z`) in the release branch. +2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: + - `## [x.y.z] โ€” YYYY-MM-DD` +3. Keep `## [Unreleased]` as the first changelog section for upcoming work. +4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. + +## API Docs + +1. Update `docs/openapi.yaml`: + - `info.version` must equal `package.json` version. +2. Validate endpoint examples if API contracts changed. + +## Runtime Docs + +1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. +2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. +3. Update localized docs if source docs changed significantly. + +## Automated Check + +Run the sync guard locally before opening PR: + +```bash +npm run check:docs-sync +``` + +CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/da/TROUBLESHOOTING.md b/docs/i18n/ar/docs/TROUBLESHOOTING.md similarity index 77% rename from docs/i18n/da/TROUBLESHOOTING.md rename to docs/i18n/ar/docs/TROUBLESHOOTING.md index 63c148000a..2bbdea5394 100644 --- a/docs/i18n/da/TROUBLESHOOTING.md +++ b/docs/i18n/ar/docs/TROUBLESHOOTING.md @@ -1,11 +1,9 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/TROUBLESHOOTING.md) +# Troubleshooting (ุงู„ุนุฑุจูŠุฉ) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/TROUBLESHOOTING.md) --- -# Troubleshooting - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/TROUBLESHOOTING.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/TROUBLESHOOTING.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/TROUBLESHOOTING.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/TROUBLESHOOTING.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/TROUBLESHOOTING.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/TROUBLESHOOTING.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/TROUBLESHOOTING.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/TROUBLESHOOTING.md) - Common problems and solutions for OmniRoute. --- diff --git a/docs/i18n/ar/USER_GUIDE.md b/docs/i18n/ar/docs/USER_GUIDE.md similarity index 82% rename from docs/i18n/ar/USER_GUIDE.md rename to docs/i18n/ar/docs/USER_GUIDE.md index cc5cd9715c..fec281bdac 100644 --- a/docs/i18n/ar/USER_GUIDE.md +++ b/docs/i18n/ar/docs/USER_GUIDE.md @@ -1,8 +1,6 @@ # User Guide (ุงู„ุนุฑุจูŠุฉ) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/USER_GUIDE.md) - -> ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/USER_GUIDE.md) --- @@ -320,7 +318,7 @@ Model: cc/claude-opus-4-6 --- -## ๐Ÿš€ Deployment +## ุงู„ู†ุดุฑ ### Global npm install (Recommended) @@ -511,23 +509,26 @@ post_install() { ### Environment Variables -| Variable | Default | Description | -| ------------------------- | ------------------------------------ | ------------------------------------------------------- | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | -| `INITIAL_PASSWORD` | `123456` | First login password | -| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | -| `PORT` | framework default | Service port (`20128` in examples) | -| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | -| `NODE_ENV` | runtime default | Set `production` for deploy | -| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | -| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | -| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | -| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | -| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | -| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | -| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | -| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | +| 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/*` | +| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand | +| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | For the full environment variable reference, see the [README](../README.md). @@ -598,6 +599,11 @@ curl -X POST http://localhost:20128/api/provider-models \ Or use Dashboard: **Providers โ†’ [Provider] โ†’ Custom Models**. +Notes: + +- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers. +- The **Custom Models** section is intended for providers that do not expose managed available-model imports. + ### Dedicated Provider Routes Route requests directly to a specific provider with model validation: @@ -642,6 +648,14 @@ Returns models grouped by provider with types (`chat`, `embedding`, `image`). - Automatic background sync with timeout + fail-fast - Prefer server-side `BASE_URL`/`CLOUD_URL` in production +### Cloudflare Quick Tunnel + +- Available in **Dashboard โ†’ Endpoints** for Docker and other self-hosted deployments +- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint +- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary +- Tunnel URLs are ephemeral and change every time you stop/start the tunnel +- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download + ### LLM Gateway Intelligence (Phase 9) - **Semantic Cache** โ€” Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) @@ -757,11 +771,11 @@ OmniRoute implements provider-level resilience with four components: 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 | +| 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 unless `DISABLE_SQLITE_AUTO_BACKUP=true` | ```bash # API: Export database @@ -787,10 +801,11 @@ curl -X POST http://localhost:20128/api/db-backups/import \ ### Settings Dashboard -The settings page is organized into 5 tabs for easy navigation: +The settings page is organized into 6 tabs for easy navigation: | Tab | Contents | | -------------- | ---------------------------------------------------------------------------------------------- | +| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility | | **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | | **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | | **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | diff --git a/docs/i18n/ar/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/ar/docs/VM_DEPLOYMENT_GUIDE.md new file mode 100644 index 0000000000..e43cb85ad4 --- /dev/null +++ b/docs/i18n/ar/docs/VM_DEPLOYMENT_GUIDE.md @@ -0,0 +1,403 @@ +# OmniRoute โ€” Deployment Guide on VM with Cloudflare (ุงู„ุนุฑุจูŠุฉ) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/VM_DEPLOYMENT_GUIDE.md) + +--- + +Complete guide to install and configure OmniRoute on a VM (VPS) with domain managed via Cloudflare. + +--- + +## Prerequisites + +| Item | Minimum | Recommended | +| ---------- | ------------------------ | ---------------- | +| **CPU** | 1 vCPU | 2 vCPU | +| **RAM** | 1 GB | 2 GB | +| **Disk** | 10 GB SSD | 25 GB SSD | +| **OS** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS | +| **Domain** | Registered on Cloudflare | โ€” | +| **Docker** | Docker Engine 24+ | Docker 27+ | + +**Tested providers**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. + +--- + +## 1. Configure the VM + +### 1.1 Create the instance + +On your preferred VPS provider: + +- Choose Ubuntu 24.04 LTS +- Select the minimum plan (1 vCPU / 1 GB RAM) +- Set a strong root password or configure SSH key +- Note the **public IP** (e.g., `203.0.113.10`) + +### 1.2 Connect via SSH + +```bash +ssh root@203.0.113.10 +``` + +### 1.3 Update the system + +```bash +apt update && apt upgrade -y +``` + +### 1.4 Install Docker + +```bash +# Install dependencies +apt install -y ca-certificates curl gnupg + +# Add official Docker repository +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 Install nginx + +```bash +apt install -y nginx +``` + +### 1.6 Configure 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 +``` + +> **Tip**: For maximum security, restrict ports 80 and 443 to Cloudflare IPs only. See the [Advanced Security](#advanced-security) section. + +--- + +## 2. Install OmniRoute + +### 2.1 Create configuration directory + +```bash +mkdir -p /opt/omniroute +``` + +### 2.2 Create environment variables file + +```bash +cat > /opt/omniroute/.env << โ€˜EOFโ€™ +# === Security === +JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY +INITIAL_PASSWORD=YourSecurePassword123! +API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY +STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY +STORAGE_ENCRYPTION_KEY_VERSION=v1 +MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT + +# === 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 (change to your domain) === +BASE_URL=https://llms.seudominio.com +NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com + +# === Cloud Sync (optional) === +# CLOUD_URL=https://cloud.omniroute.online +# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online +EOF +``` + +> โš ๏ธ **IMPORTANT**: Generate unique secret keys! Use `openssl rand -hex 32` for each key. + +### 2.3 Start the 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 Verify that it is running + +```bash +docker ps | grep omniroute +docker logs omniroute --tail 20 +``` + +It should display: `[DB] SQLite database ready` and `listening on port 20128`. + +--- + +## 3. Configure nginx (Reverse Proxy) + +### 3.1 Generate SSL certificate (Cloudflare Origin) + +In the Cloudflare dashboard: + +1. Go to **SSL/TLS โ†’ Origin Server** +2. Click **Create Certificate** +3. Keep the defaults (15 years, \*.yourdomain.com) +4. Copy the **Origin Certificate** and the **Private Key** + +```bash +mkdir -p /etc/nginx/ssl + +# Paste the certificate +nano /etc/nginx/ssl/origin.crt + +# Paste the private key +nano /etc/nginx/ssl/origin.key + +chmod 600 /etc/nginx/ssl/origin.key +``` + +### 3.2 Nginx Configuration + +```bash +cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ +# Default server โ€” blocks direct access via 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.yourdomain.com; # Change to your domain + + 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.yourdomain.com; + return 301 https://$server_name$request_uri; +} +NGINX +``` + +### 3.3 Enable and Test + +```bash +# Remove default configuration +rm -f /etc/nginx/sites-enabled/default + +# Enable OmniRoute +ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute + +# Test and reload +nginx -t && systemctl reload nginx +``` + +--- + +## 4. Configure Cloudflare DNS + +### 4.1 Add DNS record + +In the Cloudflare dashboard โ†’ DNS: + +| Type | Name | Content | Proxy | +| ---- | ------ | ---------------------- | ---------- | +| A | `llms` | `203.0.113.10` (VM IP) | โœ… Proxied | + +### 4.2 Configure SSL + +Under **SSL/TLS โ†’ Overview**: + +- Mode: **Full (Strict)** + +Under **SSL/TLS โ†’ Edge Certificates**: + +- Always Use HTTPS: โœ… On +- Minimum TLS Version: TLS 1.2 +- Automatic HTTPS Rewrites: โœ… On + +### 4.3 Testing + +```bash +curl -sI https://llms.seudominio.com/health +# Should return HTTP/2 200 +``` + +--- + +## 5. Operations and Maintenance + +### Upgrade to a new version + +```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 +``` + +### View logs + +```bash +docker logs -f omniroute # Real-time stream +docker logs omniroute --tail 50 # Last 50 lines +``` + +### Manual database backup + +```bash +# Copy data from the volume to the host +docker cp omniroute:/app/data ./backup-$(date +%F) + +# Or compress the entire volume +docker run --rm -v omniroute-data:/data -v $(pwd):/backup \ + alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data +``` + +### Restore from 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. Advanced Security + +### Restrict nginx to Cloudflare IPs + +```bash +cat > /etc/nginx/cloudflare-ips.conf << โ€˜CFโ€™ +# Cloudflare IPv4 ranges โ€” update periodically +# 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 +``` + +Add the following to `nginx.conf` inside the `http {}` block: + +```nginx +include /etc/nginx/cloudflare-ips.conf; +``` + +### Install fail2ban + +```bash +apt install -y fail2ban +systemctl enable fail2ban +systemctl start fail2ban + +# Check status +fail2ban-client status sshd +``` + +### Block direct access to the Docker port + +```bash +# Prevent direct external access to port 20128 +iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP +iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT + +# Persist the rules +apt install -y iptables-persistent +netfilter-persistent save +``` + +--- + +## 7. Deploy to Cloudflare Workers (Optional) + +For remote access via Cloudflare Workers (without exposing the VM directly): + +```bash +# In the local repository +cd omnirouteCloud +npm install +npx wrangler login +npx wrangler deploy +``` + +See the full documentation at [omnirouteCloud/README.md](../omnirouteCloud/README.md). + +--- + +## Port Summary + +| Port | Service | Access | +| ----- | ----------- | -------------------------- | +| 22 | SSH | Public (with fail2ban) | +| 80 | nginx HTTP | Redirect โ†’ HTTPS | +| 443 | nginx HTTPS | Via Cloudflare Proxy | +| 20128 | OmniRoute | Localhost only (via nginx) | diff --git a/docs/i18n/ar/src/lib/a2a/README.md b/docs/i18n/ar/src/lib/a2a/README.md new file mode 100644 index 0000000000..2ded085cac --- /dev/null +++ b/docs/i18n/ar/src/lib/a2a/README.md @@ -0,0 +1,752 @@ +# OmniRoute A2A Server (ุงู„ุนุฑุจูŠุฉ) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../../../src/lib/a2a/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../../../es/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../../../fr/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../../../de/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../../../it/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../../../ru/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../../../zh-CN/src/lib/a2a/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../../../ja/src/lib/a2a/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../../../ko/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../../../ar/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../../../in/src/lib/a2a/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../../../th/src/lib/a2a/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../../../vi/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../../../id/src/lib/a2a/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../../../ms/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../../../nl/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../../../pl/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../../../sv/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../../../no/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../../../da/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../../../fi/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../../../pt/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../../../ro/src/lib/a2a/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../../../hu/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../../../bg/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../../../sk/src/lib/a2a/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../../../uk-UA/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../../../he/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../../../phi/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../../../pt-BR/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../../../cs/src/lib/a2a/README.md) + +--- + +> **Agent-to-Agent Protocol v0.3** โ€” Enables any AI agent to use OmniRoute as an intelligent routing agent via JSON-RPC 2.0. + +The A2A Server exposes OmniRoute as a **first-class agent** that other agents can discover, delegate tasks to, and collaborate with using the [A2A Protocol](https://google.github.io/A2A/). + +--- + +## ุงู„ู‡ู†ุฏุณุฉ + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Orchestrator Agent โ”‚ +โ”‚ (LangChain, CrewAI, AutoGen, Custom Agent) โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ 1. GET /.well-known/agent.json (discover) + โ”‚ 2. POST /a2a (JSON-RPC 2.0) + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ OmniRoute A2A Server โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Task Manager โ”‚ โ”‚ Skill Engine โ”‚ โ”‚ SSE Streaming โ”‚ โ”‚ +โ”‚ โ”‚ (lifecycle) โ”‚โ”€โ”€โ”‚ (registry) โ”‚โ”€โ”€โ”‚ (real-time) โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ +โ”‚ Skills: โ”‚ โ”‚ +โ”‚ โ”œโ”€ smart-routing โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ””โ”€ quota-management โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ Routing Decision Logger โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ OmniRoute Gateway (internal) + /v1/chat/completions, /api/combos, /api/usage/quota +``` + +--- + +## ุจุฏุงูŠุฉ ุณุฑูŠุนุฉ + +### Agent Discovery + +Every A2A-compatible agent exposes an **Agent Card** at `/.well-known/agent.json`: + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +**Response:** + +```json +{ + "name": "OmniRoute", + "description": "Intelligent AI gateway with auto-routing across 50+ providers", + "url": "http://localhost:20128/a2a", + "version": "1.8.1", + "capabilities": { + "streaming": true, + "pushNotifications": false + }, + "skills": [ + { + "id": "smart-routing", + "name": "Smart Routing", + "description": "Routes prompts through OmniRoute intelligent pipeline", + "tags": ["routing", "llm", "multi-provider", "cost-optimization"], + "examples": [ + "Write a hello world in Python", + "Explain quantum computing using the cheapest provider" + ] + }, + { + "id": "quota-management", + "name": "Quota Management", + "description": "Natural-language queries about provider quotas", + "tags": ["quota", "analytics", "cost"], + "examples": [ + "Which provider has the most quota remaining?", + "Suggest a free combo for coding" + ] + } + ], + "authentication": { + "schemes": ["bearer"], + "apiKeyHeader": "Authorization" + } +} +``` + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Send a message to a skill and receive the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python hello world"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "a1b2c3d4-...", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "print('Hello, World!')" }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.0030)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "2026-03-04T..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"Quantum computing..."}}} + +: heartbeat 2026-03-04T21:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Running Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Skills Reference + +### `smart-routing` + +Routes prompts through OmniRoute's intelligent pipeline with full observability. + +**Parameters (in `metadata`):** + +| Parameter | Type | Default | Description | +| --------- | -------- | ------------ | ---------------------------------------------------------------------------------------- | +| `model` | `string` | `"auto"` | Target model (e.g., `claude-sonnet-4`, `gpt-4o`, `auto`) | +| `combo` | `string` | active combo | Specific combo to route through | +| `budget` | `number` | none | Maximum cost in USD for this request | +| `role` | `string` | none | Task role hint: `coding`, `review`, `planning`, `analysis`, `debugging`, `documentation` | + +**Returns:** + +| Field | Description | +| ------------------------------ | --------------------------------------------------------- | +| `artifacts[].content` | The LLM response text | +| `metadata.routing_explanation` | Human-readable explanation of routing decision | +| `metadata.cost_envelope` | Estimated vs actual cost with currency | +| `metadata.resilience_trace` | Array of events (primary_selected, fallback_needed, etc.) | +| `metadata.policy_verdict` | Whether the request was allowed and why | + +### `quota-management` + +Answers natural-language queries about provider quotas. + +**Query types (inferred from message content):** + +| Query Pattern | Response Type | +| ---------------------------------------------- | -------------------------------------------------------- | +| Contains `"ranking"`, `"most quota"`, `"best"` | Providers ranked by remaining quota | +| Contains `"free"`, `"suggest"` | Lists free combos or suggests free-tier providers | +| Default | Full quota summary with warnings for low-quota providers | + +--- + +## Task Lifecycle + +``` +submitted โ”€โ”€โ†’ working โ”€โ”€โ†’ completed + โ”€โ”€โ†’ failed + โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ†’ cancelled +``` + +| State | Description | +| ----------- | ----------------------------------------------------- | +| `submitted` | Task created, queued for execution | +| `working` | Skill handler is executing | +| `completed` | Execution succeeded, artifacts available | +| `failed` | Execution failed or task expired (TTL: 5 min default) | +| `cancelled` | Cancelled by client via `tasks/cancel` | + +- Terminal states: `completed`, `failed`, `cancelled` (no further transitions) +- Expired tasks in `submitted` or `working` are auto-marked as `failed` +- Tasks are garbage-collected after 2ร— TTL + +--- + +## Client Examples + +### Python โ€” Orchestrator Agent + +```python +""" +A2A Client โ€” Python example. +Discovers OmniRoute agent, sends a task, and processes the result. +""" +import requests +import json + +BASE_URL = "http://localhost:20128" +API_KEY = "your-api-key" +HEADERS = { + "Content-Type": "application/json", + "Authorization": f"Bearer {API_KEY}", +} + +# 1. Discover agent capabilities +agent_card = requests.get(f"{BASE_URL}/.well-known/agent.json").json() +print(f"Agent: {agent_card['name']} v{agent_card['version']}") +print(f"Skills: {[s['id'] for s in agent_card['skills']]}") + +# 2. Send a smart-routing task +response = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python quicksort implementation"}], + "metadata": { + "model": "auto", + "combo": "fast-coding", + "budget": 0.10, + } + } +}) +result = response.json()["result"] +print(f"\n๐Ÿ“ Response: {result['artifacts'][0]['content'][:200]}...") +print(f"๐Ÿ”€ Routing: {result['metadata']['routing_explanation']}") +print(f"๐Ÿ’ฐ Cost: ${result['metadata']['cost_envelope']['actual']}") +print(f"๐Ÿ›ก๏ธ Policy: {result['metadata']['policy_verdict']['reason']}") + +# 3. Query quota status +quota_resp = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-2", + "method": "message/send", + "params": { + "skill": "quota-management", + "messages": [{"role": "user", "content": "Which provider has the most quota remaining?"}], + } +}) +quota_result = quota_resp.json()["result"] +print(f"\n๐Ÿ“Š Quota: {quota_result['artifacts'][0]['content']}") +``` + +### TypeScript โ€” Multi-Agent Orchestrator + +```typescript +/** + * A2A Client โ€” TypeScript example. + * Shows agent discovery, task delegation, and streaming. + */ + +const BASE_URL = "http://localhost:20128"; +const API_KEY = "your-api-key"; + +interface JsonRpcResponse { + jsonrpc: "2.0"; + id: string | number; + result?: T; + error?: { code: number; message: string }; +} + +async function a2aCall(method: string, params: Record): Promise { + const resp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: `${method}-${Date.now()}`, + method, + params, + }), + }); + const json: JsonRpcResponse = await resp.json(); + if (json.error) throw new Error(`[${json.error.code}] ${json.error.message}`); + return json.result!; +} + +// โ”€โ”€ Agent Discovery โ”€โ”€ +const agentCard = await fetch(`${BASE_URL}/.well-known/agent.json`).then((r) => r.json()); +console.log(`Connected to: ${agentCard.name} (${agentCard.skills.length} skills)`); + +// โ”€โ”€ Smart Routing: Send a coding task โ”€โ”€ +const routingResult = await a2aCall("message/send", { + skill: "smart-routing", + messages: [{ role: "user", content: "Implement a Redis cache wrapper in TypeScript" }], + metadata: { model: "claude-sonnet-4", role: "coding" }, +}); +console.log("Response:", routingResult.artifacts[0].content); +console.log("Provider:", routingResult.metadata.routing_explanation); + +// โ”€โ”€ Quota Management: Find free alternatives โ”€โ”€ +const quotaResult = await a2aCall("message/send", { + skill: "quota-management", + messages: [{ role: "user", content: "Suggest free combos for documentation" }], +}); +console.log("Free combos:", quotaResult.artifacts[0].content); + +// โ”€โ”€ Streaming: Real-time response โ”€โ”€ +const streamResp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "stream-1", + method: "message/stream", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Explain microservices architecture" }], + }, + }), +}); + +const reader = streamResp.body!.getReader(); +const decoder = new TextDecoder(); +while (true) { + const { done, value } = await reader.read(); + if (done) break; + const chunk = decoder.decode(value); + for (const line of chunk.split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + if (event.params.chunk) { + process.stdout.write(event.params.chunk.content); + } + if (event.params.task.state === "completed") { + console.log("\nโœ… Stream completed"); + } + } + } +} +``` + +### Python โ€” LangChain A2A Integration + +```python +""" +LangChain integration โ€” Use OmniRoute A2A as a custom LLM. +""" +from langchain.llms.base import BaseLLM +from langchain.schema import LLMResult, Generation +import requests +from typing import List, Optional + +class OmniRouteA2A(BaseLLM): + base_url: str = "http://localhost:20128" + api_key: str = "" + model: str = "auto" + combo: Optional[str] = None + + @property + def _llm_type(self) -> str: + return "omniroute-a2a" + + def _call(self, prompt: str, stop: Optional[List[str]] = None, **kwargs) -> str: + response = requests.post( + f"{self.base_url}/a2a", + headers={ + "Content-Type": "application/json", + "Authorization": f"Bearer {self.api_key}", + }, + json={ + "jsonrpc": "2.0", + "id": "langchain-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": prompt}], + "metadata": { + "model": self.model, + **({"combo": self.combo} if self.combo else {}), + }, + }, + }, + ) + result = response.json()["result"] + return result["artifacts"][0]["content"] + + def _generate(self, prompts: List[str], stop=None, **kwargs) -> LLMResult: + return LLMResult( + generations=[[Generation(text=self._call(p, stop))] for p in prompts] + ) + +# Usage +llm = OmniRouteA2A( + base_url="http://localhost:20128", + api_key="your-key", + model="auto", + combo="fast-coding", +) +result = llm("Write a Python function to merge two sorted lists") +print(result) +``` + +### Go โ€” A2A Client + +```go +package main + +import ( + "bytes" + "encoding/json" + "fmt" + "io" + "net/http" +) + +const baseURL = "http://localhost:20128" +const apiKey = "your-api-key" + +type JsonRpcRequest struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Method string `json:"method"` + Params interface{} `json:"params"` +} + +type JsonRpcResponse struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Result interface{} `json:"result"` + Error *struct { + Code int `json:"code"` + Message string `json:"message"` + } `json:"error"` +} + +func a2aCall(method string, params interface{}) (*JsonRpcResponse, error) { + body, _ := json.Marshal(JsonRpcRequest{ + Jsonrpc: "2.0", + ID: "go-1", + Method: method, + Params: params, + }) + + req, _ := http.NewRequest("POST", baseURL+"/a2a", bytes.NewReader(body)) + req.Header.Set("Content-Type", "application/json") + req.Header.Set("Authorization", "Bearer "+apiKey) + + resp, err := http.DefaultClient.Do(req) + if err != nil { + return nil, err + } + defer resp.Body.Close() + data, _ := io.ReadAll(resp.Body) + + var result JsonRpcResponse + json.Unmarshal(data, &result) + return &result, nil +} + +func main() { + // Discover agent + resp, _ := http.Get(baseURL + "/.well-known/agent.json") + defer resp.Body.Close() + body, _ := io.ReadAll(resp.Body) + fmt.Println("Agent Card:", string(body)) + + // Send smart-routing task + result, _ := a2aCall("message/send", map[string]interface{}{ + "skill": "smart-routing", + "messages": []map[string]string{{"role": "user", "content": "Hello from Go!"}}, + "metadata": map[string]interface{}{"model": "auto"}, + }) + out, _ := json.MarshalIndent(result.Result, "", " ") + fmt.Println("Result:", string(out)) +} +``` + +--- + +## Use Cases + +### ๐Ÿค– Use Case 1: Multi-Agent Coding Pipeline + +An orchestrator agent delegates code generation to OmniRoute, then passes the output to a review agent. + +```python +def coding_pipeline(task: str): + # Step 1: Generate code via OmniRoute A2A + code_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Write production-quality code: {task}"} + ], metadata={"model": "auto", "role": "coding"}) + code = code_result["artifacts"][0]["content"] + + # Step 2: Review the code via OmniRoute A2A (different model) + review_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Review this code for bugs and improvements:\n\n{code}"} + ], metadata={"model": "auto", "role": "review"}) + review = review_result["artifacts"][0]["content"] + + # Step 3: Check costs + print(f"Code cost: ${code_result['metadata']['cost_envelope']['actual']}") + print(f"Review cost: ${review_result['metadata']['cost_envelope']['actual']}") + + return {"code": code, "review": review} +``` + +### ๐Ÿ’ก Use Case 2: Quota-Aware Agent Swarm + +Multiple agents share quota through OmniRoute, using the quota skill to coordinate. + +```python +async def quota_aware_agent(agent_name: str, task: str): + # Check quota before starting + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Which provider has the most quota remaining?"} + ]) + print(f"[{agent_name}] {quota['artifacts'][0]['content']}") + + # Send request with budget constraint + result = a2a_send("smart-routing", [ + {"role": "user", "content": task} + ], metadata={"budget": 0.05}) + + policy = result["metadata"]["policy_verdict"] + if not policy["allowed"]: + print(f"[{agent_name}] โš ๏ธ Budget exceeded: {policy['reason']}") + # Fall back to free combo + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Suggest free combos"} + ]) + print(f"[{agent_name}] Free alternatives: {quota['artifacts'][0]['content']}") + + return result +``` + +### ๐Ÿ“Š Use Case 3: Real-Time Streaming Dashboard + +A monitoring agent streams responses and displays progress in real-time. + +```typescript +async function streamingDashboard(prompt: string) { + const response = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { "Content-Type": "application/json", Authorization: `Bearer ${API_KEY}` }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "dash-1", + method: "message/stream", + params: { skill: "smart-routing", messages: [{ role: "user", content: prompt }] }, + }), + }); + + let totalChunks = 0; + const reader = response.body!.getReader(); + const decoder = new TextDecoder(); + + while (true) { + const { done, value } = await reader.read(); + if (done) break; + + for (const line of decoder.decode(value).split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + const state = event.params.task.state; + + if (state === "working" && event.params.chunk) { + totalChunks++; + process.stdout.write( + `\r[Chunk ${totalChunks}] ${event.params.chunk.content.slice(0, 50)}...` + ); + } + if (state === "completed") { + const meta = event.params.metadata; + console.log( + `\nโœ… Done | Cost: $${meta?.cost_envelope?.actual || 0} | Route: ${meta?.routing_explanation || "N/A"}` + ); + } + if (state === "failed") { + console.error(`\nโŒ Failed: ${event.params.metadata?.error}`); + } + } + } + } +} +``` + +### ๐Ÿ” Use Case 4: Task Polling Pattern + +For long-running tasks, poll the task status instead of waiting synchronously. + +```python +import time + +def poll_task(task_id: str, timeout: int = 60): + """Poll task status until completion or timeout.""" + start = time.time() + while time.time() - start < timeout: + result = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "poll-1", + "method": "tasks/get", + "params": {"taskId": task_id}, + }).json() + + task = result["result"]["task"] + state = task["state"] + print(f" Task {task_id[:8]}... state={state}") + + if state in ("completed", "failed", "cancelled"): + return task + time.sleep(2) + + # Timeout โ€” cancel the task + requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "cancel-1", + "method": "tasks/cancel", + "params": {"taskId": task_id}, + }) + raise TimeoutError(f"Task {task_id} timed out after {timeout}s") +``` + +--- + +## Error Codes + +| Code | Constant | Meaning | +| ------ | ------------------------ | ---------------------------------------- | +| -32700 | โ€” | Parse error (invalid JSON) | +| -32600 | `INVALID_REQUEST` | Invalid JSON-RPC request or unauthorized | +| -32601 | `METHOD_NOT_FOUND` | Unknown method or skill | +| -32602 | `INVALID_PARAMS` | Missing or invalid parameters | +| -32603 | `INTERNAL_ERROR` | Skill execution failed | +| -32001 | `TASK_NOT_FOUND` | Task ID not found | +| -32002 | `TASK_ALREADY_COMPLETED` | Cannot modify a completed task | +| -32003 | `UNAUTHORIZED` | Invalid or missing API key | +| -32004 | `BUDGET_EXCEEDED` | Request exceeds configured budget | +| -32005 | `PROVIDER_UNAVAILABLE` | No available providers | + +--- + +## Authentication + +All `/a2a` requests require a Bearer token via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server (`OMNIROUTE_API_KEY` is empty), authentication is bypassed. + +--- + +## File Structure + +``` +src/lib/a2a/ +โ”œโ”€โ”€ taskManager.ts # Task lifecycle (create/update/cancel/list), TTL, cleanup +โ”œโ”€โ”€ taskExecution.ts # Generic task executor with state management +โ”œโ”€โ”€ streaming.ts # SSE stream formatting, heartbeat, chunk/completion events +โ”œโ”€โ”€ routingLogger.ts # Routing decision logger (stats, history, retention) +โ””โ”€โ”€ skills/ + โ”œโ”€โ”€ smartRouting.ts # Smart routing skill (routes via /v1/chat/completions) + โ””โ”€โ”€ quotaManagement.ts # Quota management skill (natural-language quota queries) + +src/app/a2a/ +โ””โ”€โ”€ route.ts # Next.js API route handler (JSON-RPC 2.0 dispatch) + +open-sse/mcp-server/ +โ””โ”€โ”€ schemas/a2a.ts # Zod schemas (AgentCard, Task, JSON-RPC, SSE events) +``` + +--- + +## Comparison: MCP vs A2A + +| Feature | MCP Server | A2A Server | +| ----------------- | ---------------------------- | ------------------------------------------------- | +| **Protocol** | Model Context Protocol | Agent-to-Agent Protocol v0.3 | +| **Transport** | stdio / HTTP | HTTP (JSON-RPC 2.0) | +| **Discovery** | Tool listing via MCP | `/.well-known/agent.json` | +| **Granularity** | 16 individual tools | 2 high-level skills | +| **Best for** | IDE agents (Cursor, VS Code) | Multi-agent systems (LangChain, CrewAI) | +| **Streaming** | Not supported | SSE via `message/stream` | +| **Task tracking** | No | Full lifecycle (submitted โ†’ completed) | +| **Observability** | Audit log per tool call | Cost envelope + resilience trace + policy verdict | + +--- + +## ุงู„ุฑุฎุตุฉ + +Part of [OmniRoute](https://github.com/diegosouzapw/OmniRoute) โ€” MIT License. diff --git a/docs/i18n/bg/CHANGELOG.md b/docs/i18n/bg/CHANGELOG.md index 1a1b54d984..ad4d497a74 100644 --- a/docs/i18n/bg/CHANGELOG.md +++ b/docs/i18n/bg/CHANGELOG.md @@ -1,12 +1,92 @@ # Changelog (ะ‘ัŠะปะณะฐั€ัะบะธ) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CHANGELOG.md) --- - ## [Unreleased] +### ๐Ÿ› ๏ธ Maintenance + +- **AGENTS.md rewrite:** Condensed from 297โ†’153 lines. Added build/lint/test commands (including single-test execution), code style guidelines (Prettier, TypeScript, ESLint, naming, imports, error handling, security), and trimmed verbose architecture tables for AI agent consumption. + +## [3.4.2] - 2026-04-01 + +### ๐Ÿ› Bug Fixes + +- **CI Stabilization:** Fixed failing analytics/settings Playwright selectors and request assertions so GitHub Actions E2E runs pass reliably across localized UIs and switch-based controls. +- **Deterministic Tests:** Removed date-sensitive quota fixtures from Copilot usage tests and aligned idempotency/model catalog tests with the merged runtime behavior. +- **MCP Type Hardening:** Removed zero-budget explicit `any` regressions from the MCP server tool registration path, restoring the `check:any-budget:t11` workflow gate. + +### ๐Ÿ› ๏ธ Maintenance + +- **Release Branch Integration:** Consolidated the active feature branches into `release/v3.4.2` on top of current `main` and validated the branch with lint, unit, coverage, build, and CI-mode E2E runs. + +## [3.4.1] - 2026-03-31 + +> [!WARNING] +> **BREAKING CHANGE: request logging, retention, and logging environment variables have been redesigned.** +> On the first startup after upgrading, OmniRoute archives legacy request logs from `DATA_DIR/logs/`, legacy `DATA_DIR/call_logs/`, and `DATA_DIR/log.txt` into `DATA_DIR/log_archives/*.zip`, then removes the deprecated layout and switches to the new unified artifact format under `DATA_DIR/call_logs/`. + +### โœจ New Features + +- **.ENV Migration Utility:** Included `scripts/migrate-env.mjs` to seamlessly migrate `= 18 < 24 (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` | `20128` | Server port | +| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | Base URL for frontend | +| `JWT_SECRET` | (generate above) | JWT signing secret | +| `INITIAL_PASSWORD` | `CHANGEME` | First login password | +| `APP_LOG_LEVEL` | `info` | Log verbosity level | + +### Dashboard Settings + +The dashboard provides UI toggles for features that can also be configured via environment variables: + +| Setting Location | Toggle | Description | +| ------------------- | ------------------ | ------------------------------ | +| Settings โ†’ Advanced | Debug Mode | Enable debug request logs (UI) | +| Settings โ†’ General | Sidebar Visibility | Show/hide sidebar sections | + +These settings are stored in the database and persist across restarts, overriding env var defaults when set. + +### 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:20128/dashboard` +- **API**: `http://localhost:20128/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`, `mcp`, `a2a`, `memory`, `skills`. + +--- + +## Running Tests + +```bash +# All tests (unit + vitest + ecosystem + e2e) +npm run test:all + +# Single test file (Node.js native test runner โ€” most tests use this) +node --import tsx/esm --test tests/unit/your-file.test.mjs + +# Vitest (MCP server, autoCombo, cache) +npm run test:vitest + +# E2E tests (requires Playwright) +npm run test:e2e + +# Protocol clients E2E (MCP transports, A2A) +npm run test:protocols:e2e + +# Ecosystem compatibility tests +npm run test:ecosystem + +# Coverage (55% min statements/lines/functions; 60% branches) +npm run test:coverage +npm run coverage:report + +# Lint + format check +npm run lint +npm run check +``` + +Coverage notes: + +- `npm run test:coverage` measures source coverage for the main unit test suite, excludes `tests/**`, and includes `open-sse/**` +- `npm run coverage:report` prints the detailed file-by-file report from the latest coverage run +- `npm run test:coverage:legacy` preserves the older metric for historical comparison +- See `docs/COVERAGE_PLAN.md` for the phased coverage improvement roadmap + +Current test status: **122 unit test files** covering: + +- Provider translators and format conversion +- Rate limiting, circuit breaker, and resilience +- Semantic cache, idempotency, progress tracking +- Database operations and schema (21 DB modules) +- OAuth flows and authentication +- API endpoint validation (Zod v4) +- MCP server tools and scope enforcement +- Memory and Skills systems + +--- + +## Code Style + +- **ESLint** โ€” Run `npm run lint` before committing +- **Prettier** โ€” Auto-formatted via `lint-staged` on commit (2 spaces, semicolons, double quotes, 100 char width, es5 trailing commas) +- **TypeScript** โ€” All `src/` code uses `.ts`/`.tsx`; `open-sse/` uses `.ts`/`.js`; document with TSDoc (`@param`, `@returns`, `@throws`) +- **No `eval()`** โ€” ESLint enforces `no-eval`, `no-implied-eval`, `no-new-func` +- **Zod validation** โ€” Use Zod v4 schemas for all API input validation +- **Naming**: Files = camelCase/kebab-case, components = PascalCase, constants = UPPER_SNAKE + +--- + +## Project Structure + +``` +src/ # TypeScript (.ts / .tsx) +โ”œโ”€โ”€ app/ # Next.js 16 App Router +โ”‚ โ”œโ”€โ”€ (dashboard)/ # Dashboard pages (23 sections) +โ”‚ โ”œโ”€โ”€ api/ # API routes (51 directories) +โ”‚ โ””โ”€โ”€ login/ # Auth pages (.tsx) +โ”œโ”€โ”€ domain/ # Policy engine (policyEngine, comboResolver, costRules, etc.) +โ”œโ”€โ”€ lib/ # Core business logic (.ts) +โ”‚ โ”œโ”€โ”€ a2a/ # Agent-to-Agent v0.3 protocol server +โ”‚ โ”œโ”€โ”€ acp/ # Agent Communication Protocol registry +โ”‚ โ”œโ”€โ”€ compliance/ # Compliance policy engine +โ”‚ โ”œโ”€โ”€ db/ # SQLite database layer (21 modules + 16 migrations) +โ”‚ โ”œโ”€โ”€ memory/ # Persistent conversational memory +โ”‚ โ”œโ”€โ”€ oauth/ # OAuth providers, services, and utilities +โ”‚ โ”œโ”€โ”€ skills/ # Extensible skill framework +โ”‚ โ”œโ”€โ”€ usage/ # Usage tracking and cost calculation +โ”‚ โ””โ”€โ”€ localDb.ts # Re-export layer only โ€” never add logic here +โ”œโ”€โ”€ middleware/ # Request middleware (promptInjectionGuard) +โ”œโ”€โ”€ mitm/ # MITM proxy (cert, DNS, target routing) +โ”œโ”€โ”€ shared/ +โ”‚ โ”œโ”€โ”€ components/ # React components (.tsx) +โ”‚ โ”œโ”€โ”€ constants/ # Provider definitions (60+), MCP scopes, routing strategies +โ”‚ โ”œโ”€โ”€ utils/ # Circuit breaker, sanitizer, auth helpers +โ”‚ โ””โ”€โ”€ validation/ # Zod v4 schemas +โ””โ”€โ”€ sse/ # SSE proxy pipeline + +open-sse/ # @omniroute/open-sse workspace +โ”œโ”€โ”€ executors/ # 14 provider-specific request executors +โ”œโ”€โ”€ handlers/ # 11 request handlers (chat, responses, embeddings, images, etc.) +โ”œโ”€โ”€ mcp-server/ # MCP server (25 tools, 3 transports, 10 scopes) +โ”œโ”€โ”€ services/ # 36+ services (combo, autoCombo, rateLimitManager, etc.) +โ”œโ”€โ”€ translator/ # Format translators (OpenAI โ†” Claude โ†” Gemini โ†” Responses โ†” Ollama) +โ”œโ”€โ”€ transformer/ # Responses API transformer +โ””โ”€โ”€ utils/ # 22 utility modules (stream, TLS, proxy, logging) + +electron/ # Electron desktop app (cross-platform) + +tests/ +โ”œโ”€โ”€ unit/ # Node.js test runner (122 test files) +โ”œโ”€โ”€ integration/ # Integration tests +โ”œโ”€โ”€ e2e/ # Playwright tests +โ”œโ”€โ”€ security/ # Security tests +โ”œโ”€โ”€ translator/ # Translator-specific tests +โ””โ”€โ”€ load/ # Load tests + +docs/ # Documentation +โ”œโ”€โ”€ ARCHITECTURE.md # System architecture +โ”œโ”€โ”€ API_REFERENCE.md # All endpoints +โ”œโ”€โ”€ USER_GUIDE.md # Provider setup, CLI integration +โ”œโ”€โ”€ TROUBLESHOOTING.md # Common issues +โ”œโ”€โ”€ MCP-SERVER.md # MCP server (25 tools) +โ”œโ”€โ”€ A2A-SERVER.md # A2A agent protocol +โ”œโ”€โ”€ AUTO-COMBO.md # Auto-combo engine +โ”œโ”€โ”€ CLI-TOOLS.md # CLI tools integration +โ”œโ”€โ”€ COVERAGE_PLAN.md # Test coverage improvement plan +โ”œโ”€โ”€ openapi.yaml # OpenAPI specification +โ””โ”€โ”€ adr/ # Architecture Decision Records +``` + +--- + +## Adding a New Provider + +### Step 1: Register Provider Constants + +Add to `src/shared/constants/providers.ts` โ€” Zod-validated at module load. + +### Step 2: Add Executor (if custom logic needed) + +Create executor in `open-sse/executors/your-provider.ts` extending the base executor. + +### Step 3: Add Translator (if non-OpenAI format) + +Create request/response translators in `open-sse/translator/`. + +### Step 4: Add OAuth Config (if OAuth-based) + +Add OAuth credentials in `src/lib/oauth/constants/oauth.ts` and service in `src/lib/oauth/services/`. + +### Step 5: Register Models + +Add model definitions in `open-sse/config/providerRegistry.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 +- [ ] All inputs validated with Zod schemas +- [ ] CHANGELOG updated (if user-facing change) +- [ ] Documentation updated (if applicable) + +--- + +## Releasing + +Releases are managed via the `/generate-release` workflow. When a new GitHub Release is created, the package is **automatically published to npm** via GitHub Actions. + +--- + +## Getting Help + +- **Architecture**: See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) +- **API Reference**: See [`docs/API_REFERENCE.md`](docs/API_REFERENCE.md) +- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **ADRs**: See `docs/adr/` for architectural decision records diff --git a/docs/i18n/bg/FEATURES.md b/docs/i18n/bg/FEATURES.md deleted file mode 100644 index 5df3ee54bf..0000000000 --- a/docs/i18n/bg/FEATURES.md +++ /dev/null @@ -1,147 +0,0 @@ -# OmniRoute โ€” Dashboard Features Gallery (ะ‘ัŠะปะณะฐั€ัะบะธ) - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) - -> ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../docs/FEATURES.md) - ---- - -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 (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. - -![Providers Dashboard](screenshots/01-providers.png) - ---- - -## ๐ŸŽจ Combos - -Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. - -![Combos Dashboard](screenshots/02-combos.png) - ---- - -## ๐Ÿ“Š Analytics - -Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. - -![Analytics Dashboard](screenshots/03-analytics.png) - ---- - -## ๐Ÿฅ System Health - -Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. - -![Health Dashboard](screenshots/04-health.png) - ---- - -## ๐Ÿ”ง Translator Playground - -Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). - -![Translator Playground](screenshots/05-translator.png) - ---- - -## ๐ŸŽฎ Model Playground _(v2.0.9+)_ - -Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. - ---- - -## ๐ŸŽจ Themes _(v2.0.5+)_ - -Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. - ---- - -## โš™๏ธ Settings - -Comprehensive settings panel with tabs: - -- **General** โ€” System storage, backup management (export/import database) -- **Appearance** โ€” Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls -- **Security** โ€” API endpoint protection, custom provider blocking, IP filtering, session info -- **Routing** โ€” Model aliases, background task degradation -- **Resilience** โ€” Rate limit persistence, circuit breaker tuning -- **Advanced** โ€” Configuration overrides - -![Settings Dashboard](screenshots/06-settings.png) - ---- - -## ๐Ÿ”ง CLI Tools - -One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. - -![CLI Tools Dashboard](screenshots/07-cli-tools.png) - ---- - -## ๐Ÿค– CLI Agents _(v2.0.11+)_ - -Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: - -- **Installation status** โ€” Installed / Not Found with version detection -- **Protocol badges** โ€” stdio, HTTP, etc. -- **Custom agents** โ€” Register any CLI tool via form (name, binary, version command, spawn args) -- **CLI Fingerprint Matching** โ€” Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP - ---- - -## ๐Ÿ–ผ๏ธ Media _(v2.0.3+)_ - -Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. - ---- - -## ๐Ÿ“ Request Logs - -Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. - -![Usage Logs](screenshots/08-usage.png) - ---- - -## ๐ŸŒ API Endpoint - -Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. - -![Endpoint Dashboard](screenshots/09-endpoint.png) - ---- - -## ๐Ÿ”‘ API Key Management - -Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. - ---- - -## ๐Ÿ“‹ Audit Log - -Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. - ---- - -## ๐Ÿ–ฅ๏ธ Desktop Application - -Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. - -Key features: - -- Server readiness polling (no blank screen on cold start) -- System tray with port management -- Content Security Policy -- Single-instance lock -- Auto-update on restart -- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) -- Hardened Electron build packaging โ€” symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+) - -๐Ÿ“– See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/bg/README.md b/docs/i18n/bg/README.md index f8bb217706..15dfbef8b7 100644 --- a/docs/i18n/bg/README.md +++ b/docs/i18n/bg/README.md @@ -1,12 +1,12 @@ # ๐Ÿš€ OmniRoute โ€” The Free AI Gateway (ะ‘ัŠะปะณะฐั€ัะบะธ) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/README.md) --- ### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback. -_Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._ +_Your universal API proxy โ€” one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._ **Chat Completions โ€ข Embeddings โ€ข Image Generation โ€ข Video โ€ข Music โ€ข Audio โ€ข Reranking โ€ข **Web Search** โ€ข MCP Server โ€ข A2A Protocol โ€ข 100% TypeScript** @@ -46,15 +46,17 @@ _Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now wi > - `APP_LOG_FILE_PATH` > - `APP_LOG_MAX_FILE_SIZE` > - `APP_LOG_RETENTION_DAYS` +> - `APP_LOG_MAX_FILES` > - `APP_LOG_LEVEL` > - `APP_LOG_FORMAT` > - `CALL_LOG_RETENTION_DAYS` +> - `CALL_LOG_MAX_ENTRIES` > > For release details and upgrade notes, see the [CHANGELOG](CHANGELOG.md). --- -## ๐Ÿ†• What's New in v3.0.0 +## ๐Ÿ†• What's New > **Upgrading from v2.9.5?** โ€” See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes. @@ -274,7 +276,7 @@ Developers pay $20โ€“200/month for Claude Pro, Codex Pro, or GitHub Copilot. Eve - **Smart 4-Tier Fallback** โ€” If subscription quota runs out, automatically redirects to API Key โ†’ Cheap โ†’ Free with zero manual intervention - **Real-Time Quota Tracking** โ€” Shows token consumption in real-time with reset countdown (5h, daily, weekly) - **Multi-Account Support** โ€” Multiple accounts per provider with auto round-robin โ€” when one runs out, switches to the next -- **Custom Combos** โ€” Customizable fallback chains with 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Custom Combos** โ€” Customizable fallback chains with 9 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random) - **Codex Business Quotas** โ€” Business/Team workspace quota monitoring directly in the dashboard @@ -286,7 +288,7 @@ OpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If **How OmniRoute solves it:** -- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 67+ providers +- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 60+ providers - **Format Translation** โ€” Automatic and transparent: OpenAI โ†” Claude โ†” Gemini โ†” Responses API - **Response Sanitization** โ€” Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+ - **Role Normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI providers; `system` โ†’ `user` for GLM/ERNIE @@ -372,7 +374,7 @@ Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code.. - **CLI Tools Dashboard** โ€” Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline - **GitHub Copilot Config Generator** โ€” Generates `chatLanguageModels.json` for VS Code with bulk model selection - **Onboarding Wizard** โ€” Guided 4-step setup for first-time users -- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 67+ providers +- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 60+ providers @@ -419,7 +421,7 @@ When a call fails, the dev doesn't know if it was a rate limit, expired token, w - **SQLite Proxy Logs** โ€” Persistent logs that survive server restarts - **Translator Playground** โ€” 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time) - **Request Telemetry** โ€” p50/p95/p99 latency + X-Request-Id tracing -- **File-Based Logging with Rotation** โ€” Console interceptor captures everything to JSON log with size-based rotation +- **File-Based Logging with Rotation** โ€” App logs rotate by size, retention days, and archive count; call log artifacts rotate by retention days and file count - **System Info Report** โ€” `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage. @@ -514,7 +516,7 @@ Developers who want all responses in a specific language, with a specific tone, - **System Prompt Injection** โ€” Global prompt applied to all requests - **Thinking Budget Validation** โ€” Reasoning token allocation control per request (passthrough, auto, custom, adaptive) -- **6 Routing Strategies** โ€” Global strategies that determine how requests are distributed +- **9 Routing Strategies** โ€” Global strategies that determine how requests are distributed - **Wildcard Router** โ€” `provider/*` patterns route dynamically to any provider - **Combo Enable/Disable Toggle** โ€” Toggle combos directly from the dashboard - **Provider Toggle** โ€” Enable/disable all connections for a provider with one click @@ -581,7 +583,7 @@ Different clients should have least-privilege access to tool categories. **How OmniRoute solves it:** -- 9 granular MCP scopes for controlled tool access +- 10 granular MCP scopes for controlled tool access - Scope enforcement and visibility in MCP management UI - Safe default posture for operational tooling @@ -1325,19 +1327,19 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. ### ๐Ÿค– Agent & Protocol Operations (v2.0) -| Feature | What It Does | -| ------------------------------------- | -------------------------------------------------------------------------------------------------- | -| ๐Ÿ”ง **MCP Server (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) | -| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | -| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | -| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | -| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | -| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | -| ๐Ÿ” **MCP Scope Enforcement** | 9 granular scope permissions for controlled tool access | -| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | -| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | -| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | -| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | +| Feature | What It Does | +| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| ๐Ÿ”ง **MCP Server (25 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools | +| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | +| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | +| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | +| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | +| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | +| ๐Ÿ” **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access | +| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | +| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | +| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | +| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | ### ๐Ÿง  Routing & Intelligence @@ -1348,7 +1350,7 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. | ๐Ÿ”„ **Format Translation** | OpenAI โ†” Claude โ†” Gemini โ†” Responses with schema-safe conversions | | ๐Ÿ‘ฅ **Multi-Account Support** | Multiple accounts per provider with intelligent selection | | ๐Ÿ”„ **Auto Token Refresh** | OAuth tokens refresh automatically with retry | -| ๐ŸŽจ **Custom Combos** | 6 balancing strategies + fallback chain control | +| ๐ŸŽจ **Custom Combos** | 9 balancing strategies + fallback chain control | | ๐ŸŒ **Wildcard Router** | `provider/*` dynamic routing | | ๐Ÿง  **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits | | ๐Ÿ”€ **Model Aliases** | Built-in + custom model aliasing and migration safety | @@ -1949,6 +1951,7 @@ opencode - Request artifacts are written to `DATA_DIR/call_logs/` as one JSON file per request - Enable pipeline capture from Dashboard โ†’ Logs โ†’ Request Logs if you need detailed per-stage payloads - Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log` +- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed **Connection test shows "Invalid" for OpenAI-compatible providers** diff --git a/docs/i18n/bg/RELEASE_CHECKLIST.md b/docs/i18n/bg/RELEASE_CHECKLIST.md deleted file mode 100644 index 903e812c3f..0000000000 --- a/docs/i18n/bg/RELEASE_CHECKLIST.md +++ /dev/null @@ -1,37 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/RELEASE_CHECKLIST.md) - ---- - -# Release Checklist - -Use this checklist before tagging or publishing a new OmniRoute release. - -## Version and Changelog - -1. Bump `package.json` version (`x.y.z`) in the release branch. -2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: - - `## [x.y.z] โ€” YYYY-MM-DD` -3. Keep `## [Unreleased]` as the first changelog section for upcoming work. -4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. - -## API Docs - -1. Update `docs/openapi.yaml`: - - `info.version` must equal `package.json` version. -2. Validate endpoint examples if API contracts changed. - -## Runtime Docs - -1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. -2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. -3. Update localized docs if source docs changed significantly. - -## Automated Check - -Run the sync guard locally before opening PR: - -```bash -npm run check:docs-sync -``` - -CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/bg/SECURITY.md b/docs/i18n/bg/SECURITY.md new file mode 100644 index 0000000000..aba3c49e3c --- /dev/null +++ b/docs/i18n/bg/SECURITY.md @@ -0,0 +1,179 @@ +# Security Policy (ะ‘ัŠะปะณะฐั€ัะบะธ) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../SECURITY.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/SECURITY.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/SECURITY.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/SECURITY.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/SECURITY.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/SECURITY.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/SECURITY.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/SECURITY.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/SECURITY.md) + +--- + +## 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 | +| ------- | -------------- | +| 3.4.x | โœ… Active | +| 3.0.x | โœ… Security | +| < 3.0.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 | +| **MCP Scopes** | 10 granular scopes for MCP tool access control | + +### ๐Ÿ›ก๏ธ 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:::` +- 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** | Allowlist/blocklist IP ranges in dashboard | +| **Rate Limiting** | Per-provider rate limits with automatic backoff | +| **Anti-Thundering Herd** | Mutex + per-connection locking prevents cascading 502s | +| **TLS Fingerprint** | Browser-like TLS fingerprint spoofing to reduce bot detection | +| **CLI Fingerprint** | Per-provider header/body ordering to match native CLI signatures | + +### ๐Ÿ”Œ Resilience & Availability + +| 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 `CALL_LOG_RETENTION_DAYS` | +| **No-Log Opt-out** | Per API key `noLog` flag disables request logging | +| **Audit Log** | Administrative actions tracked in `audit_log` table | +| **MCP Audit** | SQLite-backed audit logging for all MCP tool calls | +| **Zod Validation** | All API inputs validated with Zod v4 schemas at module load | + +--- + +## 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 +- Provider constants validated at module load via Zod (`src/shared/validation/providerSchema.ts`) diff --git a/docs/i18n/bg/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/bg/VM_DEPLOYMENT_GUIDE.md deleted file mode 100644 index 60aa723bf6..0000000000 --- a/docs/i18n/bg/VM_DEPLOYMENT_GUIDE.md +++ /dev/null @@ -1,401 +0,0 @@ -# OmniRoute โ€” ะ ัŠะบะพะฒะพะดัั‚ะฒะพ ะทะฐ ะฒะฝะตะดั€ัะฒะฐะฝะต ะฝะฐ VM ั Cloudflare - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](../pt-BR/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](../es/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](../fr/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](../it/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](../ru/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](../zh-CN/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](../de/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](../in/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](../th/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](../uk-UA/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](../ar/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](../ja/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](../vi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](../bg/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](../da/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](../fi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](../he/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](../hu/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](../id/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](../ko/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](../ms/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](../nl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](../no/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](../pt/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](../ro/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](../pl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](../sk/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](../sv/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](../phi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](../cs/VM_DEPLOYMENT_GUIDE.md) - -ะŸัŠะปะฝะพ ั€ัŠะบะพะฒะพะดัั‚ะฒะพ ะทะฐ ะธะฝัั‚ะฐะปะธั€ะฐะฝะต ะธ ะบะพะฝั„ะธะณัƒั€ะธั€ะฐะฝะต ะฝะฐ OmniRoute ะฝะฐ VM (VPS) ั ะดะพะผะตะนะฝ, ัƒะฟั€ะฐะฒะปัะฒะฐะฝ ั‡ั€ะตะท Cloudflare. - ---- - -## ะŸั€ะตะดะฟะพัั‚ะฐะฒะบะธ - -| ะั€ั‚ะธะบัƒะป | ะœะธะฝะธะผัƒะผ | ะŸั€ะตะฟะพั€ัŠั‡ะฒะฐ ัะต | -| ---------- | ------------------------ | ---------------- | -| **CPU** | 1 vCPU | 2 vCPU | -| **RAM** | 1 GB | 2 GB | -| **ะ”ะธัะบ** | 10 GB SSD | 25 GB SSD | -| **OS** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS | -| **ะ”ะพะผะตะนะฝ** | ะ ะตะณะธัั‚ั€ะธั€ะฐะฝ ะฒ Cloudflare | โ€” | -| **ะ”ะพะบะตั€** | Docker Engine 24+ | ะ”ะพะบะตั€ 27+ | - -**ะขะตัั‚ะฒะฐะฝะธ ะดะพัั‚ะฐะฒั‡ะธั†ะธ**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. - ---- - -## 1. ะšะพะฝั„ะธะณัƒั€ะธั€ะฐะนั‚ะต VM - -### 1.1 ะกัŠะทะดะฐะนั‚ะต ะตะบะทะตะผะฟะปัั€ะฐ - -ะะฐ ะฟั€ะตะดะฟะพั‡ะธั‚ะฐะฝะธั ะพั‚ ะฒะฐั VPS ะดะพัั‚ะฐะฒั‡ะธะบ: - -- ะ˜ะทะฑะตั€ะตั‚ะต Ubuntu 24.04 LTS -- ะ˜ะทะฑะตั€ะตั‚ะต ะผะธะฝะธะผะฐะปะฝะธั ะฟะปะฐะฝ (1 vCPU / 1 GB RAM) -- ะ—ะฐะดะฐะนั‚ะต ัะธะปะฝะฐ root ะฟะฐั€ะพะปะฐ ะธะปะธ ะบะพะฝั„ะธะณัƒั€ะธั€ะฐะนั‚ะต SSH ะบะปัŽั‡ -- ะžะฑัŠั€ะฝะตั‚ะต ะฒะฝะธะผะฐะฝะธะต ะฝะฐ **ะฟัƒะฑะปะธั‡ะฝะธั IP** (ะฝะฐะฟั€. `203.0.113.10`) - -### 1.2 ะกะฒัŠั€ะทะฒะฐะฝะต ั‡ั€ะตะท SSH - -```bash -ssh root@203.0.113.10 -``` - -### 1.3 ะะบั‚ัƒะฐะปะธะทะธั€ะฐะนั‚ะต ัะธัั‚ะตะผะฐั‚ะฐ - -```bash -apt update && apt upgrade -y -``` - -### 1.4 ะ˜ะฝัั‚ะฐะปะธั€ะฐะนั‚ะต Docker - -```bash -# Install dependencies -apt install -y ca-certificates curl gnupg - -# Add official Docker repository -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 ะ˜ะฝัั‚ะฐะปะธั€ะฐะนั‚ะต nginx - -```bash -apt install -y nginx -``` - -### 1.6 ะšะพะฝั„ะธะณัƒั€ะธั€ะฐะฝะต ะฝะฐ ะทะฐั‰ะธั‚ะฝะฐ ัั‚ะตะฝะฐ (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 -``` - -> **ะกัŠะฒะตั‚**: ะ—ะฐ ะผะฐะบัะธะผะฐะปะฝะฐ ัะธะณัƒั€ะฝะพัั‚ ะพะณั€ะฐะฝะธั‡ะตั‚ะต ะฟะพั€ั‚ะพะฒะต 80 ะธ 443 ัะฐะผะพ ะดะพ IP ะฐะดั€ะตัะธ ะฝะฐ Cloudflare. ะ’ะธะถั‚ะต ั€ะฐะทะดะตะปะฐ [Advanced Security](#advanced-security). - ---- - -## 2. ะ˜ะฝัั‚ะฐะปะธั€ะฐะนั‚ะต OmniRoute - -### 2.1 ะกัŠะทะดะฐะนั‚ะต ะบะพะฝั„ะธะณัƒั€ะฐั†ะธะพะฝะฝะฐ ะดะธั€ะตะบั‚ะพั€ะธั - -```bash -mkdir -p /opt/omniroute -``` - -### 2.2 ะกัŠะทะดะฐะนั‚ะต ั„ะฐะนะป ั ะฟั€ะพะผะตะฝะปะธะฒะธ ะฝะฐ ัั€ะตะดะฐั‚ะฐ - -```bash -cat > /opt/omniroute/.env << โ€˜EOFโ€™ -# === Security === -JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY -INITIAL_PASSWORD=YourSecurePassword123! -API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY -STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY -STORAGE_ENCRYPTION_KEY_VERSION=v1 -MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT - -# === 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 (change to your domain) === -BASE_URL=https://llms.seudominio.com -NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com - -# === Cloud Sync (optional) === -# CLOUD_URL=https://cloud.omniroute.online -# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online -EOF -``` - -> โš ๏ธ **ะ’ะะ–ะะž**: ะ“ะตะฝะตั€ะธั€ะฐะนั‚ะต ัƒะฝะธะบะฐะปะฝะธ ัะตะบั€ะตั‚ะฝะธ ะบะปัŽั‡ะพะฒะต! ะ˜ะทะฟะพะปะทะฒะฐะนั‚ะต `openssl rand -hex 32` ะทะฐ ะฒัะตะบะธ ะบะปัŽั‡. - -### 2.3 ะกั‚ะฐั€ั‚ะธั€ะฐะนั‚ะต ะบะพะฝั‚ะตะนะฝะตั€ะฐ - -```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 ะŸั€ะพะฒะตั€ะตั‚ะต ะดะฐะปะธ ั€ะฐะฑะพั‚ะธ - -```bash -docker ps | grep omniroute -docker logs omniroute --tail 20 -``` - -ะขั€ัะฑะฒะฐ ะดะฐ ะฟะพะบะฐะทะฒะฐ: `[DB] SQLite database ready` ะธ `listening on port 20128`. - ---- - -## 3. ะšะพะฝั„ะธะณัƒั€ะธั€ะฐะนั‚ะต nginx (ะพะฑั€ะฐั‚ะตะฝ ะฟั€ะพะบัะธ) - -### 3.1 ะ“ะตะฝะตั€ะธั€ะฐะฝะต ะฝะฐ SSL ัะตั€ั‚ะธั„ะธะบะฐั‚ (Cloudflare Origin) - -ะ’ ั‚ะฐะฑะปะพั‚ะพ ะทะฐ ัƒะฟั€ะฐะฒะปะตะฝะธะต ะฝะฐ Cloudflare: - -1. ะžั‚ะธะดะตั‚ะต ะฝะฐ **SSL/TLS โ†’ Origin Server** -2. ะฉั€ะฐะบะฝะตั‚ะต ะฒัŠั€ั…ัƒ **ะกัŠะทะดะฐะฒะฐะฝะต ะฝะฐ ัะตั€ั‚ะธั„ะธะบะฐั‚** -3. ะ—ะฐะฟะฐะทะตั‚ะต ะฝะฐัั‚ั€ะพะนะบะธั‚ะต ะฟะพ ะฟะพะดั€ะฐะทะฑะธั€ะฐะฝะต (15 ะณะพะดะธะฝะธ, \*.yourdomain.com) -4. ะšะพะฟะธั€ะฐะนั‚ะต **ะกะตั€ั‚ะธั„ะธะบะฐั‚ะฐ ะทะฐ ะฟั€ะพะธะทั…ะพะด** ะธ **ะ›ะธั‡ะฝะธั ะบะปัŽั‡** - -```bash -mkdir -p /etc/nginx/ssl - -# Paste the certificate -nano /etc/nginx/ssl/origin.crt - -# Paste the private key -nano /etc/nginx/ssl/origin.key - -chmod 600 /etc/nginx/ssl/origin.key -``` - -### 3.2 ะšะพะฝั„ะธะณัƒั€ะฐั†ะธั ะฝะฐ Nginx - -```bash -cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ -# Default server โ€” blocks direct access via 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.yourdomain.com; # Change to your domain - - 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.yourdomain.com; - return 301 https://$server_name$request_uri; -} -NGINX -``` - -### 3.3 ะะบั‚ะธะฒะธั€ะฐะฝะต ะธ ั‚ะตัั‚ะฒะฐะฝะต - -```bash -# Remove default configuration -rm -f /etc/nginx/sites-enabled/default - -# Enable OmniRoute -ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute - -# Test and reload -nginx -t && systemctl reload nginx -``` - ---- - -## 4. ะšะพะฝั„ะธะณัƒั€ะธั€ะฐะนั‚ะต Cloudflare DNS - -### 4.1 ะ”ะพะฑะฐะฒะตั‚ะต DNS ะทะฐะฟะธั - -ะ’ ั‚ะฐะฑะปะพั‚ะพ ะทะฐ ัƒะฟั€ะฐะฒะปะตะฝะธะต ะฝะฐ Cloudflare โ†’ DNS: - -| ะขะธะฟ | ะ˜ะผะต | ะกัŠะดัŠั€ะถะฐะฝะธะต | ะŸั€ะพะบัะธ | -| --- | ------ | ---------------------- | ------------ | -| A | `llms` | `203.0.113.10` (VM IP) | โœ… ะŸั€ะพะบัะธั€ะฐะฝ | - -### 4.2 ะšะพะฝั„ะธะณัƒั€ะธั€ะฐะนั‚ะต SSL - -ะŸะพะด **SSL/TLS โ†’ ะžะฑั‰ ะฟั€ะตะณะปะตะด**: - -- ะ ะตะถะธะผ: **ะŸัŠะปะตะฝ (ัั‚ั€ะพะณ)** - -ะŸะพะด **SSL/TLS โ†’ Edge Certificates**: - -- ะ’ะธะฝะฐะณะธ ะธะทะฟะพะปะทะฒะฐะนั‚ะต HTTPS: โœ… ะ’ะบะป -- ะœะธะฝะธะผะฐะปะฝะฐ TLS ะฒะตั€ัะธั: TLS 1.2 -- ะะฒั‚ะพะผะฐั‚ะธั‡ะฝะพ ะฟั€ะตะฝะฐะฟะธัะฒะฐะฝะต ะฝะฐ HTTPS: โœ… ะ’ะบะปัŽั‡ะตะฝะพ - -### 4.3 ะขะตัั‚ะฒะฐะฝะต - -```bash -curl -sI https://llms.seudominio.com/health -# Should return HTTP/2 200 -``` - ---- - -## 5. ะžะฟะตั€ะฐั†ะธะธ ะธ ะฟะพะดะดั€ัŠะถะบะฐ - -### ะะฐะดัั‚ั€ะพะนั‚ะต ะดะพ ะฝะพะฒะฐ ะฒะตั€ัะธั - -```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 -``` - -### ะŸั€ะตะณะปะตะด ะฝะฐ ั€ะตะณะธัั‚ั€ะฐั†ะธะพะฝะฝะธ ั„ะฐะนะปะพะฒะต - -```bash -docker logs -f omniroute # Real-time stream -docker logs omniroute --tail 50 # Last 50 lines -``` - -### ะ ัŠั‡ะฝะพ ะฐั€ั…ะธะฒะธั€ะฐะฝะต ะฝะฐ ะฑะฐะทะฐ ะดะฐะฝะฝะธ - -```bash -# Copy data from the volume to the host -docker cp omniroute:/app/data ./backup-$(date +%F) - -# Or compress the entire volume -docker run --rm -v omniroute-data:/data -v $(pwd):/backup \ - alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data -``` - -### ะ’ัŠะทัั‚ะฐะฝะพะฒัะฒะฐะฝะต ะพั‚ ั€ะตะทะตั€ะฒะฝะพ ะบะพะฟะธะต - -```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. ะ ะฐะทัˆะธั€ะตะฝะฐ ัะธะณัƒั€ะฝะพัั‚ - -### ะžะณั€ะฐะฝะธั‡ะตั‚ะต nginx ะดะพ IP ะฐะดั€ะตัะธ ะฝะฐ Cloudflare - -```bash -cat > /etc/nginx/cloudflare-ips.conf << โ€˜CFโ€™ -# Cloudflare IPv4 ranges โ€” update periodically -# 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 -``` - -ะ”ะพะฑะฐะฒะตั‚ะต ัะปะตะดะฝะพั‚ะพ ะบัŠะผ `nginx.conf` ะฒ ะฑะปะพะบะฐ `http {}`: - -```nginx -include /etc/nginx/cloudflare-ips.conf; -``` - -### ะ˜ะฝัั‚ะฐะปะธั€ะฐะนั‚ะต fail2ban - -```bash -apt install -y fail2ban -systemctl enable fail2ban -systemctl start fail2ban - -# Check status -fail2ban-client status sshd -``` - -### ะ‘ะปะพะบะธั€ะฐะนั‚ะต ะดะธั€ะตะบั‚ะฝะธั ะดะพัั‚ัŠะฟ ะดะพ ะฟะพั€ั‚ะฐ ะฝะฐ Docker - -```bash -# Prevent direct external access to port 20128 -iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP -iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT - -# Persist the rules -apt install -y iptables-persistent -netfilter-persistent save -``` - ---- - -## 7. ะ ะฐะทะฟะพะปะพะถะตั‚ะต ะฒ Cloudflare Workers (ะฟะพ ะธะทะฑะพั€) - -ะ—ะฐ ะพั‚ะดะฐะปะตั‡ะตะฝ ะดะพัั‚ัŠะฟ ั‡ั€ะตะท Cloudflare Workers (ะฑะตะท ะดะธั€ะตะบั‚ะฝะพ ะธะทะปะฐะณะฐะฝะต ะฝะฐ VM): - -```bash -# In the local repository -cd omnirouteCloud -npm install -npx wrangler login -npx wrangler deploy -``` - -ะ’ะธะถั‚ะต ะฟัŠะปะฝะฐั‚ะฐ ะดะพะบัƒะผะตะฝั‚ะฐั†ะธั ะฝะฐ [omnirouteCloud/README.md](../omnirouteCloud/README.md). - ---- - -## ะ ะตะทัŽะผะต ะฝะฐ ะฟะพั€ั‚ะฐ - -| ะŸั€ะธัั‚ะฐะฝะธั‰ะต | ะžะฑัะปัƒะถะฒะฐะฝะต | ะ”ะพัั‚ัŠะฟ | -| ---------- | ----------- | ------------------------------ | -| 22 | SSH | ะŸัƒะฑะปะธั‡ะตะฝ (ั fail2ban) | -| 80 | nginx HTTP | ะŸั€ะตะฝะฐัะพั‡ะฒะฐะฝะต โ†’ HTTPS | -| 443 | nginx HTTPS | ะงั€ะตะท ะฟั€ะพะบัะธ Cloudflare | -| 20128 | OmniRoute | ะกะฐะผะพ ะปะพะบะฐะปะตะฝ ั…ะพัั‚ (ั‡ั€ะตะท nginx) | diff --git a/docs/i18n/bg/docs/A2A-SERVER.md b/docs/i18n/bg/docs/A2A-SERVER.md new file mode 100644 index 0000000000..f07600eb54 --- /dev/null +++ b/docs/i18n/bg/docs/A2A-SERVER.md @@ -0,0 +1,200 @@ +# OmniRoute A2A Server Documentation (ะ‘ัŠะปะณะฐั€ัะบะธ) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/A2A-SERVER.md) + +--- + +> Agent-to-Agent Protocol v0.3 โ€” OmniRoute as an intelligent routing agent + +## Agent Discovery + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements. + +--- + +## Authentication + +All `/a2a` requests require an API key via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server, authentication is bypassed. + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Sends a message to a skill and waits for the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a hello world in Python"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "uuid", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "..." }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}} + +: heartbeat 2026-03-03T17:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Available Skills + +| Skill | Description | +| :----------------- | :------------------------------------------------------------------------------------------------------------------------------ | +| `smart-routing` | Routes prompts through OmniRoute's intelligent pipeline. Returns response with routing explanation, cost, and resilience trace. | +| `quota-management` | Answers natural-language queries about provider quotas, suggests free combos, and provides quota rankings. | + +--- + +## Task Lifecycle + +``` +submitted โ†’ working โ†’ completed + โ†’ failed + โ†’ cancelled +``` + +- Tasks expire after 5 minutes (configurable) +- Terminal states: `completed`, `failed`, `cancelled` +- Event log tracks every state transition + +--- + +## Error Codes + +| Code | Meaning | +| :----- | :----------------------------- | +| -32700 | Parse error (invalid JSON) | +| -32600 | Invalid request / Unauthorized | +| -32601 | Method or skill not found | +| -32602 | Invalid params | +| -32603 | Internal error | + +--- + +## Integration Examples + +### Python (requests) + +```python +import requests + +resp = requests.post("http://localhost:20128/a2a", json={ + "jsonrpc": "2.0", "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Hello"}] + } +}, headers={"Authorization": "Bearer YOUR_KEY"}) + +result = resp.json()["result"] +print(result["artifacts"][0]["content"]) +print(result["metadata"]["routing_explanation"]) +``` + +### TypeScript (fetch) + +```typescript +const resp = await fetch("http://localhost:20128/a2a", { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: "Bearer YOUR_KEY", + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "1", + method: "message/send", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Hello" }], + }, + }), +}); +const { result } = await resp.json(); +console.log(result.metadata.routing_explanation); +``` diff --git a/docs/i18n/bg/docs/API_REFERENCE.md b/docs/i18n/bg/docs/API_REFERENCE.md new file mode 100644 index 0000000000..f8377b7fed --- /dev/null +++ b/docs/i18n/bg/docs/API_REFERENCE.md @@ -0,0 +1,465 @@ +# API Reference (ะ‘ัŠะปะณะฐั€ัะบะธ) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/API_REFERENCE.md) + +--- + +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 | +| `X-Session-Id` | Request | Sticky session key for external session affinity | +| `x_session_id` | Request | Underscore variant also accepted (direct HTTP) | +| `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 | +| `X-OmniRoute-Session-Id` | Response | Effective session ID used by OmniRoute | + +> Nginx note: if you rely on underscore headers (for example `x_session_id`), enable `underscores_in_headers 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/stats + +# Clear all caches +DELETE /api/cache/stats +``` + +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/PATCH | 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 + provider summary (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`) | +| `/api/cache/stats` | 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 | + +### Tunnels + +| Endpoint | Method | Description | +| -------------------------- | ------ | ----------------------------------------------------------------------- | +| `/api/tunnels/cloudflared` | GET | Read Cloudflare Quick Tunnel install/runtime status for the dashboard | +| `/api/tunnels/cloudflared` | POST | Enable or disable the Cloudflare Quick Tunnel (`action=enable/disable`) | + +### 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`. + +### ACP Agents + +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | + +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). + +### Resilience & Rate Limits + +| Endpoint | Method | Description | +| ----------------------- | --------- | ------------------------------- | +| `/api/resilience` | GET/PATCH | 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` diff --git a/docs/i18n/bg/docs/ARCHITECTURE.md b/docs/i18n/bg/docs/ARCHITECTURE.md new file mode 100644 index 0000000000..01ffe3a560 --- /dev/null +++ b/docs/i18n/bg/docs/ARCHITECTURE.md @@ -0,0 +1,814 @@ +# OmniRoute Architecture (ะ‘ัŠะปะณะฐั€ัะบะธ) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/ARCHITECTURE.md) + +--- + +_Last updated: 2026-03-28_ + +## 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 (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developerโ†’system, systemโ†’user) for cross-provider compatibility +- Structured output conversion (json_schema โ†’ Gemini responseSchema) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) +- Global system prompt injection +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout โ†’ budget โ†’ fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) + +Primary runtime model: + +- Next.js 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.) + +## Dashboard Surface (Current) + +Main pages under `src/app/(dashboard)/dashboard/`: + +- `/dashboard` โ€” quick start + provider overview +- `/dashboard/endpoint` โ€” endpoint proxy + MCP + A2A + API endpoint tabs +- `/dashboard/providers` โ€” provider connections and credentials +- `/dashboard/combos` โ€” combo strategies, templates, model routing rules +- `/dashboard/costs` โ€” cost aggregation and pricing visibility +- `/dashboard/analytics` โ€” usage analytics and evaluations +- `/dashboard/limits` โ€” quota/rate controls +- `/dashboard/cli-tools` โ€” CLI onboarding, runtime detection, config generation +- `/dashboard/agents` โ€” detected ACP agents + custom agent registration +- `/dashboard/media` โ€” image/video/music playground +- `/dashboard/search-tools` โ€” search provider testing and history +- `/dashboard/health` โ€” uptime, circuit breakers, rate limits +- `/dashboard/logs` โ€” request/proxy/audit/console logs +- `/dashboard/settings` โ€” system settings tabs (general, routing, combo defaults, etc.) +- `/dashboard/api-manager` โ€” API key lifecycle and model permissions + +## 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[(storage.sqlite)] + UDB[(usage tables + log artifacts)] + end + + subgraph Upstreams[Upstream Providers] + P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/Qoder/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/route.ts` (GET) +- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- OAuth: `src/app/api/oauth/*` +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` +- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI tooling helpers: `src/app/api/cli-tools/*` +- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) +- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) โ€” provider profiles, circuit breaker, rate limit state +- Resilience reset: `src/app/api/resilience/reset` (POST) โ€” reset breakers + cooldowns +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) +- Telemetry: `src/app/api/telemetry/summary` (GET) +- Budget: `src/app/api/usage/budget` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Policies: `src/app/api/policies` (GET/POST) + +## 2) SSE + 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` +- Response sanitization: `open-sse/handlers/responseSanitizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.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`, `qoder.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 (SQLite): + +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** + +Usage persistence: + +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present + +Domain State DB (SQLite): + +- `src/lib/db/domainState.ts` โ€” CRUD operations 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`, `src/shared/services/modelSyncScheduler.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Periodic task: `src/shared/services/modelSyncScheduler.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. Combo routing adds one extra guard: provider-scoped 400s such as upstream content-block and role-validation failures are treated as model-local failures so later combo targets can still run. + +## 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: + +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` + +## Deployment Topology + +```mermaid +flowchart LR + 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[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] + end + + subgraph External[External Services] + Providers[AI Providers] + SyncCloud[Cloud Sync Service] + end + + CLI --> Next + Browser --> Next + Next --> Core + Next --> MainDB + Core --> MainDB + Core --> UsageDB + Core --> Providers + Next --> SyncCloud +``` + +## Module Mapping (Decision-Critical) + +### Route and API Modules + +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle +- `src/app/api/models/alias`: alias management +- `src/app/api/combos*`: fallback combo management +- `src/app/api/pricing`: pricing overrides for cost calculation +- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers +- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) +- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) +- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) +- `src/app/api/sessions`: active session listing (GET) +- `src/app/api/rate-limits`: per-account rate limit status (GET) + +### Routing and Execution Core + +- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior + +### Translation Registry and Format Converters + +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` +- Format constants: `open-sse/translator/formats.ts` + +### Persistence + +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables + +## Provider Executor Coverage (Strategy Pattern) + +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. + +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, Qoder, 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 | +| Qoder | openai | OAuth (Basic) | โœ… | โœ… | โœ… | โš ๏ธ Per request | +| OpenRouter | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| GLM/Kimi/MiniMax | claude | API Key | โœ… | โœ… | โŒ | โŒ | +| DeepSeek | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Groq | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| xAI (Grok) | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Mistral | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Perplexity | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Together AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Fireworks AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Cerebras | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Cohere | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| NVIDIA NIM | openai | API Key | โœ… | โœ… | โŒ | โŒ | + +## Format Translation Coverage + +Detected source formats include: + +- `openai` +- `openai-responses` +- `claude` +- `gemini` + +Target formats include: + +- OpenAI chat/Responses +- Claude +- Gemini/Gemini-CLI/Antigravity envelope +- Kiro +- Cursor + +Translations use **OpenAI as the hub format** โ€” all conversions go through OpenAI as intermediate: + +``` +Source Format โ†’ OpenAI (hub) โ†’ Target Format +``` + +Translations are selected dynamically based on source payload shape and provider target format. + +Additional processing layers in the translation pipeline: + +- **Response sanitization** โ€” Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI targets; merges `system` โ†’ `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** โ€” Parses `...` blocks from content into `reasoning_content` field +- **Structured output** โ€” Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` + +## Supported API Endpoints + +| 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` | Provider Models | Provider model metadata backing custom and managed available models | + +## 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 `/logs//` 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 + +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON โ†’ SQLite migration compatibility path + +## Observability and Operational Signals + +Runtime visibility sources: + +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- four-stage detailed payload captures in SQLite (`request_detail_logs`) when `settings.detailed_logs_enabled=true` +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption + +Detailed request payload capture stores up to four JSON payload stages per routed call: + +- raw request received from the client +- translated request actually sent upstream +- provider response reconstructed as JSON; streamed responses are compacted to the final summary plus stream metadata +- final client response returned by OmniRoute; streamed responses are stored in the same compact summary form + +## Security-Sensitive Boundaries + +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics + +## Environment and Runtime Matrix + +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` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). + +## Operational Verification Checklist + +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: +- `GET /api/settings` +- `GET /api/v1/models` +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/bg/docs/AUTO-COMBO.md b/docs/i18n/bg/docs/AUTO-COMBO.md new file mode 100644 index 0000000000..ae23e60325 --- /dev/null +++ b/docs/i18n/bg/docs/AUTO-COMBO.md @@ -0,0 +1,67 @@ +# OmniRoute Auto-Combo Engine (ะ‘ัŠะปะณะฐั€ัะบะธ) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/AUTO-COMBO.md) + +--- + +> Self-managing model chains with adaptive scoring + +## How It Works + +The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**: + +| Factor | Weight | Description | +| :--------- | :----- | :---------------------------------------------- | +| Quota | 0.20 | Remaining capacity [0..1] | +| Health | 0.25 | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 | +| CostInv | 0.20 | Inverse cost (cheaper = higher score) | +| LatencyInv | 0.15 | Inverse p95 latency (faster = higher) | +| TaskFit | 0.10 | Model ร— task type fitness score | +| Stability | 0.10 | Low variance in latency/errors | + +## Mode Packs + +| Pack | Focus | Key Weight | +| :---------------------- | :----------- | :--------------- | +| ๐Ÿš€ **Ship Fast** | Speed | latencyInv: 0.35 | +| ๐Ÿ’ฐ **Cost Saver** | Economy | costInv: 0.40 | +| ๐ŸŽฏ **Quality First** | Best model | taskFit: 0.40 | +| ๐Ÿ“ก **Offline Friendly** | Availability | quota: 0.40 | + +## Self-Healing + +- **Temporary exclusion**: Score < 0.2 โ†’ excluded for 5 min (progressive backoff, max 30 min) +- **Circuit breaker awareness**: OPEN โ†’ auto-excluded; HALF_OPEN โ†’ probe requests +- **Incident mode**: >50% OPEN โ†’ disable exploration, maximize stability +- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout + +## Bandit Exploration + +5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode. + +## API + +```bash +# Create auto-combo +curl -X POST http://localhost:20128/api/combos/auto \ + -H "Content-Type: application/json" \ + -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}' + +# List auto-combos +curl http://localhost:20128/api/combos/auto +``` + +## Task Fitness + +30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` โ†’ high coding score). + +## Files + +| File | Purpose | +| :------------------------------------------- | :------------------------------------ | +| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization | +| `open-sse/services/autoCombo/taskFitness.ts` | Model ร— task fitness lookup | +| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap | +| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode | +| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles | +| `src/app/api/combos/auto/route.ts` | REST API | diff --git a/docs/i18n/bg/docs/CLI-TOOLS.md b/docs/i18n/bg/docs/CLI-TOOLS.md new file mode 100644 index 0000000000..250b245f18 --- /dev/null +++ b/docs/i18n/bg/docs/CLI-TOOLS.md @@ -0,0 +1,348 @@ +# CLI Tools Setup Guide โ€” OmniRoute (ะ‘ัŠะปะณะฐั€ัะบะธ) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CLI-TOOLS.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CLI-TOOLS.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CLI-TOOLS.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CLI-TOOLS.md) + +--- + +This guide explains how to install and configure all supported AI coding CLI tools +to use **OmniRoute** as the unified backend, giving you centralized key management, +cost tracking, model switching, and request logging across every tool. + +--- + +## How It Works + +``` +Claude / Codex / OpenCode / Cline / KiloCode / Continue / Kiro / Cursor / Copilot + โ”‚ + โ–ผ (all point to OmniRoute) + http://YOUR_SERVER:20128/v1 + โ”‚ + โ–ผ (OmniRoute routes to the right provider) + Anthropic / OpenAI / Gemini / DeepSeek / Groq / Mistral / ... +``` + +**Benefits:** + +- One API key to manage all tools +- Cost tracking across all CLIs in the dashboard +- Model switching without reconfiguring every tool +- Works locally and on remote servers (VPS) + +--- + +## Supported Tools (Dashboard Source of Truth) + +The dashboard cards in `/dashboard/cli-tools` are generated from `src/shared/constants/cliTools.ts`. +Current list (v3.0.0-rc.16): + +| Tool | ID | Command | Setup Mode | Install Method | +| ------------------ | ------------- | ---------- | ---------- | -------------- | +| **Claude Code** | `claude` | `claude` | env | npm | +| **OpenAI Codex** | `codex` | `codex` | custom | npm | +| **Factory Droid** | `droid` | `droid` | custom | bundled/CLI | +| **OpenClaw** | `openclaw` | `openclaw` | custom | bundled/CLI | +| **Cursor** | `cursor` | app | guide | desktop app | +| **Cline** | `cline` | `cline` | custom | npm | +| **Kilo Code** | `kilo` | `kilocode` | custom | npm | +| **Continue** | `continue` | extension | guide | VS Code | +| **Antigravity** | `antigravity` | internal | mitm | OmniRoute | +| **GitHub Copilot** | `copilot` | extension | custom | VS Code | +| **OpenCode** | `opencode` | `opencode` | guide | npm | +| **Kiro AI** | `kiro` | app/cli | mitm | desktop/CLI | + +### CLI fingerprint sync (Agents + Settings) + +`/dashboard/agents` and `Settings > CLI Fingerprint` use `src/shared/constants/cliCompatProviders.ts`. +This keeps provider IDs aligned with CLI cards and legacy IDs. + +| CLI ID | Fingerprint Provider ID | +| ---------------------------------------------------------------------------------------------------- | ----------------------- | +| `kilo` | `kilocode` | +| `copilot` | `github` | +| `claude` / `codex` / `antigravity` / `kiro` / `cursor` / `cline` / `opencode` / `droid` / `openclaw` | same ID | + +Legacy IDs still accepted for compatibility: `copilot`, `kimi-coding`, `qwen`. + +--- + +## Step 1 โ€” Get an OmniRoute API Key + +1. Open the OmniRoute dashboard โ†’ **API Manager** (`/dashboard/api-manager`) +2. Click **Create API Key** +3. Give it a name (e.g. `cli-tools`) and select all permissions +4. Copy the key โ€” you'll need it for every CLI below + +> Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` + +--- + +## Step 2 โ€” Install CLI Tools + +All npm-based tools require Node.js 18+: + +```bash +# Claude Code (Anthropic) +npm install -g @anthropic-ai/claude-code + +# OpenAI Codex +npm install -g @openai/codex + +# OpenCode +npm install -g opencode-ai + +# Cline +npm install -g cline + +# KiloCode +npm install -g kilocode + +# Kiro CLI (Amazon โ€” requires curl + unzip) +apt-get install -y unzip # on Debian/Ubuntu +curl -fsSL https://cli.kiro.dev/install | bash +export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc +``` + +**Verify:** + +```bash +claude --version # 2.x.x +codex --version # 0.x.x +opencode --version # x.x.x +cline --version # 2.x.x +kilocode --version # x.x.x (or: kilo --version) +kiro-cli --version # 1.x.x +``` + +--- + +## Step 3 โ€” Set Global Environment Variables + +Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`: + +```bash +# OmniRoute Universal Endpoint +export OPENAI_BASE_URL="http://localhost:20128/v1" +export OPENAI_API_KEY="sk-your-omniroute-key" +export ANTHROPIC_BASE_URL="http://localhost:20128/v1" +export ANTHROPIC_API_KEY="sk-your-omniroute-key" +export GEMINI_BASE_URL="http://localhost:20128/v1" +export GEMINI_API_KEY="sk-your-omniroute-key" +``` + +> For a **remote server** replace `localhost:20128` with the server IP or domain, +> e.g. `http://192.168.0.15:20128`. + +--- + +## Step 4 โ€” Configure Each Tool + +### Claude Code + +```bash +# Via CLI: +claude config set --global api-base-url http://localhost:20128/v1 + +# Or create ~/.claude/settings.json: +mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF +{ + "apiBaseUrl": "http://localhost:20128/v1", + "apiKey": "sk-your-omniroute-key" +} +EOF +``` + +**Test:** `claude "say hello"` + +--- + +### OpenAI Codex + +```bash +mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF +model: auto +apiKey: sk-your-omniroute-key +apiBaseUrl: http://localhost:20128/v1 +EOF +``` + +**Test:** `codex "what is 2+2?"` + +--- + +### OpenCode + +```bash +mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF +[provider.openai] +base_url = "http://localhost:20128/v1" +api_key = "sk-your-omniroute-key" +EOF +``` + +**Test:** `opencode` + +--- + +### Cline (CLI or VS Code) + +**CLI mode:** + +```bash +mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF +{ + "apiProvider": "openai", + "openAiBaseUrl": "http://localhost:20128/v1", + "openAiApiKey": "sk-your-omniroute-key" +} +EOF +``` + +**VS Code mode:** +Cline extension settings โ†’ API Provider: `OpenAI Compatible` โ†’ Base URL: `http://localhost:20128/v1` + +Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ Cline โ†’ Apply Config**. + +--- + +### KiloCode (CLI or VS Code) + +**CLI mode:** + +```bash +kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key +``` + +**VS Code settings:** + +```json +{ + "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", + "kilo-code.apiKey": "sk-your-omniroute-key" +} +``` + +Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ KiloCode โ†’ Apply Config**. + +--- + +### Continue (VS Code Extension) + +Edit `~/.continue/config.yaml`: + +```yaml +models: + - name: OmniRoute + provider: openai + model: auto + apiBase: http://localhost:20128/v1 + apiKey: sk-your-omniroute-key + default: true +``` + +Restart VS Code after editing. + +--- + +### Kiro CLI (Amazon) + +```bash +# Login to your AWS/Kiro account: +kiro-cli login + +# The CLI uses its own auth โ€” OmniRoute is not needed as backend for Kiro CLI itself. +# Use kiro-cli alongside OmniRoute for other tools. +kiro-cli status +``` + +--- + +### Cursor (Desktop App) + +> **Note:** Cursor routes requests through its cloud. For OmniRoute integration, +> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL. + +Via GUI: **Settings โ†’ Models โ†’ OpenAI API Key** + +- Base URL: `https://your-domain.com/v1` +- API Key: your OmniRoute key + +--- + +## Dashboard Auto-Configuration + +The OmniRoute dashboard automates configuration for most tools: + +1. Go to `http://localhost:20128/dashboard/cli-tools` +2. Expand any tool card +3. Select your API key from the dropdown +4. Click **Apply Config** (if tool is detected as installed) +5. Or copy the generated config snippet manually + +--- + +## Built-in Agents: Droid & OpenClaw + +**Droid** and **OpenClaw** are AI agents built directly into OmniRoute โ€” no installation needed. +They run as internal routes and use OmniRoute's model routing automatically. + +- Access: `http://localhost:20128/dashboard/agents` +- Configure: same combos and providers as all other tools +- No API key or CLI install required + +--- + +## Available API Endpoints + +| Endpoint | Description | Use For | +| -------------------------- | ----------------------------- | --------------------------- | +| `/v1/chat/completions` | Standard chat (all providers) | All modern tools | +| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows | +| `/v1/completions` | Legacy text completions | Older tools using `prompt:` | +| `/v1/embeddings` | Text embeddings | RAG, search | +| `/v1/images/generations` | Image generation | DALL-E, Flux, etc. | +| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS | +| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI | + +--- + +## ะžั‚ัั‚ั€ะฐะฝัะฒะฐะฝะต ะฝะฐ ะฟั€ะพะฑะปะตะผะธ + +| Error | Cause | Fix | +| ------------------------- | ----------------------- | ------------------------------------------ | +| `Connection refused` | OmniRoute not running | `pm2 start omniroute` | +| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` | +| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` | +| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` | +| CLI shows "not installed" | Binary not in PATH | Check `which ` | +| `kiro-cli: not found` | Not in PATH | `export PATH="$HOME/.local/bin:$PATH"` | + +--- + +## Quick Setup Script (One Command) + +```bash +# Install all CLIs and configure for OmniRoute (replace with your key and server URL) +OMNIROUTE_URL="http://localhost:20128/v1" +OMNIROUTE_KEY="sk-your-omniroute-key" + +npm install -g @anthropic-ai/claude-code @openai/codex opencode-ai cline kilocode + +# Kiro CLI +apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash + +# Write configs +mkdir -p ~/.claude ~/.codex ~/.config/opencode ~/.continue + +cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" +cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" +cat >> ~/.bashrc << EOF +export OPENAI_BASE_URL="$OMNIROUTE_URL" +export OPENAI_API_KEY="$OMNIROUTE_KEY" +export ANTHROPIC_BASE_URL="$OMNIROUTE_URL" +export ANTHROPIC_API_KEY="$OMNIROUTE_KEY" +EOF + +source ~/.bashrc +echo "โœ… All CLIs installed and configured for OmniRoute" +``` diff --git a/docs/i18n/bg/CODEBASE_DOCUMENTATION.md b/docs/i18n/bg/docs/CODEBASE_DOCUMENTATION.md similarity index 91% rename from docs/i18n/bg/CODEBASE_DOCUMENTATION.md rename to docs/i18n/bg/docs/CODEBASE_DOCUMENTATION.md index e2d7950052..c11218f38e 100644 --- a/docs/i18n/bg/CODEBASE_DOCUMENTATION.md +++ b/docs/i18n/bg/docs/CODEBASE_DOCUMENTATION.md @@ -1,11 +1,9 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CODEBASE_DOCUMENTATION.md) +# omniroute โ€” Codebase Documentation (ะ‘ัŠะปะณะฐั€ัะบะธ) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CODEBASE_DOCUMENTATION.md) --- -# omniroute โ€” Codebase Documentation - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) - > A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. --- @@ -352,7 +350,7 @@ flowchart LR The **format translation engine** using a self-registering plugin system. -#### Architecture +#### ะั€ั…ะธั‚ะตะบั‚ัƒั€ะฐ ```mermaid graph TD diff --git a/docs/i18n/bg/docs/COVERAGE_PLAN.md b/docs/i18n/bg/docs/COVERAGE_PLAN.md new file mode 100644 index 0000000000..dc4b31b34f --- /dev/null +++ b/docs/i18n/bg/docs/COVERAGE_PLAN.md @@ -0,0 +1,170 @@ +# Test Coverage Plan (ะ‘ัŠะปะณะฐั€ัะบะธ) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/COVERAGE_PLAN.md) + +--- + +Last updated: 2026-03-28 + +## Baseline + +There are multiple coverage numbers depending on how the report is computed. For planning, only one of them is useful. + +| Metric | Scope | Statements / Lines | Branches | Functions | Notes | +| -------------------- | ----------------------------------------------------- | -----------------: | -------: | --------: | --------------------------------------------------- | +| Legacy | Old `npm run test:coverage` | 79.42% | 75.15% | 67.94% | Inflated: counts test files and excludes `open-sse` | +| Diagnostic | Source-only, excluding tests and excluding `open-sse` | 68.16% | 63.55% | 64.06% | Useful only to isolate `src/**` | +| Recommended baseline | Source-only, excluding tests and including `open-sse` | 56.95% | 66.05% | 57.80% | This is the project-wide baseline to improve | + +The recommended baseline is the number to optimize against. + +## Rules + +- Coverage targets apply to source files, not to `tests/**`. +- `open-sse/**` is part of the product and must remain in scope. +- New code should not reduce coverage in touched areas. +- Prefer testing behavior and branch outcomes over implementation details. +- Prefer temp SQLite databases and small fixtures over broad mocks for `src/lib/db/**`. + +## Current command set + +- `npm run test:coverage` + - Main source coverage gate for the unit test suite + - Generates `text-summary`, `html`, `json-summary`, and `lcov` +- `npm run coverage:report` + - Detailed file-by-file report from the latest run +- `npm run test:coverage:legacy` + - Historical comparison only + +## Milestones + +| Phase | Target | Focus | +| ------- | ---------------------: | ------------------------------------------------- | +| Phase 1 | 60% statements / lines | Quick wins and low-risk utility coverage | +| Phase 2 | 65% statements / lines | DB and route foundations | +| Phase 3 | 70% statements / lines | Provider validation and usage analytics | +| Phase 4 | 75% statements / lines | `open-sse` translators and helpers | +| Phase 5 | 80% statements / lines | `open-sse` handlers and executor branches | +| Phase 6 | 85% statements / lines | Harder edge cases, branch debt, regression suites | +| Phase 7 | 90% statements / lines | Final sweep, gap closure, strict ratchet | + +Branches and functions should ratchet upward with each phase, but the primary hard target is statements / lines. + +## Priority hotspots + +These files or areas offer the best return for the next phases: + +1. `open-sse/handlers` + - `chatCore.ts` at 7.57% + - Overall directory at 29.07% +2. `open-sse/translator/request` + - Overall directory at 36.39% + - Many translators are still near single-digit coverage +3. `open-sse/translator/response` + - Overall directory at 8.07% +4. `open-sse/executors` + - Overall directory at 36.62% +5. `src/lib/db` + - `models.ts` at 20.66% + - `registeredKeys.ts` at 34.46% + - `modelComboMappings.ts` at 36.25% + - `settings.ts` at 46.40% + - `webhooks.ts` at 33.33% +6. `src/lib/usage` + - `usageHistory.ts` at 21.12% + - `usageStats.ts` at 9.56% + - `costCalculator.ts` at 30.00% +7. `src/lib/providers` + - `validation.ts` at 41.16% +8. Low-risk utility and API files for early gains + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/api/errorResponse.ts` + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +## Execution checklist + +### Phase 1: 56.95% -> 60% + +- [x] Fix coverage metric so it reflects source code instead of test files +- [x] Keep a legacy coverage script for comparison +- [x] Record the baseline and hotspots in-repo +- [ ] Add focused tests for low-risk utilities: + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/fetchTimeout.ts` + - `src/lib/api/errorResponse.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/display/names.ts` +- [ ] Add route tests for: + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +### Phase 2: 60% -> 65% + +- [ ] Add DB-backed tests for: + - `src/lib/db/modelComboMappings.ts` + - `src/lib/db/settings.ts` + - `src/lib/db/registeredKeys.ts` +- [ ] Cover branch behavior in: + - `src/lib/providers/validation.ts` + - `src/app/api/v1/embeddings/route.ts` + - `src/app/api/v1/moderations/route.ts` + +### Phase 3: 65% -> 70% + +- [ ] Add usage analytics tests for: + - `src/lib/usage/usageHistory.ts` + - `src/lib/usage/usageStats.ts` + - `src/lib/usage/costCalculator.ts` +- [ ] Expand route coverage for proxy management and settings branches + +### Phase 4: 70% -> 75% + +- [ ] Cover translator helpers and central translation paths: + - `open-sse/translator/index.ts` + - `open-sse/translator/helpers/*` + - `open-sse/translator/request/*` + - `open-sse/translator/response/*` + +### Phase 5: 75% -> 80% + +- [ ] Add handler-level tests for: + - `open-sse/handlers/chatCore.ts` + - `open-sse/handlers/responsesHandler.js` + - `open-sse/handlers/imageGeneration.js` + - `open-sse/handlers/embeddings.js` +- [ ] Add executor branch coverage for provider-specific auth, retries, and endpoint overrides + +### Phase 6: 80% -> 85% + +- [ ] Merge more edge-case suites into the main coverage path +- [ ] Increase function coverage for DB modules with weak constructor/helper coverage +- [ ] Close branch gaps in `settings.ts`, `registeredKeys.ts`, `validation.ts`, and translator helpers + +### Phase 7: 85% -> 90% + +- [ ] Treat the remaining low-coverage files as blockers +- [ ] Add regression tests for every uncovered production bug fixed during the push to 90% +- [ ] Raise the coverage gate in CI only after the local baseline is stable for at least two consecutive runs + +## Ratchet policy + +Update `npm run test:coverage` thresholds only after the project actually exceeds the next milestone with a comfortable buffer. + +Recommended ratchet sequence: + +1. 55/60/55 +2. 60/62/58 +3. 65/64/62 +4. 70/66/66 +5. 75/70/72 +6. 80/75/78 +7. 85/80/84 +8. 90/85/88 + +Order is `statements-lines / branches / functions`. + +## Known gap + +The current coverage command measures the main Node unit suite and includes source reached from it, including `open-sse`. It does not yet merge Vitest coverage into a single unified report. That merge is worth doing later, but it is not a blocker for starting the 60% -> 80% climb. diff --git a/docs/i18n/bg/docs/FEATURES.md b/docs/i18n/bg/docs/FEATURES.md index f497f4cfd1..bf49c0d3f4 100644 --- a/docs/i18n/bg/docs/FEATURES.md +++ b/docs/i18n/bg/docs/FEATURES.md @@ -1,6 +1,6 @@ # OmniRoute โ€” Dashboard Features Gallery (ะ‘ัŠะปะณะฐั€ัะบะธ) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/FEATURES.md) --- @@ -10,7 +10,7 @@ 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). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. ![Providers Dashboard](screenshots/01-providers.png) diff --git a/docs/i18n/bg/docs/MCP-SERVER.md b/docs/i18n/bg/docs/MCP-SERVER.md new file mode 100644 index 0000000000..5efd42c421 --- /dev/null +++ b/docs/i18n/bg/docs/MCP-SERVER.md @@ -0,0 +1,87 @@ +# OmniRoute MCP Server Documentation (ะ‘ัŠะปะณะฐั€ัะบะธ) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/MCP-SERVER.md) + +--- + +> Model Context Protocol server with 16 intelligent tools + +## ะ˜ะฝัั‚ะฐะปะธั€ะฐะฝะต + +OmniRoute MCP is built-in. Start it with: + +```bash +omniroute --mcp +``` + +Or via the open-sse transport: + +```bash +# HTTP streamable transport (port 20130) +omniroute --dev # MCP auto-starts on /mcp endpoint +``` + +## IDE Configuration + +See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup. + +--- + +## Essential Tools (8) + +| Tool | Description | +| :------------------------------ | :--------------------------------------- | +| `omniroute_get_health` | Gateway health, circuit breakers, uptime | +| `omniroute_list_combos` | All configured combos with models | +| `omniroute_get_combo_metrics` | Performance metrics for a specific combo | +| `omniroute_switch_combo` | Switch active combo by ID/name | +| `omniroute_check_quota` | Quota status per provider or all | +| `omniroute_route_request` | Send a chat completion through OmniRoute | +| `omniroute_cost_report` | Cost analytics for a time period | +| `omniroute_list_models_catalog` | Full model catalog with capabilities | + +## Advanced Tools (8) + +| Tool | Description | +| :--------------------------------- | :---------------------------------------------------------- | +| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | +| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | +| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | +| `omniroute_test_combo` | Live-test all models in a combo via a real upstream request | +| `omniroute_get_provider_metrics` | Detailed metrics for one provider | +| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | +| `omniroute_explain_route` | Explain a past routing decision | +| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | + +## Authentication + +MCP tools are authenticated via API key scopes. Each tool requires specific scopes: + +| Scope | Tools | +| :------------- | :----------------------------------------------- | +| `read:health` | get_health, get_provider_metrics | +| `read:combos` | list_combos, get_combo_metrics | +| `write:combos` | switch_combo | +| `read:quota` | check_quota | +| `write:route` | route_request, simulate_route, test_combo | +| `read:usage` | cost_report, get_session_snapshot, explain_route | +| `write:config` | set_budget_guard, set_resilience_profile | +| `read:models` | list_models_catalog, best_combo_for_task | + +## Audit Logging + +Every tool call is logged to `mcp_tool_audit` with: + +- Tool name, arguments, result +- Duration (ms), success/failure +- API key hash, timestamp + +## Files + +| File | Purpose | +| :------------------------------------------- | :------------------------------------------ | +| `open-sse/mcp-server/server.ts` | MCP server creation + 16 tool registrations | +| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport | +| `open-sse/mcp-server/auth.ts` | API key + scope validation | +| `open-sse/mcp-server/audit.ts` | Tool call audit logging | +| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers | diff --git a/docs/i18n/bg/docs/RELEASE_CHECKLIST.md b/docs/i18n/bg/docs/RELEASE_CHECKLIST.md new file mode 100644 index 0000000000..451d2cd518 --- /dev/null +++ b/docs/i18n/bg/docs/RELEASE_CHECKLIST.md @@ -0,0 +1,37 @@ +# Release Checklist (ะ‘ัŠะปะณะฐั€ัะบะธ) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/RELEASE_CHECKLIST.md) + +--- + +Use this checklist before tagging or publishing a new OmniRoute release. + +## Version and Changelog + +1. Bump `package.json` version (`x.y.z`) in the release branch. +2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: + - `## [x.y.z] โ€” YYYY-MM-DD` +3. Keep `## [Unreleased]` as the first changelog section for upcoming work. +4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. + +## API Docs + +1. Update `docs/openapi.yaml`: + - `info.version` must equal `package.json` version. +2. Validate endpoint examples if API contracts changed. + +## Runtime Docs + +1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. +2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. +3. Update localized docs if source docs changed significantly. + +## Automated Check + +Run the sync guard locally before opening PR: + +```bash +npm run check:docs-sync +``` + +CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/bg/TROUBLESHOOTING.md b/docs/i18n/bg/docs/TROUBLESHOOTING.md similarity index 77% rename from docs/i18n/bg/TROUBLESHOOTING.md rename to docs/i18n/bg/docs/TROUBLESHOOTING.md index 63c148000a..002fdc491f 100644 --- a/docs/i18n/bg/TROUBLESHOOTING.md +++ b/docs/i18n/bg/docs/TROUBLESHOOTING.md @@ -1,11 +1,9 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/TROUBLESHOOTING.md) +# Troubleshooting (ะ‘ัŠะปะณะฐั€ัะบะธ) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/TROUBLESHOOTING.md) --- -# Troubleshooting - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/TROUBLESHOOTING.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/TROUBLESHOOTING.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/TROUBLESHOOTING.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/TROUBLESHOOTING.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/TROUBLESHOOTING.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/TROUBLESHOOTING.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/TROUBLESHOOTING.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/TROUBLESHOOTING.md) - Common problems and solutions for OmniRoute. --- diff --git a/docs/i18n/bg/USER_GUIDE.md b/docs/i18n/bg/docs/USER_GUIDE.md similarity index 82% rename from docs/i18n/bg/USER_GUIDE.md rename to docs/i18n/bg/docs/USER_GUIDE.md index d6649af4a7..d68a4c1dfe 100644 --- a/docs/i18n/bg/USER_GUIDE.md +++ b/docs/i18n/bg/docs/USER_GUIDE.md @@ -1,8 +1,6 @@ # User Guide (ะ‘ัŠะปะณะฐั€ัะบะธ) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/USER_GUIDE.md) - -> ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/USER_GUIDE.md) --- @@ -320,7 +318,7 @@ Model: cc/claude-opus-4-6 --- -## ๐Ÿš€ Deployment +## ะ ะฐะทะณั€ัŠั‰ะฐะฝะต ### Global npm install (Recommended) @@ -511,23 +509,26 @@ post_install() { ### Environment Variables -| Variable | Default | Description | -| ------------------------- | ------------------------------------ | ------------------------------------------------------- | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | -| `INITIAL_PASSWORD` | `123456` | First login password | -| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | -| `PORT` | framework default | Service port (`20128` in examples) | -| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | -| `NODE_ENV` | runtime default | Set `production` for deploy | -| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | -| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | -| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | -| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | -| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | -| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | -| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | -| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | +| 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/*` | +| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand | +| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | For the full environment variable reference, see the [README](../README.md). @@ -598,6 +599,11 @@ curl -X POST http://localhost:20128/api/provider-models \ Or use Dashboard: **Providers โ†’ [Provider] โ†’ Custom Models**. +Notes: + +- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers. +- The **Custom Models** section is intended for providers that do not expose managed available-model imports. + ### Dedicated Provider Routes Route requests directly to a specific provider with model validation: @@ -642,6 +648,14 @@ Returns models grouped by provider with types (`chat`, `embedding`, `image`). - Automatic background sync with timeout + fail-fast - Prefer server-side `BASE_URL`/`CLOUD_URL` in production +### Cloudflare Quick Tunnel + +- Available in **Dashboard โ†’ Endpoints** for Docker and other self-hosted deployments +- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint +- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary +- Tunnel URLs are ephemeral and change every time you stop/start the tunnel +- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download + ### LLM Gateway Intelligence (Phase 9) - **Semantic Cache** โ€” Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) @@ -757,11 +771,11 @@ OmniRoute implements provider-level resilience with four components: 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 | +| 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 unless `DISABLE_SQLITE_AUTO_BACKUP=true` | ```bash # API: Export database @@ -787,10 +801,11 @@ curl -X POST http://localhost:20128/api/db-backups/import \ ### Settings Dashboard -The settings page is organized into 5 tabs for easy navigation: +The settings page is organized into 6 tabs for easy navigation: | Tab | Contents | | -------------- | ---------------------------------------------------------------------------------------------- | +| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility | | **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | | **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | | **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | diff --git a/docs/i18n/bg/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/bg/docs/VM_DEPLOYMENT_GUIDE.md new file mode 100644 index 0000000000..0e75a7842e --- /dev/null +++ b/docs/i18n/bg/docs/VM_DEPLOYMENT_GUIDE.md @@ -0,0 +1,403 @@ +# OmniRoute โ€” Deployment Guide on VM with Cloudflare (ะ‘ัŠะปะณะฐั€ัะบะธ) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/VM_DEPLOYMENT_GUIDE.md) + +--- + +Complete guide to install and configure OmniRoute on a VM (VPS) with domain managed via Cloudflare. + +--- + +## Prerequisites + +| Item | Minimum | Recommended | +| ---------- | ------------------------ | ---------------- | +| **CPU** | 1 vCPU | 2 vCPU | +| **RAM** | 1 GB | 2 GB | +| **Disk** | 10 GB SSD | 25 GB SSD | +| **OS** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS | +| **Domain** | Registered on Cloudflare | โ€” | +| **Docker** | Docker Engine 24+ | Docker 27+ | + +**Tested providers**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. + +--- + +## 1. Configure the VM + +### 1.1 Create the instance + +On your preferred VPS provider: + +- Choose Ubuntu 24.04 LTS +- Select the minimum plan (1 vCPU / 1 GB RAM) +- Set a strong root password or configure SSH key +- Note the **public IP** (e.g., `203.0.113.10`) + +### 1.2 Connect via SSH + +```bash +ssh root@203.0.113.10 +``` + +### 1.3 Update the system + +```bash +apt update && apt upgrade -y +``` + +### 1.4 Install Docker + +```bash +# Install dependencies +apt install -y ca-certificates curl gnupg + +# Add official Docker repository +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 Install nginx + +```bash +apt install -y nginx +``` + +### 1.6 Configure 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 +``` + +> **Tip**: For maximum security, restrict ports 80 and 443 to Cloudflare IPs only. See the [Advanced Security](#advanced-security) section. + +--- + +## 2. Install OmniRoute + +### 2.1 Create configuration directory + +```bash +mkdir -p /opt/omniroute +``` + +### 2.2 Create environment variables file + +```bash +cat > /opt/omniroute/.env << โ€˜EOFโ€™ +# === Security === +JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY +INITIAL_PASSWORD=YourSecurePassword123! +API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY +STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY +STORAGE_ENCRYPTION_KEY_VERSION=v1 +MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT + +# === 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 (change to your domain) === +BASE_URL=https://llms.seudominio.com +NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com + +# === Cloud Sync (optional) === +# CLOUD_URL=https://cloud.omniroute.online +# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online +EOF +``` + +> โš ๏ธ **IMPORTANT**: Generate unique secret keys! Use `openssl rand -hex 32` for each key. + +### 2.3 Start the 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 Verify that it is running + +```bash +docker ps | grep omniroute +docker logs omniroute --tail 20 +``` + +It should display: `[DB] SQLite database ready` and `listening on port 20128`. + +--- + +## 3. Configure nginx (Reverse Proxy) + +### 3.1 Generate SSL certificate (Cloudflare Origin) + +In the Cloudflare dashboard: + +1. Go to **SSL/TLS โ†’ Origin Server** +2. Click **Create Certificate** +3. Keep the defaults (15 years, \*.yourdomain.com) +4. Copy the **Origin Certificate** and the **Private Key** + +```bash +mkdir -p /etc/nginx/ssl + +# Paste the certificate +nano /etc/nginx/ssl/origin.crt + +# Paste the private key +nano /etc/nginx/ssl/origin.key + +chmod 600 /etc/nginx/ssl/origin.key +``` + +### 3.2 Nginx Configuration + +```bash +cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ +# Default server โ€” blocks direct access via 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.yourdomain.com; # Change to your domain + + 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.yourdomain.com; + return 301 https://$server_name$request_uri; +} +NGINX +``` + +### 3.3 Enable and Test + +```bash +# Remove default configuration +rm -f /etc/nginx/sites-enabled/default + +# Enable OmniRoute +ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute + +# Test and reload +nginx -t && systemctl reload nginx +``` + +--- + +## 4. Configure Cloudflare DNS + +### 4.1 Add DNS record + +In the Cloudflare dashboard โ†’ DNS: + +| Type | Name | Content | Proxy | +| ---- | ------ | ---------------------- | ---------- | +| A | `llms` | `203.0.113.10` (VM IP) | โœ… Proxied | + +### 4.2 Configure SSL + +Under **SSL/TLS โ†’ Overview**: + +- Mode: **Full (Strict)** + +Under **SSL/TLS โ†’ Edge Certificates**: + +- Always Use HTTPS: โœ… On +- Minimum TLS Version: TLS 1.2 +- Automatic HTTPS Rewrites: โœ… On + +### 4.3 Testing + +```bash +curl -sI https://llms.seudominio.com/health +# Should return HTTP/2 200 +``` + +--- + +## 5. Operations and Maintenance + +### Upgrade to a new version + +```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 +``` + +### View logs + +```bash +docker logs -f omniroute # Real-time stream +docker logs omniroute --tail 50 # Last 50 lines +``` + +### Manual database backup + +```bash +# Copy data from the volume to the host +docker cp omniroute:/app/data ./backup-$(date +%F) + +# Or compress the entire volume +docker run --rm -v omniroute-data:/data -v $(pwd):/backup \ + alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data +``` + +### Restore from 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. Advanced Security + +### Restrict nginx to Cloudflare IPs + +```bash +cat > /etc/nginx/cloudflare-ips.conf << โ€˜CFโ€™ +# Cloudflare IPv4 ranges โ€” update periodically +# 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 +``` + +Add the following to `nginx.conf` inside the `http {}` block: + +```nginx +include /etc/nginx/cloudflare-ips.conf; +``` + +### Install fail2ban + +```bash +apt install -y fail2ban +systemctl enable fail2ban +systemctl start fail2ban + +# Check status +fail2ban-client status sshd +``` + +### Block direct access to the Docker port + +```bash +# Prevent direct external access to port 20128 +iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP +iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT + +# Persist the rules +apt install -y iptables-persistent +netfilter-persistent save +``` + +--- + +## 7. Deploy to Cloudflare Workers (Optional) + +For remote access via Cloudflare Workers (without exposing the VM directly): + +```bash +# In the local repository +cd omnirouteCloud +npm install +npx wrangler login +npx wrangler deploy +``` + +See the full documentation at [omnirouteCloud/README.md](../omnirouteCloud/README.md). + +--- + +## Port Summary + +| Port | Service | Access | +| ----- | ----------- | -------------------------- | +| 22 | SSH | Public (with fail2ban) | +| 80 | nginx HTTP | Redirect โ†’ HTTPS | +| 443 | nginx HTTPS | Via Cloudflare Proxy | +| 20128 | OmniRoute | Localhost only (via nginx) | diff --git a/docs/i18n/bg/src/lib/a2a/README.md b/docs/i18n/bg/src/lib/a2a/README.md new file mode 100644 index 0000000000..51ea7b5055 --- /dev/null +++ b/docs/i18n/bg/src/lib/a2a/README.md @@ -0,0 +1,752 @@ +# OmniRoute A2A Server (ะ‘ัŠะปะณะฐั€ัะบะธ) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../../../src/lib/a2a/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../../../es/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../../../fr/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../../../de/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../../../it/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../../../ru/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../../../zh-CN/src/lib/a2a/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../../../ja/src/lib/a2a/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../../../ko/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../../../ar/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../../../in/src/lib/a2a/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../../../th/src/lib/a2a/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../../../vi/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../../../id/src/lib/a2a/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../../../ms/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../../../nl/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../../../pl/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../../../sv/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../../../no/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../../../da/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../../../fi/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../../../pt/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../../../ro/src/lib/a2a/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../../../hu/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../../../bg/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../../../sk/src/lib/a2a/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../../../uk-UA/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../../../he/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../../../phi/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../../../pt-BR/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../../../cs/src/lib/a2a/README.md) + +--- + +> **Agent-to-Agent Protocol v0.3** โ€” Enables any AI agent to use OmniRoute as an intelligent routing agent via JSON-RPC 2.0. + +The A2A Server exposes OmniRoute as a **first-class agent** that other agents can discover, delegate tasks to, and collaborate with using the [A2A Protocol](https://google.github.io/A2A/). + +--- + +## ะั€ั…ะธั‚ะตะบั‚ัƒั€ะฐ + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Orchestrator Agent โ”‚ +โ”‚ (LangChain, CrewAI, AutoGen, Custom Agent) โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ 1. GET /.well-known/agent.json (discover) + โ”‚ 2. POST /a2a (JSON-RPC 2.0) + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ OmniRoute A2A Server โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Task Manager โ”‚ โ”‚ Skill Engine โ”‚ โ”‚ SSE Streaming โ”‚ โ”‚ +โ”‚ โ”‚ (lifecycle) โ”‚โ”€โ”€โ”‚ (registry) โ”‚โ”€โ”€โ”‚ (real-time) โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ +โ”‚ Skills: โ”‚ โ”‚ +โ”‚ โ”œโ”€ smart-routing โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ””โ”€ quota-management โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ Routing Decision Logger โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ OmniRoute Gateway (internal) + /v1/chat/completions, /api/combos, /api/usage/quota +``` + +--- + +## ะ‘ัŠั€ะท ัั‚ะฐั€ั‚ + +### Agent Discovery + +Every A2A-compatible agent exposes an **Agent Card** at `/.well-known/agent.json`: + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +**Response:** + +```json +{ + "name": "OmniRoute", + "description": "Intelligent AI gateway with auto-routing across 50+ providers", + "url": "http://localhost:20128/a2a", + "version": "1.8.1", + "capabilities": { + "streaming": true, + "pushNotifications": false + }, + "skills": [ + { + "id": "smart-routing", + "name": "Smart Routing", + "description": "Routes prompts through OmniRoute intelligent pipeline", + "tags": ["routing", "llm", "multi-provider", "cost-optimization"], + "examples": [ + "Write a hello world in Python", + "Explain quantum computing using the cheapest provider" + ] + }, + { + "id": "quota-management", + "name": "Quota Management", + "description": "Natural-language queries about provider quotas", + "tags": ["quota", "analytics", "cost"], + "examples": [ + "Which provider has the most quota remaining?", + "Suggest a free combo for coding" + ] + } + ], + "authentication": { + "schemes": ["bearer"], + "apiKeyHeader": "Authorization" + } +} +``` + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Send a message to a skill and receive the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python hello world"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "a1b2c3d4-...", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "print('Hello, World!')" }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.0030)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "2026-03-04T..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"Quantum computing..."}}} + +: heartbeat 2026-03-04T21:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Running Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Skills Reference + +### `smart-routing` + +Routes prompts through OmniRoute's intelligent pipeline with full observability. + +**Parameters (in `metadata`):** + +| Parameter | Type | Default | Description | +| --------- | -------- | ------------ | ---------------------------------------------------------------------------------------- | +| `model` | `string` | `"auto"` | Target model (e.g., `claude-sonnet-4`, `gpt-4o`, `auto`) | +| `combo` | `string` | active combo | Specific combo to route through | +| `budget` | `number` | none | Maximum cost in USD for this request | +| `role` | `string` | none | Task role hint: `coding`, `review`, `planning`, `analysis`, `debugging`, `documentation` | + +**Returns:** + +| Field | Description | +| ------------------------------ | --------------------------------------------------------- | +| `artifacts[].content` | The LLM response text | +| `metadata.routing_explanation` | Human-readable explanation of routing decision | +| `metadata.cost_envelope` | Estimated vs actual cost with currency | +| `metadata.resilience_trace` | Array of events (primary_selected, fallback_needed, etc.) | +| `metadata.policy_verdict` | Whether the request was allowed and why | + +### `quota-management` + +Answers natural-language queries about provider quotas. + +**Query types (inferred from message content):** + +| Query Pattern | Response Type | +| ---------------------------------------------- | -------------------------------------------------------- | +| Contains `"ranking"`, `"most quota"`, `"best"` | Providers ranked by remaining quota | +| Contains `"free"`, `"suggest"` | Lists free combos or suggests free-tier providers | +| Default | Full quota summary with warnings for low-quota providers | + +--- + +## Task Lifecycle + +``` +submitted โ”€โ”€โ†’ working โ”€โ”€โ†’ completed + โ”€โ”€โ†’ failed + โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ†’ cancelled +``` + +| State | Description | +| ----------- | ----------------------------------------------------- | +| `submitted` | Task created, queued for execution | +| `working` | Skill handler is executing | +| `completed` | Execution succeeded, artifacts available | +| `failed` | Execution failed or task expired (TTL: 5 min default) | +| `cancelled` | Cancelled by client via `tasks/cancel` | + +- Terminal states: `completed`, `failed`, `cancelled` (no further transitions) +- Expired tasks in `submitted` or `working` are auto-marked as `failed` +- Tasks are garbage-collected after 2ร— TTL + +--- + +## Client Examples + +### Python โ€” Orchestrator Agent + +```python +""" +A2A Client โ€” Python example. +Discovers OmniRoute agent, sends a task, and processes the result. +""" +import requests +import json + +BASE_URL = "http://localhost:20128" +API_KEY = "your-api-key" +HEADERS = { + "Content-Type": "application/json", + "Authorization": f"Bearer {API_KEY}", +} + +# 1. Discover agent capabilities +agent_card = requests.get(f"{BASE_URL}/.well-known/agent.json").json() +print(f"Agent: {agent_card['name']} v{agent_card['version']}") +print(f"Skills: {[s['id'] for s in agent_card['skills']]}") + +# 2. Send a smart-routing task +response = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python quicksort implementation"}], + "metadata": { + "model": "auto", + "combo": "fast-coding", + "budget": 0.10, + } + } +}) +result = response.json()["result"] +print(f"\n๐Ÿ“ Response: {result['artifacts'][0]['content'][:200]}...") +print(f"๐Ÿ”€ Routing: {result['metadata']['routing_explanation']}") +print(f"๐Ÿ’ฐ Cost: ${result['metadata']['cost_envelope']['actual']}") +print(f"๐Ÿ›ก๏ธ Policy: {result['metadata']['policy_verdict']['reason']}") + +# 3. Query quota status +quota_resp = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-2", + "method": "message/send", + "params": { + "skill": "quota-management", + "messages": [{"role": "user", "content": "Which provider has the most quota remaining?"}], + } +}) +quota_result = quota_resp.json()["result"] +print(f"\n๐Ÿ“Š Quota: {quota_result['artifacts'][0]['content']}") +``` + +### TypeScript โ€” Multi-Agent Orchestrator + +```typescript +/** + * A2A Client โ€” TypeScript example. + * Shows agent discovery, task delegation, and streaming. + */ + +const BASE_URL = "http://localhost:20128"; +const API_KEY = "your-api-key"; + +interface JsonRpcResponse { + jsonrpc: "2.0"; + id: string | number; + result?: T; + error?: { code: number; message: string }; +} + +async function a2aCall(method: string, params: Record): Promise { + const resp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: `${method}-${Date.now()}`, + method, + params, + }), + }); + const json: JsonRpcResponse = await resp.json(); + if (json.error) throw new Error(`[${json.error.code}] ${json.error.message}`); + return json.result!; +} + +// โ”€โ”€ Agent Discovery โ”€โ”€ +const agentCard = await fetch(`${BASE_URL}/.well-known/agent.json`).then((r) => r.json()); +console.log(`Connected to: ${agentCard.name} (${agentCard.skills.length} skills)`); + +// โ”€โ”€ Smart Routing: Send a coding task โ”€โ”€ +const routingResult = await a2aCall("message/send", { + skill: "smart-routing", + messages: [{ role: "user", content: "Implement a Redis cache wrapper in TypeScript" }], + metadata: { model: "claude-sonnet-4", role: "coding" }, +}); +console.log("Response:", routingResult.artifacts[0].content); +console.log("Provider:", routingResult.metadata.routing_explanation); + +// โ”€โ”€ Quota Management: Find free alternatives โ”€โ”€ +const quotaResult = await a2aCall("message/send", { + skill: "quota-management", + messages: [{ role: "user", content: "Suggest free combos for documentation" }], +}); +console.log("Free combos:", quotaResult.artifacts[0].content); + +// โ”€โ”€ Streaming: Real-time response โ”€โ”€ +const streamResp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "stream-1", + method: "message/stream", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Explain microservices architecture" }], + }, + }), +}); + +const reader = streamResp.body!.getReader(); +const decoder = new TextDecoder(); +while (true) { + const { done, value } = await reader.read(); + if (done) break; + const chunk = decoder.decode(value); + for (const line of chunk.split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + if (event.params.chunk) { + process.stdout.write(event.params.chunk.content); + } + if (event.params.task.state === "completed") { + console.log("\nโœ… Stream completed"); + } + } + } +} +``` + +### Python โ€” LangChain A2A Integration + +```python +""" +LangChain integration โ€” Use OmniRoute A2A as a custom LLM. +""" +from langchain.llms.base import BaseLLM +from langchain.schema import LLMResult, Generation +import requests +from typing import List, Optional + +class OmniRouteA2A(BaseLLM): + base_url: str = "http://localhost:20128" + api_key: str = "" + model: str = "auto" + combo: Optional[str] = None + + @property + def _llm_type(self) -> str: + return "omniroute-a2a" + + def _call(self, prompt: str, stop: Optional[List[str]] = None, **kwargs) -> str: + response = requests.post( + f"{self.base_url}/a2a", + headers={ + "Content-Type": "application/json", + "Authorization": f"Bearer {self.api_key}", + }, + json={ + "jsonrpc": "2.0", + "id": "langchain-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": prompt}], + "metadata": { + "model": self.model, + **({"combo": self.combo} if self.combo else {}), + }, + }, + }, + ) + result = response.json()["result"] + return result["artifacts"][0]["content"] + + def _generate(self, prompts: List[str], stop=None, **kwargs) -> LLMResult: + return LLMResult( + generations=[[Generation(text=self._call(p, stop))] for p in prompts] + ) + +# Usage +llm = OmniRouteA2A( + base_url="http://localhost:20128", + api_key="your-key", + model="auto", + combo="fast-coding", +) +result = llm("Write a Python function to merge two sorted lists") +print(result) +``` + +### Go โ€” A2A Client + +```go +package main + +import ( + "bytes" + "encoding/json" + "fmt" + "io" + "net/http" +) + +const baseURL = "http://localhost:20128" +const apiKey = "your-api-key" + +type JsonRpcRequest struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Method string `json:"method"` + Params interface{} `json:"params"` +} + +type JsonRpcResponse struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Result interface{} `json:"result"` + Error *struct { + Code int `json:"code"` + Message string `json:"message"` + } `json:"error"` +} + +func a2aCall(method string, params interface{}) (*JsonRpcResponse, error) { + body, _ := json.Marshal(JsonRpcRequest{ + Jsonrpc: "2.0", + ID: "go-1", + Method: method, + Params: params, + }) + + req, _ := http.NewRequest("POST", baseURL+"/a2a", bytes.NewReader(body)) + req.Header.Set("Content-Type", "application/json") + req.Header.Set("Authorization", "Bearer "+apiKey) + + resp, err := http.DefaultClient.Do(req) + if err != nil { + return nil, err + } + defer resp.Body.Close() + data, _ := io.ReadAll(resp.Body) + + var result JsonRpcResponse + json.Unmarshal(data, &result) + return &result, nil +} + +func main() { + // Discover agent + resp, _ := http.Get(baseURL + "/.well-known/agent.json") + defer resp.Body.Close() + body, _ := io.ReadAll(resp.Body) + fmt.Println("Agent Card:", string(body)) + + // Send smart-routing task + result, _ := a2aCall("message/send", map[string]interface{}{ + "skill": "smart-routing", + "messages": []map[string]string{{"role": "user", "content": "Hello from Go!"}}, + "metadata": map[string]interface{}{"model": "auto"}, + }) + out, _ := json.MarshalIndent(result.Result, "", " ") + fmt.Println("Result:", string(out)) +} +``` + +--- + +## Use Cases + +### ๐Ÿค– Use Case 1: Multi-Agent Coding Pipeline + +An orchestrator agent delegates code generation to OmniRoute, then passes the output to a review agent. + +```python +def coding_pipeline(task: str): + # Step 1: Generate code via OmniRoute A2A + code_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Write production-quality code: {task}"} + ], metadata={"model": "auto", "role": "coding"}) + code = code_result["artifacts"][0]["content"] + + # Step 2: Review the code via OmniRoute A2A (different model) + review_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Review this code for bugs and improvements:\n\n{code}"} + ], metadata={"model": "auto", "role": "review"}) + review = review_result["artifacts"][0]["content"] + + # Step 3: Check costs + print(f"Code cost: ${code_result['metadata']['cost_envelope']['actual']}") + print(f"Review cost: ${review_result['metadata']['cost_envelope']['actual']}") + + return {"code": code, "review": review} +``` + +### ๐Ÿ’ก Use Case 2: Quota-Aware Agent Swarm + +Multiple agents share quota through OmniRoute, using the quota skill to coordinate. + +```python +async def quota_aware_agent(agent_name: str, task: str): + # Check quota before starting + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Which provider has the most quota remaining?"} + ]) + print(f"[{agent_name}] {quota['artifacts'][0]['content']}") + + # Send request with budget constraint + result = a2a_send("smart-routing", [ + {"role": "user", "content": task} + ], metadata={"budget": 0.05}) + + policy = result["metadata"]["policy_verdict"] + if not policy["allowed"]: + print(f"[{agent_name}] โš ๏ธ Budget exceeded: {policy['reason']}") + # Fall back to free combo + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Suggest free combos"} + ]) + print(f"[{agent_name}] Free alternatives: {quota['artifacts'][0]['content']}") + + return result +``` + +### ๐Ÿ“Š Use Case 3: Real-Time Streaming Dashboard + +A monitoring agent streams responses and displays progress in real-time. + +```typescript +async function streamingDashboard(prompt: string) { + const response = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { "Content-Type": "application/json", Authorization: `Bearer ${API_KEY}` }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "dash-1", + method: "message/stream", + params: { skill: "smart-routing", messages: [{ role: "user", content: prompt }] }, + }), + }); + + let totalChunks = 0; + const reader = response.body!.getReader(); + const decoder = new TextDecoder(); + + while (true) { + const { done, value } = await reader.read(); + if (done) break; + + for (const line of decoder.decode(value).split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + const state = event.params.task.state; + + if (state === "working" && event.params.chunk) { + totalChunks++; + process.stdout.write( + `\r[Chunk ${totalChunks}] ${event.params.chunk.content.slice(0, 50)}...` + ); + } + if (state === "completed") { + const meta = event.params.metadata; + console.log( + `\nโœ… Done | Cost: $${meta?.cost_envelope?.actual || 0} | Route: ${meta?.routing_explanation || "N/A"}` + ); + } + if (state === "failed") { + console.error(`\nโŒ Failed: ${event.params.metadata?.error}`); + } + } + } + } +} +``` + +### ๐Ÿ” Use Case 4: Task Polling Pattern + +For long-running tasks, poll the task status instead of waiting synchronously. + +```python +import time + +def poll_task(task_id: str, timeout: int = 60): + """Poll task status until completion or timeout.""" + start = time.time() + while time.time() - start < timeout: + result = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "poll-1", + "method": "tasks/get", + "params": {"taskId": task_id}, + }).json() + + task = result["result"]["task"] + state = task["state"] + print(f" Task {task_id[:8]}... state={state}") + + if state in ("completed", "failed", "cancelled"): + return task + time.sleep(2) + + # Timeout โ€” cancel the task + requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "cancel-1", + "method": "tasks/cancel", + "params": {"taskId": task_id}, + }) + raise TimeoutError(f"Task {task_id} timed out after {timeout}s") +``` + +--- + +## Error Codes + +| Code | Constant | Meaning | +| ------ | ------------------------ | ---------------------------------------- | +| -32700 | โ€” | Parse error (invalid JSON) | +| -32600 | `INVALID_REQUEST` | Invalid JSON-RPC request or unauthorized | +| -32601 | `METHOD_NOT_FOUND` | Unknown method or skill | +| -32602 | `INVALID_PARAMS` | Missing or invalid parameters | +| -32603 | `INTERNAL_ERROR` | Skill execution failed | +| -32001 | `TASK_NOT_FOUND` | Task ID not found | +| -32002 | `TASK_ALREADY_COMPLETED` | Cannot modify a completed task | +| -32003 | `UNAUTHORIZED` | Invalid or missing API key | +| -32004 | `BUDGET_EXCEEDED` | Request exceeds configured budget | +| -32005 | `PROVIDER_UNAVAILABLE` | No available providers | + +--- + +## Authentication + +All `/a2a` requests require a Bearer token via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server (`OMNIROUTE_API_KEY` is empty), authentication is bypassed. + +--- + +## File Structure + +``` +src/lib/a2a/ +โ”œโ”€โ”€ taskManager.ts # Task lifecycle (create/update/cancel/list), TTL, cleanup +โ”œโ”€โ”€ taskExecution.ts # Generic task executor with state management +โ”œโ”€โ”€ streaming.ts # SSE stream formatting, heartbeat, chunk/completion events +โ”œโ”€โ”€ routingLogger.ts # Routing decision logger (stats, history, retention) +โ””โ”€โ”€ skills/ + โ”œโ”€โ”€ smartRouting.ts # Smart routing skill (routes via /v1/chat/completions) + โ””โ”€โ”€ quotaManagement.ts # Quota management skill (natural-language quota queries) + +src/app/a2a/ +โ””โ”€โ”€ route.ts # Next.js API route handler (JSON-RPC 2.0 dispatch) + +open-sse/mcp-server/ +โ””โ”€โ”€ schemas/a2a.ts # Zod schemas (AgentCard, Task, JSON-RPC, SSE events) +``` + +--- + +## Comparison: MCP vs A2A + +| Feature | MCP Server | A2A Server | +| ----------------- | ---------------------------- | ------------------------------------------------- | +| **Protocol** | Model Context Protocol | Agent-to-Agent Protocol v0.3 | +| **Transport** | stdio / HTTP | HTTP (JSON-RPC 2.0) | +| **Discovery** | Tool listing via MCP | `/.well-known/agent.json` | +| **Granularity** | 16 individual tools | 2 high-level skills | +| **Best for** | IDE agents (Cursor, VS Code) | Multi-agent systems (LangChain, CrewAI) | +| **Streaming** | Not supported | SSE via `message/stream` | +| **Task tracking** | No | Full lifecycle (submitted โ†’ completed) | +| **Observability** | Audit log per tool call | Cost envelope + resilience trace + policy verdict | + +--- + +## ะ›ะธั†ะตะฝะท + +Part of [OmniRoute](https://github.com/diegosouzapw/OmniRoute) โ€” MIT License. diff --git a/docs/i18n/cs/A2A-SERVER.md b/docs/i18n/cs/A2A-SERVER.md deleted file mode 100644 index eeea4337cc..0000000000 --- a/docs/i18n/cs/A2A-SERVER.md +++ /dev/null @@ -1,196 +0,0 @@ -# Dokumentace k serveru OmniRoute A2A - -> Protokol Agent-to-Agent v0.3 โ€” OmniRoute jako inteligentnรญ smฤ›rovacรญ agent - -## Objevovรกnรญ agentลฏ - -```bash -curl http://localhost:20128/.well-known/agent.json -``` - -Vrรกtรญ kartu agenta popisujรญcรญ schopnosti, dovednosti a poลพadavky na ovฤ›ล™ovรกnรญ OmniRoute. - ---- - -## Ovฤ›ล™ovรกnรญ - -Vลกechny poลพadavky `/a2a` vyลพadujรญ klรญฤ API zadanรฝ prostล™ednictvรญm hlaviฤky `Authorization` : - -``` -Authorization: Bearer YOUR_OMNIROUTE_API_KEY -``` - -Pokud na serveru nenรญ nakonfigurovรกn ลพรกdnรฝ klรญฤ API, ovฤ›ล™ovรกnรญ se obejde. - ---- - -## Metody JSON-RPC 2.0 - -### `message/send` โ€” synchronnรญ spuลกtฤ›nรญ - -Odeลกle zprรกvu dovednosti a ฤekรก na รบplnou odpovฤ›ฤ. - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{ - "jsonrpc": "2.0", - "id": "1", - "method": "message/send", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Write a hello world in Python"}], - "metadata": {"model": "auto", "combo": "fast-coding"} - } - }' -``` - -**Odpovฤ›ฤ:** - -```json -{ - "jsonrpc": "2.0", - "id": "1", - "result": { - "task": { "id": "uuid", "state": "completed" }, - "artifacts": [{ "type": "text", "content": "..." }], - "metadata": { - "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)", - "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, - "resilience_trace": [ - { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." } - ], - "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } - } - } -} -``` - -### `message/stream` โ€” SSE streamovรกnรญ - -Stejnรฉ jako `message/send` , ale vracรญ udรกlosti odeslanรฉ serverem pro streamovรกnรญ v reรกlnรฉm ฤase. - -```bash -curl -N -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{ - "jsonrpc": "2.0", - "id": "1", - "method": "message/stream", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Explain quantum computing"}] - } - }' -``` - -**Udรกlosti SSE:** - -``` -data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}} - -: heartbeat 2026-03-03T17:00:00Z - -data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} -``` - -### `tasks/get` โ€” Dotaz na stav รบlohy - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' -``` - -### `tasks/cancel` โ€” Zruลกit รบkol - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' -``` - ---- - -## Dostupnรฉ dovednosti - -Dovednost | Popis -:-- | :-- -`smart-routing` | Smฤ›ruje vรฝzvy prostล™ednictvรญm inteligentnรญho kanรกlu OmniRoute. Vracรญ odpovฤ›ฤ s vysvฤ›tlenรญm smฤ›rovรกnรญ, nรกklady a trasou odolnosti. -`quota-management` | Odpovรญdรก na dotazy v pล™irozenรฉm jazyce tรฝkajรญcรญ se kvรณt poskytovatelลฏ, navrhuje bezplatnรฉ kombinace a poskytuje hodnocenรญ kvรณt. - ---- - -## ลฝivotnรญ cyklus รบkolu - -``` -submitted โ†’ working โ†’ completed - โ†’ failed - โ†’ cancelled -``` - -- รškoly vyprลกรญ po 5 minutรกch (konfigurovatelnรฉ) -- Stavy terminรกlu: `completed` , `failed` , `cancelled` -- Zรกznam udรกlostรญ sleduje kaลพdรฝ pล™echod stavu - ---- - -## Chybovรฉ kรณdy - -Kรณd | Vรฝznam -:-- | :-- --32700 | Chyba pล™i analรฝze (neplatnรฝ JSON) --32600 | Neplatnรฝ poลพadavek / Neautorizovanรฝ --32601 | Metoda nebo dovednost nenalezena --32602 | Neplatnรฉ parametry --32603 | Internรญ chyba - ---- - -## Pล™รญklady integrace - -### Python (poลพadavky) - -```python -import requests - -resp = requests.post("http://localhost:20128/a2a", json={ - "jsonrpc": "2.0", "id": "1", - "method": "message/send", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Hello"}] - } -}, headers={"Authorization": "Bearer YOUR_KEY"}) - -result = resp.json()["result"] -print(result["artifacts"][0]["content"]) -print(result["metadata"]["routing_explanation"]) -``` - -### TypeScript (naฤtenรญ) - -```typescript -const resp = await fetch("http://localhost:20128/a2a", { - method: "POST", - headers: { - "Content-Type": "application/json", - Authorization: "Bearer YOUR_KEY", - }, - body: JSON.stringify({ - jsonrpc: "2.0", - id: "1", - method: "message/send", - params: { - skill: "smart-routing", - messages: [{ role: "user", content: "Hello" }], - }, - }), -}); -const { result } = await resp.json(); -console.log(result.metadata.routing_explanation); -``` diff --git a/docs/i18n/cs/API_REFERENCE.md b/docs/i18n/cs/API_REFERENCE.md deleted file mode 100644 index faa9628318..0000000000 --- a/docs/i18n/cs/API_REFERENCE.md +++ /dev/null @@ -1,453 +0,0 @@ -# Referenฤnรญ informace k API - -๐ŸŒ **Jazyky:** ๐Ÿ‡บ๐Ÿ‡ธ [angliฤtina](API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brazรญlie)](i18n/pt-BR/API_REFERENCE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/API_REFERENCE.md) | ๐Ÿ‡จ๐Ÿ‡ณ[ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/API_REFERENCE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/API_REFERENCE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/API_REFERENCE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต[ๆ—ฅๆœฌ่ชž](i18n/ja/API_REFERENCE.md)| ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dรกnsko](i18n/da/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/API_REFERENCE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [maฤarลกtina](i18n/hu/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonรฉsie](i18n/id/API_REFERENCE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/API_REFERENCE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nizozemsko](i18n/nl/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugalsko)](i18n/pt/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipรญnec](i18n/phi/API_REFERENCE.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](i18n/cs/API_REFERENCE.md) - -Kompletnรญ referenฤnรญ pล™รญruฤka pro vลกechny koncovรฉ body rozhranรญ OmniRoute API. - ---- - -## Obsah - -- [Dokonฤenรญ chatu](#chat-completions) -- [Vloลพenรญ](#embeddings) -- [Generovรกnรญ obrรกzkลฏ](#image-generation) -- [Seznam modelลฏ](#list-models) -- [Koncovรฉ body kompatibility](#compatibility-endpoints) -- [Sรฉmantickรก mezipamฤ›ลฅ](#semantic-cache) -- [ล˜รญdicรญ panel a sprรกva](#dashboard--management) -- [Zpracovรกnรญ ลพรกdosti](#request-processing) -- [Ovฤ›ล™ovรกnรญ](#authentication) - ---- - -## Dokonฤenรญ chatu - -```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 -} -``` - -### Vlastnรญ zรกhlavรญ - -| Zรกhlavรญ | Smฤ›r | Popis | -| ------------------------ | ------- | ------------------------------------------------- | -| `X-OmniRoute-No-Cache` | ลฝรกdost | Nastavenรญm na `true` se vynechรก mezipamฤ›ลฅ | -| `X-OmniRoute-Progress` | ลฝรกdost | Nastaveno na `true` pro udรกlosti prลฏbฤ›hu | -| `Idempotency-Key` | ลฝรกdost | Klรญฤ pro deduplikaci (okno 5 s) | -| `X-Request-Id` | ลฝรกdost | Alternativnรญ klรญฤ pro odstranฤ›nรญ duplicitnรญch dat | -| `X-OmniRoute-Cache` | Odpovฤ›ฤ | `HIT` or `MISS` (nestreamovanรฉ) | -| `X-OmniRoute-Idempotent` | Odpovฤ›ฤ | `true` , pokud je odstranฤ›na duplikace | -| `X-OmniRoute-Progress` | Odpovฤ›ฤ | `enabled` pokud je zapnuto sledovรกnรญ prลฏbฤ›hu | - -> Poznรกmka Nginx: pokud spolรฉhรกte na hlaviฤky s podtrลพรญtkem (napล™รญklad `x_session_id`), povolte `underscores_in_headers on;`. - ---- - -## Vloลพenรญ - -```bash -POST /v1/embeddings -Authorization: Bearer your-api-key -Content-Type: application/json - -{ - "model": "nebius/Qwen/Qwen3-Embedding-8B", - "input": "The food was delicious" -} -``` - -Dostupnรญ poskytovatelรฉ: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA. - -```bash -# List all embedding models -GET /v1/embeddings -``` - ---- - -## Generovรกnรญ obrรกzkลฏ - -```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" -} -``` - -Dostupnรญ poskytovatelรฉ: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI. - -```bash -# List all image models -GET /v1/images/generations -``` - ---- - -## Seznam modelลฏ - -```bash -GET /v1/models -Authorization: Bearer your-api-key - -โ†’ Returns all chat, embedding, and image models + combos in OpenAI format -``` - ---- - -## Koncovรฉ body kompatibility - -| Metoda | Cesta | Formรกt | -| ------ | --------------------------- | --------------------- | -| POST | `/v1/chat/completions` | OpenAI | -| POST | `/v1/messages` | Anthropic | -| POST | `/v1/responses` | Reakce OpenAI | -| POST | `/v1/embeddings` | OpenAI | -| POST | `/v1/images/generations` | OpenAI | -| GET | `/v1/models` | OpenAI | -| POST | `/v1/messages/count_tokens` | Anthropic | -| GET | `/v1beta/models` | Blรญลพenci | -| POST | `/v1beta/models/{...path}` | Gemini generuje obsah | -| POST | `/v1/api/chat` | Ollama | - -### Vyhrazenรฉ trasy poskytovatelลฏ - -```bash -POST /v1/providers/{provider}/chat/completions -POST /v1/providers/{provider}/embeddings -POST /v1/providers/{provider}/images/generations -``` - -Pokud chybรญ prefix poskytovatele, automaticky se pล™idรก. Neshodnรฉ modely vrรกtรญ chybu `400` . - ---- - -## Sรฉmantickรก mezipamฤ›ลฅ - -```bash -# Get cache stats -GET /api/cache - -# Clear all caches -DELETE /api/cache -``` - -Pล™รญklad odpovฤ›di: - -```json -{ - "semanticCache": { - "memorySize": 42, - "memoryMaxSize": 500, - "dbSize": 128, - "hitRate": 0.65 - }, - "idempotency": { - "activeKeys": 3, - "windowMs": 5000 - } -} -``` - ---- - -## ล˜รญdicรญ panel a sprรกva - -### Ovฤ›ล™ovรกnรญ - -| Koncovรฝ bod | Metoda | Popis | -| ----------------------------- | ------- | ------------------------------- | -| `/api/auth/login` | POST | Pล™ihlรกลกenรญ | -| `/api/auth/logout` | POST | Odhlรกsit se | -| `/api/settings/require-login` | GET/PUT | Vyลพaduje se pล™epnutรญ pล™ihlรกลกenรญ | - -### Sprรกva poskytovatelลฏ - -| Koncovรฝ bod | Metoda | Popis | -| ---------------------------- | --------------- | --------------------------------- | -| `/api/providers` | GET/POST | Seznam / vytvoล™enรญ poskytovatelลฏ | -| `/api/providers/[id]` | GET/PUT/DELETE | Sprรกva poskytovatele | -| `/api/providers/[id]/test` | POST | Testovacรญ pล™ipojenรญ poskytovatele | -| `/api/providers/[id]/models` | GET | Seznam modelลฏ poskytovatelลฏ | -| `/api/providers/validate` | POST | Ovฤ›ล™enรญ konfigurace poskytovatele | -| `/api/provider-nodes*` | Rลฏznรฉ | Sprรกva uzlลฏ poskytovatelลฏ | -| `/api/provider-models` | GET/POST/DELETE | Vlastnรญ modely | - -### Toky OAuth - -| Koncovรฝ bod | Metoda | Popis | -| -------------------------------- | ------ | ---------------------------------- | -| `/api/oauth/[provider]/[action]` | Rลฏznรฉ | OAuth specifickรฝ pro poskytovatele | - -### Smฤ›rovรกnรญ a konfigurace - -| Koncovรฝ bod | Metoda | Popis | -| --------------------- | -------- | ----------------------------------------- | -| `/api/models/alias` | GET/POST | Aliasy modelลฏ | -| `/api/models/catalog` | GET | Vลกechny modely podle poskytovatele + typu | -| `/api/combos*` | Rลฏznรฉ | Sprรกva kombinacรญ | -| `/api/keys*` | Rลฏznรฉ | Sprรกva klรญฤลฏ API | -| `/api/pricing` | GET | Cena modelu | - -### Vyuลพitรญ a analรฝzy - -| Koncovรฝ bod | Metoda | Popis | -| --------------------------- | ------ | ----------------------------- | -| `/api/usage/history` | GET | Historie pouลพรญvรกnรญ | -| `/api/usage/logs` | GET | Protokoly pouลพรญvรกnรญ | -| `/api/usage/request-logs` | GET | Protokoly na รบrovni poลพadavkลฏ | -| `/api/usage/[connectionId]` | GET | Vyuลพitรญ na pล™ipojenรญ | - -### Nastavenรญ - -| Koncovรฝ bod | Metoda | Popis | -| ------------------------------- | ------- | -------------------------------------- | -| `/api/settings` | GET/PUT | Obecnรก nastavenรญ | -| `/api/settings/proxy` | GET/PUT | Konfigurace sรญลฅovรฉho proxy serveru | -| `/api/settings/proxy/test` | POST | Testovacรญ pล™ipojenรญ k proxy serveru | -| `/api/settings/ip-filter` | GET/PUT | Seznam povolenรฝch/blokovanรฝch IP adres | -| `/api/settings/thinking-budget` | GET/PUT | Zdลฏvodnฤ›nรญ rozpoฤtu tokenลฏ | -| `/api/settings/system-prompt` | GET/PUT | Globรกlnรญ systรฉmovรฝ vรฝzva | - -### Monitorovรกnรญ - -| Koncovรฝ bod | Metoda | Popis | -| ------------------------ | ---------- | ------------------------------- | -| `/api/sessions` | GET | Sledovรกnรญ aktivnรญch relacรญ | -| `/api/rate-limits` | GET | Limity sazeb na รบฤet | -| `/api/monitoring/health` | GET | Kontrola stavu | -| `/api/cache` | GET/DELETE | Statistiky mezipamฤ›ti / vymazat | - -### Zรกlohovรกnรญ a export/import - -| Koncovรฝ bod | Metoda | Popis | -| --------------------------- | ------ | ---------------------------------------------- | -| `/api/db-backups` | GET | Seznam dostupnรฝch zรกloh | -| `/api/db-backups` | DรT | Vytvoล™te ruฤnรญ zรกlohu | -| `/api/db-backups` | POST | Obnovenรญ z konkrรฉtnรญ zรกlohy | -| `/api/db-backups/export` | GET | Stรกhnout databรกzi jako soubor .sqlite | -| `/api/db-backups/import` | POST | Nahrajte soubor .sqlite pro nahrazenรญ databรกze | -| `/api/db-backups/exportAll` | GET | Stรกhnout plnou zรกlohu jako archiv .tar.gz | - -### Synchronizace s cloudem - -| Koncovรฝ bod | Metoda | Popis | -| ---------------------- | ------ | ------------------------------- | -| `/api/sync/cloud` | Rลฏznรฉ | Operace synchronizace s cloudem | -| `/api/sync/initialize` | POST | Inicializovat synchronizaci | -| `/api/cloud/*` | Rลฏznรฉ | Sprรกva cloudu | - -### Nรกstroje CLI - -| Koncovรฝ bod | Metoda | Popis | -| ---------------------------------- | ------ | ---------------------------------------- | -| `/api/cli-tools/claude-settings` | GET | Stav Clauda CLI | -| `/api/cli-tools/codex-settings` | GET | Stav pล™รญkazovรฉho ล™รกdku Codexu | -| `/api/cli-tools/droid-settings` | GET | Stav pล™รญkazovรฉho ล™รกdku Droidu | -| `/api/cli-tools/openclaw-settings` | GET | Stav rozhranรญ pล™รญkazovรฉho ล™รกdku OpenClaw | -| `/api/cli-tools/runtime/[toolId]` | GET | Generickรฉ bฤ›hovรฉ prostล™edรญ CLI | - -Mezi odpovฤ›di CLI patล™รญ: `installed` , `runnable` , `command` , `commandPath` , `runtimeMode` , `reason` . - -### Agenti ACP - -| Koncovรฝ bod | Metoda | Popis | -| ----------------- | ------- | ----------------------------------------------------------------------------- | -| `/api/acp/agents` | GET | Zobrazit seznam vลกech detekovanรฝch agentลฏ (vestavฤ›nรฝch + vlastnรญch) se stavem | -| `/api/acp/agents` | POST | Pล™idat vlastnรญho agenta nebo obnovit mezipamฤ›ลฅ detekce | -| `/api/acp/agents` | VYMAZAT | Odebrรกnรญ vlastnรญho agenta podle parametru dotazu `id` | - -Odpovฤ›ฤ GET obsahuje `agents[]` (id, name, binary, version, installed, protocol, isCustom) a `summary` (total, installed, notFound, builtIn, custom). - -### Odolnost a limity rychlosti - -| Koncovรฝ bod | Metoda | Popis | -| ----------------------- | ------- | --------------------------------------- | -| `/api/resilience` | GET/PUT | Zรญskรกnรญ/aktualizace profilลฏ odolnosti | -| `/api/resilience/reset` | POST | Resetujte jistiฤe | -| `/api/rate-limits` | GET | Stav limitu sazby na รบฤet | -| `/api/rate-limit` | GET | Konfigurace globรกlnรญho limitu rychlosti | - -### Evals - -| Koncovรฝ bod | Metoda | Popis | -| ------------ | -------- | -------------------------------------- | -| `/api/evals` | GET/POST | Vypsat eval sady / spustit vyhodnocenรญ | - -### Zรกsady - -| Koncovรฝ bod | Metoda | Popis | -| --------------- | --------------- | ------------------------ | -| `/api/policies` | GET/POST/DELETE | Sprรกva smฤ›rovacรญch zรกsad | - -### Dodrลพovรกnรญ - -| Koncovรฝ bod | Metoda | Popis | -| --------------------------- | ------ | ---------------------------------- | -| `/api/compliance/audit-log` | GET | Protokol auditu shody (poslednรญ N) | - -### v1beta (kompatibilnรญ s Gemini) - -| Koncovรฝ bod | Metoda | Popis | -| -------------------------- | ------ | ------------------------------------ | -| `/v1beta/models` | GET | Seznam modelลฏ ve formรกtu Gemini | -| `/v1beta/models/{...path}` | POST | Koncovรฝ bod Gemini `generateContent` | - -Tyto koncovรฉ body zrcadlรญ formรกt API Gemini pro klienty, kteล™รญ oฤekรกvajรญ nativnรญ kompatibilitu sady Gemini SDK. - -### Internรญ / systรฉmovรก API - -| Koncovรฝ bod | Metoda | Popis | -| --------------- | ------ | --------------------------------------------------------------- | -| `/api/init` | GET | Kontrola inicializace aplikace (pouลพรญvรก se pล™i prvnรญm spuลกtฤ›nรญ) | -| `/api/tags` | GET | Tagy modelลฏ kompatibilnรญ s Ollamou (pro klienty Ollamy) | -| `/api/restart` | POST | Spustit ล™รกdnรฝ restart serveru | -| `/api/shutdown` | POST | Spustit ล™รกdnรฉ vypnutรญ serveru | - -> **Poznรกmka:** Tyto koncovรฉ body pouลพรญvรก internฤ› systรฉm nebo pro kompatibilitu s klienty Ollama. Koncovรญ uลพivatelรฉ je obvykle nevolajรญ. - ---- - -## Pล™epis zvuku - -```bash -POST /v1/audio/transcriptions -Authorization: Bearer your-api-key -Content-Type: multipart/form-data -``` - -Pล™episujte zvukovรฉ soubory pomocรญ Deepgramu nebo AssemblyAI. - -**ลฝรกdost:** - -```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" -``` - -**Odpovฤ›ฤ:** - -```json -{ - "text": "Hello, this is the transcribed audio content.", - "task": "transcribe", - "language": "en", - "duration": 12.5 -} -``` - -**Podporovanรญ poskytovatelรฉ:** `deepgram/nova-3` , `assemblyai/best` . - -**Podporovanรฉ formรกty:** `mp3` , `wav` , `m4a` , `flac` , `ogg` , `webm` . - ---- - -## Kompatibilita s Ollamou - -Pro klienty, kteล™รญ pouลพรญvajรญ formรกt API od Ollamy: - -```bash -# Chat endpoint (Ollama format) -POST /v1/api/chat - -# Model listing (Ollama format) -GET /api/tags -``` - -Poลพadavky jsou automaticky pล™eklรกdรกny mezi formรกtem Ollama a internรญm formรกtem. - ---- - -## Telemetrie - -```bash -# Get latency telemetry summary (p50/p95/p99 per provider) -GET /api/telemetry/summary -``` - -**Odpovฤ›ฤ:** - -```json -{ - "providers": { - "claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 }, - "github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 } - } -} -``` - ---- - -## Rozpoฤet - -```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" -} -``` - ---- - -## Dostupnost modelu - -```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" -} -``` - ---- - -## Zpracovรกnรญ ลพรกdosti - -1. Klient odesรญlรก poลพadavek na `/v1/*` -2. Obsluลพnรก rutina trasy volรก `handleChat` , `handleEmbedding` , `handleAudioTranscription` nebo `handleImageGeneration` -3. Model je vyล™eลกen (pล™รญmรฝ poskytovatel/model nebo alias/kombinace) -4. Pล™ihlaลกovacรญ รบdaje vybranรฉ z lokรกlnรญ databรกze s filtrovรกnรญm dostupnosti รบฤtลฏ -5. Pro chat: `handleChatCore` โ€” detekce formรกtu, pล™eklad, kontrola mezipamฤ›ti, kontrola idempotence -6. Provรกdฤ›cรญ program poskytovatele odesรญlรก poลพadavek nadล™azenรฉmu serveru -7. Odpovฤ›ฤ pล™eloลพena zpฤ›t do klientskรฉho formรกtu (chat) nebo vrรกcena tak, jak je (vloลพenรฉ prvky/obrรกzky/zvuk) -8. Zaznamenรกno pouลพitรญ/protokolovรกnรญ -9. Zรกloลพnรญ metoda se pouลพije na chyby podle pravidel kombinace. - -รšplnรฝ referenฤnรญ popis architektury: [`ARCHITECTURE.md`](ARCHITECTURE.md) - ---- - -## Ovฤ›ล™ovรกnรญ - -- Trasy dashboardu ( `/dashboard/*` ) pouลพรญvajรญ soubor cookie `auth_token` -- Pล™ihlรกลกenรญ pouลพรญvรก uloลพenรฝ hash hesla; zรกloลพnรญ nastavenรญ je `INITIAL_PASSWORD` -- `requireLogin` lze pล™epรญnat pล™es `/api/settings/require-login` -- Trasy `/v1/*` volitelnฤ› vyลพadujรญ klรญฤ API nosiฤe, pokud `REQUIRE_API_KEY=true` diff --git a/docs/i18n/cs/ARCHITECTURE.md b/docs/i18n/cs/ARCHITECTURE.md deleted file mode 100644 index 3b2153f2cd..0000000000 --- a/docs/i18n/cs/ARCHITECTURE.md +++ /dev/null @@ -1,782 +0,0 @@ -# Architektura OmniRoute - -๐ŸŒ **Jazyky:** ๐Ÿ‡บ๐Ÿ‡ธ [angliฤtina](ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brazรญlie)](i18n/pt-BR/ARCHITECTURE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/ARCHITECTURE.md) | ๐Ÿ‡จ๐Ÿ‡ณ[ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/ARCHITECTURE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/ARCHITECTURE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/ARCHITECTURE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต[ๆ—ฅๆœฌ่ชž](i18n/ja/ARCHITECTURE.md)| ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dรกnsko](i18n/da/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/ARCHITECTURE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [maฤarลกtina](i18n/hu/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonรฉsie](i18n/id/ARCHITECTURE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/ARCHITECTURE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nizozemsko](i18n/nl/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugalsko)](i18n/pt/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipรญnec](i18n/phi/ARCHITECTURE.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](i18n/cs/ARCHITECTURE.md) - -_Poslednรญ aktualizace: 2026-03-04_ - -## Shrnutรญ pro manaลพery - -OmniRoute je lokรกlnรญ smฤ›rovacรญ brรกna a dashboard s umฤ›lou inteligencรญ postavenรฝ na Next.js. Poskytuje jeden koncovรฝ bod kompatibilnรญ s OpenAI ( `/v1/*` ) a smฤ›ruje provoz napล™รญฤ nฤ›kolika upstreamovรฝmi poskytovateli s pล™ekladem, zรกloลพnรญmi funkcemi, obnovou tokenลฏ a sledovรกnรญm vyuลพitรญ. - -Zรกkladnรญ schopnosti: - -- API prostล™edรญ kompatibilnรญ s OpenAI pro CLI/nรกstroje (28 poskytovatelลฏ) -- Pล™eklad poลพadavkลฏ/odpovฤ›dรญ napล™รญฤ formรกty poskytovatelลฏ -- Zรกloลพnรญ kombinace modelลฏ (sekvence s vรญce modely) -- Zรกloลพnรญ ล™eลกenรญ na รบrovni รบฤtu (vรญce รบฤtลฏ na poskytovatele) -- Sprรกva pล™ipojenรญ poskytovatele OAuth + API klรญฤลฏ -- Generovรกnรญ embeddingลฏ pomocรญ `/v1/embeddings` (6 poskytovatelลฏ, 9 modelลฏ) -- Generovรกnรญ obrรกzkลฏ pomocรญ `/v1/images/generations` (4 poskytovatelรฉ, 9 modelลฏ) -- Pro modely uvaลพovรกnรญ zvaลพte analรฝzu tagลฏ ( `...` ). -- Sanitizace odpovฤ›dรญ pro striktnรญ kompatibilitu s OpenAI SDK -- Normalizace rolรญ (vรฝvojรกล™โ†’systรฉm, systรฉmโ†’uลพivatel) pro kompatibilitu mezi poskytovateli -- Konverze strukturovanรฉho vรฝstupu (json_schema โ†’ Gemini responseSchema) -- Lokรกlnรญ perzistence pro poskytovatele, klรญฤe, aliasy, kombinace, nastavenรญ, ceny -- Sledovรกnรญ vyuลพitรญ/nรกkladลฏ a protokolovรกnรญ poลพadavkลฏ -- Volitelnรก cloudovรก synchronizace pro synchronizaci vรญce zaล™รญzenรญ/stavลฏ -- Seznam povolenรฝch/blokovanรฝch IP adres pro ล™รญzenรญ pล™รญstupu k API -- ล˜รญzenรญ rozpoฤtu (prลฏchozรญ/automatickรฉ/vlastnรญ/adaptivnรญ) -- Globรกlnรญ systรฉmovรก vรฝzva k vloลพenรญ -- Sledovรกnรญ relacรญ a otisky prstลฏ -- Vylepลกenรฉ omezenรญ sazeb pro jednotlivรฉ รบฤty s profily specifickรฝmi pro poskytovatele -- Vzor jistiฤลฏ pro odolnost poskytovatele -- Ochrana stรกda proti hromลฏm s uzamฤenรญm mutexลฏ -- Mezipamฤ›ลฅ pro deduplikaci poลพadavkลฏ zaloลพenรก na podpisech -- Vrstva domรฉny: dostupnost modelu, pravidla nรกkladลฏ, zรกloลพnรญ politika, politika blokovรกnรญ -- Perzistence stavu domรฉny (mezipamฤ›ลฅ SQLite pro zรกpis pro zรกloลพnรญ funkce, rozpoฤty, uzamฤenรญ, jistiฤe) -- Modul zรกsad pro centralizovanรฉ vyhodnocovรกnรญ poลพadavkลฏ (uzamฤenรญ โ†’ rozpoฤet โ†’ zรกloลพnรญ) -- Vyลพรกdat telemetrii s agregacรญ latence p50/p95/p99 -- Korelaฤnรญ ID (X-Request-Id) pro trasovรกnรญ typu end-to-end -- Protokolovรกnรญ auditu shody s pล™edpisy s moลพnostรญ odhlรกลกenรญ pro kaลพdรฝ klรญฤ API -- Evaluaฤnรญ rรกmec pro zajiลกtฤ›nรญ kvality LLM -- ล˜รญdicรญ panel uลพivatelskรฉho rozhranรญ Resilience se stavem jistiฤe v reรกlnรฉm ฤase -- Modulรกrnรญ poskytovatelรฉ OAuth (12 jednotlivรฝch modulลฏ v adresรกล™i `src/lib/oauth/providers/` ) - -Primรกrnรญ bฤ›hovรฝ model: - -- Trasy aplikace Next.js v `src/app/api/*` implementujรญ jak API dashboardลฏ, tak i API kompatibility. -- Sdรญlenรฉ jรกdro SSE/routing v `src/sse/*` + `open-sse/*` zvlรกdรก spouลกtฤ›nรญ poskytovatelลฏ, pล™eklad, streamovรกnรญ, zรกloลพnรญ operace a vyuลพitรญ. - -## Rozsah a hranice - -### V rozsahu - -- Bฤ›hovรฉ prostล™edรญ lokรกlnรญ brรกny -- Rozhranรญ API pro sprรกvu ล™รญdicรญch panelลฏ -- Ovฤ›ล™ovรกnรญ poskytovatele a aktualizace tokenu -- ลฝรกdost o pล™eklad a streamovรกnรญ SSE -- Lokรกlnรญ stav + perzistence vyuลพitรญ -- Volitelnรก orchestrace synchronizace s cloudem - -### Mimo rozsah - -- Implementace cloudovรฉ sluลพby za `NEXT_PUBLIC_CLOUD_URL` -- SLA/ล™รญdicรญ rovina poskytovatele mimo lokรกlnรญ proces -- Samotnรฉ externรญ binรกrnรญ soubory CLI (Claude CLI, Codex CLI atd.) - -## Kontext systรฉmu na vysokรฉ รบrovni - -```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[(storage.sqlite)] - UDB[(usage tables + log artifacts)] - end - - subgraph Upstreams[Upstream Providers] - P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/Qoder/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 -``` - -## Zรกkladnรญ bฤ›hovรฉ komponenty - -## 1) API a smฤ›rovacรญ vrstva (trasy aplikacรญ Next.js) - -Hlavnรญ adresรกล™e: - -- `src/app/api/v1/*` a `src/app/api/v1beta/*` pro rozhranรญ API pro zajiลกtฤ›nรญ kompatibility -- `src/app/api/*` pro API pro sprรกvu/konfiguraci -- Dalลกรญ pล™episy v `next.config.mjs` mapujรญ `/v1/*` na `/api/v1/*` - -Dลฏleลพitรฉ zpลฏsoby kompatibility: - -- `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` โ€” obsahuje vlastnรญ modely s `custom: true` -- `src/app/api/v1/embeddings/route.ts` โ€” generovรกnรญ embeddingลฏ (6 poskytovatelลฏ) -- `src/app/api/v1/images/generations/route.ts` โ€” generovรกnรญ obrรกzkลฏ (4+ poskytovatelลฏ vฤetnฤ› Antigravity/Nebius) -- `src/app/api/v1/messages/count_tokens/route.ts` -- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` โ€” vyhrazenรฝ chat pro jednotlivรฉ poskytovatele -- `src/app/api/v1/providers/[provider]/embeddings/route.ts` โ€” vyhrazenรก vklรกdรกnรญ pro jednotlivรฉ poskytovatele -- `src/app/api/v1/providers/[provider]/images/generations/route.ts` โ€” vyhrazenรฉ obrazy pro jednotlivรฉ poskytovatele -- `src/app/api/v1beta/models/route.ts` -- `src/app/api/v1beta/models/[...path]/route.ts` - -Domรฉny sprรกvy: - -- Auth/settings: `src/app/api/auth/*` , `src/app/api/settings/*` -- Poskytovatelรฉ/pล™ipojenรญ: `src/app/api/providers*` -- Uzly poskytovatele: `src/app/api/provider-nodes*` -- Vlastnรญ modely: `src/app/api/provider-models` (GET/POST/DELETE) -- Katalog modelลฏ: `src/app/api/models/route.ts` (GET) -- Konfigurace proxy: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) -- OAuth: `src/app/api/oauth/*` -- Klรญฤe/aliasy/kombinace/ceny: `src/app/api/keys*` , `src/app/api/models/alias` , `src/app/api/combos*` , `src/app/api/pricing` -- Pouลพitรญ: `src/app/api/usage/*` -- Synchronizace/cloud: `src/app/api/sync/*` , `src/app/api/cloud/*` -- Pomocnรฉ nรกstroje pro CLI: `src/app/api/cli-tools/*` -- IP filtr: `src/app/api/settings/ip-filter` (GET/PUT) -- Rozpoฤet pro myลกlenรญ: `src/app/api/settings/thinking-budget` (GET/PUT) -- Systรฉmovรฝ pล™รญkaz: `src/app/api/settings/system-prompt` (GET/PUT) -- Relace: `src/app/api/sessions` (GET) -- Limity rychlosti: `src/app/api/rate-limits` (GET) -- Odolnost: `src/app/api/resilience` (GET/PATCH) โ€” profily poskytovatelลฏ, jistiฤ, stav limitu rychlosti -- Reset odolnosti: `src/app/api/resilience/reset` (POST) โ€” reset jistiฤลฏ + doby zchlazenรญ -- Statistiky mezipamฤ›ti: `src/app/api/cache/stats` (GET/DELETE) -- Dostupnost modelu: `src/app/api/models/availability` (GET/POST) -- Telemetrie: `src/app/api/telemetry/summary` (GET) -- Rozpoฤet: `src/app/api/usage/budget` (GET/POST) -- Zรกloลพnรญ ล™etฤ›zce: `src/app/api/fallback/chains` (GET/POST/DELETE) -- Audit shody: `src/app/api/compliance/audit-log` (GET) -- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) -- Zรกsady: `src/app/api/policies` (GET/POST) - -## 2) SSE + Pล™ekladatelskรฉ jรกdro - -Hlavnรญ moduly toku: - -- Zรกznam: `src/sse/handlers/chat.ts` -- Orchestrace jรกdra: `open-sse/handlers/chatCore.ts` -- Adaptรฉry pro spuลกtฤ›nรญ poskytovatelลฏ: `open-sse/executors/*` -- Detekce formรกtu/konfigurace poskytovatele: `open-sse/services/provider.ts` -- Analรฝza/ล™eลกenรญ modelu: `src/sse/services/model.ts` , `open-sse/services/model.ts` -- Logika zรกloลพnรญho รบฤtu: `open-sse/services/accountFallback.ts` -- Registr pล™ekladลฏ: `open-sse/translator/index.ts` -- Transformace streamลฏ: `open-sse/utils/stream.ts` , `open-sse/utils/streamHandler.ts` -- Extrakce/normalizace vyuลพitรญ: `open-sse/utils/usageTracking.ts` -- Analyzรกtor tagลฏ Think: `open-sse/utils/thinkTagParser.ts` -- Obsluลพnรก rutina pro vklรกdรกnรญ: `open-sse/handlers/embeddings.ts` -- Registr poskytovatelลฏ vklรกdรกnรญ: `open-sse/config/embeddingRegistry.ts` -- Obsluลพnรก rutina generovรกnรญ obrรกzkลฏ: `open-sse/handlers/imageGeneration.ts` -- Registr poskytovatelลฏ obrรกzkลฏ: `open-sse/config/imageRegistry.ts` -- Sanitizace odpovฤ›dรญ: `open-sse/handlers/responseSanitizer.ts` -- Normalizace rolรญ: `open-sse/services/roleNormalizer.ts` - -Sluลพby (obchodnรญ logika): - -- Vรฝbฤ›r/skรณrovรกnรญ รบฤtu: `open-sse/services/accountSelector.ts` -- Sprรกva ลพivotnรญho cyklu kontextu: `open-sse/services/contextManager.ts` -- Vynucenรญ filtrovรกnรญ IP adres: `open-sse/services/ipFilter.ts` -- Sledovรกnรญ relacรญ: `open-sse/services/sessionManager.ts` -- Poลพadavek na deduplikaci: `open-sse/services/signatureCache.ts` -- Vloลพenรญ systรฉmovรฉho promptu: `open-sse/services/systemPrompt.ts` -- ล˜รญzenรญ rozpoฤtu v duchu myลกlenek: `open-sse/services/thinkingBudget.ts` -- Smฤ›rovรกnรญ pomocรญ modelu zรกstupnรฝch znakลฏ: `open-sse/services/wildcardRouter.ts` -- Sprรกva limitลฏ rychlosti: `open-sse/services/rateLimitManager.ts` -- Jistiฤ: `open-sse/services/circuitBreaker.ts` - -Moduly domรฉnovรฉ vrstvy: - -- Dostupnost modelu: `src/lib/domain/modelAvailability.ts` -- Pravidla/rozpoฤty nรกkladลฏ: `src/lib/domain/costRules.ts` -- Zรกloลพnรญ zรกsady: `src/lib/domain/fallbackPolicy.ts` -- Kombinovanรฝ resolver: `src/lib/domain/comboResolver.ts` -- Zรกsady uzamฤenรญ: `src/lib/domain/lockoutPolicy.ts` -- Modul zรกsad: `src/domain/policyEngine.ts` โ€” centralizovanรฉ uzamฤenรญ โ†’ rozpoฤet โ†’ vyhodnocenรญ zรกloลพnรญho reลพimu -- Katalog chybovรฝch kรณdลฏ: `src/lib/domain/errorCodes.ts` -- ID poลพadavku: `src/lib/domain/requestId.ts` -- ฤŒasovรฝ limit naฤtenรญ: `src/lib/domain/fetchTimeout.ts` -- Poลพadovat telemetrii: `src/lib/domain/requestTelemetry.ts` -- Shoda/audit: `src/lib/domain/compliance/index.ts` -- Zkuลกebnรญ bฤ›ลพec: `src/lib/domain/evalRunner.ts` -- Perzistence stavu domรฉny: `src/lib/db/domainState.ts` โ€” SQLite CRUD pro zรกloลพnรญ ล™etฤ›zce, rozpoฤty, historii nรกkladลฏ, stav uzamฤenรญ, jistiฤe - -Moduly poskytovatelลฏ OAuth (12 jednotlivรฝch souborลฏ v adresรกล™i `src/lib/oauth/providers/` ): - -- Index registru: `src/lib/oauth/providers/index.ts` -- Jednotlivรญ poskytovatelรฉ: `claude.ts` , `codex.ts` , `gemini.ts` , `antigravity.ts` , `qoder.ts` , `qwen.ts` , `kimi-coding.ts` , `github.ts` , `kiro.ts` , `cursor.ts` , `kilocode.ts` , `cline.ts` -- Thin wrapper: `src/lib/oauth/providers.ts` โ€” reexporty z jednotlivรฝch modulลฏ - -## 3) Vrstva perzistence - -Primรกrnรญ stavovรก databรกze (SQLite): - -- Zรกkladnรญ infrastruktura: `src/lib/db/core.ts` (better-sqlite3, migrace, WAL) -- Reexportnรญ fasรกda: `src/lib/localDb.ts` (tenkรก vrstva kompatibility pro volajรญcรญ) -- soubor: `${DATA_DIR}/storage.sqlite` (nebo `$XDG_CONFIG_HOME/omniroute/storage.sqlite` pokud je nastaveno, jinak `~/.omniroute/storage.sqlite` ) -- entity (tabulky + jmennรฉ prostory KV): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels** , **proxyConfig** , **ipFilter** , **thinkingBudget** , **systemPrompt** - -Trvalost pouลพรญvรกnรญ: - -- fasรกda: `src/lib/usageDb.ts` (dekomponovanรฉ moduly v `src/lib/usage/*` ) -- SQLite tabulky v `storage.sqlite` : `usage_history` , `call_logs` , `proxy_logs` -- Volitelnรฉ artefakty souborลฏ zลฏstรกvajรญ pro รบฤely kompatibility/ladฤ›nรญ ( `${DATA_DIR}/log.txt` , `${DATA_DIR}/call_logs/` , `/logs/...` ) -- Starลกรญ soubory JSON jsou migrovรกny do SQLite pล™i migracรญch pล™i spuลกtฤ›nรญ, pokud jsou k dispozici. - -Databรกze stavu domรฉny (SQLite): - -- `src/lib/db/domainState.ts` โ€” CRUD operace pro stav domรฉny -- Tabulky (vytvoล™enรฉ v `src/lib/db/core.ts` ): `domain_fallback_chains` , `domain_budgets` , `domain_cost_history` , `domain_lockout_state` , `domain_circuit_breakers` -- Vzor mezipamฤ›ti pro zรกpis: mapy v pamฤ›ti jsou autoritativnรญ za bฤ›hu; mutace se zapisujรญ synchronnฤ› do SQLite; stav se obnovuje z databรกze pล™i studenรฉm startu. - -## 4) Ovฤ›ล™ovacรญ a bezpeฤnostnรญ povrchy - -- Autorizace souborลฏ cookie v dashboardu: `src/proxy.ts` , `src/app/api/auth/login/route.ts` -- Generovรกnรญ/ovฤ›ล™enรญ klรญฤe API: `src/shared/utils/apiKey.ts` -- Tajnรฉ kรณdy poskytovatele pล™etrvรกvaly v poloลพkรกch `providerConnections` -- Podpora odchozรญ proxy pล™es `open-sse/utils/proxyFetch.ts` (promฤ›nnรฉ prostล™edรญ) a `open-sse/utils/networkProxy.ts` (konfigurovatelnรฉ pro jednotlivรฉ poskytovatele nebo globรกlnฤ›) - -## 5) Synchronizace s cloudem - -- Inicializace plรกnovaฤe: `src/lib/initCloudSync.ts` , `src/shared/services/initializeCloudSync.ts` -- Periodickรก รบloha: `src/shared/services/cloudSyncScheduler.ts` -- ล˜รญdicรญ trasa: `src/app/api/sync/cloud/route.ts` - -## ลฝivotnรญ cyklus poลพadavku ( `/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 -``` - -## Kombinovanรฝ + zรกloลพnรญ proces pro รบฤet - -```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] -``` - -Rozhodnutรญ o zรกloลพnรญch metodรกch jsou ล™รญzena souborem `open-sse/services/accountFallback.ts` s vyuลพitรญm stavovรฝch kรณdลฏ a heuristik chybovรฝch zprรกv. - -## ลฝivotnรญ cyklus aktualizace OAuth a onboardingu tokenu - -```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 -``` - -Obnovenรญ bฤ›hem ลพivรฉho provozu se provรกdรญ uvnitล™ `open-sse/handlers/chatCore.ts` pomocรญ exekutoru `refreshCredentials()` . - -## ลฝivotnรญ cyklus synchronizace s cloudem (Povolit / Synchronizovat / Zakรกzat) - -```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 -``` - -Pravidelnou synchronizaci spouลกtรญ `CloudSyncScheduler` , kdyลพ je povolen cloud. - -## Datovรฝ model a mapa รบloลพiลกtฤ› - -```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 - } -``` - -Soubory fyzickรฉho รบloลพiลกtฤ›: - -- primรกrnรญ bฤ›hovรก databรกze: `${DATA_DIR}/storage.sqlite` -- ล™รกdky protokolu poลพadavku: `${DATA_DIR}/log.txt` (artefakt kompatibility/ladฤ›nรญ) -- Archivy strukturovanรฝch dat volรกnรญ: `${DATA_DIR}/call_logs/` -- volitelnรฉ relace pล™ekladaฤe/vyลพรกdรกnรญ ladฤ›nรญ: `/logs/...` - -## Topologie nasazenรญ - -```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[(storage.sqlite)] - UsageDB[(usage tables + log artifacts)] - end - - subgraph External[External Services] - Providers[AI Providers] - SyncCloud[Cloud Sync Service] - end - - CLI --> Next - Browser --> Next - Next --> Core - Next --> MainDB - Core --> MainDB - Core --> UsageDB - Core --> Providers - Next --> SyncCloud -``` - -## Mapovรกnรญ modulลฏ (kritickรฉ pro rozhodnutรญ) - -### Moduly tras a API - -- `src/app/api/v1/*` , `src/app/api/v1beta/*` : API pro zajiลกtฤ›nรญ kompatibility -- `src/app/api/v1/providers/[provider]/*` : vyhrazenรฉ trasy pro jednotlivรฉ poskytovatele (chat, vklรกdรกnรญ, obrรกzky) -- `src/app/api/providers*` : CRUD poskytovatele, validace, testovรกnรญ -- `src/app/api/provider-nodes*` : sprรกva uzlลฏ kompatibilnรญch s vlastnรญmi nรกstroji -- `src/app/api/provider-models` : sprรกva vlastnรญch modelลฏ (CRUD) -- `src/app/api/models/route.ts` : API katalogu modelลฏ (aliasy + vlastnรญ modely) -- `src/app/api/oauth/*` : Toky OAuth/kรณdu zaล™รญzenรญ -- `src/app/api/keys*` : ลพivotnรญ cyklus lokรกlnรญho klรญฤe API -- `src/app/api/models/alias` : sprรกva aliasลฏ -- `src/app/api/combos*` : sprรกva zรกloลพnรญch kombinacรญ -- `src/app/api/pricing` : pล™epsรกnรญ cen pro vรฝpoฤet nรกkladลฏ -- `src/app/api/settings/proxy` : konfigurace proxy (GET/PUT/DELETE) -- `src/app/api/settings/proxy/test` : test pล™ipojenรญ odchozรญ proxy (POST) -- `src/app/api/usage/*` : API pro pouลพitรญ a protokoly -- `src/app/api/sync/*` + `src/app/api/cloud/*` : synchronizace s cloudem a pomocnรญci pro prรกci s cloudem -- `src/app/api/cli-tools/*` : lokรกlnรญ programy pro zรกpis/kontrolu konfigurace CLI -- `src/app/api/settings/ip-filter` : Seznam povolenรฝch/blokovanรฝch IP adres (GET/PUT) -- `src/app/api/settings/thinking-budget` : konfigurace rozpoฤtu tokenu thinking (GET/PUT) -- `src/app/api/settings/system-prompt` : globรกlnรญ systรฉmovรฝ pล™รญkaz (GET/PUT) -- `src/app/api/sessions` : vรฝpis aktivnรญch relacรญ (GET) -- `src/app/api/rate-limits` : stav limitu rychlosti pro รบฤet (GET) - -### Smฤ›rovacรญ a spouลกtฤ›cรญ jรกdro - -- `src/sse/handlers/chat.ts` : parsovรกnรญ poลพadavkลฏ, zpracovรกnรญ kombinacรญ, smyฤka vรฝbฤ›ru รบฤtu -- `open-sse/handlers/chatCore.ts` : pล™eklad, odeslรกnรญ exekutoru, zpracovรกnรญ opakovรกnรญ/obnovenรญ, nastavenรญ streamu -- `open-sse/executors/*` : chovรกnรญ sรญtฤ› a formรกtu specifickรฉ pro poskytovatele - -### Registr pล™ekladลฏ a pล™evodnรญky formรกtลฏ - -- `open-sse/translator/index.ts` : registr a orchestrace pล™ekladaฤลฏ -- ลฝรกdost o pล™ekladatele: `open-sse/translator/request/*` -- Pล™ekladaฤe odpovฤ›dรญ: `open-sse/translator/response/*` -- Formรกtovacรญ konstanty: `open-sse/translator/formats.ts` - -### Perzistence - -- `src/lib/db/*` : perzistentnรญ uklรกdรกnรญ konfigurace/stavu a domรฉny v SQLite -- `src/lib/localDb.ts` : reexport kompatibility pro databรกzovรฉ moduly -- `src/lib/usageDb.ts` : fasรกda historie pouลพitรญ/zรกznamลฏ volรกnรญ nad tabulkami SQLite - -## Pokrytรญ poskytovatele a vykonavatele (strategickรฝ vzorec) - -Kaลพdรฝ poskytovatel mรก specializovanรฝ exekutor rozลกiล™ujรญcรญ `BaseExecutor` (v `open-sse/executors/base.ts` ), kterรฝ zajiลกลฅuje vytvรกล™enรญ URL adres, konstrukci hlaviฤek, opakovรกnรญ s exponenciรกlnรญm odkladem, hooky pro obnovenรญ povฤ›ล™enรญ a orchestraฤnรญ metodu `execute()` . - -| Vykonavatel | Poskytovatel(รฉ) | Speciรกlnรญ manipulace | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- | -| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, Qoder, OpenRouter, GLM, Kimi, MiniMax, DeepSeek, Groq, xAI, Mistral, Perplexity, Together, Fireworks, Cerebras, Cohere, NVIDIA | Konfigurace dynamickรฉ adresy URL/zรกhlavรญ pro kaลพdรฉho poskytovatele | -| `AntigravityExecutor` | Google Antigravity | Vlastnรญ ID projektลฏ/relacรญ, analรฝza Opakovรกnรญ po | -| `CodexExecutor` | OpenAI Codex | Vklรกdรก systรฉmovรฉ instrukce, vynucuje รบsilรญ k uvaลพovรกnรญ | -| `CursorExecutor` | IDE kurzoru | Protokol ConnectRPC, kรณdovรกnรญ Protobuf, podepisovรกnรญ poลพadavkลฏ pomocรญ kontrolnรญho souฤtu | -| `GithubExecutor` | GitHub Copilot | Aktualizace tokenu Copilot, hlaviฤky napodobujรญcรญ VSCode | -| `KiroExecutor` | AWS CodeWhisperer/Kiro | Binรกrnรญ formรกt AWS EventStream โ†’ konverze SSE | -| `GeminiCLIExecutor` | Gemini CLI | Cyklus obnovy tokenu Google OAuth | - -Vลกichni ostatnรญ poskytovatelรฉ (vฤetnฤ› uzlลฏ kompatibilnรญch s vlastnรญmi funkcemi) pouลพรญvajรญ `DefaultExecutor` . - -## Matice kompatibility poskytovatelลฏ - -| Poskytovatel | Formรกt | Autorizace | Proud | Nestreamovanรฉ | Obnovenรญ tokenu | API pro pouลพitรญ | -| ------------------------------ | --------------- | ---------------------------------- | -------------------- | ------------- | --------------- | --------------------------- | -| Claude | Claude | Klรญฤ API / OAuth | โœ… | โœ… | โœ… | โš ๏ธ Pouze pro administrรกtory | -| Blรญลพenci | Blรญลพenci | Klรญฤ API / OAuth | โœ… | โœ… | โœ… | โš ๏ธ Cloudovรก konzole | -| Gemini CLI | gemini-cli | OAuth | โœ… | โœ… | โœ… | โš ๏ธ Cloudovรก konzole | -| Antigravity | antigravitace | OAuth | โœ… | โœ… | โœ… | โœ… Plnรก kvรณta API | -| OpenAI | otevล™eno | Klรญฤ API | โœ… | โœ… | โŒ | โŒ | -| Kodex | openai-odpovฤ›di | OAuth | โœ… vynucenรฝ | โŒ | โœ… | โœ… Limity sazeb | -| GitHub Copilot | otevล™eno | OAuth + token Copilota | โœ… | โœ… | โœ… | โœ… Snรญmky kvรณt | -| Kurzor | kurzor | Vlastnรญ kontrolnรญ souฤet | โœ… | โœ… | โŒ | โŒ | -| Kiro | Kiro | OIDC pro jednotnรฉ pล™ihlaลกovรกnรญ AWS | โœ… (Stream udรกlostรญ) | โŒ | โœ… | โœ… Limity pouลพitรญ | -| Qwen | otevล™eno | OAuth | โœ… | โœ… | โœ… | โš ๏ธ Na vyลพรกdรกnรญ | -| Qoder | otevล™eno | OAuth (zรกkladnรญ) | โœ… | โœ… | โœ… | โš ๏ธ Na vyลพรกdรกnรญ | -| OpenRouter | otevล™eno | Klรญฤ API | โœ… | โœ… | โŒ | โŒ | -| GLM/Kimi/MiniMax | Claude | Klรญฤ API | โœ… | โœ… | โŒ | โŒ | -| Hlubokรฉ vyhledรกvรกnรญ | otevล™eno | Klรญฤ API | โœ… | โœ… | โŒ | โŒ | -| Groq | otevล™eno | Klรญฤ API | โœ… | โœ… | โŒ | โŒ | -| xAI (Grok) | otevล™eno | Klรญฤ API | โœ… | โœ… | โŒ | โŒ | -| Mistral | otevล™eno | Klรญฤ API | โœ… | โœ… | โŒ | โŒ | -| Zmatek | otevล™eno | Klรญฤ API | โœ… | โœ… | โŒ | โŒ | -| Spoleฤnฤ› s umฤ›lou inteligencรญ | otevล™eno | Klรญฤ API | โœ… | โœ… | โŒ | โŒ | -| Ohลˆostroj s umฤ›lou inteligencรญ | otevล™eno | Klรญฤ API | โœ… | โœ… | โŒ | โŒ | -| Mozky | otevล™eno | Klรญฤ API | โœ… | โœ… | โŒ | โŒ | -| Soudrลพnรฝ | otevล™eno | Klรญฤ API | โœ… | โœ… | โŒ | โŒ | -| NVIDIA NIM | otevล™eno | Klรญฤ API | โœ… | โœ… | โŒ | โŒ | - -## Pokrytรญ pล™ekladลฏ formรกtลฏ - -Mezi detekovanรฉ zdrojovรฉ formรกty patล™รญ: - -- `openai` -- `openai-responses` -- `claude` -- `gemini` - -Cรญlovรฉ formรกty zahrnujรญ: - -- Chat/Odpovฤ›di v OpenAI -- Claude -- Obรกlka Gemini/Gemini-CLI/Antigravity -- Kiro -- Kurzor - -Pล™eklady pouลพรญvajรญ **jako รบstล™ednรญ formรกt OpenAI** โ€“ vลกechny konverze prochรกzejรญ OpenAI jako zprostล™edkovatel: - -``` -Source Format โ†’ OpenAI (hub) โ†’ Target Format -``` - -Pล™eklady jsou vybรญrรกny dynamicky na zรกkladฤ› tvaru zdrojovรฉho datovรฉho obsahu a formรกtu cรญlovรฉho poskytovatele. - -Dalลกรญ vrstvy zpracovรกnรญ v pล™ekladovรฉm kanรกlu: - -- **Sanitizace odpovฤ›dรญ** โ€“ Odstraลˆuje nestandardnรญ pole z odpovฤ›dรญ ve formรกtu OpenAI (streamovanรฝch i nestreamovanรฝch), aby byla zajiลกtฤ›na pล™รญsnรก shoda se SDK. -- **Normalizace rolรญ** โ€” Pล™evรกdรญ `developer` โ†’ `system` pro cรญle mimo OpenAI; sluฤuje `system` โ†’ `user` pro modely, kterรฉ odmรญtajรญ systรฉmovou roli (GLM, ERNIE) -- **Extrakce tagu Think** โ€” Analyzuje bloky `...` z obsahu do pole `reasoning_content` -- **Strukturovanรฝ vรฝstup** โ€” Pล™evede OpenAI `response_format.json_schema` na `responseMimeType` + `responseSchema` z Gemini. - -## Podporovanรฉ koncovรฉ body API - -| Koncovรฝ bod | Formรกt | Psovod | -| -------------------------------------------------- | ------------------------- | ------------------------------------------------------- | -| `POST /v1/chat/completions` | Chat s OpenAI | `src/sse/handlers/chat.ts` | -| `POST /v1/messages` | Claude Messages | Stejnรฝ obsluลพnรฝ program (automaticky detekovรกno) | -| `POST /v1/responses` | Reakce OpenAI | `open-sse/handlers/responsesHandler.ts` | -| `POST /v1/embeddings` | Vklรกdรกnรญ OpenAI | `open-sse/handlers/embeddings.ts` | -| `GET /v1/embeddings` | Seznam modelลฏ | Trasa API | -| `POST /v1/images/generations` | Obrรกzky OpenAI | `open-sse/handlers/imageGeneration.ts` | -| `GET /v1/images/generations` | Seznam modelลฏ | Trasa API | -| `POST /v1/providers/{provider}/chat/completions` | Chat s OpenAI | Vyhrazenรฉ pro kaลพdรฉho poskytovatele s ovฤ›ล™ovรกnรญm modelu | -| `POST /v1/providers/{provider}/embeddings` | Vklรกdรกnรญ OpenAI | Vyhrazenรฉ pro kaลพdรฉho poskytovatele s ovฤ›ล™ovรกnรญm modelu | -| `POST /v1/providers/{provider}/images/generations` | Obrรกzky OpenAI | Vyhrazenรฉ pro kaลพdรฉho poskytovatele s ovฤ›ล™ovรกnรญm modelu | -| `POST /v1/messages/count_tokens` | Poฤet ลพetonลฏ Claude | Trasa API | -| `GET /v1/models` | Seznam modelลฏ OpenAI | Trasa API (chat + vklรกdรกnรญ + obrรกzek + vlastnรญ modely) | -| `GET /api/models/catalog` | Katalog | Vลกechny modely seskupenรฉ podle poskytovatele + typu | -| `POST /v1beta/models/*:streamGenerateContent` | Rodรกk z Blรญลพencลฏ | Trasa API | -| `GET/PUT/DELETE /api/settings/proxy` | Konfigurace proxy serveru | Konfigurace sรญลฅovรฉho proxy serveru | -| `POST /api/settings/proxy/test` | Pล™ipojenรญ proxy serveru | Koncovรฝ bod testu stavu/pล™ipojenรญ proxy serveru | -| `GET/POST/DELETE /api/provider-models` | Vlastnรญ modely | Sprรกva vlastnรญch modelลฏ pro kaลพdรฉho poskytovatele | - -## Obejรญt obsluลพnou rutinu - -Obsluลพnรก rutina bypassu ( `open-sse/utils/bypassHandler.ts` ) zachycuje znรกmรฉ โ€žthrowawayโ€œ poลพadavky z Claude CLI โ€“ warmup pingy, extrakce titulkลฏ a poฤty tokenลฏ โ€“ a vracรญ **faleลกnou odpovฤ›ฤ** bez spotล™ebovรกnรญ tokenลฏ upstreamovรฉho poskytovatele. Toto se spustรญ pouze tehdy, kdyลพ `User-Agent` obsahuje `claude-cli` . - -## Kanรกl protokolovรกnรญ poลพadavkลฏ - -Zรกznamnรญk poลพadavkลฏ ( `open-sse/utils/requestLogger.ts` ) poskytuje 7stupลˆovรฝ kanรกl protokolovรกnรญ ladฤ›nรญ, ve vรฝchozรญm nastavenรญ zakรกzanรฝ a povolenรฝ pomocรญ `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 -``` - -Soubory se zapisujรญ do `/logs//` pro kaลพdou relaci poลพadavku. - -## Zpลฏsoby selhรกnรญ a odolnost - -## 1) Dostupnost รบฤtu/poskytovatele - -- Doba ochlazovรกnรญ รบฤtu poskytovatele pล™i pล™echodnรฝch chybรกch/chybรกch rychlosti/autentizace -- zรกloลพnรญ รบฤet pล™ed selhรกnรญm poลพadavku -- zรกloลพnรญ kombinovanรฝ model, kdyลพ je aktuรกlnรญ cesta modelu/poskytovatele vyฤerpรกna - -## 2) Platnost tokenu - -- pล™edbฤ›ลพnรก kontrola a obnovenรญ s opakovanรฝm pokusem o obnovenรญ poskytovatelลฏ -- Opakovรกnรญ 401/403 po pokusu o obnovenรญ v hlavnรญ cestฤ› - -## 3) Bezpeฤnost streamu - -- streamovacรญ ล™adiฤ s vฤ›domรญm odpojenรญ -- pล™ekladovรฝ proud s vyprรกzdnฤ›nรญm konce proudu a zpracovรกnรญm `[DONE]` -- Zรกloลพnรญ odhad vyuลพitรญ, kdyลพ chybรญ metadata vyuลพitรญ poskytovatele - -## 4) Zhorลกenรญ cloudovรฉ synchronizace - -- Zobrazujรญ se chyby synchronizace, ale lokรกlnรญ bฤ›hovรฉ prostล™edรญ pokraฤuje. -- Plรกnovaฤ mรก logiku umoลพลˆujรญcรญ opakovรกnรญ, ale periodickรฉ provรกdฤ›nรญ v souฤasnรฉ dobฤ› ve vรฝchozรญm nastavenรญ volรก synchronizaci s jednรญm pokusem. - -## 5) Integrita dat - -- Migrace schรฉmatu SQLite a automatickรฉ aktualizace hookลฏ pล™i spuลกtฤ›nรญ -- Cesta kompatibility migrace starลกรญ verze JSON โ†’ SQLite - -## Pozorovatelnost a provoznรญ signรกly - -Zdroje viditelnosti za bฤ›hu: - -- protokoly konzole ze `src/sse/utils/logger.ts` -- Agregace vyuลพitรญ na poลพadavek v SQLite ( `usage_history` , `call_logs` , `proxy_logs` ) -- textovรฝ stav poลพadavku pล™ihlรกลกenรญ `log.txt` (volitelnรฉ/kompatibilnรญ) -- volitelnรฉ hlubokรฉ protokoly poลพadavkลฏ/pล™ekladลฏ v `logs/` pokud `ENABLE_REQUEST_LOGS=true` -- Koncovรฉ body pouลพitรญ dashboardu ( `/api/usage/*` ) pro spotล™ebu v uลพivatelskรฉm rozhranรญ - -## Hranice citlivรฉ z hlediska zabezpeฤenรญ - -- Tajnรฝ kรณd JWT ( `JWT_SECRET` ) zajiลกลฅuje ovฤ›ล™ovรกnรญ/podepisovรกnรญ souborลฏ cookie relace dashboardu. -- Poฤรกteฤnรญ bootstrap hesla ( `INITIAL_PASSWORD` ) by mฤ›l bรฝt explicitnฤ› nakonfigurovรกn pro zล™izovรกnรญ pล™i prvnรญm spuลกtฤ›nรญ. -- Tajnรฝ klรญฤ API HMAC ( `API_KEY_SECRET` ) zabezpeฤuje formรกt vygenerovanรฉho lokรกlnรญho klรญฤe API. -- Tajnรฉ klรญฤe/tokeny poskytovatele (klรญฤe/tokeny API) jsou uloลพeny v lokรกlnรญ databรกzi a mฤ›ly by bรฝt chrรกnฤ›ny na รบrovni souborovรฉho systรฉmu. -- Koncovรฉ body synchronizace cloudu se spolรฉhajรญ na sรฉmantiku ovฤ›ล™ovรกnรญ klรญฤe API + ID poฤรญtaฤe. - -## Matice prostล™edรญ a bฤ›hovรฉho prostล™edรญ - -Promฤ›nnรฉ prostล™edรญ aktivnฤ› pouลพรญvanรฉ kรณdem: - -- Aplikace/autentizace: `JWT_SECRET` , `INITIAL_PASSWORD` -- รšloลพiลกtฤ›: `DATA_DIR` -- Chovรกnรญ kompatibilnรญho uzlu: `ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` -- Volitelnรฉ pล™epsรกnรญ รบloลพnรฉ zรกkladny (Linux/macOS, kdyลพ `DATA_DIR` nenรญ nastaveno): `XDG_CONFIG_HOME` -- Bezpeฤnostnรญ hashovรกnรญ: `API_KEY_SECRET` , `MACHINE_ID_SALT` -- Protokolovรกnรญ: `ENABLE_REQUEST_LOGS` -- Synchronizace/cloudovรฉ URL: `NEXT_PUBLIC_BASE_URL` , `NEXT_PUBLIC_CLOUD_URL` -- Odchozรญ proxy: `HTTP_PROXY` , `HTTPS_PROXY` , `ALL_PROXY` , `NO_PROXY` a varianty s malรฝmi pรญsmeny -- Pล™รญznaky funkcรญ SOCKS5: `ENABLE_SOCKS5_PROXY` , `NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` -- Pomocnรญci pro platformu/bฤ›hovรฉ prostล™edรญ (ne konfigurace specifickรก pro aplikaci): `APPDATA` , `NODE_ENV` , `PORT` , `HOSTNAME` - -## Znรกmรฉ architektonickรฉ poznรกmky - -1. `usageDb` a `localDb` sdรญlejรญ stejnou zรกkladnรญ adresรกล™ovou politiku ( `DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute` ) se starลกรญ migracรญ souborลฏ. -2. `/api/v1/route.ts` deleguje na stejnรฝ jednotnรฝ nรกstroj pro tvorbu katalogลฏ, kterรฝ pouลพรญvรก `/api/v1/models` ( `src/app/api/v1/models/catalog.ts` ), aby se zabrรกnilo sรฉmantickรฉmu posunu. -3. Pokud je povoleno, zaznamenรกvaฤ poลพadavkลฏ zapisuje celรฉ zรกhlavรญ/tฤ›lo; adresรกล™ protokolu je povaลพovรกn za citlivรฝ. -4. Chovรกnรญ cloudu zรกvisรญ na sprรกvnรฉ adrese `NEXT_PUBLIC_BASE_URL` a dosaลพitelnosti cloudovรฉho koncovรฉho bodu. -5. Adresรกล™ `open-sse/` je publikovรกn jako **balรญฤek npm workspace** `@omniroute/open-sse` . Zdrojovรฝ kรณd jej importuje pล™es `@omniroute/open-sse/...` (vyล™eลกeno pomocรญ `transpilePackages` v Next.js). Cesty k souborลฏm v tomto dokumentu stรกle pouลพรญvajรญ nรกzev adresรกล™e `open-sse/` pro รบฤely konzistence. -6. Grafy v dashboardu pouลพรญvajรญ **Recharts** (zaloลพenรฉ na SVG) pro pล™รญstupnรฉ a interaktivnรญ vizualizace analytiky (sloupcovรฉ grafy vyuลพitรญ modelu, tabulky s rozpisem poskytovatelลฏ s mรญrou รบspฤ›ลกnosti). -7. E2E testy pouลพรญvajรญ **Playwright** ( `tests/e2e/` ), spouลกtฤ›nรฉ pomocรญ `npm run test:e2e` . Unit testy pouลพรญvajรญ **Node.js test runner** ( `tests/unit/` ), spouลกtฤ›nรฉ pomocรญ `npm run test:unit` . Zdrojovรฝ kรณd pod `src/` je **TypeScript** ( `.ts` / `.tsx` ); pracovnรญ prostor `open-sse/` zลฏstรกvรก JavaScript ( `.js` ). -8. Strรกnka nastavenรญ je uspoล™รกdรกna do 5 zรกloลพek: Zabezpeฤenรญ, Smฤ›rovรกnรญ (6 globรกlnรญch strategiรญ: fill-first, round robin, p2c, nรกhodnรฉ, nejmรฉnฤ› pouลพรญvanรฉ, nรกkladovฤ› optimalizovanรฉ), Odolnost (upravitelnรฉ limity rychlosti, jistiฤ, zรกsady), AI (rozpoฤet promyลกlenรฝ, systรฉmovรฝ vรฝzva, mezipamฤ›ลฅ vรฝzev), Pokroฤilรฉ (proxy). - -## Kontrolnรญ seznam provoznรญho ovฤ›ล™enรญ - -- Sestavenรญ ze zdroje: `npm run build` -- Sestavenรญ obrazu Dockeru: `docker build -t omniroute .` -- Spusลฅte sluลพbu a ovฤ›ล™te: -- `GET /api/settings` -- `GET /api/v1/models` -- Zรกkladnรญ URL cรญle CLI by mฤ›la bรฝt `http://:20128/v1` , pokud `PORT=20128` diff --git a/docs/i18n/cs/AUTO-COMBO.md b/docs/i18n/cs/AUTO-COMBO.md deleted file mode 100644 index 70232be750..0000000000 --- a/docs/i18n/cs/AUTO-COMBO.md +++ /dev/null @@ -1,63 +0,0 @@ -# OmniRoute Auto-Combo Engine - -> Samosprรกvnรฉ ล™etฤ›zce modelลฏ s adaptivnรญm bodovรกnรญm - -## Jak to funguje - -Systรฉm Auto-Combo dynamicky vybรญrรก nejlepลกรญho poskytovatele/model pro kaลพdรฝ poลพadavek pomocรญ **6faktorovรฉ skรณrovacรญ funkce** : - -Faktor | Hmotnost | Popis -:-- | :-- | :-- -Kvรณta | 0,20 | Zbรฝvajรญcรญ kapacita [0..1] -Zdravรญ | 0,25 | Jistiฤ: ZAVล˜ENO=1,0, POLOVINA=0,5, OTEVล˜ENO=0,0 -Nรกklady na fakturu | 0,20 | Inverznรญ nรกklady (levnฤ›jลกรญ = vyลกลกรญ skรณre) -LatencyInv | 0,15 | Inverznรญ latence p95 (rychlejลกรญ = vyลกลกรญ) -TaskFit | 0,10 | Skรณre zdatnost modelu ร— typu รบlohy -Stabilita | 0,10 | Nรญzkรก variabilita latence/chyb - -## Balรญฤky mรณdลฏ - -Balรญฤek | Soustล™edit | Hmotnost klรญฤe -:-- | :-- | :-- -๐Ÿš€ **Rychlรฉ odeslรกnรญ** | Rychlost | latenceInv: 0,35 -๐Ÿ’ฐ **รšspora nรกkladลฏ** | Ekonomika | Nรกklady na รบฤet: 0,40 -๐ŸŽฏ **Kvalita na prvnรญm mรญstฤ›** | Nejlepลกรญ model | taskFit: 0,40 -๐Ÿ“ก **Vhodnรฉ pro offline pouลพitรญ** | Dostupnost | kvรณta: 0,40 - -## Samolรฉฤenรญ - -- **Doฤasnรฉ vylouฤenรญ** : Skรณre < 0,2 โ†’ vylouฤeno na 5 minut (postupnรฉ oddluลพovรกnรญ, max. 30 minut) -- **Upozornฤ›nรญ na jistiฤ** : OTEVล˜ENO โ†’ automatickรฉ vylouฤenรญ; POLOVIฤŒNร OTEVล˜ENO โ†’ poลพadavky sondy -- **Reลพim incidentu** : >50% OTEVล˜ENO โ†’ deaktivovat prลฏzkum, maximalizovat stabilitu -- **Obnova po zchlazenรญ** : Po vylouฤenรญ je prvnรญ poลพadavek โ€žsondaโ€œ se zkrรกcenรฝm ฤasovรฝm limitem. - -## Prลฏzkum banditลฏ - -5 % poลพadavkลฏ (konfigurovatelnรฝch) je smฤ›rovรกno k nรกhodnรฝm poskytovatelลฏm k prozkoumรกnรญ. V reลพimu incidentu je toto nastavenรญ zakรกzรกno. - -## API - -```bash -# Create auto-combo -curl -X POST http://localhost:20128/api/combos/auto \ - -H "Content-Type: application/json" \ - -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}' - -# List auto-combos -curl http://localhost:20128/api/combos/auto -``` - -## รškol Fitness - -Vรญce neลพ 30 modelลฏ hodnocenรฝch v 6 typech รบkolลฏ ( `coding` , `review` , `planning` , `analysis` , `debugging` , `documentation` ). Podporuje zรกstupnรฉ znaky (napล™. `*-coder` โ†’ vysokรฉ skรณre kรณdovรกnรญ). - -## Soubory - -Soubor | รšฤel -:-- | :-- -`open-sse/services/autoCombo/scoring.ts` | Skรณrovacรญ funkce a normalizace poolu -`open-sse/services/autoCombo/taskFitness.ts` | Vyhledรกvรกnรญ vhodnosti modelu ร— รบkolu -`open-sse/services/autoCombo/engine.ts` | Logika vรฝbฤ›ru, bandita, rozpoฤtovรฝ strop -`open-sse/services/autoCombo/selfHealing.ts` | Vylouฤenรญ, sondy, reลพim incidentu -`open-sse/services/autoCombo/modePacks.ts` | 4 hmotnostnรญ profily -`src/app/api/combos/auto/route.ts` | REST API diff --git a/docs/i18n/cs/CHANGELOG.md b/docs/i18n/cs/CHANGELOG.md index f6db8a8d16..1aeb98c251 100644 --- a/docs/i18n/cs/CHANGELOG.md +++ b/docs/i18n/cs/CHANGELOG.md @@ -1,275 +1,2011 @@ -# Seznam zmฤ›n +# Changelog (ฤŒeลกtina) -## [Nevydanรฉ] +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CHANGELOG.md) --- -## [2.7.8] โ€” 18. 3. 2026 +## [Unreleased] -> Sprint: Chyba uklรกdรกnรญ rozpoฤtu + funkce kombinovanรฉho agenta v uลพivatelskรฉm rozhranรญ + oprava zabezpeฤenรญ tagu omniModel. +### ๐Ÿ› ๏ธ Maintenance -### ๐Ÿ› Opravy chyb +- **AGENTS.md rewrite:** Condensed from 297โ†’153 lines. Added build/lint/test commands (including single-test execution), code style guidelines (Prettier, TypeScript, ESLint, naming, imports, error handling, security), and trimmed verbose architecture tables for AI agent consumption. -- **fix(budget)** : โ€žUloลพit limityโ€œ jiลพ nevracรญ chybu 422 โ€” `warningThreshold` se nynรญ sprรกvnฤ› odesรญlรก jako zlomek (0โ€“1) mรญsto procenta (0โ€“100) (#451) -- **oprava(kombinace)** : internรญ tag mezipamฤ›ti `` je nynรญ odstranฤ›n pล™ed pล™eposรญlรกnรญm poลพadavkลฏ poskytovatelลฏm, ฤรญmลพ se zabrรกnรญ pล™eruลกenรญ relace mezipamฤ›ti (#454) +## [3.4.2] - 2026-04-01 -### โœจ Funkce +### ๐Ÿ› Bug Fixes -- **feat(combos)** : Do modรกlnรญho okna pro vytvรกล™enรญ/รบpravy komb pล™idรกna sekce Funkce agenta โ€“ zpล™รญstupnฤ›nรญ pล™epsรกnรญ `system_message` , `tool_filter_regex` a `context_cache_protection` pล™รญmo z dashboardu (#454) +- **CI Stabilization:** Fixed failing analytics/settings Playwright selectors and request assertions so GitHub Actions E2E runs pass reliably across localized UIs and switch-based controls. +- **Deterministic Tests:** Removed date-sensitive quota fixtures from Copilot usage tests and aligned idempotency/model catalog tests with the merged runtime behavior. +- **MCP Type Hardening:** Removed zero-budget explicit `any` regressions from the MCP server tool registration path, restoring the `check:any-budget:t11` workflow gate. + +### ๐Ÿ› ๏ธ Maintenance + +- **Release Branch Integration:** Consolidated the active feature branches into `release/v3.4.2` on top of current `main` and validated the branch with lint, unit, coverage, build, and CI-mode E2E runs. + +## [3.4.1] - 2026-03-31 + +> [!WARNING] +> **BREAKING CHANGE: request logging, retention, and logging environment variables have been redesigned.** +> On the first startup after upgrading, OmniRoute archives legacy request logs from `DATA_DIR/logs/`, legacy `DATA_DIR/call_logs/`, and `DATA_DIR/log.txt` into `DATA_DIR/log_archives/*.zip`, then removes the deprecated layout and switches to the new unified artifact format under `DATA_DIR/call_logs/`. + +### โœจ New Features + +- **.ENV Migration Utility:** Included `scripts/migrate-env.mjs` to seamlessly migrate ` Sprint: Pรกd Dockeru pino, oprava workeru Codex CLI responses, synchronizace zรกmkลฏ balรญฤkลฏ. +### Funkce -### ๐Ÿ› Opravy chyb +- **Subscription Utilization Analytics:** Added quota snapshot time-series tracking, Provider Utilization and Combo Health tabs with recharts visualizations, and corresponding API endpoints (#847) +- **SQLite Backup Control:** New `OMNIROUTE_DISABLE_AUTO_BACKUP` env flag to disable automatic SQLite backups (#846) +- **Model Registry Update:** Injected `gpt-5.4-mini` into the Codex provider's array of models (#756) +- **Provider Limit Tracking:** Track and display when provider rate limits were last refreshed per account (#843) -- **oprava(docker)** : `pino-abstract-transport` a `pino-pretty` jsou nynรญ explicitnฤ› kopรญrovรกny ve fรกzi Docker Runner โ€” Samostatnรฉ trasovรกnรญ Next.js tyto zรกvislosti peerลฏ pล™ehlรญลพรญ, coลพ zpลฏsobuje pรกd `Cannot find module pino-abstract-transport` pล™i spuลกtฤ›nรญ (#449) -- **fix(responses)** : Odstranฤ›nรญ `initTranslators()` z trasy `/v1/responses` โ€” worker Next.js `the worker has exited` uncaughtException pล™i poลพadavcรญch Codex CLI (#450) +### ๐Ÿ› Bug Fixes -### ๐Ÿ”ง รšdrลพba - -- **chore(deps)** : `package-lock.json` je nynรญ commitovรกn pล™i kaลพdรฉm upgradu verze, aby se zajistilo, ลพe Docker `npm ci` pouลพije pล™esnรฉ verze zรกvislostรญ. +- **Qwen Auth Routing:** Re-routed Qwen OAuth completions from the DashScope API to the Web Inference API (`chat.qwen.ai`), resolving authorization failures (#844, #807, #832) +- **Qwen Auto-Retry Loop:** Added targeted 429 Quota Exceeded backoff handling inside `chatCore` protecting burst requests +- **Codex OAuth Fallback:** Modern browser popup blocking no longer traps the user; it automatically falls back to manual URL entry (#808) +- **Claude Token Refresh:** Anthropic's strict `application/json` boundaries are now respected during token generation instead of encoded URLs (#836) +- **Codex Messages Schema:** Stripped purist `messages` injects from native passthrough requests to avoid structural rejections from the ChatGPT upstream (#806) +- **CLI Detection Size Limit:** Safely bumped the Node binary scanning upper bound from 100MB to 350MB, allowing heavy standalone tools like Claude Code (229MB) and OpenCode (153MB) to be correctly detected by the VPS runtime (#809) +- **CLI Runtime Environment:** Restored ability for CLI configurations to respect user override paths (`CLI_{PROVIDER}_BIN`) bypassing strict path-bound discovery rules +- **Nvidia Header Conflicts:** Removed `prompt_cache_key` properties from upstream headers when calling non-Anthropic providers (#848) +- **Codex Fast Tier Toggle:** Restored Codex service tier toggle contrast in light mode (#842) +- **Test Infrastructure:** Updated `t28-model-catalog-updates` test that incorrectly expected the outdated DashScope endpoint for the Qwen native registry --- -## [2.7.5] โ€” 18. 3. 2026 +## [3.3.9] - 2026-03-31 -> Sprint: Vylepลกenรญ uลพivatelskรฉho rozhranรญ a oprava kontroly stavu rozhranรญ Windows CLI. +### ๐Ÿ› Bug Fixes -### ๐Ÿ› Opravy chyb - -- **fix(ux)** : Zobrazit na pล™ihlaลกovacรญ strรกnce nรกpovฤ›du k vรฝchozรญmu heslu โ€” novรญ uลพivatelรฉ nynรญ pod polem pro zadรกnรญ hesla vidรญ `"Default password: 123456"` (#437) -- **fix(cli)** : Claude CLI a dalลกรญ nรกstroje nainstalovanรฉ npm jsou nynรญ sprรกvnฤ› detekovรกny jako spustitelnรฉ ve Windows โ€” spawn pouลพรญvรก `shell:true` k rozpoznรกnรญ `.cmd` wrapperลฏ pล™es PATHEXT (#447) +- **Custom Provider Rotation:** Integrated `getRotatingApiKey` internally inside DefaultExecutor, ensuring `extraApiKeys` rotation triggers correctly for custom and compatible upstream providers (#815) --- -## [2.7.4] โ€” 18. 3. 2026 +## [3.3.8] - 2026-03-30 -> Sprint: Panel vyhledรกvacรญch nรกstrojลฏ, opravy i18n, limity Copilota, oprava validace Serperu. +### Funkce -### ๐Ÿš€ Vlastnosti +- **Models API Filtering:** Endpoint `/v1/models` now dynamically filters its list based on the permissions tied to the `Authorization: Bearer ` when restricted access is on (#781) +- **Qoder Integration:** Native integration for Qoder AI natively replacing the legacy iFlow platform mappings (#660) +- **Prompt Cache Tracking:** Added tracking capabilities and frontend visualization (Stats card) for semantic and prompt caching in the Dashboard UI -- **feat(search)** : Pล™idรกno hล™iลกtฤ› pro vyhledรกvรกnรญ (10. koncovรฝ bod), strรกnka s nรกstroji pro vyhledรกvรกnรญ s porovnรกnรญm poskytovatelลฏ/kanรกlovรฝm pล™eล™azenรญm/historiรญ vyhledรกvรกnรญ, lokรกlnรญ smฤ›rovรกnรญ pro pล™eล™azenรญ, ochrana autorizace ve vyhledรกvacรญm API (#443 od @Regis-RCR) - - Novรก trasa: `/dashboard/search-tools` - - Poloลพka postrannรญho panelu v sekci Ladฤ›nรญ - - `GET /api/search/providers` a `GET /api/search/stats` s ochranou autorizace - - Lokรกlnรญ smฤ›rovรกnรญ provider_nodes pro `/v1/rerank` - - 30+ klรญฤลฏ i18n ve vyhledรกvacรญm jmennรฉm prostoru +### ๐Ÿ› Bug Fixes -### ๐Ÿ› Opravy chyb - -- **fix(search)** : Oprava normalizรกtoru Brave News (vracel 0 vรฝsledkลฏ), vynucenรญ zkrรกcenรญ max_results po normalizaci, oprava URL pro naฤรญtรกnรญ strรกnek z koncovรฝch bodลฏ (#443 od @Regis-RCR) -- **fix(analytics)** : Lokalizace popiskลฏ dnลฏ/dat v analytickรฝch nรกstrojรญch โ€” nahrazenรญ pevnฤ› zakรณdovanรฝch portugalskรฝch ล™etฤ›zcลฏ pomocรญ `Intl.DateTimeFormat(locale)` (#444 od @hijak) -- **oprava(copilot)** : Oprava zobrazenรญ typu รบฤtu GitHub Copilot, filtrovรกnรญ zavรกdฤ›jรญcรญch ล™รกdkลฏ neomezenรฝch kvรณt z dashboardu limitลฏ (#445 od @hijak) -- **oprava(poskytovatelรฉ)** : Zastavit odmรญtรกnรญ platnรฝch klรญฤลฏ Serper API โ€“ odpovฤ›di jinรฉ neลพ 4xx povaลพovat za platnรฉ ovฤ›ล™ovรกnรญ (#446 od @hijak) +- **Cache Dashboard Sizing:** Improved the UI layout sizes and context headers for the advanced cache pages (#835) +- **Debug Sidebar Visibility:** Fixed an issue where the debug toggle wouldn't correctly show/hide sidebar debug details (#834) +- **Gemini Model Prefixing:** Modified the namespace fallback to properly route via `gemini-cli/` instead of `gc/` to respect upstream specs (#831) +- **OpenRouter Sync:** Improved compatibility synchronization to automatically ingest the available models catalog correctly from OpenRouter (#830) +- **Streaming Payloads Mapping:** Reserialization of reasoning fields natively resolves conflict alias paths when output is streaming to edge devices --- -## [2.7.3] โ€” 18. 3. 2026 +## [3.3.7] - 2026-03-30 -> Sprint: Oprava zรกloลพnรญ kvรณty pro pล™รญmรฉ API Codexu. +### ๐Ÿ› Bug Fixes -### ๐Ÿ› Opravy chyb - -- **oprava(codex)** : Blokovรกnรญ tรฝdennรญch vyฤerpรกvajรญcรญch รบฤtลฏ v pล™รญmรฉm zรกloลพnรญm rozhranรญ API (#440) - - Porovnรกvรกnรญ prefixลฏ `resolveQuotaWindow()` : `"weekly"` nynรญ odpovรญdรก klรญฤลฏm mezipamฤ›ti `"weekly (7d)"` - - `applyCodexWindowPolicy()` sprรกvnฤ› vynucuje pล™epรญnรกnรญ `useWeekly` / `use5h` - - 4 novรฉ regresnรญ testy (celkem 766) +- **OpenCode Config:** Restructured generated `opencode.json` to use the `@ai-sdk/openai-compatible` record-based schema with `options` and `models` as object maps instead of flat arrays, fixing config validation failures (#816) +- **i18n Missing Keys:** Added missing `cloudflaredUrlNotice` translation key across all 30 language files to prevent `MISSING_MESSAGE` console errors in the Endpoint page (#823) --- -## [2.7.2] โ€” 18. 3. 2026 +## [3.3.6] - 2026-03-30 -> Sprint: Opravy kontrastu uลพivatelskรฉho rozhranรญ v reลพimu Light. +### ๐Ÿ› Bug Fixes -### ๐Ÿ› Opravy chyb - -- **fix(logs)** : Oprava kontrastu svฤ›telnรฉho reลพimu v protokolech poลพadavkลฏ, tlaฤรญtek filtrลฏ a kombinovanรฉho odznaku (#378) - - Tlaฤรญtka filtrลฏ Chyba/รšspฤ›ch/Kombinace jsou nynรญ ฤitelnรก i ve svฤ›tlรฉm reลพimu. - - Odznak kombinovanรฉ ล™ady pouลพรญvรก ve svฤ›tlรฉm reลพimu silnฤ›jลกรญ fialovou barvu +- **Token Accounting:** Included prompt cache tokens safely in historical usage inputs calculations for correct quota deductions (PR #822) +- **Combo Test Probes:** Fixed combo testing logic false negatives by resolving parsing for reasoning-only responses and enabled massive parallelization via Promise.all (PR #828) +- **Docker Quick Tunnels:** Embedded required ca-certificates inside the base runtime container to resolve Cloudflared TLS startup failures, and surfaced stdout network errors replacing generic exit codes (PR #829) --- -## [2.7.1] โ€” 17. 3. 2026 +## [3.3.5] - 2026-03-30 -> Sprint: Sjednocenรฉ smฤ›rovรกnรญ webovรฉho vyhledรกvรกnรญ (POST /v1/search) s 5 poskytovateli + opravy zabezpeฤenรญ Next.js 16.1.7 (6 CVE). +### โœจ New Features -### โœจ Novรฉ funkce +- **Gemini Quota Tracking:** Added real-time Gemini CLI quota tracking via the `retrieveUserQuota` API (PR #825) +- **Cache Dashboard:** Enhanced the Cache Dashboard to display prompt cache metrics, 24h trends, and estimated cost savings (PR #824) -- **feat(search)** : Sjednocenรฉ smฤ›rovรกnรญ webovรฉho vyhledรกvรกnรญ โ€” `POST /v1/search` s 5 poskytovateli (Serper, Brave, Perplexity, Exa, Tavily) - - Automatickรฉ pล™epnutรญ napล™รญฤ poskytovateli, vรญce neลพ 6 500 bezplatnรฝch vyhledรกvรกnรญ/mฤ›sรญc - - Mezipamฤ›ลฅ v pamฤ›ti se sluฤovรกnรญm poลพadavkลฏ (konfigurovatelnรฉ TTL) - - Dashboard: Karta Analytika vyhledรกvรกnรญ v `/dashboard/analytics` s rozpisem poskytovatelลฏ, mรญrou zรกsahลฏ do mezipamฤ›ti a sledovรกnรญm nรกkladลฏ - - Novรฉ API: `GET /api/v1/search/analytics` pro statistiky vyhledรกvacรญch poลพadavkลฏ - - Migrace databรกze: sloupec `request_type` v `call_logs` pro sledovรกnรญ poลพadavkลฏ mimo chat - - Ovฤ›ล™enรญ Zod ( `v1SearchSchema` ), chrรกnฤ›nรฉ autorizacรญ, nรกklady zaznamenรกny pomocรญ `recordCost()` +### ๐Ÿ› Bug Fixes -### ๐Ÿ”’ Bezpeฤnost - -- **deps** : Next.js 16.1.6 โ†’ 16.1.7 โ€” opravuje 6 CVE: - - **Kritickรฉ** : CVE-2026-29057 (paลกovรกnรญ HTTP poลพadavkลฏ pล™es http-proxy) - - **Vysokรก** : CVE-2026-27977, CVE-2026-27978 (WebSocket + akce serveru) - - **Mรฉdium** : CVE-2026-27979, CVE-2026-27980, CVE-2026-jcc7 - -### ๐Ÿ“ Novรฉ soubory - -| Soubor | รšฤel | -| ---------------------------------------------------------------- | -------------------------------------------------------- | -| `open-sse/handlers/search.ts` | Vyhledรกvacรญ obsluลพnรก rutina s routovรกnรญm 5 poskytovatelลฏ | -| `open-sse/config/searchRegistry.ts` | Registr poskytovatelลฏ (autorizace, nรกklady, kvรณta, TTL) | -| `open-sse/services/searchCache.ts` | Mezipamฤ›ลฅ v pamฤ›ti se sluฤovรกnรญm poลพadavkลฏ | -| `src/app/api/v1/search/route.ts` | Trasa Next.js (POST + GET) | -| `src/app/api/v1/search/analytics/route.ts` | API pro statistiky vyhledรกvรกnรญ | -| `src/app/(dashboard)/dashboard/analytics/SearchAnalyticsTab.tsx` | Karta analytickรฉho panelu | -| `src/lib/db/migrations/007_search_request_type.sql` | Migrace databรกze | -| `tests/unit/search-registry.test.mjs` | 277 ล™รกdkลฏ jednotkovรฝch testลฏ | +- **User Experience:** Removed invasive auto-opening OAuth modal loops on barren provider detailed pages (PR #820) +- **Dependency Updates:** Bumped and locked down dependencies for development and production trees including Next.js 16.2.1, Recharts, and TailwindCSS 4.2.2 (PR #826, #827) --- -## [2.7.0] โ€” 17. 3. 2026 +## [3.3.4] - 2026-03-30 -> Sprint: Funkce inspirovanรฉ ClawRouterem โ€“ pล™รญznak volรกnรญ toolCalling, vรญcejazyฤnรก detekce zรกmฤ›ru, benchmarkem ล™รญzenรฝ fallback, deduplikace poลพadavkลฏ, plugin RouterStrategy, ceny Grok-4 Fast + GLM-5 + MiniMax M2.5 + Kimi K2.5. +### โœจ New Features -### โœจ Novรฉ modely a ceny +- **A2A Workflows:** Added deterministic FSM orchestrator for multi-step agent workflows. +- **Graceful Degradation:** Added a new multi-layer fallback framework to preserve core functionality during partial system outages. +- **Config Audit:** Added an audit trail with diff detection to track changes and enable configuration rollbacks. +- **Provider Health:** Added provider expiration tracking with proactive UI alerts for expiring API keys. +- **Adaptive Routing:** Added an adaptive volume and complexity detector to override routing strategies dynamically based on load. +- **Provider Diversity:** Implemented provider diversity scoring via Shannon entropy to improve load distribution. +- **Auto-Disable Bounds:** Added an Auto-Disable Banned Accounts setting toggle to the Resilience dashboard. -- **feat. (ceny)** : xAI Grok-4 Fast โ€” `$0.20/$0.50 per 1M tokens` , latence 1143 ms p50, podpora volรกnรญ nรกstrojลฏ -- **feat. (ceny)** : xAI Grok-4 (standardnรญ) โ€” `$0.20/$1.50 per 1M tokens` , coลพ je dลฏvodem k odmรญtnutรญ. -- **vรฝkon (ceny)** : GLM-5 pล™es Z.AI โ€” `$0.5/1M` , 128 tisรญc vรฝstupnรญch kontextลฏ -- **vรฝkon (ceny)** : MiniMax M2.5 โ€” `$0.30/1M input` , uvaลพovรกnรญ + agentnรญ รบkoly -- **feat.(ceny)** : DeepSeek V3.2 โ€” aktualizovanรฉ ceny `$0.27/$1.10 per 1M` -- **vรฝkon (cena)** : Kimi K2.5 pล™es Moonshot API โ€” pล™รญmรฝ pล™รญstup k Moonshot API -- **feat(providers)** : Pล™idรกn poskytovatel Z.AI (alias `zai` ) โ€” rodina GLM-5 s vรฝstupem 128K +### ๐Ÿ› Bug Fixes -### ๐Ÿง  Smฤ›rovacรญ inteligence +- **Codex & Claude Compatibility:** Fixed UI fallbacks, patched Codex non-streaming integration issues, and resolved CLI runtime detection on Windows. +- **Release Automation:** Expanded permissions required for the Electron App build in GitHub Actions. +- **Cloudflare Runtime:** Addressed correct runtime isolation exit codes for Cloudflared tunnel components. -- **feat(registry)** : pล™รญznak `toolCalling` pro kaลพdรฝ model v registru poskytovatelลฏ โ€“ kombinace nynรญ mohou preferovat/vyลพadovat modely s moลพnostรญ volรกnรญ nรกstrojลฏ -- **feat(scoring)** : Detekce vรญcejazyฤnรฉho zรกmฤ›ru pro skรณrovรกnรญ AutoCombo โ€” skriptovรฉ/jazykovรฉ vzory PT/ZH/ES/AR ovlivลˆujรญ vรฝbฤ›r modelu podle kontextu poลพadavku -- **feat(fallback)** : ล˜etฤ›zce zรกloลพnรญch metod ล™รญzenรฉ benchmarky โ€” skuteฤnรก data o latenci (p50 z `comboMetrics` ) pouลพรญvanรก k dynamickรฉmu pล™eskupenรญ priorit zรกloลพnรญch metod -- **feat(dedup)** : Vyลพรกdรกnรญ deduplikace pomocรญ content-hash โ€” 5sekundovรฉ okno idempotence zabraลˆuje duplicitnรญm volรกnรญm poskytovatele v opakovanรฉm pokusu o odeslรกnรญ klientลฏm -- **feat(router)** : Pล™ipojitelnรฉ rozhranรญ `RouterStrategy` v `autoCombo/routerStrategy.ts` โ€” lze vloลพit vlastnรญ logiku smฤ›rovรกnรญ bez รบpravy jรกdra +### ๐Ÿงช Tests -### ๐Ÿ”ง Vylepลกenรญ serveru MCP - -- **feat(mcp)** : 2 novรก pokroฤilรก schรฉmata nรกstrojลฏ: `omniroute_get_provider_metrics` (p50/p95/p99 na poskytovatele) a `omniroute_explain_route` (vysvฤ›tlenรญ rozhodnutรญ o smฤ›rovรกnรญ) -- **feat(mcp)** : Aktualizovรกny rozsahy autorizace nรกstroje MCP โ€“ pล™idรกn rozsah `metrics:read` pro nรกstroje pro metriky poskytovatelลฏ -- **feat(mcp)** : `omniroute_best_combo_for_task` nynรญ akceptuje parametr `languageHint` pro vรญcejazyฤnรฉ smฤ›rovรกnรญ - -### ๐Ÿ“Š Pozorovatelnost - -- **feat(metrics)** : Soubor `comboMetrics.ts` rozลกรญล™en o sledovรกnรญ percentilลฏ latence v reรกlnรฉm ฤase pro kaลพdรฉho poskytovatele/รบฤet. -- **feat(health)** : Rozhranรญ Health API ( `/api/monitoring/health` ) nynรญ vracรญ pole `p50Latency` a `errorRate` pro kaลพdรฉho poskytovatele. -- **feat(usage)** : Migrace historie pouลพitรญ pro sledovรกnรญ latence pro jednotlivรฉ modely - -### ๐Ÿ—„๏ธ Migrace databรกzรญ - -- **feat(migrations)** : Novรฝ sloupec `latency_p50` v tabulce `combo_metrics` โ€” nulovรฝ, bezpeฤnรฝ pro stรกvajรญcรญ uลพivatele - -### ๐Ÿ› Opravy chyb / Uzavล™enรญ - -- **close(#411)** : rozliลกenรญ haลกovanรฝch modulลฏ better-sqlite3 ve Windows โ€” opraveno ve verzi 2.6.10 (f02c5b5) -- **close(#409)** : Dokonฤenรญ chatu GitHub Copilot selhรกvรก u modelลฏ Claude pล™i pล™ipojenรญ souborลฏ โ€“ opraveno ve verzi 2.6.9 (838f1d6) -- **close(#405)** : Duplikรกt #411 โ€“ vyล™eลกeno - -## [2.6.10] โ€” 17. 3. 2026 - -> Oprava pro Windows: staลพenรญ pล™edkompilovanรฉho better-sqlite3 bez node-gyp/Pythonu/MSVC (#426). - -### ๐Ÿ› Opravy chyb - -- **fix(install/#426)** : Ve Windows dล™รญve selhรกval pล™รญkaz `npm install -g omniroute` s `better_sqlite3.node is not a valid Win32 application` , protoลพe pล™iloลพenรฝ nativnรญ binรกrnรญ soubor byl zkompilovรกn pro Linux. Pล™idรกvรก **strategii 1.5** do `scripts/postinstall.mjs` : pouลพรญvรก `@mapbox/node-pre-gyp install --fallback-to-build=false` (pล™iloลพeno v rรกmci `better-sqlite3` ) ke staลพenรญ sprรกvnรฉho pล™edkompilovanรฉho binรกrnรญho souboru pro aktuรกlnรญ OS/arch bez nutnosti pouลพitรญ jakรฝchkoli nรกstrojลฏ pro sestavenรญ (ลพรกdnรฝ node-gyp, ลพรกdnรฝ Python, ลพรกdnรฝ MSVC). Vracรญ se k `npm rebuild` pouze v pล™รญpadฤ›, ลพe stahovรกnรญ selลพe. Pล™idรกvรก chybovรฉ zprรกvy specifickรฉ pro platformu s jasnรฝmi pokyny k ruฤnรญ opravฤ›. +- **Test Suite Updates:** Expanded test coverage for volume detectors, provider diversity, configuration audit, and FSM. --- -## [2.6.9] โ€” 17. 3. 2026 +## [3.3.3] - 2026-03-29 -> Opravy CI (t11 s libovolnรฝm rozpoฤtem), oprava chyby ฤ. 409 (souborovรฉ pล™รญlohy pล™es Copilot+Claude), korekce pracovnรญho postupu vydรกnรญ. +### ๐Ÿ› Bug Fixes -### ๐Ÿ› Opravy chyb - -- **fix(ci)** : Odstranฤ›nรญ slova โ€žanyโ€œ z komentรกล™ลฏ v `openai-responses.ts` a `chatCore.ts` , kterรฉ neproลกly kontrolou rozpoฤtu t11 `\bany\b` (faleลกnฤ› pozitivnรญ vรฝsledek z poฤรญtรกnรญ regexลฏ v komentรกล™รญch). -- **oprava(chatCore)** : Normalizovat nepodporovanรฉ typy ฤรกstรญ obsahu pล™ed pล™eposlรกnรญm poskytovatelลฏm (#409 โ€” Kurzor odesรญlรก `{type:"file"}` kdyลพ jsou pล™ipojeny soubory `.md` ; Copilot a dalลกรญ poskytovatelรฉ kompatibilnรญ s OpenAI odmรญtajรญ s "type musรญ bรฝt buฤ 'image_url', nebo 'text'"; oprava pล™evรกdรญ bloky `file` / `document` na `text` a odstraลˆuje neznรกmรฉ typy) - -### ๐Ÿ”ง Pracovnรญ postup - -- **chore(generate-release)** : Pล™idat pravidlo pro atomickรฝ commit โ€” navรฝลกenรญ verze ( `npm version patch` ) MUSร probฤ›hnout pล™ed commitem souborลฏ funkcรญ, aby se zajistilo, ลพe tag vลพdy ukazuje na commit obsahujรญcรญ vลกechny zmฤ›ny verzรญ dohromady. +- **CI/CD Reliability:** Patched GitHub Actions to stable dependency versions (`actions/checkout@v4`, `actions/upload-artifact@v4`) to mitigate unannounced builder environment deprecations. +- **Image Fallbacks:** Replaced arbitrary fallback chains in `ProviderIcon.tsx` with explicit asset validation to prevent UI loading `` components for files that don't exist, eliminating `404` errors in dashboard console logs (#745). +- **Admin Updater:** Dynamic source-installation detection for the dashboard Updater. Safely disables the `Update Now` button when OmniRoute is built locally rather than through npm, prompting for `git pull` (#743). +- **Update ERESOLVE Error:** Injected `package.json` overrides for `react`/`react-dom` and enabled `--legacy-peer-deps` within the internal automatic updater scripts to resolve breaking dependency tree conflicts with `@lobehub/ui`. --- -## [2.6.8] โ€” 17. 3. 2026 +## [3.3.2] - 2026-03-29 -> Sprint: Kombinace jako agent (systรฉmovรฝ pล™รญkaz + filtr nรกstrojลฏ), ochrana kontextovรฉho uklรกdรกnรญ do mezipamฤ›ti, automatickรก aktualizace, podrobnรฉ protokoly, MITM Kiro IDE. +### โœจ New Features -### ๐Ÿ—„๏ธ Migrace databรกzรญ (bez nutnosti aktualizace โ€“ bezpeฤnรฉ pro stรกvajรญcรญ uลพivatele) +- **Cloudflare Tunnels:** Cloudflare Quick Tunnel integration with dashboard controls (PR #772). +- **Diagnostics:** Semantic cache bypass for combo live tests (PR #773). -- **005_combo_agent_fields.sql** : `ALTER TABLE combos ADD COLUMN system_message TEXT DEFAULT NULL` , `tool_filter_regex TEXT DEFAULT NULL` , `context_cache_protection INTEGER DEFAULT 0` -- **006_detailed_request_logs.sql** : Novรก tabulka `request_detail_logs` s triggerem kruhovรฉho bufferu s 500 zรกznamy, moลพnost pล™ihlรกลกenรญ pล™es pล™epรญnaฤ nastavenรญ +### ๐Ÿ› Bug Fixes -### โœจ Funkce - -- **feat(combo)** : Pล™epsรกnรญ systรฉmovรฝch zprรกv pro Combo (#399 โ€” pole `system_message` nahrazuje nebo vklรกdรก systรฉmovรฝ vรฝzvu pล™ed pล™esmฤ›rovรกnรญm poskytovateli) -- **feat(combo)** : Regulรกrnรญ vรฝraz filtru nรกstrojลฏ pro kaลพdou kombinaci (#399 โ€” `tool_filter_regex` uchovรกvรก pouze nรกstroje odpovรญdajรญcรญ vzoru; podporuje formรกty OpenAI + Anthropic) -- **feat(combo)** : Ochrana pล™ed uklรกdรกnรญm do mezipamฤ›ti kontextu (#401 โ€” `context_cache_protection` oznaฤuje odpovฤ›di s `provider/model` a modelem pins pro zajiลกtฤ›nรญ kontinuity relace) -- **feat(settings)** : Automatickรก aktualizace pล™es Nastavenรญ (#320 โ€” `GET /api/system/version` + `POST /api/system/update` โ€” kontroluje registr npm a aktualizuje na pozadรญ s restartem pm2) -- **feat(logs)** : Podrobnรฉ protokoly poลพadavkลฏ (#378 โ€” zachycuje kompletnรญ tฤ›la procesลฏ ve 4 fรกzรญch: poลพadavek klienta, pล™eloลพenรฝ poลพadavek, odpovฤ›ฤ poskytovatele, odpovฤ›ฤ klienta โ€” pล™epรญnรกnรญ pล™ihlรกลกenรญ, oล™ezรกvรกnรญ na 64 kB, kruhovรก vyrovnรกvacรญ pamฤ›ลฅ s 500 zรกznamy) -- **feat(mitm)** : Profil MITM Kiro IDE (#336 โ€” `src/mitm/targets/kiro.ts` cรญlรญ na api.anthropic.com, znovu vyuลพรญvรก stรกvajรญcรญ infrastrukturu MITM) +- **Streaming Stability:** Apply `FETCH_TIMEOUT_MS` to streaming requests' initial `fetch()` call to prevent 300s Node.js TCP timeout causing silent task failures (#769). +- **i18n:** Add missing `windsurf` and `copilot` entries to `toolDescriptions` across all 33 locale files (#748). +- **GLM Coding Audit:** Complete provider audit fixing ReDoS vulnerabilities, context window sizing (128k/16k), and model registry syncing (PR #778). --- -## [2.6.7] โ€” 17. 3. 2026 +## [3.3.1] - 2026-03-29 -> Sprint: Vylepลกenรญ SSE, rozลกรญล™enรญ lokรกlnรญch provider_nodes, registr proxy, opravy Claude passthrough. +### ๐Ÿ› Bug Fixes -### โœจ Funkce - -- **feat(health)** : Kontrola stavu lokรกlnรญch `provider_nodes` na pozadรญ s exponenciรกlnรญm zpoลพdฤ›nรญm (30sโ†’300s) a `Promise.allSettled` pro zamezenรญ blokovรกnรญ (#423, @Regis-RCR) -- **feat(embeddings)** : Smฤ›rovรกnรญ `/v1/embeddings` do lokรกlnรญch uzlลฏ `provider_nodes` โ€” `buildDynamicEmbeddingProvider()` s ovฤ›ล™enรญm nรกzvu hostitele (#422, @Regis-RCR) -- **feat(audio)** : Smฤ›rovรกnรญ TTS/STT do lokรกlnรญch `provider_nodes` โ€” `buildDynamicAudioProvider()` s ochranou SSRF (#416, @Regis-RCR) -- **feat(proxy)** : Registr proxy, API pro sprรกvu a zobecnฤ›nรญ limitลฏ kvรณt (#429, @Regis-RCR) - -### ๐Ÿ› Opravy chyb - -- **fix(sse)** : Odstranฤ›nรญ polรญ specifickรฝch pro Claude ( `metadata` , `anthropic_version` ), pokud je cรญl kompatibilnรญ s OpenAI (#421, @prakersh) -- **fix(sse)** : Extrahuje vyuลพitรญ Claude SSE ( `input_tokens` , `output_tokens` , cache tokeny) v reลพimu prลฏchozรญho streamu (#420, @prakersh) -- **fix(sse)** : Generovรกnรญ zรกloลพnรญho `call_id` pro volรกnรญ nรกstrojลฏ s chybฤ›jรญcรญmi/prรกzdnรฝmi ID (#419, @prakersh) -- **oprava(sse)** : Prลฏchod mezi Claudey a Claudey โ€” pล™ednรญ tฤ›lo zcela nedotฤeno, bez opฤ›tovnรฉho pล™ekladu (#418, @prakersh) -- **fix(sse)** : Filtrovat osiล™elรฉ poloลพky `tool_result` po zhuลกtฤ›nรญ kontextu Claude Code, aby se zabrรกnilo chybรกm 400 (#417, @prakersh) -- **fix(sse)** : Pล™eskoฤit volรกnรญ nรกstrojลฏ s prรกzdnรฝmi nรกzvy v pล™ekladaฤi Responses API, aby se zabrรกnilo nekoneฤnรฝm smyฤkรกm `placeholder_tool` (#415, @prakersh) -- **fix(sse)** : Odstranฤ›nรญ prรกzdnรฝch blokลฏ textovรฉho obsahu pล™ed pล™ekladem (#427, @prakersh) -- **fix(api)** : Pล™idรกno `refreshable: true` do testovacรญ konfigurace Claude OAuth (#428, @prakersh) - -### ๐Ÿ“ฆ Zรกvislosti - -- Zvรฝลกenรญ `vitest` , `@vitest/*` a souvisejรญcรญ devDependencies (#414, @dependabot) +- **OpenAI Codex:** Fallback processing fix for `type: "text"` elements carrying null or empty datasets that caused 400 rejection (#742). +- **Opencode:** Update schema alignment to singular `provider` to match official spec (#774). +- **Gemini CLI:** Inject missing end-user quota headers preventing 403 authorization lockouts (#775). +- **DB Recovery:** Refactor multipart payload imports into raw binary buffered arrays to bypass reverse proxy max body limits (#770). --- -## [2.6.6] โ€” 17. 3. 2026 +## [3.3.0] - 2026-03-29 -> Oprava: Kompatibilita s Turbopackem/Dockerem โ€” odebrรกnรญ protokolu `node:` ze vลกech importลฏ `src/` . +### โœจ Enhancements & Refactoring -### ๐Ÿ› Opravy chyb +- **Release Stabilization** โ€” Finalized v3.2.9 release (combo diagnostics, quality gates, Gemini tool fix) and created missing git tag. Consolidated all staged changes into a single atomic release commit. -- **fix(build)** : Z pล™รญkazลฏ `import` v 17 souborech v `src/` byl odstranฤ›n prefix `node:` protocol. Importy `node:fs` , `node:path` , `node:url` , `node:os` atd. zpลฏsobovaly, ลพe `Ecmascript file had an error` v sestavenรญch Turbopack (Next.js 15 Docker) a pล™i upgradech ze starลกรญch globรกlnรญch instalacรญ npm. Dotฤenรฉ soubory: `migrationRunner.ts` , `core.ts` , `backup.ts` , `prompts.ts` , `dataPaths.ts` a 12 dalลกรญch v `src/app/api/` a `src/lib/` . -- **chore(workflow)** : Aktualizovรกn `generate-release.md` , aby synchronizace Docker Hubu a nasazenรญ duรกlnรญho VPS zahrnovaly **povinnรฉ** kroky v kaลพdรฉ verzi. +### ๐Ÿ› Bug Fixes + +- **Auto-Update Test** โ€” Fixed `buildDockerComposeUpdateScript` test assertion to match unexpanded shell variable references (`$TARGET_TAG`, `${TARGET_TAG#v}`) in the generated deploy script, aligning with the refactored template from v3.2.8. +- **Circuit Breaker Test** โ€” Hardened `combo-circuit-breaker.test.mjs` by injecting `maxRetries: 0` to prevent retry inflation from skewing failure count assertions during breaker state transitions. --- -## [2.6.5] โ€” 17. 3. 2026 +## [3.2.9] - 2026-03-29 -> Sprint: filtrovรกnรญ parametrลฏ modelu uvaลพovรกnรญ, oprava chyby 404 lokรกlnรญho poskytovatele, poskytovatel Kilo Gateway, vylepลกenรญ zรกvislostรญ. +### โœจ Enhancements & Refactoring -### โœจ Novรฉ funkce +- **Combo Diagnostics** โ€” Introduced a live test bypass flag (`forceLiveComboTest`) allowing administrators to execute real upstream health checks that bypass all local circuit-breaker and cooldown state mechanisms, enabling precise diagnostics during rolling outages (PR #759) +- **Quality Gates** โ€” Added automated response quality validation for combos and officially integrated `claude-4.6` model support into the core routing schemas (PR #762) -- **feat(api)** : Pล™idรกn **Kilo Gateway** ( `api.kilo.ai` ) jako novรฝ poskytovatel API klรญฤลฏ (alias `kg` ) โ€” vรญce neลพ 335 modelลฏ, 6 bezplatnรฝch modelลฏ, 3 modely automatickรฉho smฤ›rovรกnรญ ( `kilo-auto/frontier` , `kilo-auto/balanced` , `kilo-auto/free` ). Prลฏchozรญ modely podporovรกny pล™es endpoint `/api/gateway/models` . (PR #408 od @Regis-RCR) +### ๐Ÿ› Bug Fixes -### ๐Ÿ› Opravy chyb +- **Tool Definition Validation** โ€” Repaired Gemini API integration by normalizing enum types inside tool definitions, preventing upstream HTTP 400 parameter errors (PR #760) -- **fix(sse)** : Odstranฤ›nรญ nepodporovanรฝch parametrลฏ pro modely uvaลพovรกnรญ (o1, o1-mini, o1-pro, o3, o3-mini). Modely v rodinฤ› `o1` / `o3` odmรญtajรญ `temperature` , `top_p` , `frequency_penalty` , `presence_penalty` , `logprobs` , `top_logprobs` a `n` s HTTP 400. Parametry jsou nynรญ odstraลˆovรกny na vrstvฤ› `chatCore` pล™ed pล™eposรญlรกnรญm. Pouลพรญvรก deklarativnรญ pole `unsupportedParams` pro kaลพdรฝ model a pล™edpoฤรญtanou mapu O(1) pro vyhledรกvรกnรญ. (PR #412 od @Regis-RCR) -- **fix(sse)** : Kรณd 404 lokรกlnรญho poskytovatele nynรญ vede k **uzamฤenรญ pouze modelu (5 sekund)** namรญsto uzamฤenรญ na รบrovni pล™ipojenรญ (2 minuty). Kdyลพ lokรกlnรญ inferenฤnรญ backend (Ollama, LM Studio, oMLX) vrรกtรญ kรณd 404 pro neznรกmรฝ model, pล™ipojenรญ zลฏstane aktivnรญ a ostatnรญ modely okamลพitฤ› pokraฤujรญ v prรกci. Takรฉ opravuje jiลพ existujรญcรญ chybu, kdy `model` nebyl pล™edรกn funkci `markAccountUnavailable()` . Lokรกlnรญ poskytovatelรฉ detekovรกni pomocรญ nรกzvu hostitele ( `localhost` , `127.0.0.1` , `::1` , rozลกiล™itelnรฉ pomocรญ promฤ›nnรฉ prostล™edรญ `LOCAL_HOSTNAMES` ). (PR #410 od @Regis-RCR) +--- -### ๐Ÿ“ฆ Zรกvislosti +## [3.2.8] - 2026-03-29 + +### โœจ Enhancements & Refactoring + +- **Docker Auto-Update UI** โ€” Integrated a detached background update process for Docker Compose deployments. The Dashboard UI now seamlessly tracks update lifecycle events combining JSON REST responses with SSE streaming progress overlays for robust cross-environment reliability. +- **Cache Analytics** โ€” Repaired zero-metrics visualization mapping by migrating Semantic Cache telemetry logs directly into the centralized tracking SQLite module. + +### ๐Ÿ› Bug Fixes + +- **Authentication Logic** โ€” Fixed a bug where saving dashboard settings or adding models failed with a 401 Unauthorized error when `requireLogin` was disabled. API endpoints now correctly evaluate the global authentication toggle. Resolved global redirection by reactivating `src/middleware.ts`. +- **CLI Tool Detection (Windows)** โ€” Prevented fatal initialization exceptions during CLI environment detection by catching `cross-spawn` ENOENT errors correctly. Adds explicit detection paths for `\AppData\Local\droid\droid.exe`. +- **Codex Native Passthrough** โ€” Normalized model translation parameters preventing context poisoning in proxy pass-through mode, enforcing generic `store: false` constraints explicitly for all Codex-originated requests. +- **SSE Token Reporting** โ€” Normalized provider tool-call chunk `finish_reason` detection, fixing 0% Usage analytics for stream-only responses missing strict `` indicators. +- **DeepSeek Tags** โ€” Implemented an explicit `` extraction mapping inside `responsesHandler.ts`, ensuring DeepSeek reasoning streams map equivalently to native Anthropic `` structures. + +--- + +## [3.2.7] - 2026-03-29 + +### Fixed + +- **Seamless UI Updates**: The "Update Now" feature on the Dashboard now provides live, transparent feedback using Server-Sent Events (SSE). It performs package installation, native module rebuilds (better-sqlite3), and PM2 restarts reliably while showing real-time loaders instead of silently hanging. + +--- + +## [3.2.6] โ€” 2026-03-29 + +### โœจ Enhancements & Refactoring + +- **API Key Reveal (#740)** โ€” Added a scoped API key copy flow in the Api Manager, protected by the `ALLOW_API_KEY_REVEAL` environment variable. +- **Sidebar Visibility Controls (#739)** โ€” Admins can now hide any sidebar navigation link via the Appearance settings to reduce visual clutter. +- **Strict Combo Testing (#735)** โ€” Hardened the combo health check endpoint to require live text responses from models instead of just soft reachability signals. +- **Streamed Detailed Logs (#734)** โ€” Switched detailed request logging for SSE streams to reconstruct the final payload, saving immense amounts of SQLite database size and significantly cleaning up the UI. + +### ๐Ÿ› Bug Fixes + +- **OpenCode Go MiniMax Auth (#733)** โ€” Corrected the authentication header logic for `minimax` models on OpenCode Go to use `x-api-key` instead of standard bearer tokens across the `/messages` protocol. + +--- + +## [3.2.5] โ€” 2026-03-29 + +### โœจ Enhancements & Refactoring + +- **Void Linux Deployment Support (#732)** โ€” Integrated `xbps-src` packaging template and instructions to natively compile and install OmniRoute with `better-sqlite3` bindings via cross-compilation target. + +## [3.2.4] โ€” 2026-03-29 + +### โœจ Enhancements & Refactoring + +- **Qoder AI Migration (#660)** โ€” Completely migrated the legacy `iFlow` core provider onto `Qoder AI` maintaining stable API routing capabilities. + +### ๐Ÿ› Bug Fixes + +- **Gemini Tools HTTP 400 Payload Invalid Argument (#731)** โ€” Prevented `thoughtSignature` array injections inside standard Gemini `functionCall` sequences blocking agentic routing flows. + +--- + +## [3.2.3] โ€” 2026-03-29 + +### โœจ Enhancements & Refactoring + +- **Provider Limits Quota UI (#728)** โ€” Normalized quota limit logic and data labeling inside the Limits interface. + +### ๐Ÿ› Bug Fixes + +- **Core Routing Schemas & Leaks** โ€” Expanded `comboStrategySchema` to natively support `fill-first` and `p2c` strategies to unblock complex combo editing natively. +- **Thinking Tags Extraction (CLI)** โ€” Restructured CLI token responses sanitizer RegEx capturing model reasoning structures inside streams avoiding broken `` extractions breaking response text output format. +- **Strict Format Enforcements** โ€” Hardened pipeline sanitization execution making it universally apply to translation mode targets. + +--- + +## [3.2.2] โ€” 2026-03-29 + +### โœจ New Features + +- **Four-Stage Request Log Pipeline (#705)** โ€” Refactored log persistence to save comprehensive payloads at four distinct pipeline stages: Client Request, Translated Provider Request, Provider Response, and Translated Client Response. Introduced `streamPayloadCollector` for robust SSE stream truncation and payload serialization. + +### ๐Ÿ› Bug Fixes + +- **Mobile UI Fixes (#659)** โ€” Prevented table components on the dashboard from breaking the layout on narrow viewports by adding proper horizontal scrolling and overflow containment to `DashboardLayout`. +- **Claude Prompt Cache Fixes (#708)** โ€” Ensured `cache_control` blocks in Claude-to-Claude fallback loops are faithfully preserved and passed safely back to Anthropic models. +- **Gemini Tool Definitions (#725)** โ€” Fixed schema translation errors when declaring simple `object` parameter types for Gemini function calling. + +## [3.2.1] โ€” 2026-03-29 + +### โœจ New Features + +- **Global Fallback Provider (#689)** โ€” When all combo models are exhausted (502/503), OmniRoute now attempts a configurable global fallback model before returning the error. Set `globalFallbackModel` in settings to enable. + +### ๐Ÿ› Bug Fixes + +- **Fix #721** โ€” Fixed context pinning bypass during tool-call responses. Non-streaming tagging used wrong JSON path (`json.messages` โ†’ `json.choices[0].message`). Streaming injection now triggers on `finish_reason` chunks for tool-call-only streams. `injectModelTag()` now appends synthetic pin messages for non-string content. +- **Fix #709** โ€” Confirmed already fixed (v3.1.9) โ€” `system-info.mjs` creates directories recursively. Closed. +- **Fix #707** โ€” Confirmed already fixed (v3.1.9) โ€” empty tool name sanitization in `chatCore.ts`. Closed. + +### ๐Ÿงช Tests + +- Added 6 unit tests for context pinning with tool-call responses (null content, array content, roundtrip, re-injection) + +## [3.2.0] โ€” 2026-03-28 + +### โœจ New Features + +- **Cache Management UI** โ€” Added a dedicated semantic caching dashboard at \`/dashboard/cache\` with targeted API invalidation and 31-language i18n support (PR #701 by @oyi77) +- **GLM Quota Tracking** โ€” Added real-time usage and session quota tracking for the GLM Coding (Z.AI) provider (PR #698 by @christopher-s) +- **Detailed Log Payloads** โ€” Wired full four-stage pipeline payload capturing (original, translated, provider-response, streamed-deltas) directly into the UI (PR #705 by @rdself) + +### ๐Ÿ› Bug Fixes + +- **Fix #708** โ€” Prevented token bleeding for Claude Code users routing through OmniRoute by correctly preserving native \`cache_control\` headers during Claude-to-Claude passthrough (PR #708 by @tombii) +- **Fix #719** โ€” Setup internal auth boundaries for \`ModelSyncScheduler\` to prevent unauthenticated daemon failures on startup (PR #719 by @rdself) +- **Fix #718** โ€” Rebuilt badge rendering in Provider Limits UI preventing bad quota boundaries overlap (PR #718 by @rdself) +- **Fix #704** โ€” Fixed Combo Fallbacks breaking on HTTP 400 content-policy errors preventing model-rotation dead-routing (PR #704 by @rdself) + +### ๐Ÿ”’ Security & Dependencies + +- Bumped \`path-to-regexp\` to \`8.4.0\` resolving dependabot vulnerabilities (PR #715) + +## [3.1.10] โ€” 2026-03-28 + +### ๐Ÿ› Bug Fixes + +- **Fix #706** โ€” Fixed icon fallback rendering caused by Tailwind V4 `font-sans` override by applying `!important` to `.material-symbols-outlined`. +- **Fix #703** โ€” Fixed GitHub Copilot broken streams by enabling `responses` to `openai` format translation for any custom models leveraging `apiFormat: "responses"`. +- **Fix #702** โ€” Replaced flat-rate usage tracking with accurate DB pricing calculations for both streaming and non-streaming responses. +- **Fix #716** โ€” Cleaned up Claude tool-call translation state, correctly parsing streaming arguments and preventing OpenAI `tool_calls` chunks from repeating the `id` field. + +## [3.1.9] โ€” 2026-03-28 + +### โœจ New Features + +- **Schema Coercion** โ€” Auto-coerce string-encoded numeric JSON Schema constraints (e.g. `"minimum": "1"`) to proper types, preventing 400 errors from Cursor, Cline, and other clients sending malformed tool schemas. +- **Tool Description Sanitization** โ€” Ensure tool descriptions are always strings; converts `null`, `undefined`, or numeric descriptions to empty strings before sending to providers. +- **Clear All Models Button** โ€” Added i18n translations for the "Clear All Models" provider action across all 30 languages. +- **Codex Auth Export** โ€” Added Codex `auth.json` export and apply-local buttons for seamless CLI integration. +- **Windsurf BYOK Notes** โ€” Added official limitation warnings to the Windsurf CLI tool card documenting BYOK constraints. + +### ๐Ÿ› Bug Fixes + +- **Fix #709** โ€” `system-info.mjs` no longer crashes when the output directory doesn't exist (added `mkdirSync` with recursive flag). +- **Fix #710** โ€” A2A `TaskManager` singleton now uses `globalThis` to prevent state leakage across Next.js API route recompilations in dev mode. E2E test suite updated to handle 401 gracefully. +- **Fix #711** โ€” Added provider-specific `max_tokens` cap enforcement for upstream requests. +- **Fix #605 / #592** โ€” Strip `proxy_` prefix from tool names in non-streaming Claude responses; fixed LongCat validation URL. +- **Call Logs Max Cap** โ€” Upgraded `getMaxCallLogs()` with caching layer, env var support (`CALL_LOGS_MAX`), and DB settings integration. + +### ๐Ÿงช Tests + +- Test suite expanded from 964 โ†’ 1027 tests (63 new tests) +- Added `schema-coercion.test.mjs` โ€” 9 tests for numeric field coercion and tool description sanitization +- Added `t40-opencode-cli-tools-integration.test.mjs` โ€” OpenCode/Windsurf CLI integration tests +- Enhanced feature-tests branch with comprehensive coverage tooling + +### ๐Ÿ“ New Files + +| File | Purpose | +| -------------------------------------------------------- | ----------------------------------------------------------- | +| `open-sse/translator/helpers/schemaCoercion.ts` | Schema coercion and tool description sanitization utilities | +| `tests/unit/schema-coercion.test.mjs` | Unit tests for schema coercion | +| `tests/unit/t40-opencode-cli-tools-integration.test.mjs` | CLI tool integration tests | +| `COVERAGE_PLAN.md` | Test coverage planning document | + +### ๐Ÿ› Bug Fixes + +- **Claude Prompt Caching Passthrough** โ€” Fixed cache_control markers being stripped in Claude passthrough mode (Claude โ†’ OmniRoute โ†’ Claude), which caused Claude Code users to deplete their Anthropic API quota 5-10x faster than direct connections. OmniRoute now preserves client's cache_control markers when sourceFormat and targetFormat are both Claude, ensuring prompt caching works correctly and dramatically reducing token consumption. + +## [3.1.8] - 2026-03-27 + +### ๐Ÿ› Bug Fixes & Features + +- **Platform Core:** Implemented global state handling for Hidden Models & Combos preventing them from cluttering the catalog or leaking into connected MCP agents (#681). +- **Stability:** Patched streaming crashes related to the native Antigravity provider integration failing due to unhandled undefined state arrays (#684). +- **Localization Sync:** Deployed a fully overhauled `i18n` synchronizer detecting missing nested JSON properties and retro-fitting 30 locales sequentially (#685).## [3.1.7] - 2026-03-27 + +### ๐Ÿ› Bug Fixes + +- **Streaming Stability:** Fixed `hasValuableContent` returning `undefined` for empty chunks in SSE streams (#676). +- **Tool Calling:** Fixed an issue in `sseParser.ts` where non-streaming Claude responses with multiple tool calls dropped the `id` of subsequent tool calls due to incorrect index-based deduplication (#671). + +--- + +## [3.1.6] โ€” 2026-03-27 + +### ๐Ÿ› Bug Fixes + +- **Claude Native Tool Name Restoration** โ€” Tool names like `TodoWrite` are no longer prefixed with `proxy_` in Claude passthrough responses (both streaming and non-streaming). Includes unit test coverage (PR #663 by @coobabm) +- **Clear All Models Alias Cleanup** โ€” "Clear All Models" button now also removes associated model aliases, preventing ghost models in the UI (PR #664 by @rdself) + +--- + +## [3.1.5] โ€” 2026-03-27 + +### ๐Ÿ› Bug Fixes + +- **Backoff Auto-Decay** โ€” Rate-limited accounts now auto-recover when their cooldown window expires, fixing a deadlock where high `backoffLevel` permanently deprioritized accounts (PR #657 by @brendandebeasi) + +### ๐ŸŒ i18n + +- **Chinese translation overhaul** โ€” Comprehensive rewrite of `zh-CN.json` with improved accuracy (PR #658 by @only4copilot) + +--- + +## [3.1.4] โ€” 2026-03-27 + +### ๐Ÿ› Bug Fixes + +- **Streaming Override Fix** โ€” Explicit `stream: true` in request body now takes priority over `Accept: application/json` header. Clients sending both will correctly receive SSE streaming responses (#656) + +### ๐ŸŒ i18n + +- **Czech string improvements** โ€” Refined terminology across `cs.json` (PR #655 by @zen0bit) + +--- + +## [3.1.3] โ€” 2026-03-26 + +### ๐ŸŒ i18n & Community + +- **~70 missing translation keys** added to `en.json` and 12 languages (PR #652 by @zen0bit) +- **Czech documentation updated** โ€” CLI-TOOLS, API_REFERENCE, VM_DEPLOYMENT guides (PR #652) +- **Translation validation scripts** โ€” `check_translations.py` and `validate_translation.py` for CI/QA (PR #651 by @zen0bit) + +--- + +## [3.1.2] โ€” 2026-03-26 + +### ๐Ÿ› Bug Fixes + +- **Critical: Tool Calling Regression** โ€” Fixed `proxy_Bash` errors by disabling the `proxy_` tool name prefix in the Claude passthrough path. Tools like `Bash`, `Read`, `Write` were being renamed to `proxy_Bash`, `proxy_Read`, etc., causing Claude to reject them (#618) +- **Kiro Account Ban Documentation** โ€” Documented as upstream AWS anti-fraud false positive, not an OmniRoute issue (#649) + +### ๐Ÿงช Tests + +- **936 tests, 0 failures** + +--- + +## [3.1.1] โ€” 2026-03-26 + +### โœจ New Features + +- **Vision Capability Metadata**: Added `capabilities.vision`, `input_modalities`, and `output_modalities` to `/v1/models` entries for vision-capable models (PR #646) +- **Gemini 3.1 Models**: Added `gemini-3.1-pro-preview` and `gemini-3.1-flash-lite-preview` to the Antigravity provider (#645) + +### ๐Ÿ› Bug Fixes + +- **Ollama Cloud 401 Error**: Fixed incorrect API base URL โ€” changed from `api.ollama.com` to official `ollama.com/v1/chat/completions` (#643) +- **Expired Token Retry**: Added bounded retry with exponential backoff (5โ†’10โ†’20 min) for expired OAuth connections instead of permanently skipping them (PR #647) + +### ๐Ÿงช Tests + +- **936 tests, 0 failures** + +--- + +## [3.1.0] โ€” 2026-03-26 + +### โœจ New Features + +- **GitHub Issue Templates**: Added standardized bug report, feature request, and config/proxy issue templates (#641) +- **Clear All Models**: Added a "Clear All Models" button to the provider detail page with i18n support in 29 languages (#634) + +### ๐Ÿ› Bug Fixes + +- **Locale Conflict (`in.json`)**: Renamed the Hindi locale file from `in.json` (Indonesian ISO code) to `hi.json` to fix translation conflicts in Weblate (#642) +- **Codex Empty Tool Names**: Moved tool name sanitization before the native Codex passthrough, fixing 400 errors from upstream providers when tools had empty names (#637) +- **Streaming Newline Artifacts**: Added `collapseExcessiveNewlines` to the response sanitizer, collapsing runs of 3+ consecutive newlines from thinking models into a standard double newline (#638) +- **Claude Reasoning Effort**: Converted OpenAI `reasoning_effort` param to Claude's native `thinking` budget block across all request paths, including automatic `max_tokens` adjustment (#627) +- **Qwen Token Refresh**: Implemented proactive pre-expiry OAuth token refreshes (5-minute buffer) to prevent requests from failing when using short-lived tokens (#631) + +### ๐Ÿงช Tests + +- **936 tests, 0 failures** (+10 tests since 3.0.9) + +--- + +## [3.0.9] โ€” 2026-03-26 + +### ๐Ÿ› Bug Fixes + +- **NaN tokens in Claude Code / client responses (#617):** + - `sanitizeUsage()` now cross-maps `input_tokens`โ†’`prompt_tokens` and `output_tokens`โ†’`completion_tokens` before the whitelist filter, fixing responses showing NaN/0 token counts when providers return Claude-style usage field names + +### Bezpeฤnost + +- Updated `yaml` package to fix stack overflow vulnerability (GHSA-48c2-rrv3-qjmp) + +### ๐Ÿ“‹ Issue Triage + +- Closed #613 (Codestral โ€” resolved with Custom Provider workaround) +- Commented on #615 (OpenCode dual-endpoint โ€” workaround provided, tracked as feature request) +- Commented on #618 (tool call visibility โ€” requesting v3.0.9 test) +- Commented on #627 (effort level โ€” already supported) + +--- + +## [3.0.8] โ€” 2026-03-25 + +### ๐Ÿ› Bug Fixes + +- **Translation Failures for OpenAI-format Providers in Claude CLI (#632):** + - Handle `reasoning_details[]` array format from StepFun/OpenRouter โ€” converts to `reasoning_content` + - Handle `reasoning` field alias from some providers โ†’ normalized to `reasoning_content` + - Cross-map usage field names: `input_tokens`โ†”`prompt_tokens`, `output_tokens`โ†”`completion_tokens` in `filterUsageForFormat` + - Fix `extractUsage` to accept both `input_tokens`/`output_tokens` and `prompt_tokens`/`completion_tokens` as valid usage fields + - Applied to both streaming (`sanitizeStreamingChunk`, `openai-to-claude.ts` translator) and non-streaming (`sanitizeMessage`) paths + +--- + +## [3.0.7] โ€” 2026-03-25 + +### ๐Ÿ› Bug Fixes + +- **Antigravity Token Refresh:** Fixed `client_secret is missing` error for npm-installed users โ€” the `clientSecretDefault` was empty in providerRegistry, causing Google to reject token refresh requests (#588) +- **OpenCode Zen Models:** Added `modelsUrl` to the OpenCode Zen registry entry so "Import from /models" works correctly (#612) +- **Streaming Artifacts:** Fixed excessive newlines left in responses after thinking-tag signature stripping (#626) +- **Proxy Fallback:** Added automatic retry without proxy when SOCKS5 relay fails +- **Proxy Test:** Test endpoint now resolves real credentials from DB via proxyId + +### โœจ New Features + +- **Playground Account/Key Selector:** Persistent, always-visible dropdown to select specific provider accounts/keys for testing โ€” fetches all connections at startup and filters by selected provider +- **CLI Tools Dynamic Models:** Model selection now dynamically fetches from `/v1/models` API โ€” providers like Kiro now show their full model catalog +- **Antigravity Model List:** Updated with Claude Sonnet 4.5, Claude Sonnet 4, GPT 5, GPT 5 Mini; enabled `passthroughModels` for dynamic model access (#628) + +### ๐Ÿ”ง Maintenance + +- Merged PR #625 โ€” Provider Limits light mode background fix + +--- + +## [3.0.6] โ€” 2026-03-25 + +### ๐Ÿ› Bug Fixes + +- **Limits/Proxy:** Fixed Codex limit fetching for accounts behind SOCKS5 proxies โ€” token refresh now runs inside proxy context +- **CI:** Fixed integration test `v1/models` assertion failure in CI environments without provider connections +- **Settings:** Proxy test button now shows success/failure results immediately (previously hidden behind health data) + +### โœจ New Features + +- **Playground:** Added Account selector dropdown โ€” test specific connections individually when a provider has multiple accounts + +### ๐Ÿ”ง Maintenance + +- Merged PR #623 โ€” LongCat API base URL path correction + +--- + +## [3.0.5] โ€” 2026-03-25 + +### โœจ New Features + +- **Limits UI:** Added tag grouping feature to the connections dashboard to improve visual organization for accounts with custom tags. + +--- + +## [3.0.4] โ€” 2026-03-25 + +### ๐Ÿ› Bug Fixes + +- **Streaming:** Fixed `TextDecoder` state corruption inside combo `sanitize` TransformStream which caused SSE garbled output matching multibyte characters (PR #614) +- **Providers UI:** Safely render HTML tags inside provider connection error tooltips using `dangerouslySetInnerHTML` +- **Proxy Settings:** Added missing `username` and `password` payload body properties allowing authenticated proxies to be successfully verified from the Dashboard. +- **Provider API:** Bound soft exception returns to `getCodexUsage` preventing API HTTP 500 failures when token fetch fails + +--- + +## [3.0.3] โ€” 2026-03-25 + +### โœจ New Features + +- **Auto-Sync Models:** Added a UI toggle and `sync-models` endpoint to automatically synchronise model lists per provider using a scheduled interval scheduler (PR #597) + +### ๐Ÿ› Bug Fixes + +- **Timeouts:** Elevated default proxies `FETCH_TIMEOUT_MS` and `STREAM_IDLE_TIMEOUT_MS` to 10 minutes to properly support deep reasoning models (like o1) without aborting requests (Fixes #609) +- **CLI Tool Detection:** Improved cross-platform detection handling NVM paths, Windows `PATHEXT` (preventing `.cmd` wrappers issue), and custom NPM prefixes (PR #598) +- **Streaming Logs:** Implemented `tool_calls` delta accumulation in streaming response logs so function calls are tracked and persisted accurately in DB (PR #603) +- **Model Catalog:** Removed auth exemption, properly hiding `comfyui` and `sdwebui` models when no provider is explicitly configured (PR #599) + +### ๐ŸŒ Translations + +- **cs:** Improved Czech translation strings across the app (PR #601) + +## [3.0.2] โ€” 2026-03-25 + +### ๐Ÿš€ Enhancements & Features + +#### feat(ui): Connection Tag Grouping + +- Added a Tag/Group field to `EditConnectionModal` (stored in `providerSpecificData.tag`) without requiring DB schema migrations. +- Connections in the provider view now dynamically group by tag with visual dividers. +- Untagged connections appear first without a header, followed by tagged groups in alphabetical order. +- The tag grouping automatically applies to the Codex/Copilot/Antigravity Limits section since toggles exist inside connection rows. + +### ๐Ÿ› Bug Fixes + +#### fix(ui): Proxy Management UI Stabilization + +- **Missing badges on connection cards:** Fixed by using `resolveProxyForConnection()` rather than static mapping. +- **Test Connection disabled in saved mode:** Enabled the Test button by resolving proxy config from the saved list. +- **Config Modal freezing:** Added `onClose()` calls after save/clear to prevent the UI from freezing. +- **Double usage counting:** `ProxyRegistryManager` now loads usage eagerly on mount with deduplication by `scope` + `scopeId`. Usage counts were replaced with a Test button displaying IP/latency inline. + +#### fix(translator): `function_call` prefix stripping + +- Repaired an incomplete fix from PR #607 where only `tool_use` blocks stripped Claude's `proxy_` tool prefix. Now, clients using the OpenAI Responses API format will also correctly receive tool tools without the `proxy_` prefix. + +--- + +## [3.0.1] โ€” 2026-03-25 + +### ๐Ÿ”ง Hotfix Patch โ€” Critical Bug Fixes + +Three critical regressions reported by users after the v3.0.0 launch have been resolved. + +#### fix(translator): strip `proxy_` prefix in non-streaming Claude responses (#605) + +The `proxy_` prefix added by Claude OAuth was only stripped from **streaming** responses. In **non-streaming** mode, `translateNonStreamingResponse` had no access to the `toolNameMap`, causing clients to receive mangled tool names like `proxy_read_file` instead of `read_file`. + +**Fix:** Added optional `toolNameMap` parameter to `translateNonStreamingResponse` and applied prefix stripping in the Claude `tool_use` block handler. `chatCore.ts` now passes the map through. + +#### fix(validation): add LongCat specialty validator to skip /models probe (#592) + +LongCat AI does not expose `GET /v1/models`. The generic `validateOpenAICompatibleProvider` validator fell through to a chat-completions fallback only if `validationModelId` was set, which LongCat doesn't configure. This caused provider validation to fail with a misleading error on add/save. + +**Fix:** Added `longcat` to the specialty validators map, probing `/chat/completions` directly and treating any non-auth response as a pass. + +#### fix(translator): normalize object tool schemas for Anthropic (#595) + +MCP tools (e.g. `pencil`, `computer_use`) forward tool definitions with `{type:"object"}` but without a `properties` field. Anthropic's API rejects these with: `object schema missing properties`. + +**Fix:** In `openai-to-claude.ts`, inject `properties: {}` as a safe default when `type` is `"object"` and `properties` is absent. + +--- + +### ๐Ÿ”€ Community PRs Merged (2) + +| PR | Author | Summary | +| -------- | ------- | -------------------------------------------------------------------------- | +| **#589** | @flobo3 | docs(i18n): fix Russian translation for Playground and Testbed | +| **#591** | @rdself | fix(ui): improve Provider Limits light mode contrast and plan tier display | + +--- + +### โœ… Issues Resolved + +`#592` `#595` `#605` + +--- + +### ๐Ÿงช Tests + +- **926 tests, 0 failures** (unchanged from v3.0.0) + +--- + +## [3.0.0] โ€” 2026-03-24 + +### ๐ŸŽ‰ OmniRoute v3.0.0 โ€” The Free AI Gateway, Now with 67+ Providers + +> **The biggest release ever.** From 36 providers in v2.9.5 to **67+ providers** in v3.0.0 โ€” with MCP Server, A2A Protocol, auto-combo engine, Provider Icons, Registered Keys API, 926 tests, and contributions from **12 community members** across **10 merged PRs**. +> +> Consolidated from v3.0.0-rc.1 through rc.17 (17 release candidates over 3 days of intense development). + +--- + +### ๐Ÿ†• New Providers (+31 since v2.9.5) + +| Provider | Alias | Tier | Notes | +| ----------------------------- | --------------- | ----------- | --------------------------------------------------------------------------- | +| **OpenCode Zen** | `opencode-zen` | Free | 3 models via `opencode.ai/zen/v1` (PR #530 by @kang-heewon) | +| **OpenCode Go** | `opencode-go` | Paid | 4 models via `opencode.ai/zen/go/v1` (PR #530 by @kang-heewon) | +| **LongCat AI** | `lc` | Free | 50M tokens/day (Flash-Lite) + 500K/day (Chat/Thinking) during public beta | +| **Pollinations AI** | `pol` | Free | No API key needed โ€” GPT-5, Claude, Gemini, DeepSeek V3, Llama 4 (1 req/15s) | +| **Cloudflare Workers AI** | `cf` | Free | 10K Neurons/day โ€” ~150 LLM responses or 500s Whisper audio, edge inference | +| **Scaleway AI** | `scw` | Free | 1M free tokens for new accounts โ€” EU/GDPR compliant (Paris) | +| **AI/ML API** | `aiml` | Free | $0.025/day free credits โ€” 200+ models via single endpoint | +| **Puter AI** | `pu` | Free | 500+ models (GPT-5, Claude Opus 4, Gemini 3 Pro, Grok 4, DeepSeek V3) | +| **Alibaba Cloud (DashScope)** | `ali` | Paid | International + China endpoints via `alicode`/`alicode-intl` | +| **Alibaba Coding Plan** | `bcp` | Paid | Alibaba Model Studio with Anthropic-compatible API | +| **Kimi Coding (API Key)** | `kmca` | Paid | Dedicated API-key-based Kimi access (separate from OAuth) | +| **MiniMax Coding** | `minimax` | Paid | International endpoint | +| **MiniMax (China)** | `minimax-cn` | Paid | China-specific endpoint | +| **Z.AI (GLM-5)** | `zai` | Paid | Zhipu AI next-gen GLM models | +| **Vertex AI** | `vertex` | Paid | Google Cloud โ€” Service Account JSON or OAuth access_token | +| **Ollama Cloud** | `ollamacloud` | Paid | Ollama's hosted API service | +| **Synthetic** | `synthetic` | Paid | Passthrough models gateway | +| **Kilo Gateway** | `kg` | Paid | Passthrough models gateway | +| **Perplexity Search** | `pplx-search` | Paid | Dedicated search-grounded endpoint | +| **Serper Search** | `serper-search` | Paid | Web search API integration | +| **Brave Search** | `brave-search` | Paid | Brave Search API integration | +| **Exa Search** | `exa-search` | Paid | Neural search API integration | +| **Tavily Search** | `tavily-search` | Paid | AI search API integration | +| **NanoBanana** | `nb` | Paid | Image generation API | +| **ElevenLabs** | `el` | Paid | Text-to-speech voice synthesis | +| **Cartesia** | `cartesia` | Paid | Ultra-fast TTS voice synthesis | +| **PlayHT** | `playht` | Paid | Voice cloning and TTS | +| **Inworld** | `inworld` | Paid | AI character voice chat | +| **SD WebUI** | `sdwebui` | Self-hosted | Stable Diffusion local image generation | +| **ComfyUI** | `comfyui` | Self-hosted | ComfyUI local workflow node-based generation | +| **GLM Coding** | `glm` | Paid | BigModel/Zhipu coding-specific endpoint | + +**Total: 67+ providers** (4 Free, 8 OAuth, 55 API Key) + unlimited OpenAI/Anthropic-Compatible custom providers. + +--- + +### โœจ Major Features + +#### ๐Ÿ”‘ Registered Keys Provisioning API (#464) + +Auto-generate and issue OmniRoute API keys programmatically with per-provider and per-account quota enforcement. + +| Endpoint | Method | Description | +| ------------------------------- | ------------ | ------------------------------------------------ | +| `/api/v1/registered-keys` | `POST` | Issue a new key โ€” raw key returned **once only** | +| `/api/v1/registered-keys` | `GET` | List registered keys (masked) | +| `/api/v1/registered-keys/{id}` | `GET/DELETE` | Get metadata / Revoke | +| `/api/v1/quotas/check` | `GET` | Pre-validate quota before issuing | +| `/api/v1/providers/{id}/limits` | `GET/PUT` | Configure per-provider issuance limits | +| `/api/v1/accounts/{id}/limits` | `GET/PUT` | Configure per-account issuance limits | +| `/api/v1/issues/report` | `POST` | Report quota events to GitHub Issues | + +**Security:** Keys stored as SHA-256 hashes. Raw key shown once on creation, never retrievable again. + +#### ๐ŸŽจ Provider Icons via @lobehub/icons (#529) + +130+ provider logos using `@lobehub/icons` React components (SVG). Fallback chain: **Lobehub SVG โ†’ existing PNG โ†’ generic icon**. Applied across Dashboard, Providers, and Agents pages with standardized `ProviderIcon` component. + +#### ๐Ÿ”„ Model Auto-Sync Scheduler (#488) + +Auto-refreshes model lists for connected providers every **24 hours**. Runs on server startup. Configurable via `MODEL_SYNC_INTERVAL_HOURS`. + +#### ๐Ÿ”€ Per-Model Combo Routing (#563) + +Map model name patterns (glob) to specific combos for automatic routing: + +- `claude-sonnet*` โ†’ code-combo, `gpt-4o*` โ†’ openai-combo, `gemini-*` โ†’ google-combo +- New `model_combo_mappings` table with glob-to-regex matching +- Dashboard UI section: "Model Routing Rules" with inline add/edit/toggle/delete + +#### ๐Ÿงญ API Endpoints Dashboard + +Interactive catalog, webhooks management, OpenAPI viewer โ€” all in one tabbed page at `/dashboard/endpoint`. + +#### ๐Ÿ” Web Search Providers + +5 new search provider integrations: **Perplexity Search**, **Serper**, **Brave Search**, **Exa**, **Tavily** โ€” enabling grounded AI responses with real-time web data. + +#### ๐Ÿ“Š Search Analytics + +New tab in `/dashboard/analytics` โ€” provider breakdown, cache hit rate, cost tracking. API: `GET /api/v1/search/analytics`. + +#### ๐Ÿ›ก๏ธ Per-API-Key Rate Limits (#452) + +`max_requests_per_day` and `max_requests_per_minute` columns with in-memory sliding-window enforcement returning HTTP 429. + +#### ๐ŸŽต Media Playground + +Full media generation playground at `/dashboard/media`: Image Generation, Video, Music, Audio Transcription (2GB upload limit), and Text-to-Speech. + +--- + +### ๐Ÿ”’ Security & CI/CD + +- **CodeQL remediation** โ€” Fixed 10+ alerts: 6 polynomial-redos, 1 insecure-randomness (`Math.random()` โ†’ `crypto.randomUUID()`), 1 shell-command-injection +- **Route validation** โ€” Zod schemas + `validateBody()` on **176/176 API routes** โ€” CI enforced +- **CVE fix** โ€” dompurify XSS vulnerability (GHSA-v2wj-7wpq-c8vv) resolved via npm overrides +- **Flatted** โ€” Bumped 3.3.3 โ†’ 3.4.2 (CWE-1321 prototype pollution) +- **Docker** โ€” Upgraded `docker/setup-buildx-action` v3 โ†’ v4 + +--- + +### ๐Ÿ› Bug Fixes (40+) + +#### OAuth & Auth + +- **#537** โ€” Gemini CLI OAuth: clear actionable error when `GEMINI_OAUTH_CLIENT_SECRET` missing in Docker +- **#549** โ€” CLI settings routes now resolve real API key from `keyId` (not masked strings) +- **#574** โ€” Login no longer freezes after skipping wizard password setup +- **#506** โ€” Cross-platform `machineId` rewritten (Windows REG.exe โ†’ macOS ioreg โ†’ Linux โ†’ hostname fallback) + +#### Providers & Routing + +- **#536** โ€” LongCat AI: fixed `baseUrl` and `authHeader` +- **#535** โ€” Pinned model override: `body.model` correctly set to `pinnedModel` +- **#570** โ€” Unprefixed Claude models now resolve to Anthropic provider +- **#585** โ€” `` internal tags no longer leak to clients in SSE streaming +- **#493** โ€” Custom provider model naming no longer mangled by prefix stripping +- **#490** โ€” Streaming + context cache protection via `TransformStream` injection +- **#511** โ€” `` tag injected into first content chunk (not after `[DONE]`) + +#### CLI & Tools + +- **#527** โ€” Claude Code + Codex loop: `tool_result` blocks now converted to text +- **#524** โ€” OpenCode config saved correctly (XDG_CONFIG_HOME, TOML format) +- **#522** โ€” API Manager: removed misleading "Copy masked key" button +- **#546** โ€” `--version` returning `unknown` on Windows (PR by @k0valik) +- **#544** โ€” Secure CLI tool detection via known installation paths (PR by @k0valik) +- **#510** โ€” Windows MSYS2/Git-Bash paths normalized automatically +- **#492** โ€” CLI detects `mise`/`nvm`-managed Node when `app/server.js` missing + +#### Streaming & SSE + +- **PR #587** โ€” Revert `resolveDataDir` import in responsesTransformer for Cloudflare Workers compat (@k0valik) +- **PR #495** โ€” Bottleneck 429 infinite wait: drop waiting jobs on rate limit (@xandr0s) +- **#483** โ€” Stop trailing `data: null` after `[DONE]` signal +- **#473** โ€” Zombie SSE streams: timeout reduced 300s โ†’ 120s for faster fallback + +#### Media & Transcription + +- **Transcription** โ€” Deepgram `video/mp4` โ†’ `audio/mp4` MIME mapping, auto language detection, punctuation +- **TTS** โ€” `[object Object]` error display fixed for ElevenLabs-style nested errors +- **Upload limits** โ€” Media transcription increased to 2GB (nginx `client_max_body_size 2g` + `maxDuration=300`) + +--- + +### ๐Ÿ”ง Infrastructure & Improvements + +#### Sub2api Gap Analysis (T01โ€“T15 + T23โ€“T42) + +- **T01** โ€” `requested_model` column in call logs (migration 009) +- **T02** โ€” Strip empty text blocks from nested `tool_result.content` +- **T03** โ€” Parse `x-codex-5h-*` / `x-codex-7d-*` quota headers +- **T04** โ€” `X-Session-Id` header for external sticky routing +- **T05** โ€” Rate-limit DB persistence with dedicated API +- **T06** โ€” Account deactivated โ†’ permanent block (1-year cooldown) +- **T07** โ€” X-Forwarded-For IP validation (`extractClientIp()`) +- **T08** โ€” Per-API-key session limits with sliding-window enforcement +- **T09** โ€” Codex vs Spark rate-limit scopes (separate pools) +- **T10** โ€” Credits exhausted โ†’ distinct 1h cooldown fallback +- **T11** โ€” `max` reasoning effort โ†’ 131072 budget tokens +- **T12** โ€” MiniMax M2.7 pricing entries +- **T13** โ€” Stale quota display fix (reset window awareness) +- **T14** โ€” Proxy fast-fail TCP check (โ‰ค2s, cached 30s) +- **T15** โ€” Array content normalization for Anthropic +- **T23** โ€” Intelligent quota reset fallback (header extraction) +- **T24** โ€” `503` cooldown + `406` mapping +- **T25** โ€” Provider validation fallback +- **T29** โ€” Vertex AI Service Account JWT auth +- **T33** โ€” Thinking level to budget conversion +- **T36** โ€” `403` vs `429` error classification +- **T38** โ€” Centralized model specifications (`modelSpecs.ts`) +- **T39** โ€” Endpoint fallback for `fetchAvailableModels` +- **T41** โ€” Background task auto-redirect to flash models +- **T42** โ€” Image generation aspect ratio mapping + +#### Other Improvements + +- **Per-model upstream custom headers** โ€” via configuration UI (PR #575 by @zhangqiang8vip) +- **Model context length** โ€” configurable in model metadata (PR #578 by @hijak) +- **Model prefix stripping** โ€” option to remove provider prefix from model names (PR #582 by @jay77721) +- **Gemini CLI deprecation** โ€” marked deprecated with Google OAuth restriction warning +- **YAML parser** โ€” replaced custom parser with `js-yaml` for correct OpenAPI spec parsing +- **ZWS v5** โ€” HMR leak fix (485 DB connections โ†’ 1, memory 2.4GB โ†’ 195MB) +- **Log export** โ€” New JSON export button on dashboard with time range dropdown +- **Update notification banner** โ€” dashboard homepage shows when new versions are available + +--- + +### ๐ŸŒ i18n & Documentation + +- **30 languages** at 100% parity โ€” 2,788 missing keys synced +- **Czech** โ€” Full translation: 22 docs, 2,606 UI strings (PR by @zen0bit) +- **Chinese (zh-CN)** โ€” Complete retranslation (PR by @only4copilot) +- **VM Deployment Guide** โ€” Translated to English as source document +- **API Reference** โ€” Added `/v1/embeddings` and `/v1/audio/speech` endpoints +- **Provider count** โ€” Updated from 36+/40+/44+ to **67+** across README and all 30 i18n READMEs + +--- + +### ๐Ÿ”€ Community PRs Merged (10) + +| PR | Author | Summary | +| -------- | --------------- | -------------------------------------------------------------------- | +| **#587** | @k0valik | fix(sse): revert resolveDataDir import for Cloudflare Workers compat | +| **#582** | @jay77721 | feat(proxy): model name prefix stripping option | +| **#581** | @jay77721 | fix(npm): link electron-release to npm-publish workflow | +| **#578** | @hijak | feat: configurable context length in model metadata | +| **#575** | @zhangqiang8vip | feat: per-model upstream headers, compat PATCH, chat alignment | +| **#562** | @coobabm | fix: MCP session management, Claude passthrough, detectFormat | +| **#561** | @zen0bit | fix(i18n): Czech translation corrections | +| **#555** | @k0valik | fix(sse): centralized `resolveDataDir()` for path resolution | +| **#546** | @k0valik | fix(cli): `--version` returning `unknown` on Windows | +| **#544** | @k0valik | fix(cli): secure CLI tool detection via installation paths | +| **#542** | @rdself | fix(ui): light mode contrast CSS theme variables | +| **#530** | @kang-heewon | feat: OpenCode Zen + Go providers with `OpencodeExecutor` | +| **#512** | @zhangqiang8vip | feat: per-protocol model compatibility (`compatByProtocol`) | +| **#497** | @zhangqiang8vip | fix: dev-mode HMR resource leaks (ZWS v5) | +| **#495** | @xandr0s | fix: Bottleneck 429 infinite wait (drop waiting jobs) | +| **#494** | @zhangqiang8vip | feat: MiniMax developerโ†’system role fix | +| **#480** | @prakersh | fix: stream flush usage extraction | +| **#479** | @prakersh | feat: Codex 5.3/5.4 and Anthropic pricing entries | +| **#475** | @only4copilot | feat(i18n): improved Chinese translation | + +**Thank you to all contributors!** ๐Ÿ™ + +--- + +### ๐Ÿ“‹ Issues Resolved (50+) + +`#452` `#458` `#462` `#464` `#466` `#473` `#474` `#481` `#483` `#487` `#488` `#489` `#490` `#491` `#492` `#493` `#506` `#508` `#509` `#510` `#511` `#513` `#520` `#521` `#522` `#524` `#525` `#527` `#529` `#531` `#532` `#535` `#536` `#537` `#541` `#546` `#549` `#563` `#570` `#574` `#585` + +--- + +### ๐Ÿงช Tests + +- **926 tests, 0 failures** (up from 821 in v2.9.5) +- +105 new tests covering: model-combo mappings, registered keys, OpencodeExecutor, Bailian provider, route validation, error classification, aspect ratio mapping, and more + +--- + +### ๐Ÿ“ฆ Database Migrations + +| Migration | Description | +| --------- | --------------------------------------------------------------------- | +| **008** | `registered_keys`, `provider_key_limits`, `account_key_limits` tables | +| **009** | `requested_model` column in `call_logs` | +| **010** | `model_combo_mappings` table for per-model combo routing | + +--- + +### โฌ†๏ธ Upgrading from v2.9.5 + +```bash +# npm +npm install -g omniroute@3.0.0 + +# Docker +docker pull diegosouzapw/omniroute:3.0.0 + +# Migrations run automatically on first startup +``` + +> **Breaking changes:** None. All existing configurations, combos, and API keys are preserved. +> Database migrations 008-010 run automatically on startup. + +--- + +## [3.0.0-rc.17] โ€” 2026-03-24 + +### ๐Ÿ”’ Security & CI/CD + +- **CodeQL remediation** โ€” Fixed 10+ alerts: + - 6 polynomial-redos in `provider.ts` / `chatCore.ts` (replaced `(?:^|/)` alternation patterns with segment-based matching) + - 1 insecure-randomness in `acp/manager.ts` (`Math.random()` โ†’ `crypto.randomUUID()`) + - 1 shell-command-injection in `prepublish.mjs` (`JSON.stringify()` path escaping) +- **Route validation** โ€” Added Zod schemas + `validateBody()` to 5 routes missing validation: + - `model-combo-mappings` (POST, PUT), `webhooks` (POST, PUT), `openapi/try` (POST) + - CI `check:route-validation:t06` now passes: **176/176 routes validated** + +### ๐Ÿ› Bug Fixes + +- **#585** โ€” `` internal tags no longer leak to clients in SSE responses. Added outbound sanitization `TransformStream` in `combo.ts` + +### โš™๏ธ Infrastructure + +- **Docker** โ€” Upgraded `docker/setup-buildx-action` from v3 โ†’ v4 (Node.js 20 deprecation fix) +- **CI cleanup** โ€” Deleted 150+ failed/cancelled workflow runs + +### ๐Ÿงช Tests + +- Test suite: **926 tests, 0 failures** (+3 new) + +--- + +## [3.0.0-rc.16] โ€” 2026-03-24 + +### โœจ New Features + +- Increased media transcription limits +- Added Model Context Length to registry metadata +- Added per-model upstream custom headers via configuration UI +- Fixed multiple bugs, Zod valiadation for patches, and resolved various community issues. + +## [3.0.0-rc.15] โ€” 2026-03-24 + +### โœจ New Features + +- **#563** โ€” Per-model Combo Routing: map model name patterns (glob) to specific combos for automatic routing + - New `model_combo_mappings` table (migration 010) with pattern, combo_id, priority, enabled + - `resolveComboForModel()` DB function with glob-to-regex matching (case-insensitive, `*` and `?` wildcards) + - `getComboForModel()` in `model.ts`: augments `getCombo()` with model-pattern fallback + - `chat.ts`: routing decision now checks model-combo mappings before single-model handling + - API: `GET/POST /api/model-combo-mappings`, `GET/PUT/DELETE /api/model-combo-mappings/:id` + - Dashboard: "Model Routing Rules" section added to Combos page with inline add/edit/toggle/delete + - Examples: `claude-sonnet*` โ†’ code-combo, `gpt-4o*` โ†’ openai-combo, `gemini-*` โ†’ google-combo + +### ๐ŸŒ i18n + +- **Full i18n Sync**: 2,788 missing keys added across 30 language files โ€” all languages now at 100% parity with `en.json` +- **Agents page i18n**: OpenCode Integration section fully internationalized (title, description, scanning, download labels) +- **6 new keys** added to `agents` namespace for OpenCode section + +### ๐ŸŽจ UI/UX + +- **Provider Icons**: 16 missing provider icons added (3 copied, 2 downloaded, 11 SVG created) +- **SVG fallback**: `ProviderIcon` component updated with 4-tier strategy: Lobehub โ†’ PNG โ†’ SVG โ†’ Generic icon +- **Agents fingerprinting**: Synced with CLI tools โ€” added droid, openclaw, copilot, opencode to fingerprint list (14 total) + +### Bezpeฤnost + +- **CVE fix**: Resolved dompurify XSS vulnerability (GHSA-v2wj-7wpq-c8vv) via npm overrides forcing `dompurify@^3.3.2` +- `npm audit` now reports **0 vulnerabilities** + +### ๐Ÿงช Tests + +- Test suite: **923 tests, 0 failures** (+15 new model-combo mapping tests) + +--- + +## [3.0.0-rc.14] โ€” 2026-03-23 + +### ๐Ÿ”€ Community PRs Merged + +| PR | Author | Summary | +| -------- | -------- | -------------------------------------------------------------------------------------------- | +| **#562** | @coobabm | fix(ux): MCP session management, Claude passthrough normalization, OAuth modal, detectFormat | +| **#561** | @zen0bit | fix(i18n): Czech translation corrections โ€” HTTP method names and documentation updates | + +### ๐Ÿงช Tests + +- Test suite: **908 tests, 0 failures** + +--- + +## [3.0.0-rc.13] โ€” 2026-03-23 + +### ๐Ÿ”ง Bug Fixes + +- **config:** resolve real API key from `keyId` in CLI settings routes (`codex-settings`, `droid-settings`, `kilo-settings`) to prevent writing masked strings (#549) + +--- + +## [3.0.0-rc.12] โ€” 2026-03-23 + +### ๐Ÿ”€ Community PRs Merged + +| PR | Author | Summary | +| -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **#546** | @k0valik | fix(cli): `--version` returning `unknown` on Windows โ€” use `JSON.parse(readFileSync)` instead of ESM import | +| **#555** | @k0valik | fix(sse): centralized `resolveDataDir()` for path resolution in credentials, autoCombo, responses logger, and request logger | +| **#544** | @k0valik | fix(cli): secure CLI tool detection via known installation paths (8 tools) with symlink validation, file-type checks, size bounds, minimal env in healthcheck | +| **#542** | @rdself | fix(ui): improve light mode contrast โ€” add missing CSS theme variables (`bg-primary`, `bg-subtle`, `text-primary`) and fix dark-only colors in log detail | + +### ๐Ÿ”ง Bug Fixes + +- **TDZ fix in `cliRuntime.ts`** โ€” `validateEnvPath` was used before initialization at module startup by `getExpectedParentPaths()`. Reordered declarations to fix `ReferenceError`. +- **Build fixes** โ€” Added `pino` and `pino-pretty` to `serverExternalPackages` to prevent Turbopack from breaking Pino's internal worker loading. + +### ๐Ÿงช Tests + +- Test suite: **905 tests, 0 failures** + +--- + +## [3.0.0-rc.10] โ€” 2026-03-23 + +### ๐Ÿ”ง Bug Fixes + +- **#509 / #508** โ€” Electron build regression: downgraded Next.js from `16.1.x` to `16.0.10` to eliminate Turbopack module-hashing instability that caused blank screens in the Electron desktop bundle. +- **Unit test fixes** โ€” Corrected two stale test assertions (`nanobanana-image-handler` aspect ratio/resolution, `thinking-budget` Gemini `thinkingConfig` field mapping) that had drifted after recent implementation changes. +- **#541** โ€” Responded to user feedback about installation complexity; no code changes required. + +--- + +## [3.0.0-rc.9] โ€” 2026-03-23 + +### โœจ New Features + +- **T29** โ€” Vertex AI SA JSON Executor: implemented using the `jose` library to handle JWT/Service Account auth, along with configurable regions in the UI and automatic partner model URL building. +- **T42** โ€” Image generation aspect ratio mapping: created `sizeMapper` logic for generic OpenAI formats (`size`), added native `imagen3` handling, and updated NanoBanana endpoints to utilize mapped aspect ratios automatically. +- **T38** โ€” Centralized model specifications: `modelSpecs.ts` created for limits and parameters per model. + +### ๐Ÿ”ง Improvements + +- **T40** โ€” OpenCode CLI tools integration: native `opencode-zen` and `opencode-go` integration completed in earlier PR. + +--- + +## [3.0.0-rc.8] โ€” 2026-03-23 + +### ๐Ÿ”ง Bug Fixes & Improvements (Fallback, Quota & Budget) + +- **T24** โ€” `503` cooldown await fix + `406` mapping: mapped `406 Not Acceptable` to `503 Service Unavailable` with proper cooldown intervals. +- **T25** โ€” Provider validation fallback: graceful fallback to standard validation models when a specific `validationModelId` is not present. +- **T36** โ€” `403` vs `429` provider handling refinement: extracted into `errorClassifier.ts` to properly segregate hard permissions failures (`403`) from rate limits (`429`). +- **T39** โ€” Endpoint Fallback for `fetchAvailableModels`: implemented a tri-tier mechanism (`/models` -> `/v1/models` -> local generic catalog) + `list_models_catalog` MCP tool updates to reflect `source` and `warning`. +- **T33** โ€” Thinking level to budget conversion: translates qualitative thinking levels into precise budget allocations. +- **T41** โ€” Background task auto redirect: routes heavy background evaluation tasks to flash/efficient models automatically. +- **T23** โ€” Intelligent quota reset fallback: accurately extracts `x-ratelimit-reset` / `retry-after` header values or maps static cooldowns. + +--- + +## [3.0.0-rc.7] โ€” 2026-03-23 _(What's New vs v2.9.5 โ€” will be released as v3.0.0)_ + +> **Upgrade from v2.9.5:** 16 issues resolved ยท 2 community PRs merged ยท 2 new providers ยท 7 new API endpoints ยท 3 new features ยท DB migration 008+009 ยท 832 tests passing ยท 15 sub2api gap improvements (T01โ€“T15 complete). + +### ๐Ÿ†• New Providers + +| Provider | Alias | Tier | Notes | +| ---------------- | -------------- | ---- | -------------------------------------------------------------- | +| **OpenCode Zen** | `opencode-zen` | Free | 3 models via `opencode.ai/zen/v1` (PR #530 by @kang-heewon) | +| **OpenCode Go** | `opencode-go` | Paid | 4 models via `opencode.ai/zen/go/v1` (PR #530 by @kang-heewon) | + +Both providers use the new `OpencodeExecutor` with multi-format routing (`/chat/completions`, `/messages`, `/responses`, `/models/{model}:generateContent`). + +--- + +### โœจ New Features + +#### ๐Ÿ”‘ Registered Keys Provisioning API (#464) + +Auto-generate and issue OmniRoute API keys programmatically with per-provider and per-account quota enforcement. + +| Endpoint | Method | Description | +| ------------------------------------- | --------- | ------------------------------------------------ | +| `/api/v1/registered-keys` | `POST` | Issue a new key โ€” raw key returned **once only** | +| `/api/v1/registered-keys` | `GET` | List registered keys (masked) | +| `/api/v1/registered-keys/{id}` | `GET` | Get key metadata | +| `/api/v1/registered-keys/{id}` | `DELETE` | Revoke a key | +| `/api/v1/registered-keys/{id}/revoke` | `POST` | Revoke (for clients without DELETE support) | +| `/api/v1/quotas/check` | `GET` | Pre-validate quota before issuing | +| `/api/v1/providers/{id}/limits` | `GET/PUT` | Configure per-provider issuance limits | +| `/api/v1/accounts/{id}/limits` | `GET/PUT` | Configure per-account issuance limits | +| `/api/v1/issues/report` | `POST` | Report quota events to GitHub Issues | + +**DB โ€” Migration 008:** Three new tables: `registered_keys`, `provider_key_limits`, `account_key_limits`. +**Security:** Keys stored as SHA-256 hashes. Raw key shown once on creation, never retrievable again. +**Quota types:** `maxActiveKeys`, `dailyIssueLimit`, `hourlyIssueLimit` per provider and per account. +**Idempotency:** `idempotency_key` field prevents duplicate issuance. Returns `409 IDEMPOTENCY_CONFLICT` if key was already used. +**Budget per key:** `dailyBudget` / `hourlyBudget` โ€” limits how many requests a key can route per window. +**GitHub reporting:** Optional. Set `GITHUB_ISSUES_REPO` + `GITHUB_ISSUES_TOKEN` to auto-create GitHub issues on quota exceeded or issuance failures. + +#### ๐ŸŽจ Provider Icons โ€” @lobehub/icons (#529) + +All provider icons in the dashboard now use `@lobehub/icons` React components (130+ providers with SVG). +Fallback chain: **Lobehub SVG โ†’ existing `/providers/{id}.png` โ†’ generic icon**. Uses a proper React `ErrorBoundary` pattern. + +#### ๐Ÿ”„ Model Auto-Sync Scheduler (#488) + +OmniRoute now automatically refreshes model lists for connected providers every **24 hours**. + +- Runs on server startup via the existing `/api/sync/initialize` hook +- Configurable via `MODEL_SYNC_INTERVAL_HOURS` environment variable +- Covers 16 major providers +- Records last sync time in the settings database + +--- + +### ๐Ÿ”ง Bug Fixes + +#### OAuth & Auth + +- **#537 โ€” Gemini CLI OAuth:** Clear actionable error when `GEMINI_OAUTH_CLIENT_SECRET` is missing in Docker/self-hosted deployments. Previously showed cryptic `client_secret is missing` from Google. Now provides specific `docker-compose.yml` and `~/.omniroute/.env` instructions. + +#### Providers & Routing + +- **#536 โ€” LongCat AI:** Fixed `baseUrl` (`api.longcat.chat/openai`) and `authHeader` (`Authorization: Bearer`). +- **#535 โ€” Pinned model override:** `body.model` is now correctly set to `pinnedModel` when context-cache protection is active. +- **#532 โ€” OpenCode Go key validation:** Now uses the `zen/v1` test endpoint (`testKeyBaseUrl`) โ€” same key works for both tiers. + +#### CLI & Tools + +- **#527 โ€” Claude Code + Codex loop:** `tool_result` blocks are now converted to text instead of dropped, stopping infinite tool-result loops. +- **#524 โ€” OpenCode config save:** Added `saveOpenCodeConfig()` handler (XDG_CONFIG_HOME aware, writes TOML). +- **#521 โ€” Login stuck:** Login no longer freezes after skipping password setup โ€” redirects correctly to onboarding. +- **#522 โ€” API Manager:** Removed misleading "Copy masked key" button (replaced with a lock icon tooltip). +- **#532 โ€” OpenCode Go config:** Guide settings handler now handles `opencode` toolId. + +#### Developer Experience + +- **#489 โ€” Antigravity:** Missing `googleProjectId` returns a structured 422 error with reconnect guidance instead of a cryptic crash. +- **#510 โ€” Windows paths:** MSYS2/Git-Bash paths (`/c/Program Files/...`) are now normalized to `C:\\Program Files\\...` automatically. +- **#492 โ€” CLI startup:** `omniroute` CLI now detects `mise`/`nvm`-managed Node when `app/server.js` is missing and shows targeted fix instructions. + +--- + +### ๐Ÿ“– Documentation Updates + +- **#513** โ€” Docker password reset: `INITIAL_PASSWORD` env var workaround documented +- **#520** โ€” pnpm: `pnpm approve-builds better-sqlite3` step documented + +--- + +### โœ… Issues Resolved in v3.0.0 + +`#464` `#488` `#489` `#492` `#510` `#513` `#520` `#521` `#522` `#524` `#527` `#529` `#532` `#535` `#536` `#537` + +--- + +### ๐Ÿ”€ Community PRs Merged + +| PR | Author | Summary | +| -------- | ------------ | ---------------------------------------------------------------------- | +| **#530** | @kang-heewon | OpenCode Zen + Go providers with `OpencodeExecutor` and improved tests | + +--- + +## [3.0.0-rc.7] - 2026-03-23 + +### ๐Ÿ”ง Improvements (sub2api Gap Analysis โ€” T05, T08, T09, T13, T14) + +- **T05** โ€” Rate-limit DB persistence: `setConnectionRateLimitUntil()`, `isConnectionRateLimited()`, `getRateLimitedConnections()` in `providers.ts`. The existing `rate_limited_until` column is now exposed as a dedicated API โ€” OAuth token refresh must NOT touch this field to prevent rate-limit loops. +- **T08** โ€” Per-API-key session limit: `max_sessions INTEGER DEFAULT 0` added to `api_keys` via auto-migration. `sessionManager.ts` gains `registerKeySession()`, `unregisterKeySession()`, `checkSessionLimit()`, and `getActiveSessionCountForKey()`. Callers in `chatCore.js` can enforce the limit and decrement on `req.close`. +- **T09** โ€” Codex vs Spark rate-limit scopes: `getCodexModelScope()` and `getCodexRateLimitKey()` in `codex.ts`. Standard models (`gpt-5.x-codex`, `codex-mini`) get scope `"codex"`; spark models (`codex-spark*`) get scope `"spark"`. Rate-limit keys should be `${accountId}:${scope}` so exhausting one pool doesn't block the other. +- **T13** โ€” Stale quota display fix: `getEffectiveQuotaUsage(used, resetAt)` returns `0` when the reset window has passed; `formatResetCountdown(resetAt)` returns a human-readable countdown string (e.g. `"2h 35m"`). Both exported from `providers.ts` + `localDb.ts` for dashboard consumption. +- **T14** โ€” Proxy fast-fail: new `src/lib/proxyHealth.ts` with `isProxyReachable(proxyUrl, timeoutMs=2000)` (TCP check, โ‰ค2s instead of 30s timeout), `getCachedProxyHealth()`, `invalidateProxyHealth()`, and `getAllProxyHealthStatuses()`. Results cached 30s by default; configurable via `PROXY_FAST_FAIL_TIMEOUT_MS` / `PROXY_HEALTH_CACHE_TTL_MS`. + +### ๐Ÿงช Tests + +- Test suite: **832 tests, 0 failures** + +--- + +## [3.0.0-rc.6] - 2026-03-23 + +### ๐Ÿ”ง Bug Fixes & Improvements (sub2api Gap Analysis โ€” T01โ€“T15) + +- **T01** โ€” `requested_model` column in `call_logs` (migration 009): track which model the client originally requested vs the actual routed model. Enables fallback rate analytics. +- **T02** โ€” Strip empty text blocks from nested `tool_result.content`: prevents Anthropic 400 errors (`text content blocks must be non-empty`) when Claude Code chains tool results. +- **T03** โ€” Parse `x-codex-5h-*` / `x-codex-7d-*` headers: `parseCodexQuotaHeaders()` + `getCodexResetTime()` extract Codex quota windows for precise cooldown scheduling instead of generic 5-min fallback. +- **T04** โ€” `X-Session-Id` header for external sticky routing: `extractExternalSessionId()` in `sessionManager.ts` reads `x-session-id` / `x-omniroute-session` headers with `ext:` prefix to avoid collision with internal SHA-256 session IDs. Nginx-compatible (hyphenated header). +- **T06** โ€” Account deactivated โ†’ permanent block: `isAccountDeactivated()` in `accountFallback.ts` detects 401 deactivation signals and applies a 1-year cooldown to prevent retrying permanently dead accounts. +- **T07** โ€” X-Forwarded-For IP validation: new `src/lib/ipUtils.ts` with `extractClientIp()` and `getClientIpFromRequest()` โ€” skips `unknown`/non-IP entries in `X-Forwarded-For` chains (Nginx/proxy-forwarded requests). +- **T10** โ€” Credits exhausted โ†’ distinct fallback: `isCreditsExhausted()` in `accountFallback.ts` returns 1h cooldown with `creditsExhausted` flag, distinct from generic 429 rate limiting. +- **T11** โ€” `max` reasoning effort โ†’ 131072 budget tokens: `EFFORT_BUDGETS` and `THINKING_LEVEL_MAP` updated; reverse mapping now returns `"max"` for full-budget responses. Unit test updated. +- **T12** โ€” MiniMax M2.7 pricing entries added: `minimax-m2.7`, `MiniMax-M2.7`, `minimax-m2.7-highspeed` added to pricing table (sub2api PR #1120). M2.5/GLM-4.7/GLM-5/Kimi pricing already existed. +- **T15** โ€” Array content normalization: `normalizeContentToString()` helper in `openai-to-claude.ts` correctly collapses array-formatted system/tool messages to string before sending to Anthropic. + +### ๐Ÿงช Tests + +- Test suite: **832 tests, 0 failures** (unchanged from rc.5) + +--- + +## [3.0.0-rc.5] - 2026-03-22 + +### โœจ New Features + +- **#464** โ€” Registered Keys Provisioning API: auto-issue API keys with per-provider & per-account quota enforcement + - `POST /api/v1/registered-keys` โ€” issue keys with idempotency support + - `GET /api/v1/registered-keys` โ€” list (masked) registered keys + - `GET /api/v1/registered-keys/{id}` โ€” get key metadata + - `DELETE /api/v1/registered-keys/{id}` / `POST ../{id}/revoke` โ€” revoke keys + - `GET /api/v1/quotas/check` โ€” pre-validate before issuing + - `PUT /api/v1/providers/{id}/limits` โ€” set provider issuance limits + - `PUT /api/v1/accounts/{id}/limits` โ€” set account issuance limits + - `POST /api/v1/issues/report` โ€” optional GitHub issue reporting + - DB migration 008: `registered_keys`, `provider_key_limits`, `account_key_limits` tables + +--- + +## [3.0.0-rc.4] - 2026-03-22 + +### โœจ New Features + +- **#530 (PR)** โ€” OpenCode Zen and OpenCode Go providers added (by @kang-heewon) + - New `OpencodeExecutor` with multi-format routing (`/chat/completions`, `/messages`, `/responses`) + - 7 models across both tiers + +--- + +## [3.0.0-rc.3] - 2026-03-22 + +### โœจ New Features + +- **#529** โ€” Provider icons now use [@lobehub/icons](https://github.com/lobehub/lobe-icons) with graceful PNG fallback and a `ProviderIcon` component (130+ providers supported) +- **#488** โ€” Auto-update model lists every 24h via `modelSyncScheduler` (configurable via `MODEL_SYNC_INTERVAL_HOURS`) + +### ๐Ÿ”ง Bug Fixes + +- **#537** โ€” Gemini CLI OAuth: now shows clear actionable error when `GEMINI_OAUTH_CLIENT_SECRET` is missing in Docker/self-hosted deployments + +--- + +## [3.0.0-rc.2] - 2026-03-22 + +### ๐Ÿ”ง Bug Fixes + +- **#536** โ€” LongCat AI key validation: fixed baseUrl (`api.longcat.chat/openai`) and authHeader (`Authorization: Bearer`) +- **#535** โ€” Pinned model override: `body.model` is now set to `pinnedModel` when context-cache protection detects a pinned model +- **#524** โ€” OpenCode config now saved correctly: added `saveOpenCodeConfig()` handler (XDG_CONFIG_HOME aware, writes TOML) + +--- + +## [3.0.0-rc.1] - 2026-03-22 + +### ๐Ÿ”ง Bug Fixes + +- **#521** โ€” Login no longer gets stuck after skipping password setup (redirects to onboarding) +- **#522** โ€” API Manager: Removed misleading "Copy masked key" button (replaced with lock icon tooltip) +- **#527** โ€” Claude Code + Codex superpowers loop: `tool_result` blocks now converted to text instead of dropped +- **#532** โ€” OpenCode GO API key validation now uses the correct `zen/v1` endpoint (`testKeyBaseUrl`) +- **#489** โ€” Antigravity: missing `googleProjectId` returns structured 422 error with reconnect guidance +- **#510** โ€” Windows: MSYS2/Git-Bash paths (`/c/Program Files/...`) are now normalized to `C:\\Program Files\\...` +- **#492** โ€” `omniroute` CLI now detects `mise`/`nvm` when `app/server.js` is missing and shows targeted fix + +### Dokumentace + +- **#513** โ€” Docker password reset: `INITIAL_PASSWORD` env var workaround documented +- **#520** โ€” pnpm: `pnpm approve-builds better-sqlite3` documented + +### โœ… Closed Issues + +#489, #492, #510, #513, #520, #521, #522, #525, #527, #532 + +--- + +## [2.9.5] โ€” 2026-03-22 + +> Sprint: New OpenCode providers, embedding credentials fix, CLI masked key bug, CACHE_TAG_PATTERN fix. + +### ๐Ÿ› Bug Fixes + +- **CLI tools save masked API key to config files** โ€” `claude-settings`, `cline-settings`, and `openclaw-settings` POST routes now accept a `keyId` param and resolve the real API key from DB before writing to disk. `ClaudeToolCard` updated to send `keyId` instead of the masked display string. Fixes #523, #526. +- **Custom embedding providers: `No credentials` error** โ€” `/v1/embeddings` now tracks `credentialsProviderId` separately from the routing prefix, so credentials are fetched from the matching provider node ID rather than the public prefix string. Fixes a regression where `google/gemini-embedding-001` and similar custom-provider models would always fail with a credentials error. Fixes #532-related. (PR #528 by @jacob2826) +- **Context cache protection regex misses `\n` prefix** โ€” `CACHE_TAG_PATTERN` in `comboAgentMiddleware.ts` updated to match both literal `\n` (backslash-n) and actual newline U+000A that `combo.ts` streaming injects around the `` tag after fix #515. Fixes #531. + +### โœจ New Providers + +- **OpenCode Zen** โ€” Free tier gateway at `opencode.ai/zen/v1` with 3 models: `minimax-m2.5-free`, `big-pickle`, `gpt-5-nano` +- **OpenCode Go** โ€” Subscription service at `opencode.ai/zen/go/v1` with 4 models: `glm-5`, `kimi-k2.5`, `minimax-m2.7` (Claude format), `minimax-m2.5` (Claude format) +- Both providers use the new `OpencodeExecutor` which routes dynamically to `/chat/completions`, `/messages`, `/responses`, or `/models/{model}:generateContent` based on the requested model. (PR #530 by @kang-heewon) + +--- + +## [2.9.4] โ€” 2026-03-21 + +> Sprint: Bug fixes โ€” preserve Codex prompt cache key, fix tagContent JSON escaping, sync expired token status to DB. + +### ๐Ÿ› Bug Fixes + +- **fix(translator)**: Preserve `prompt_cache_key` in Responses API โ†’ Chat Completions translation (#517) + โ€” The field is a cache-affinity signal used by Codex; stripping it was preventing prompt cache hits. + Fixed in `openai-responses.ts` and `responsesApiHelper.ts`. + +- **fix(combo)**: Escape `\n` in `tagContent` so injected JSON string is valid (#515) + โ€” Template literal newlines (U+000A) are not allowed unescaped inside JSON string values. + Replaced with `\\n` literal sequences in `open-sse/services/combo.ts`. + +- **fix(usage)**: Sync expired token status back to DB on live auth failure (#491) + โ€” When the Limits & Quotas live check returns 401/403, the connection `testStatus` is now updated + to `"expired"` in the database so the Providers page reflects the same degraded state. + Fixed in `src/app/api/usage/[connectionId]/route.ts`. + +--- + +## [2.9.3] โ€” 2026-03-21 + +> Sprint: Add 5 new free AI providers โ€” LongCat, Pollinations, Cloudflare AI, Scaleway, AI/ML API. + +### โœจ New Providers + +- **feat(providers/longcat)**: Add LongCat AI (`lc/`) โ€” 50M tokens/day free (Flash-Lite) + 500K/day (Chat/Thinking) during public beta. OpenAI-compatible, standard Bearer auth. +- **feat(providers/pollinations)**: Add Pollinations AI (`pol/`) โ€” no API key required. Proxies GPT-5, Claude, Gemini, DeepSeek V3, Llama 4 (1 req/15s free). Custom executor handles optional auth. +- **feat(providers/cloudflare-ai)**: Add Cloudflare Workers AI (`cf/`) โ€” 10K Neurons/day free (~150 LLM responses or 500s Whisper audio). 50+ models on global edge. Custom executor builds dynamic URL with `accountId` from credentials. +- **feat(providers/scaleway)**: Add Scaleway Generative APIs (`scw/`) โ€” 1M free tokens for new accounts. EU/GDPR compliant (Paris). Qwen3 235B, Llama 3.1 70B, Mistral Small 3.2. +- **feat(providers/aimlapi)**: Add AI/ML API (`aiml/`) โ€” $0.025/day free credit, 200+ models (GPT-4o, Claude, Gemini, Llama) via single aggregator endpoint. + +### ๐Ÿ”„ Provider Updates + +- **feat(providers/together)**: Add `hasFree: true` + 3 permanently free model IDs: `Llama-3.3-70B-Instruct-Turbo-Free`, `Llama-Vision-Free`, `DeepSeek-R1-Distill-Llama-70B-Free` +- **feat(providers/gemini)**: Add `hasFree: true` + `freeNote` (1,500 req/day, no credit card needed, aistudio.google.com) +- **chore(providers/gemini)**: Rename display name to `Gemini (Google AI Studio)` for clarity + +### โš™๏ธ Infrastructure + +- **feat(executors/pollinations)**: New `PollinationsExecutor` โ€” omits `Authorization` header when no API key provided +- **feat(executors/cloudflare-ai)**: New `CloudflareAIExecutor` โ€” dynamic URL construction requires `accountId` in provider credentials +- **feat(executors)**: Register `pollinations`, `pol`, `cloudflare-ai`, `cf` executor mappings + +### Dokumentace + +- **docs(readme)**: Expanded free combo stack to 11 providers ($0 forever) +- **docs(readme)**: Added 4 new free provider sections (LongCat, Pollinations, Cloudflare AI, Scaleway) with model tables +- **docs(readme)**: Updated pricing table with 4 new free tier rows +- **docs(i18n/pt-BR)**: Updated pricing table + added LongCat/Pollinations/Cloudflare AI/Scaleway sections in Portuguese +- **docs(new-features/ai)**: 10 task spec files + master implementation plan in `docs/new-features/ai/` + +### ๐Ÿงช Tests + +- Test suite: **821 tests, 0 failures** (unchanged) + +--- + +## [2.9.2] โ€” 2026-03-21 + +> Sprint: Fix media transcription (Deepgram/HuggingFace Content-Type, language detection) and TTS error display. + +### ๐Ÿ› Bug Fixes + +- **fix(transcription)**: Deepgram and HuggingFace audio transcription now correctly map `video/mp4` โ†’ `audio/mp4` and other media MIME types via new `resolveAudioContentType()` helper. Previously, uploading `.mp4` files consistently returned "No speech detected" because Deepgram was receiving `Content-Type: video/mp4`. +- **fix(transcription)**: Added `detect_language=true` to Deepgram requests โ€” auto-detects audio language (Portuguese, Spanish, etc.) instead of defaulting to English. Fixes non-English transcriptions returning empty or garbage results. +- **fix(transcription)**: Added `punctuate=true` to Deepgram requests for higher-quality transcription output with correct punctuation. +- **fix(tts)**: `[object Object]` error display in Text-to-Speech responses fixed in both `audioSpeech.ts` and `audioTranscription.ts`. The `upstreamErrorResponse()` function now correctly extracts nested string messages from providers like ElevenLabs that return `{ error: { message: "...", status_code: 401 } }` instead of a flat error string. + +### ๐Ÿงช Tests + +- Test suite: **821 tests, 0 failures** (unchanged) + +### Triaged Issues + +- **#508** โ€” Tool call format regression: requested proxy logs and provider chain info (`needs-info`) +- **#510** โ€” Windows CLI healthcheck path: requested shell/Node version info (`needs-info`) +- **#485** โ€” Kiro MCP tool calls: closed as external Kiro issue (not OmniRoute) +- **#442** โ€” Baseten /models endpoint: closed (documented manual workaround) +- **#464** โ€” Key provisioning API: acknowledged as roadmap item + +--- + +## [2.9.1] โ€” 2026-03-21 + +> Sprint: Fix SSE omniModel data loss, merge per-protocol model compatibility. + +### Bug Fixes + +- **#511** โ€” Critical: `` tag was sent after `finish_reason:stop` in SSE streams, causing data loss. Tag is now injected into the first non-empty content chunk, guaranteeing delivery before SDKs close the connection. + +### Merged PRs + +- **PR #512** (@zhangqiang8vip): Per-protocol model compatibility โ€” `normalizeToolCallId` and `preserveOpenAIDeveloperRole` can now be configured per client protocol (OpenAI, Claude, Responses API). New `compatByProtocol` field in model config with Zod validation. + +### Triaged Issues + +- **#510** โ€” Windows CLI healthcheck_failed: requested PATH/version info +- **#509** โ€” Turbopack Electron regression: upstream Next.js bug, documented workarounds +- **#508** โ€” macOS black screen: suggested `--disable-gpu` workaround + +--- + +## [2.9.0] โ€” 2026-03-20 + +> Sprint: Cross-platform machineId fix, per-API-key rate limits, streaming context cache, Alibaba DashScope, search analytics, ZWS v5, and 8 issues closed. + +### โœจ New Features + +- **feat(search)**: Search Analytics tab in `/dashboard/analytics` โ€” provider breakdown, cache hit rate, cost tracking. New API: `GET /api/v1/search/analytics` (#feat/search-provider-routing) +- **feat(provider)**: Alibaba Cloud DashScope added with custom endpoint path validation โ€” configurable `chatPath` and `modelsPath` per node (#feat/custom-endpoint-paths) +- **feat(api)**: Per-API-key request-count limits โ€” `max_requests_per_day` and `max_requests_per_minute` columns with in-memory sliding-window enforcement returning HTTP 429 (#452) +- **feat(dev)**: ZWS v5 โ€” HMR leak fix (485 DB connections โ†’ 1), memory 2.4GB โ†’ 195MB, `globalThis` singletons, Edge Runtime warning fix (@zhangqiang8vip) + +### ๐Ÿ› Bug Fixes + +- **fix(#506)**: Cross-platform `machineId` โ€” `getMachineIdRaw()` rewritten with try/catch waterfall (Windows REG.exe โ†’ macOS ioreg โ†’ Linux file read โ†’ hostname โ†’ `os.hostname()`). Eliminates `process.platform` branching that Next.js bundler dead-code-eliminated, fixing `'head' is not recognized` on Windows. Also fixes #466. +- **fix(#493)**: Custom provider model naming โ€” removed incorrect prefix stripping in `DefaultExecutor.transformRequest()` that mangled org-scoped model IDs like `zai-org/GLM-5-FP8`. +- **fix(#490)**: Streaming + context cache protection โ€” `TransformStream` intercepts SSE to inject `` tag before `[DONE]` marker, enabling context cache protection for streaming responses. +- **fix(#458)**: Combo schema validation โ€” `system_message`, `tool_filter_regex`, `context_cache_protection` fields now pass Zod validation on save. +- **fix(#487)**: KIRO MITM card cleanup โ€” removed ZWS_README, generified `AntigravityToolCard` to use dynamic tool metadata. + +### ๐Ÿงช Tests + +- Added Anthropic-format tools filter unit tests (PR #397) โ€” 8 regression tests for `tool.name` without `.function` wrapper +- Test suite: **821 tests, 0 failures** (up from 813) + +### ๐Ÿ“‹ Issues Closed (8) + +- **#506** โ€” Windows machineId `head` not recognized (fixed) +- **#493** โ€” Custom provider model naming (fixed) +- **#490** โ€” Streaming context cache (fixed) +- **#452** โ€” Per-API-key request limits (implemented) +- **#466** โ€” Windows login failure (same root cause as #506) +- **#504** โ€” MITM inactive (expected behavior) +- **#462** โ€” Gemini CLI PSA (resolved) +- **#434** โ€” Electron app crash (duplicate of #402) + +## [2.8.9] โ€” 2026-03-20 + +> Sprint: Merge community PRs, fix KIRO MITM card, dependency updates. + +### Merged PRs + +- **PR #498** (@Sajid11194): Fix Windows machine ID crash (`undefined\REG.exe`). Replaces `node-machine-id` with native OS registry queries. **Closes #486.** +- **PR #497** (@zhangqiang8vip): Fix dev-mode HMR resource leaks โ€” 485 leaked DB connections โ†’ 1, memory 2.4GB โ†’ 195MB. `globalThis` singletons, Edge Runtime warning fix, Windows test stability. (+1168/-338 across 22 files) +- **PRs #499-503** (Dependabot): GitHub Actions updates โ€” `docker/build-push-action@7`, `actions/checkout@6`, `peter-evans/dockerhub-description@5`, `docker/setup-qemu-action@4`, `docker/login-action@4`. + +### Bug Fixes + +- **#505** โ€” KIRO MITM card now displays tool-specific instructions (`api.anthropic.com`) instead of Antigravity-specific text. +- **#504** โ€” Responded with UX clarification (MITM "Inactive" is expected behavior when proxy is not running). + +--- + +## [2.8.8] โ€” 2026-03-20 + +> Sprint: Fix OAuth batch test crash, add "Test All" button to individual provider pages. + +### Bug Fixes + +- **OAuth batch test crash** (ERR_CONNECTION_REFUSED): Replaced sequential for-loop with 5-connection concurrency limit + 30s per-connection timeout via `Promise.race()` + `Promise.allSettled()`. Prevents server crash when testing large OAuth provider groups (~30+ connections). + +### Funkce + +- **"Test All" button on provider pages**: Individual provider pages (e.g., `/providers/codex`) now show a "Test All" button in the Connections header when there are 2+ connections. Uses `POST /api/providers/test-batch` with `{mode: "provider", providerId}`. Results displayed in a modal with pass/fail summary and per-connection diagnosis. + +--- + +## [2.8.7] โ€” 2026-03-20 + +> Sprint: Merge PR #495 (Bottleneck 429 drop), fix #496 (custom embedding providers), triage features. + +### Bug Fixes + +- **Bottleneck 429 infinite wait** (PR #495 by @xandr0s): On 429, `limiter.stop({ dropWaitingJobs: true })` immediately fails all queued requests so upstream callers can trigger fallback. Limiter is deleted from Map so next request creates a fresh instance. +- **Custom embedding models unresolvable** (#496): `POST /v1/embeddings` now resolves custom embedding models from ALL provider_nodes (not just localhost). Enables models like `google/gemini-embedding-001` added via dashboard. + +### Issues Responded + +- **#452** โ€” Per-API-key request-count limits (acknowledged, on roadmap) +- **#464** โ€” Auto-issue API keys with provider/account limits (needs more detail) +- **#488** โ€” Auto-update model lists (acknowledged, on roadmap) +- **#496** โ€” Custom embedding provider resolution (fixed) + +--- + +## [2.8.6] โ€” 2026-03-20 + +> Sprint: Merge PR #494 (MiniMax role fix), fix KIRO MITM dashboard, triage 8 issues. + +### Funkce + +- **MiniMax developerโ†’system role fix** (PR #494 by @zhangqiang8vip): Per-model `preserveDeveloperRole` toggle. Adds "Compatibility" UI in providers page. Fixes 422 "role param error" for MiniMax and similar gateways. +- **roleNormalizer**: `normalizeDeveloperRole()` now accepts `preserveDeveloperRole` parameter with tri-state behavior (undefined=keep, true=keep, false=convert). +- **DB**: New `getModelPreserveOpenAIDeveloperRole()` and `mergeModelCompatOverride()` in `models.ts`. + +### Bug Fixes + +- **KIRO MITM dashboard** (#481/#487): `CLIToolsPageClient` now routes any `configType: "mitm"` tool to `AntigravityToolCard` (MITM Start/Stop controls). Previously only Antigravity was hardcoded. +- **AntigravityToolCard generic**: Uses `tool.image`, `tool.description`, `tool.id` instead of hardcoded Antigravity values. Guards against missing `defaultModels`. + +### Cleanup + +- Removed `ZWS_README_V2.md` (development-only docs from PR #494). + +### Issues Triaged (8) + +- **#487** โ€” Closed (KIRO MITM fixed in this release) +- **#486** โ€” needs-info (Windows REG.exe PATH issue) +- **#489** โ€” needs-info (Antigravity projectId missing, OAuth reconnect needed) +- **#492** โ€” needs-info (missing app/server.js on mise-managed Node) +- **#490** โ€” Acknowledged (streaming + context cache blocking, fix planned) +- **#491** โ€” Acknowledged (Codex auth state inconsistency) +- **#493** โ€” Acknowledged (Modal provider model name prefix, workaround provided) +- **#488** โ€” Feature request backlog (auto-update model lists) + +--- + +## [2.8.5] โ€” 2026-03-19 + +> Sprint: Fix zombie SSE streams, context cache first-turn, KIRO MITM, and triage 5 external issues. + +### Bug Fixes + +- **Zombie SSE Streams** (#473): Reduce `STREAM_IDLE_TIMEOUT_MS` from 300s โ†’ 120s for faster combo fallback when providers hang mid-stream. Configurable via env var. +- **Context Cache Tag** (#474): Fix `injectModelTag()` to handle first-turn requests (no assistant messages) โ€” context cache protection now works from the very first response. +- **KIRO MITM** (#481): Change KIRO `configType` from `guide` โ†’ `mitm` so the dashboard renders MITM Start/Stop controls. +- **E2E Test** (CI): Fix `providers-bailian-coding-plan.spec.ts` โ€” dismiss pre-existing modal overlay before clicking Add API Key button. + +### Closed Issues + +- #473 โ€” Zombie SSE streams bypass combo fallback +- #474 โ€” Context cache `` tag missing on first turn +- #481 โ€” MITM for KIRO not activatable from dashboard +- #468 โ€” Gemini CLI remote server (superseded by #462 deprecation) +- #438 โ€” Claude unable to write files (external CLI issue) +- #439 โ€” AppImage doesn't work (documented libfuse2 workaround) +- #402 โ€” ARM64 DMG "damaged" (documented xattr -cr workaround) +- #460 โ€” CLI not runnable on Windows (documented PATH fix) + +--- + +## [2.8.4] โ€” 2026-03-19 + +> Sprint: Gemini CLI deprecation, VM guide i18n fix, dependabot security fix, provider schema expansion. + +### Funkce + +- **Gemini CLI Deprecation** (#462): Mark `gemini-cli` provider as deprecated with warning โ€” Google restricts third-party OAuth usage from March 2026 +- **Provider Schema** (#462): Expand Zod validation with `deprecated`, `deprecationReason`, `hasFree`, `freeNote`, `authHint`, `apiHint` optional fields + +### Bug Fixes + +- **VM Guide i18n** (#471): Add `VM_DEPLOYMENT_GUIDE.md` to i18n translation pipeline, regenerate all 30 locale translations from English source (were stuck in Portuguese) + +### Bezpeฤnost + +- **deps**: Bump `flatted` 3.3.3 โ†’ 3.4.2 โ€” fixes CWE-1321 prototype pollution (#484, @dependabot) + +### Closed Issues + +- #472 โ€” Model Aliases regression (fixed in v2.8.2) +- #471 โ€” VM guide translations broken +- #483 โ€” Trailing `data: null` after `[DONE]` (fixed in v2.8.3) + +### Merged PRs + +- #484 โ€” deps: bump flatted from 3.3.3 to 3.4.2 (@dependabot) + +--- + +## [2.8.3] โ€” 2026-03-19 + +> Sprint: Czech i18n, SSE protocol fix, VM guide translation. + +### Funkce + +- **Czech Language** (#482): Full Czech (cs) i18n โ€” 22 docs, 2606 UI strings, language switcher updates (@zen0bit) +- **VM Deployment Guide**: Translated from Portuguese to English as the source document (@zen0bit) + +### Bug Fixes + +- **SSE Protocol** (#483): Stop sending trailing `data: null` after `[DONE]` signal โ€” fixes `AI_TypeValidationError` in strict AI SDK clients (Zod-based validators) + +### Merged PRs + +- #482 โ€” Add Czech language + Fix VM_DEPLOYMENT_GUIDE.md English source (@zen0bit) + +--- + +## [2.8.2] โ€” 2026-03-19 + +> Sprint: 2 merged PRs, model aliases routing fix, log export, and issue triage. + +### Funkce + +- **Log Export**: New Export button on `/dashboard/logs` with time range dropdown (1h, 6h, 12h, 24h). Downloads JSON of request/proxy/call logs via `/api/logs/export` API (#user-request) + +### Bug Fixes + +- **Model Aliases Routing** (#472): Settings โ†’ Model Aliases now correctly affect provider routing, not just format detection. Previously `resolveModelAlias()` output was only used for `getModelTargetFormat()` but the original model ID was sent to the provider +- **Stream Flush Usage** (#480): Usage data from the last SSE event in the buffer is now correctly extracted during stream flush (merged from @prakersh) + +### Merged PRs + +- #480 โ€” Extract usage from remaining buffer in flush handler (@prakersh) +- #479 โ€” Add missing Codex 5.3/5.4 and Anthropic model ID pricing entries (@prakersh) + +--- + +## [2.8.1] โ€” 2026-03-19 + +> Sprint: Five community PRs โ€” streaming call log fixes, Kiro compatibility, cache token analytics, Chinese translation, and configurable tool call IDs. + +### Funkce + +- **feat(logs)**: Call log response content now correctly accumulated from raw provider chunks (OpenAI/Claude/Gemini) before translation, fixing empty response payloads in streaming mode (#470, @zhangqiang8vip) +- **feat(providers)**: Per-model configurable 9-char tool call ID normalization (Mistral-style) โ€” only models with the option enabled get truncated IDs (#470) +- **feat(api)**: Key PATCH API expanded to support `allowedConnections`, `name`, `autoResolve`, `isActive`, and `accessSchedule` fields (#470) +- **feat(dashboard)**: Response-first layout in request log detail UI (#470) +- **feat(i18n)**: Improved Chinese (zh-CN) translation โ€” complete retranslation (#475, @only4copilot) + +### ๐Ÿ› Bug Fixes + +- **fix(kiro)**: Strip injected `model` field from request body โ€” Kiro API rejects unknown top-level fields (#478, @prakersh) +- **fix(usage)**: Include cache read + cache creation tokens in usage history input totals for accurate analytics (#477, @prakersh) +- **fix(callLogs)**: Support Claude format usage fields (`input_tokens`/`output_tokens`) alongside OpenAI format, include all cache token variants (#476, @prakersh) + +--- + +## [2.8.0] โ€” 2026-03-19 + +> Sprint: Bailian Coding Plan provider with editable base URLs, plus community contributions for Alibaba Cloud and Kimi Coding. + +### Funkce + +- **feat(providers)**: Added Bailian Coding Plan (`bailian-coding-plan`) โ€” Alibaba Model Studio with Anthropic-compatible API. Static catalog of 8 models including Qwen3.5 Plus, Qwen3 Coder, MiniMax M2.5, GLM 5, and Kimi K2.5. Includes custom auth validation (400=valid, 401/403=invalid) (#467, @Mind-Dragon) +- **feat(admin)**: Editable default URL in Provider Admin create/edit flows โ€” users can configure custom base URLs per connection. Persisted in `providerSpecificData.baseUrl` with Zod schema validation rejecting non-http(s) schemes (#467) + +### ๐Ÿงช Tests + +- Added 30+ unit tests and 2 e2e scenarios for Bailian Coding Plan provider covering auth validation, schema hardening, route-level behavior, and cross-layer integration + +--- + +## [2.7.10] โ€” 2026-03-19 + +> Sprint: Two new community-contributed providers (Alibaba Cloud Coding, Kimi Coding API-key) and Docker pino fix. + +### Funkce + +- **feat(providers)**: Added Alibaba Cloud Coding Plan support with two OpenAI-compatible endpoints โ€” `alicode` (China) and `alicode-intl` (International), each with 8 models (#465, @dtk1985) +- **feat(providers)**: Added dedicated `kimi-coding-apikey` provider path โ€” API-key-based Kimi Coding access is no longer forced through OAuth-only `kimi-coding` route. Includes registry, constants, models API, config, and validation test (#463, @Mind-Dragon) + +### ๐Ÿ› Bug Fixes + +- **fix(docker)**: Added missing `split2` dependency to Docker image โ€” `pino-abstract-transport` requires it at runtime but it was not being copied into the standalone container, causing `Cannot find module 'split2'` crashes (#459) + +--- + +## [2.7.9] โ€” 2026-03-18 + +> Sprint: Codex responses subpath passthrough natively supported, Windows MITM crash fixed, and Combos agent schemas adjusted. + +### Funkce + +- **feat(codex)**: Native responses subpath passthrough for Codex โ€” natively routes `POST /v1/responses/compact` to Codex upstream, maintaining Claude Code compatibility without stripping the `/compact` suffix (#457) + +### ๐Ÿ› Bug Fixes + +- **fix(combos)**: Zod schemas (`updateComboSchema` and `createComboSchema`) now include `system_message`, `tool_filter_regex`, and `context_cache_protection`. Fixes bug where agent-specific settings created via the dashboard were silently discarded by the backend validation layer (#458) +- **fix(mitm)**: Kiro MITM profile crash on Windows fixed โ€” `node-machine-id` failed due to missing `REG.exe` env, and the fallback threw a fatal `crypto is not defined` error. Fallback now safely and correctly imports crypto (#456) + +--- + +## [2.7.8] โ€” 2026-03-18 + +> Sprint: Budget save bug + combo agent features UI + omniModel tag security fix. + +### ๐Ÿ› Bug Fixes + +- **fix(budget)**: "Save Limits" no longer returns 422 โ€” `warningThreshold` is now correctly sent as fraction (0โ€“1) instead of percentage (0โ€“100) (#451) +- **fix(combos)**: `` internal cache tag is now stripped before forwarding requests to providers, preventing cache session breaks (#454) + +### Funkce + +- **feat(combos)**: Agent Features section added to combo create/edit modal โ€” expose `system_message` override, `tool_filter_regex`, and `context_cache_protection` directly from the dashboard (#454) + +--- + +## [2.7.7] โ€” 2026-03-18 + +> Sprint: Docker pino crash, Codex CLI responses worker fix, package-lock sync. + +### ๐Ÿ› Bug Fixes + +- **fix(docker)**: `pino-abstract-transport` and `pino-pretty` now explicitly copied in Docker runner stage โ€” Next.js standalone trace misses these peer deps, causing `Cannot find module pino-abstract-transport` crash on startup (#449) +- **fix(responses)**: Remove `initTranslators()` from `/v1/responses` route โ€” was crashing Next.js worker with `the worker has exited` uncaughtException on Codex CLI requests (#450) + +### ๐Ÿ”ง Maintenance + +- **chore(deps)**: `package-lock.json` now committed on every version bump to ensure Docker `npm ci` uses exact dependency versions + +--- + +## [2.7.5] โ€” 2026-03-18 + +> Sprint: UX improvements and Windows CLI healthcheck fix. + +### ๐Ÿ› Bug Fixes + +- **fix(ux)**: Show default password hint on login page โ€” new users now see `"Default password: 123456"` below the password input (#437) +- **fix(cli)**: Claude CLI and other npm-installed tools now correctly detected as runnable on Windows โ€” spawn uses `shell:true` to resolve `.cmd` wrappers via PATHEXT (#447) + +--- + +## [2.7.4] โ€” 2026-03-18 + +> Sprint: Search Tools dashboard, i18n fixes, Copilot limits, Serper validation fix. + +### Funkce + +- **feat(search)**: Add Search Playground (10th endpoint), Search Tools page with Compare Providers/Rerank Pipeline/Search History, local rerank routing, auth guards on search API (#443 by @Regis-RCR) + - New route: `/dashboard/search-tools` + - Sidebar entry under Debug section + - `GET /api/search/providers` and `GET /api/search/stats` with auth guards + - Local provider_nodes routing for `/v1/rerank` + - 30+ i18n keys in search namespace + +### ๐Ÿ› Bug Fixes + +- **fix(search)**: Fix Brave news normalizer (was returning 0 results), enforce max_results truncation post-normalization, fix Endpoints page fetch URL (#443 by @Regis-RCR) +- **fix(analytics)**: Localize analytics day/date labels โ€” replace hardcoded Portuguese strings with `Intl.DateTimeFormat(locale)` (#444 by @hijak) +- **fix(copilot)**: Correct GitHub Copilot account type display, filter misleading unlimited quota rows from limits dashboard (#445 by @hijak) +- **fix(providers)**: Stop rejecting valid Serper API keys โ€” treat non-4xx responses as valid authentication (#446 by @hijak) + +--- + +## [2.7.3] โ€” 2026-03-18 + +> Sprint: Codex direct API quota fallback fix. + +### ๐Ÿ› Bug Fixes + +- **fix(codex)**: Block weekly-exhausted accounts in direct API fallback (#440) + - `resolveQuotaWindow()` prefix matching: `"weekly"` now matches `"weekly (7d)"` cache keys + - `applyCodexWindowPolicy()` enforces `useWeekly`/`use5h` toggles correctly + - 4 new regression tests (766 total) + +--- + +## [2.7.2] โ€” 2026-03-18 + +> Sprint: Light mode UI contrast fixes. + +### ๐Ÿ› Bug Fixes + +- **fix(logs)**: Fix light mode contrast in request logs filter buttons and combo badge (#378) + - Error/Success/Combo filter buttons now readable in light mode + - Combo row badge uses stronger violet in light mode + +--- + +## [2.7.1] โ€” 2026-03-17 + +> Sprint: Unified web search routing (POST /v1/search) with 5 providers + Next.js 16.1.7 security fixes (6 CVEs). + +### โœจ New Features + +- **feat(search)**: Unified web search routing โ€” `POST /v1/search` with 5 providers (Serper, Brave, Perplexity, Exa, Tavily) + - Auto-failover across providers, 6,500+ free searches/month + - In-memory cache with request coalescing (configurable TTL) + - Dashboard: Search Analytics tab in `/dashboard/analytics` with provider breakdown, cache hit rate, cost tracking + - New API: `GET /api/v1/search/analytics` for search request statistics + - DB migration: `request_type` column on `call_logs` for non-chat request tracking + - Zod validation (`v1SearchSchema`), auth-gated, cost recorded via `recordCost()` + +### Bezpeฤnost + +- **deps**: Next.js 16.1.6 โ†’ 16.1.7 โ€” fixes 6 CVEs: + - **Critical**: CVE-2026-29057 (HTTP request smuggling via http-proxy) + - **High**: CVE-2026-27977, CVE-2026-27978 (WebSocket + Server Actions) + - **Medium**: CVE-2026-27979, CVE-2026-27980, CVE-2026-jcc7 + +### ๐Ÿ“ New Files + +| File | Purpose | +| ---------------------------------------------------------------- | ------------------------------------------ | +| `open-sse/handlers/search.ts` | Search handler with 5-provider routing | +| `open-sse/config/searchRegistry.ts` | Provider registry (auth, cost, quota, TTL) | +| `open-sse/services/searchCache.ts` | In-memory cache with request coalescing | +| `src/app/api/v1/search/route.ts` | Next.js route (POST + GET) | +| `src/app/api/v1/search/analytics/route.ts` | Search stats API | +| `src/app/(dashboard)/dashboard/analytics/SearchAnalyticsTab.tsx` | Analytics dashboard tab | +| `src/lib/db/migrations/007_search_request_type.sql` | DB migration | +| `tests/unit/search-registry.test.mjs` | 277 lines of unit tests | + +--- + +## [2.7.0] โ€” 2026-03-17 + +> Sprint: ClawRouter-inspired features โ€” toolCalling flag, multilingual intent detection, benchmark-driven fallback, request deduplication, pluggable RouterStrategy, Grok-4 Fast + GLM-5 + MiniMax M2.5 + Kimi K2.5 pricing. + +### โœจ New Models & Pricing + +- **feat(pricing)**: xAI Grok-4 Fast โ€” `$0.20/$0.50 per 1M tokens`, 1143ms p50 latency, tool calling supported +- **feat(pricing)**: xAI Grok-4 (standard) โ€” `$0.20/$1.50 per 1M tokens`, reasoning flagship +- **feat(pricing)**: GLM-5 via Z.AI โ€” `$0.5/1M`, 128K output context +- **feat(pricing)**: MiniMax M2.5 โ€” `$0.30/1M input`, reasoning + agentic tasks +- **feat(pricing)**: DeepSeek V3.2 โ€” updated pricing `$0.27/$1.10 per 1M` +- **feat(pricing)**: Kimi K2.5 via Moonshot API โ€” direct Moonshot API access +- **feat(providers)**: Z.AI provider added (`zai` alias) โ€” GLM-5 family with 128K output + +### ๐Ÿง  Routing Intelligence + +- **feat(registry)**: `toolCalling` flag per model in provider registry โ€” combos can now prefer/require tool-calling capable models +- **feat(scoring)**: Multilingual intent detection for AutoCombo scoring โ€” PT/ZH/ES/AR script/language patterns influence model selection per request context +- **feat(fallback)**: Benchmark-driven fallback chains โ€” real latency data (p50 from `comboMetrics`) used to re-order fallback priority dynamically +- **feat(dedup)**: Request deduplication via content-hash โ€” 5-second idempotency window prevents duplicate provider calls from retrying clients +- **feat(router)**: Pluggable `RouterStrategy` interface in `autoCombo/routerStrategy.ts` โ€” custom routing logic can be injected without modifying core + +### ๐Ÿ”ง MCP Server Improvements + +- **feat(mcp)**: 2 new advanced tool schemas: `omniroute_get_provider_metrics` (p50/p95/p99 per provider) and `omniroute_explain_route` (routing decision explanation) +- **feat(mcp)**: MCP tool auth scopes updated โ€” `metrics:read` scope added for provider metrics tools +- **feat(mcp)**: `omniroute_best_combo_for_task` now accepts `languageHint` parameter for multilingual routing + +### ๐Ÿ“Š Observability + +- **feat(metrics)**: `comboMetrics.ts` extended with real-time latency percentile tracking per provider/account +- **feat(health)**: Health API (`/api/monitoring/health`) now returns per-provider `p50Latency` and `errorRate` fields +- **feat(usage)**: Usage history migration for per-model latency tracking + +### ๐Ÿ—„๏ธ DB Migrations + +- **feat(migrations)**: New column `latency_p50` in `combo_metrics` table โ€” zero-breaking, safe for existing users + +### ๐Ÿ› Bug Fixes / Closures + +- **close(#411)**: better-sqlite3 hashed module resolution on Windows โ€” fixed in v2.6.10 (f02c5b5) +- **close(#409)**: GitHub Copilot chat completions fail with Claude models when files attached โ€” fixed in v2.6.9 (838f1d6) +- **close(#405)**: Duplicate of #411 โ€” resolved + +## [2.6.10] โ€” 2026-03-17 + +> Windows fix: better-sqlite3 prebuilt download without node-gyp/Python/MSVC (#426). + +### ๐Ÿ› Bug Fixes + +- **fix(install/#426)**: On Windows, `npm install -g omniroute` used to fail with `better_sqlite3.node is not a valid Win32 application` because the bundled native binary was compiled for Linux. Adds **Strategy 1.5** to `scripts/postinstall.mjs`: uses `@mapbox/node-pre-gyp install --fallback-to-build=false` (bundled within `better-sqlite3`) to download the correct prebuilt binary for the current OS/arch without requiring any build tools (no node-gyp, no Python, no MSVC). Falls back to `npm rebuild` only if the download fails. Adds platform-specific error messages with clear manual fix instructions. + +--- + +## [2.6.9] โ€” 2026-03-17 + +> CI fixes (t11 any-budget), bug fix #409 (file attachments via Copilot+Claude), release workflow correction. + +### ๐Ÿ› Bug Fixes + +- **fix(ci)**: Remove word "any" from comments in `openai-responses.ts` and `chatCore.ts` that were failing the t11 `\bany\b` budget check (false positive from regex counting comments) +- **fix(chatCore)**: Normalize unsupported content part types before forwarding to providers (#409 โ€” Cursor sends `{type:"file"}` when `.md` files are attached; Copilot and other OpenAI-compat providers reject with "type has to be either 'image_url' or 'text'"; fix converts `file`/`document` blocks to `text` and drops unknown types) + +### ๐Ÿ”ง Workflow + +- **chore(generate-release)**: Add ATOMIC COMMIT RULE โ€” version bump (`npm version patch`) MUST happen before committing feature files to ensure tag always points to a commit containing all version changes together + +--- + +## [2.6.8] โ€” 2026-03-17 + +> Sprint: Combo as Agent (system prompt + tool filter), Context Caching Protection, Auto-Update, Detailed Logs, MITM Kiro IDE. + +### ๐Ÿ—„๏ธ DB Migrations (zero-breaking โ€” safe for existing users) + +- **005_combo_agent_fields.sql**: `ALTER TABLE combos ADD COLUMN system_message TEXT DEFAULT NULL`, `tool_filter_regex TEXT DEFAULT NULL`, `context_cache_protection INTEGER DEFAULT 0` +- **006_detailed_request_logs.sql**: New `request_detail_logs` table with 500-entry ring-buffer trigger, opt-in via settings toggle + +### Funkce + +- **feat(combo)**: System Message Override per Combo (#399 โ€” `system_message` field replaces or injects system prompt before forwarding to provider) +- **feat(combo)**: Tool Filter Regex per Combo (#399 โ€” `tool_filter_regex` keeps only tools matching pattern; supports OpenAI + Anthropic formats) +- **feat(combo)**: Context Caching Protection (#401 โ€” `context_cache_protection` tags responses with `provider/model` and pins model for session continuity) +- **feat(settings)**: Auto-Update via Settings (#320 โ€” `GET /api/system/version` + `POST /api/system/update` โ€” checks npm registry and updates in background with pm2 restart) +- **feat(logs)**: Detailed Request Logs (#378 โ€” captures full pipeline bodies at 4 stages: client request, translated request, provider response, client response โ€” opt-in toggle, 64KB trim, 500-entry ring-buffer) +- **feat(mitm)**: MITM Kiro IDE profile (#336 โ€” `src/mitm/targets/kiro.ts` targets api.anthropic.com, reuses existing MITM infrastructure) + +--- + +## [2.6.7] โ€” 2026-03-17 + +> Sprint: SSE improvements, local provider_nodes extensions, proxy registry, Claude passthrough fixes. + +### Funkce + +- **feat(health)**: Background health check for local `provider_nodes` with exponential backoff (30sโ†’300s) and `Promise.allSettled` to avoid blocking (#423, @Regis-RCR) +- **feat(embeddings)**: Route `/v1/embeddings` to local `provider_nodes` โ€” `buildDynamicEmbeddingProvider()` with hostname validation (#422, @Regis-RCR) +- **feat(audio)**: Route TTS/STT to local `provider_nodes` โ€” `buildDynamicAudioProvider()` with SSRF protection (#416, @Regis-RCR) +- **feat(proxy)**: Proxy registry, management APIs, and quota-limit generalization (#429, @Regis-RCR) + +### ๐Ÿ› Bug Fixes + +- **fix(sse)**: Strip Claude-specific fields (`metadata`, `anthropic_version`) when target is OpenAI-compat (#421, @prakersh) +- **fix(sse)**: Extract Claude SSE usage (`input_tokens`, `output_tokens`, cache tokens) in passthrough stream mode (#420, @prakersh) +- **fix(sse)**: Generate fallback `call_id` for tool calls with missing/empty IDs (#419, @prakersh) +- **fix(sse)**: Claude-to-Claude passthrough โ€” forward body completely untouched, no re-translation (#418, @prakersh) +- **fix(sse)**: Filter orphaned `tool_result` items after Claude Code context compaction to avoid 400 errors (#417, @prakersh) +- **fix(sse)**: Skip empty-name tool calls in Responses API translator to prevent `placeholder_tool` infinite loops (#415, @prakersh) +- **fix(sse)**: Strip empty text content blocks before translation (#427, @prakersh) +- **fix(api)**: Add `refreshable: true` to Claude OAuth test config (#428, @prakersh) + +### ๐Ÿ“ฆ Dependencies + +- Bump `vitest`, `@vitest/*` and related devDependencies (#414, @dependabot) + +--- + +## [2.6.6] โ€” 2026-03-17 + +> Hotfix: Turbopack/Docker compatibility โ€” remove `node:` protocol from all `src/` imports. + +### ๐Ÿ› Bug Fixes + +- **fix(build)**: Removed `node:` protocol prefix from `import` statements in 17 files under `src/`. The `node:fs`, `node:path`, `node:url`, `node:os` etc. imports caused `Ecmascript file had an error` on Turbopack builds (Next.js 15 Docker) and on upgrades from older npm global installs. Affected files: `migrationRunner.ts`, `core.ts`, `backup.ts`, `prompts.ts`, `dataPaths.ts`, and 12 others in `src/app/api/` and `src/lib/`. +- **chore(workflow)**: Updated `generate-release.md` to make Docker Hub sync and dual-VPS deploy **mandatory** steps in every release. + +--- + +## [2.6.5] โ€” 2026-03-17 + +> Sprint: reasoning model param filtering, local provider 404 fix, Kilo Gateway provider, dependency bumps. + +### โœจ New Features + +- **feat(api)**: Added **Kilo Gateway** (`api.kilo.ai`) as a new API Key provider (alias `kg`) โ€” 335+ models, 6 free models, 3 auto-routing models (`kilo-auto/frontier`, `kilo-auto/balanced`, `kilo-auto/free`). Passthrough models supported via `/api/gateway/models` endpoint. (PR #408 by @Regis-RCR) + +### ๐Ÿ› Bug Fixes + +- **fix(sse)**: Strip unsupported parameters for reasoning models (o1, o1-mini, o1-pro, o3, o3-mini). Models in the `o1`/`o3` family reject `temperature`, `top_p`, `frequency_penalty`, `presence_penalty`, `logprobs`, `top_logprobs`, and `n` with HTTP 400. Parameters are now stripped at the `chatCore` layer before forwarding. Uses a declarative `unsupportedParams` field per model and a precomputed O(1) Map for lookup. (PR #412 by @Regis-RCR) +- **fix(sse)**: Local provider 404 now results in a **model-only lockout (5 seconds)** instead of a connection-level lockout (2 minutes). When a local inference backend (Ollama, LM Studio, oMLX) returns 404 for an unknown model, the connection remains active and other models continue working immediately. Also fixes a pre-existing bug where `model` was not passed to `markAccountUnavailable()`. Local providers detected via hostname (`localhost`, `127.0.0.1`, `::1`, extensible via `LOCAL_HOSTNAMES` env var). (PR #410 by @Regis-RCR) + +### ๐Ÿ“ฆ Dependencies - `better-sqlite3` 12.6.2 โ†’ 12.8.0 - `undici` 7.24.2 โ†’ 7.24.4 @@ -278,438 +2014,438 @@ --- -## [2.6.4] โ€” 17. 3. 2026 +## [2.6.4] โ€” 2026-03-17 -### ๐Ÿ› Opravy chyb +### ๐Ÿ› Bug Fixes -- **fix(providers)** : Odstranฤ›ny neexistujรญcรญ nรกzvy modelลฏ u 5 poskytovatelลฏ: - - **gemini / gemini-cli** : odstranฤ›ny `gemini-3.1-pro/flash` a `gemini-3-*-preview` (neexistujรญ v Google API v1beta); nahrazeny `gemini-2.5-pro` , `gemini-2.5-flash` , `gemini-2.0-flash` , `gemini-1.5-pro/flash` - - **antigravity** : odstranฤ›ny `gemini-3.1-pro-high/low` a `gemini-3-flash` (neplatnรฉ internรญ aliasy); nahrazeny skuteฤnรฝmi modely z verze 2.x - - **github (Copilot)** : odstranฤ›ny `gemini-3-flash-preview` a `gemini-3-pro-preview` ; nahrazeny `gemini-2.5-flash` - - **nvidia** : opraveno `nvidia/llama-3.3-70b-instruct` โ†’ `meta/llama-3.3-70b-instruct` (NVIDIA NIM pouลพรญvรก pro modely Meta jmennรฝ prostor `meta/` /); pล™idรกny `nvidia/llama-3.1-70b-instruct` a `nvidia/llama-3.1-405b-instruct` -- **fix(db/combo)** : Aktualizovรกno `free-stack` combo na vzdรกlenรฉ databรกzi: odstranฤ›no `qw/qwen3-coder-plus` (proลกlรฝ obnovovacรญ token), opraveno `nvidia/llama-3.3-70b-instruct` โ†’ `nvidia/meta/llama-3.3-70b-instruct` , opraveno `gemini/gemini-3.1-flash` โ†’ `gemini/gemini-2.5-flash` , pล™idรกno `if/deepseek-v3.2` +- **fix(providers)**: Removed non-existent model names across 5 providers: + - **gemini / gemini-cli**: removed `gemini-3.1-pro/flash` and `gemini-3-*-preview` (don't exist in Google API v1beta); replaced with `gemini-2.5-pro`, `gemini-2.5-flash`, `gemini-2.0-flash`, `gemini-1.5-pro/flash` + - **antigravity**: removed `gemini-3.1-pro-high/low` and `gemini-3-flash` (invalid internal aliases); replaced with real 2.x models + - **github (Copilot)**: removed `gemini-3-flash-preview` and `gemini-3-pro-preview`; replaced with `gemini-2.5-flash` + - **nvidia**: corrected `nvidia/llama-3.3-70b-instruct` โ†’ `meta/llama-3.3-70b-instruct` (NVIDIA NIM uses `meta/` namespace for Meta models); added `nvidia/llama-3.1-70b-instruct` and `nvidia/llama-3.1-405b-instruct` +- **fix(db/combo)**: Updated `free-stack` combo on remote DB: removed `qw/qwen3-coder-plus` (expired refresh token), corrected `nvidia/llama-3.3-70b-instruct` โ†’ `nvidia/meta/llama-3.3-70b-instruct`, corrected `gemini/gemini-3.1-flash` โ†’ `gemini/gemini-2.5-flash`, added `if/deepseek-v3.2` --- -## [2.6.3] โ€” 16. 3. 2026 +## [2.6.3] โ€” 2026-03-16 -> Sprint: hash-strip zod/pino zapeฤenรฝ do build pipeline, pล™idรกn syntetickรฝ poskytovatel, opravena cesta VPS PM2. +> Sprint: zod/pino hash-strip baked into build pipeline, Synthetic provider added, VPS PM2 path corrected. -### ๐Ÿ› Opravy chyb +### ๐Ÿ› Bug Fixes -- **fix(build)** : Turbopack hash-strip se nynรญ spouลกtรญ pล™i **kompilaci** pro Vล ECHNY balรญฤky โ€” nejen `better-sqlite3` . Krok 5.6 v `prepublish.mjs` prochรกzรญ kaลพdรฝ `.js` v `app/.next/server/` a odstraลˆuje 16znakovou hexadecimรกlnรญ pล™รญponu z jakรฉkoli hashovanรฉ `require()` . Opravuje `zod-dcb22c...` , `pino-...` atd. MODULE_NOT_FOUND u globรกlnรญch instalacรญ npm. Zavรญrรก #398. -- **Oprava (nasazenรญ)** : PM2 na obou VPS ukazoval na zastaralรฉ adresรกล™e git-clone. V globรกlnรญm balรญฤku npm pล™ekonfigurovรกno na `app/server.js` . Aktualizovรกn pracovnรญ postup `/deploy-vps` pro pouลพitรญ `npm pack + scp` (registr npm odmรญtรก balรญฤky o velikosti 299 MB). +- **fix(build)**: Turbopack hash-strip now runs at **compile time** for ALL packages โ€” not just `better-sqlite3`. Step 5.6 in `prepublish.mjs` walks every `.js` in `app/.next/server/` and strips the 16-char hex suffix from any hashed `require()`. Fixes `zod-dcb22c...`, `pino-...`, etc. MODULE_NOT_FOUND on global npm installs. Closes #398 +- **fix(deploy)**: PM2 on both VPS was pointing to stale git-clone directories. Reconfigured to `app/server.js` in the npm global package. Updated `/deploy-vps` workflow to use `npm pack + scp` (npm registry rejects 299MB packages). -### โœจ Funkce +### Funkce -- **feat(provider)** : Synthetic ( [synthetic.new](https://synthetic.new) ) โ€” inference kompatibilnรญ s OpenAI zamฤ›ล™enรก na soukromรญ. `passthroughModels: true` pro dynamickรฝ katalog modelลฏ HuggingFace. Poฤรกteฤnรญ modely: Kimi K2.5, MiniMax M2.5, GLM 4.7, DeepSeek V3.2. (PR #404 od @Regis-RCR) +- **feat(provider)**: Synthetic ([synthetic.new](https://synthetic.new)) โ€” privacy-focused OpenAI-compatible inference. `passthroughModels: true` for dynamic HuggingFace model catalog. Initial models: Kimi K2.5, MiniMax M2.5, GLM 4.7, DeepSeek V3.2. (PR #404 by @Regis-RCR) -### ๐Ÿ“‹ Problรฉmy uzavล™eny +### ๐Ÿ“‹ Issues Closed -- **zavล™รญt #398** : regrese hashovรกnรญ npm โ€” opraveno hashovรกnรญm pล™i kompilaci v prepublish -- **triรกลพ ฤ. 324** : Snรญmek obrazovky s chybou bez krokลฏ โ€“ poลพadovรกny podrobnosti o reprodukci +- **close #398**: npm hash regression โ€” fixed by compile-time hash-strip in prepublish +- **triage #324**: Bug screenshot without steps โ€” requested reproduction details --- -## [2.6.2] โ€” 16. 3. 2026 +## [2.6.2] โ€” 2026-03-16 -> Sprint: hashovรกnรญ modulลฏ kompletnฤ› opraveno, slouฤeny 2 PR (filtr Anthropic tools + vlastnรญ cesty k endpointลฏm), pล™idรกn poskytovatel Alibaba Cloud DashScope, uzavล™eny 3 zastaralรฉ problรฉmy. +> Sprint: module hashing fully fixed, 2 PRs merged (Anthropic tools filter + custom endpoint paths), Alibaba Cloud DashScope provider added, 3 stale issues closed. -### ๐Ÿ› Opravy chyb +### ๐Ÿ› Bug Fixes -- **fix(build)** : Rozลกรญล™eno hashovรกnรญ `externals` webpacku tak, aby zahrnovalo Vล ECHNY `serverExternalPackages` , nejen `better-sqlite3` . Next.js 16 Turbopack hashuje `zod` , `pino` a vลกechny ostatnรญ externรญ balรญฤky serveru do nรกzvลฏ jako `zod-dcb22c6336e0bc69` , kterรฉ za bฤ›hu v `node_modules` neexistujรญ. HASH_PATTERN regex catch-all nynรญ odstraลˆuje 16znakovou pล™รญponu a vracรญ se k zรกkladnรญmu nรกzvu balรญฤku. Takรฉ pล™idรกna `NEXT_PRIVATE_BUILD_WORKER=0` v `prepublish.mjs` pro posรญlenรญ reลพimu webpacku a nรกslednรฉ skenovรกnรญ po sestavenรญ, kterรฉ hlรกsรญ vลกechny zbรฝvajรญcรญ hashovanรฉ reference. (#396, #398, PR #403) -- **fix(chat)** : Nรกzvy nรกstrojลฏ v anthropic formรกtu ( `tool.name` bez wrapperu `.function` ) byly tiลกe vynechรกny filtrem prรกzdnรฝch nรกzvลฏ zavedenรฝm v bodฤ› #346. LiteLLM proxyuje poลพadavky s prefixem `anthropic/` ve formรกtu Anthropic Messages API, coลพ zpลฏsobuje filtrovรกnรญ vลกech nรกstrojลฏ a Anthropic vracรญ chybu `400: tool_choice.any may only be specified while providing tools` . Opraveno nรกvratem k `tool.name` , kdyลพ chybรญ `tool.function.name` . Pล™idรกno 8 regresnรญch jednotkovรฝch testลฏ. (PR #397) +- **fix(build)**: Extended webpack `externals` hash-strip to cover ALL `serverExternalPackages`, not just `better-sqlite3`. Next.js 16 Turbopack hashes `zod`, `pino`, and every other server-external package into names like `zod-dcb22c6336e0bc69` that don't exist in `node_modules` at runtime. A HASH_PATTERN regex catch-all now strips the 16-char suffix and falls back to the base package name. Also added `NEXT_PRIVATE_BUILD_WORKER=0` in `prepublish.mjs` to reinforce webpack mode, plus a post-build scan that reports any remaining hashed refs. (#396, #398, PR #403) +- **fix(chat)**: Anthropic-format tool names (`tool.name` without `.function` wrapper) were silently dropped by the empty-name filter introduced in #346. LiteLLM proxies requests with `anthropic/` prefix in Anthropic Messages API format, causing all tools to be filtered and Anthropic to return `400: tool_choice.any may only be specified while providing tools`. Fixed by falling back to `tool.name` when `tool.function.name` is absent. Added 8 regression unit tests. (PR #397) -### โœจ Funkce +### Funkce -- **feat(api)** : Vlastnรญ cesty koncovรฝch bodลฏ pro uzly poskytovatelลฏ kompatibilnรญ s OpenAI โ€” konfigurace `chatPath` a `modelsPath` pro kaลพdรฝ uzel (napล™. `/v4/chat/completions` ) v uลพivatelskรฉm rozhranรญ pro pล™ipojenรญ poskytovatele. Zahrnuje migraci databรกze ( `003_provider_node_custom_paths.sql` ) a sanitizaci cesty URL (bez `..` traversal, musรญ zaฤรญnat znakem `/` ). (PR #400) -- **feat(provider)** : Alibaba Cloud DashScope pล™idรกn jako poskytovatel kompatibilnรญ s OpenAI. Mezinรกrodnรญ endpoint: `dashscope-intl.aliyuncs.com/compatible-mode/v1` . 12 modelลฏ: `qwen-max` , `qwen-plus` , `qwen-turbo` , `qwen3-coder-plus/flash` , `qwq-plus` , `qwq-32b` , `qwen3-32b` , `qwen3-235b-a22b` . Autorizace: Nosnรฝ API klรญฤ. +- **feat(api)**: Custom endpoint paths for OpenAI-compatible provider nodes โ€” configure `chatPath` and `modelsPath` per node (e.g. `/v4/chat/completions`) in the provider connection UI. Includes a DB migration (`003_provider_node_custom_paths.sql`) and URL path sanitization (no `..` traversal, must start with `/`). (PR #400) +- **feat(provider)**: Alibaba Cloud DashScope added as OpenAI-compatible provider. International endpoint: `dashscope-intl.aliyuncs.com/compatible-mode/v1`. 12 models: `qwen-max`, `qwen-plus`, `qwen-turbo`, `qwen3-coder-plus/flash`, `qwq-plus`, `qwq-32b`, `qwen3-32b`, `qwen3-235b-a22b`. Auth: Bearer API key. -### ๐Ÿ“‹ Problรฉmy uzavล™eny +### ๐Ÿ“‹ Issues Closed -- **zavล™รญt #323** : Chyba pล™ipojenรญ Cline `[object Object]` โ€“ opraveno ve verzi 2.3.7; uลพivateli bylo doruฤeno pokyny k upgradu z verze 2.2.9 -- **zavล™รญt #337** : Sledovรกnรญ รบvฤ›ru Kiro โ€” implementovรกno ve verzi 2.5.5 (#381); odkรกzalo uลพivatele na Dashboard โ†’ Pouลพitรญ -- **triage #402** : Poลกkozenรฝ soubor ARM64 macOS DMG โ€“ poลพadovanรก verze macOS, pล™esnรก chyba a doporuฤenรฉ alternativnรญ ล™eลกenรญ `xattr -d com.apple.quarantine` +- **close #323**: Cline connection error `[object Object]` โ€” fixed in v2.3.7; instructed user to upgrade from v2.2.9 +- **close #337**: Kiro credit tracking โ€” implemented in v2.5.5 (#381); pointed user to Dashboard โ†’ Usage +- **triage #402**: ARM64 macOS DMG damaged โ€” requested macOS version, exact error, and advised `xattr -d com.apple.quarantine` workaround --- -## [2.6.1] โ€” 15. 3. 2026 +## [2.6.1] โ€” 2026-03-15 -> Kritickรก oprava pล™i spuลกtฤ›nรญ: Globรกlnรญ instalace npm v2.6.0 havarovaly s chybou 500 kvลฏli chybฤ› hashovรกnรญ nรกzvลฏ modulลฏ Turbopack/webpack v instrumentaฤnรญm hooku Next.js 16. +> Critical startup fix: v2.6.0 global npm installs crashed with a 500 error due to a Turbopack/webpack module-name hashing bug in the Next.js 16 instrumentation hook. -### ๐Ÿ› Opravy chyb +### ๐Ÿ› Bug Fixes -- **fix(build)** : Vynutit, aby byl `better-sqlite3` vลพdy vyลพadovรกn pล™esnรฝm nรกzvem balรญฤku v balรญฤku webpack server. Next.js 16 zkompiloval instrumentaฤnรญ hook do samostatnรฉho chunku a vygeneroval `require('better-sqlite3-')` โ€” hashovanรฝ nรกzev modulu, kterรฝ neexistuje v `node_modules` โ€” pล™estoลพe byl balรญฤek uveden v `serverExternalPackages` . Do konfigurace webpacku serveru byla pล™idรกna explicitnรญ funkce `externals` , takลพe bundler vลพdy vygeneruje `require('better-sqlite3')` , ฤรญmลพ se vyล™eลกรญ `500 Internal Server Error` pล™i spuลกtฤ›nรญ ฤistรฝch globรกlnรญch instalacรญ. (#394, PR #395) +- **fix(build)**: Force `better-sqlite3` to always be required by its exact package name in the webpack server bundle. Next.js 16 compiled the instrumentation hook into a separate chunk and emitted `require('better-sqlite3-')` โ€” a hashed module name that doesn't exist in `node_modules` โ€” even though the package was listed in `serverExternalPackages`. Added an explicit `externals` function to the server webpack config so the bundler always emits `require('better-sqlite3')`, resolving the startup `500 Internal Server Error` on clean global installs. (#394, PR #395) ### ๐Ÿ”ง CI -- **ci** : Do `npm-publish.yml` pล™idรกna `workflow_dispatch` se zabezpeฤenรญm synchronizace verzรญ pro manuรกlnรญ spouลกtฤ›ฤe (#392). -- **ci** : Pล™idรกn `workflow_dispatch` do `docker-publish.yml` , aktualizovรกny akce GitHubu na nejnovฤ›jลกรญ verze (#392) +- **ci**: Added `workflow_dispatch` to `npm-publish.yml` with version sync safeguard for manual triggers (#392) +- **ci**: Added `workflow_dispatch` to `docker-publish.yml`, updated GitHub Actions to latest versions (#392) --- -## [2.6.0] - 15. 3. 2026 +## [2.6.0] - 2026-03-15 -> Sprint ล™eลกenรญ problรฉmลฏ: Opraveny 4 chyby, vylepลกeno uลพivatelskรฉ rozhranรญ protokolลฏ, pล™idรกno sledovรกnรญ kreditลฏ Kiro. +> Issue resolution sprint: 4 bugs fixed, logs UX improved, Kiro credit tracking added. -### ๐Ÿ› Opravy chyb +### ๐Ÿ› Bug Fixes -- **oprava(mรฉdia)** : ComfyUI a SD WebUI se jiลพ nezobrazujรญ v seznamu poskytovatelลฏ na strรกnce Mรฉdia, pokud nejsou nakonfigurovรกny โ€” pล™i pล™ipojenรญ naฤtou `/api/providers` a skryjรญ lokรกlnรญ poskytovatele bez pล™ipojenรญ (#390) -- **oprava(auth)** : Round-robin jiลพ po zpoลพdฤ›nรญ znovu nevybรญrรก รบฤty s omezenou rychlostรญ ihned โ€“ `backoffLevel` se nynรญ pouลพรญvรก jako primรกrnรญ tล™รญdicรญ klรญฤ v rotaci LRU (#340) -- **oprava(oauth)** : Qoder (a dalลกรญ poskytovatelรฉ, kteล™รญ pล™esmฤ›rovรกvajรญ na svรฉ vlastnรญ uลพivatelskรฉ rozhranรญ) jiลพ nenechรกvajรญ modรกlnรญ okno OAuth zaseknutรฉ na โ€žฤŒekรกnรญ na autorizaciโ€œ โ€“ detektor zavล™enรฝch vyskakovacรญch oken automaticky pล™echรกzรญ do reลพimu ruฤnรญho zadรกvรกnรญ URL (#344) -- **oprava(logy)** : Tabulka protokolลฏ poลพadavkลฏ je nynรญ ฤitelnรก ve svฤ›tlรฉm reลพimu โ€“ stavovรฉ odznaky, poฤty tokenลฏ a kombinovanรฉ tagy pouลพรญvajรญ adaptivnรญ `dark:` barevnรฉ tล™รญdy (#378) +- **fix(media)**: ComfyUI and SD WebUI no longer appear in the Media page provider list when unconfigured โ€” fetches `/api/providers` on mount and hides local providers with no connections (#390) +- **fix(auth)**: Round-robin no longer re-selects rate-limited accounts immediately after cooldown โ€” `backoffLevel` is now used as primary sort key in the LRU rotation (#340) +- **fix(oauth)**: Qoder (and other providers that redirect to their own UI) no longer leave the OAuth modal stuck at "Waiting for Authorization" โ€” popup-closed detector auto-transitions to manual URL input mode (#344) +- **fix(logs)**: Request log table is now readable in light mode โ€” status badges, token counts, and combo tags use adaptive `dark:` color classes (#378) -### โœจ Funkce +### Funkce -- **feat(kiro)** : Do fetcheru vyuลพitรญ pล™idรกno sledovรกnรญ kreditลฏ Kiro โ€” dotazy `getUserCredits` z endpointu AWS CodeWhisperer (#337) +- **feat(kiro)**: Kiro credit tracking added to usage fetcher โ€” queries `getUserCredits` from AWS CodeWhisperer endpoint (#337) -### ๐Ÿ›  Domรกcรญ prรกce +### ๐Ÿ›  Chores -- **chore(tests)** : Zarovnรกnรญ `test:plan3` , `test:fixes` , `test:security` pro pouลพitรญ stejnรฉho zavadฤ›ฤe `tsx/esm` jako u `npm test` โ€“ eliminuje faleลกnฤ› negativnรญ vรฝsledky rozliลกenรญ modulลฏ v cรญlenรฝch bฤ›zรญch (PR #386) +- **chore(tests)**: Aligned `test:plan3`, `test:fixes`, `test:security` to use same `tsx/esm` loader as `npm test` โ€” eliminates module resolution false negatives in targeted runs (PR #386) --- -## [2.5.9] - 15. 3. 2026 +## [2.5.9] - 2026-03-15 -> Oprava nativnรญ passthrough Codexu + posรญlenรญ validace tฤ›la trasy. +> Codex native passthrough fix + route body validation hardening. -### ๐Ÿ› Opravy chyb +### ๐Ÿ› Bug Fixes -- **fix(codex)** : Zachovรกvรก nativnรญ prลฏchod Responses API pro klienty Codexu โ€“ zabraลˆuje zbyteฤnรฝm mutacรญm pล™ekladu (PR #387) -- **fix(api)** : Ovฤ›ล™ovรกnรญ tฤ›l poลพadavkลฏ na trasรกch pro stanovenรญ cen/synchronizaci a smฤ›rovรกnรญ รบloh โ€“ zabraลˆuje pรกdลฏm zpลฏsobenรฝm chybnฤ› formรกtovanรฝmi vstupy (PR #388) -- **fix(auth)** : Tajnรฉ hodnoty JWT pล™etrvรกvajรญ i po restartech pomocรญ `src/lib/db/secrets.ts` โ€” eliminuje chyby 401 po restartu PM2 (PR #388) +- **fix(codex)**: Preserve native Responses API passthrough for Codex clients โ€” avoids unnecessary translation mutations (PR #387) +- **fix(api)**: Validate request bodies on pricing/sync and task-routing routes โ€” prevents crashes from malformed inputs (PR #388) +- **fix(auth)**: JWT secrets persist across restarts via `src/lib/db/secrets.ts` โ€” eliminates 401 errors after pm2 restart (PR #388) --- -## [2.5.8] - 15. 3. 2026 +## [2.5.8] - 2026-03-15 -> Oprava sestavenรญ: obnovenรญ pล™ipojenรญ VPS pล™eruลกenรฉho nedokonฤenรฝm publikovรกnรญm v2.5.7. +> Build fix: restore VPS connectivity broken by v2.5.7 incomplete publish. -### ๐Ÿ› Opravy chyb +### ๐Ÿ› Bug Fixes -- **oprava(build)** : `scripts/prepublish.mjs` se stรกle pouลพรญvajรญ, zastaralรฝ pล™รญznak `--webpack` zpลฏsobuje tichรฉ selhรกnรญ samostatnรฉho sestavenรญ Next.js โ€” publikovรกnรญ npm dokonฤeno bez `app/server.js` , coลพ naruลกuje nasazenรญ VPS +- **fix(build)**: `scripts/prepublish.mjs` still used deprecated `--webpack` flag causing Next.js standalone build to fail silently โ€” npm publish completed without `app/server.js`, breaking VPS deployment --- -## [2.5.7] - 15. 3. 2026 +## [2.5.7] - 2026-03-15 -> Opravy chyb pล™i zpracovรกnรญ v Media Playground. +> Media playground error handling fixes. -### ๐Ÿ› Opravy chyb +### ๐Ÿ› Bug Fixes -- **oprava(mรฉdia)** : Pล™epis โ€žVyลพadovรกn klรญฤ APIโ€œ faleลกnฤ› pozitivnรญ, pokud zvuk neobsahuje ลพรกdnou ล™eฤ (hudba, ticho) โ€“ nynรญ se mรญsto toho zobrazuje โ€žNenรญ detekovรกna ลพรกdnรก ล™eฤโ€œ -- **oprava(media)** : `upstreamErrorResponse` v `audioTranscription.ts` a `audioSpeech.ts` nynรญ vracรญ sprรกvnรฝ JSON ( `{error:{message}}` ), coลพ umoลพลˆuje sprรกvnou detekci chyb pล™ihlaลกovacรญch รบdajลฏ 401/403 v MediaPageClient -- **oprava(mรฉdia)** : `parseApiError` nynรญ zpracovรกvรก pole `err_msg` v Deepgramu a detekuje `"api key"` v chybovรฝch zprรกvรกch pro pล™esnou klasifikaci chyb pล™ihlaลกovacรญch รบdajลฏ. +- **fix(media)**: Transcription "API Key Required" false positive when audio contains no speech (music, silence) โ€” now shows "No speech detected" instead +- **fix(media)**: `upstreamErrorResponse` in `audioTranscription.ts` and `audioSpeech.ts` now returns proper JSON (`{error:{message}}`), enabling correct 401/403 credential error detection in the MediaPageClient +- **fix(media)**: `parseApiError` now handles Deepgram's `err_msg` field and detects `"api key"` in error messages for accurate credential error classification --- -## [2.5.6] - 15. 3. 2026 +## [2.5.6] - 2026-03-15 -> Kritickรฉ opravy zabezpeฤenรญ/autentizace: OAuth v Antigravity nefunkฤnรญ + relace JWT ztraceny po restartu. +> Critical security/auth fixes: Antigravity OAuth broken + JWT sessions lost after restart. -### ๐Ÿ› Opravy chyb +### ๐Ÿ› Bug Fixes -- **fix(oauth) #384** : Antigravity Google OAuth nynรญ sprรกvnฤ› odesรญlรก `client_secret` do koncovรฉho bodu tokenu. Zรกloลพnรญ volbou pro `ANTIGRAVITY_OAUTH_CLIENT_SECRET` byl prรกzdnรฝ ล™etฤ›zec, coลพ je chyba โ€“ `client_secret` tedy nebyl v poลพadavku nikdy zahrnut, coลพ zpลฏsobovalo chyby `"client_secret is missing"` u vลกech uลพivatelลฏ bez vlastnรญ promฤ›nnรฉ prostล™edรญ. Zavรญrรก #383. -- **fix(auth) #385** : `JWT_SECRET` je nynรญ uklรกdรกn do SQLite ( `namespace='secrets'` ) pล™i prvnรญ generaci a znovu naฤten pล™i nรกslednรฝch spuลกtฤ›nรญch. Dล™รญve byl pล™i kaลพdรฉm spuลกtฤ›nรญ procesu generovรกn novรฝ nรกhodnรฝ tajnรฝ klรญฤ, kterรฝ po jakรฉmkoli restartu nebo upgradu zneplatลˆoval vลกechny existujรญcรญ soubory cookie/relace. Ovlivลˆuje `JWT_SECRET` i `API_KEY_SECRET` . Zavรญrรก #382. +- **fix(oauth) #384**: Antigravity Google OAuth now correctly sends `client_secret` to the token endpoint. The fallback for `ANTIGRAVITY_OAUTH_CLIENT_SECRET` was an empty string, which is falsy โ€” so `client_secret` was never included in the request, causing `"client_secret is missing"` errors for all users without a custom env var. Closes #383. +- **fix(auth) #385**: `JWT_SECRET` is now persisted to SQLite (`namespace='secrets'`) on first generation and reloaded on subsequent starts. Previously, a new random secret was generated each process startup, invalidating all existing cookies/sessions after any restart or upgrade. Affects both `JWT_SECRET` and `API_KEY_SECRET`. Closes #382. --- -## [2.5.5] - 15. 3. 2026 +## [2.5.5] - 2026-03-15 -> Oprava odstranฤ›nรญ duplicitnรญch dat v seznamu modelลฏ, posรญlenรญ samostatnรฉho sestavenรญ Electronu a sledovรกnรญ kreditลฏ Kiro. +> Model list dedup fix, Electron standalone build hardening, and Kiro credit tracking. -### ๐Ÿ› Opravy chyb +### ๐Ÿ› Bug Fixes -- **fix(models) #380** : `GET /api/models` nynรญ zahrnuje aliasy poskytovatelลฏ pล™i sestavovรกnรญ filtru aktivnรญho poskytovatele โ€” modely pro `claude` (alias `cc` ) a `github` (alias `gh` ) se vลพdy zobrazovaly bez ohledu na to, zda bylo nakonfigurovรกno pล™ipojenรญ, protoลพe klรญฤe `PROVIDER_MODELS` jsou aliasy, ale pล™ipojenรญ k databรกzi jsou uloลพena pod ID poskytovatelลฏ. Opraveno rozลกรญล™enรญm kaลพdรฉho aktivnรญho ID poskytovatele o jeho alias pomocรญ `PROVIDER_ID_TO_ALIAS` . Zavรญrรก #353. -- **fix(electron) #379** : Novรฉ `scripts/prepare-electron-standalone.mjs` pล™ipravรญ vyhrazenรฝ balรญฤek `/.next/electron-standalone` pล™ed zabalenรญm Electronu. Pokud je `node_modules` symbolickรฝ odkaz, dojde k ukonฤenรญ s chybou (electron-builder by na sestavovacรญ stroj odeslal bฤ›hovou zรกvislost). Multiplatformnรญ sanitizace cest pomocรญ `path.basename` . Od @kfiramar. +- **fix(models) #380**: `GET /api/models` now includes provider aliases when building the active-provider filter โ€” models for `claude` (alias `cc`) and `github` (alias `gh`) were always shown regardless of whether a connection was configured, because `PROVIDER_MODELS` keys are aliases but DB connections are stored under provider IDs. Fixed by expanding each active provider ID to also include its alias via `PROVIDER_ID_TO_ALIAS`. Closes #353. +- **fix(electron) #379**: New `scripts/prepare-electron-standalone.mjs` stages a dedicated `/.next/electron-standalone` bundle before Electron packaging. Aborts with a clear error if `node_modules` is a symlink (electron-builder would ship a runtime dependency on the build machine). Cross-platform path sanitization via `path.basename`. By @kfiramar. -### โœจ Novรฉ funkce +### โœจ New Features -- **feat(kiro) #381** : Sledovรกnรญ zลฏstatku kreditลฏ Kiro โ€” koncovรฝ bod vyuลพitรญ nynรญ vracรญ data o kreditech pro Kiro รบฤty volรกnรญm `codewhisperer.us-east-1.amazonaws.com/getUserCredits` (stejnรฝ koncovรฝ bod, kterรฝ Kiro IDE pouลพรญvรก internฤ›). Vracรญ zbรฝvajรญcรญ kredity, celkovรฝ limit, datum obnovenรญ a รบroveลˆ pล™edplatnรฉho. Uzavรญrรก #337. +- **feat(kiro) #381**: Kiro credit balance tracking โ€” usage endpoint now returns credit data for Kiro accounts by calling `codewhisperer.us-east-1.amazonaws.com/getUserCredits` (same endpoint Kiro IDE uses internally). Returns remaining credits, total allowance, renewal date, and subscription tier. Closes #337. -## [2.5.4] - 15. 3. 2026 +## [2.5.4] - 2026-03-15 -> Oprava spouลกtฤ›nรญ loggeru, oprava zabezpeฤenรญ pล™ihlaลกovacรญho bootstrapu a vylepลกenรญ spolehlivosti vรฝvojรกล™skรฉho HMR. Zlepลกenรญ infrastruktury CI. +> Logger startup fix, login bootstrap security fix, and dev HMR reliability improvement. CI infrastructure hardened. -### ๐Ÿ› Opravy chyb (PR #374, #375, #376 od @kfiramar) +### ๐Ÿ› Bug Fixes (PRs #374, #375, #376 by @kfiramar) -- **oprava(logger) #376** : Obnovit cestu k protokolovacรญmu modulu pino transport โ€” `formatters.level` v kombinaci s `transport.targets` je odmรญtnut modulem pino. Konfigurace zaloลพenรฉ na transportu nynรญ odstraลˆujรญ formรกtovaฤ รบrovnรญ pomocรญ funkce `getTransportCompatibleConfig()` . Takรฉ opravuje numerickรฉ mapovรกnรญ รบrovnรญ v `/api/logs/console` : `30โ†’info, 40โ†’warn, 50โ†’error` (bylo posunuto o jednu). -- **oprava(login) #375** : Pล™ihlaลกovacรญ strรกnka se nynรญ bootuje z veล™ejnรฉho endpointu `/api/settings/require-login` namรญsto chrรกnฤ›nรฉho `/api/settings` . V nastavenรญch chrรกnฤ›nรฝch heslem dostรกvala strรกnka pล™edbฤ›ลพnรฉho ovฤ›ล™ovรกnรญ chybu 401 a zbyteฤnฤ› se vracela k bezpeฤnรฝm vรฝchozรญm hodnotรกm. Veล™ejnรก trasa nynรญ vracรญ vลกechna bootstrapovรก metadata ( `requireLogin` , `hasPassword` , `setupComplete` ) s konzervativnรญ fallback chybou 200. -- **oprava(dev) #374** : Pล™idรกnรญ `localhost` a `127.0.0.1` do `allowedDevOrigins` v `next.config.mjs` โ€” HMR websocket byl blokovรกn pล™i pล™รญstupu k aplikaci pล™es loopback adresu, coลพ opakovanฤ› produkovalo varovรกnรญ cross-origin. +- **fix(logger) #376**: Restore pino transport logger path โ€” `formatters.level` combined with `transport.targets` is rejected by pino. Transport-backed configs now strip the level formatter via `getTransportCompatibleConfig()`. Also corrects numeric level mapping in `/api/logs/console`: `30โ†’info, 40โ†’warn, 50โ†’error` (was shifted by one). +- **fix(login) #375**: Login page now bootstraps from the public `/api/settings/require-login` endpoint instead of the protected `/api/settings`. In password-protected setups, the pre-auth page was receiving a 401 and falling back to safe defaults unnecessarily. The public route now returns all bootstrap metadata (`requireLogin`, `hasPassword`, `setupComplete`) with a conservative 200 fallback on error. +- **fix(dev) #374**: Add `localhost` and `127.0.0.1` to `allowedDevOrigins` in `next.config.mjs` โ€” HMR websocket was blocked when accessing the app via loopback address, producing repeated cross-origin warnings. -### ๐Ÿ”ง CI a infrastruktura +### ๐Ÿ”ง CI & Infrastructure -- **Oprava chyb ESLint OOM** : `eslint.config.mjs` nynรญ ignoruje `vscode-extension/**` , `electron/**` , `docs/**` , `app/.next/**` a `clipr/**` โ€” ESLint havaroval s chybou JS haldy OOM skenovรกnรญm binรกrnรญch blobลฏ a kompilovanรฝch chunkลฏ VS Code. -- **Oprava jednotkovรฉho testu** : Z 2 testovacรญch souborลฏ byl odstranฤ›n zastaralรฝ `ALTER TABLE provider_connections ADD COLUMN "group"` โ€“ sloupec je nynรญ souฤรกstรญ zรกkladnรญho schรฉmatu (pล™idรกno v #373), coลพ zpลฏsobovalo `SQLITE_ERROR: duplicate column name` pล™i kaลพdรฉm spuลกtฤ›nรญ CI. -- **Pre-commit hook** : Do `.husky/pre-commit` pล™idรกn `npm run test:unit` โ€” unit testy nynรญ blokujรญ poลกkozenรฉ commity dล™รญve, neลพ se dostanou do CI. +- **ESLint OOM fix**: `eslint.config.mjs` now ignores `vscode-extension/**`, `electron/**`, `docs/**`, `app/.next/**`, and `clipr/**` โ€” ESLint was crashing with a JS heap OOM by scanning VS Code binary blobs and compiled chunks. +- **Unit test fix**: Removed stale `ALTER TABLE provider_connections ADD COLUMN "group"` from 2 test files โ€” column is now part of the base schema (added in #373), causing `SQLITE_ERROR: duplicate column name` on every CI run. +- **Pre-commit hook**: Added `npm run test:unit` to `.husky/pre-commit` โ€” unit tests now block broken commits before they reach CI. -## [2.5.3] - 14. 3. 2026 +## [2.5.3] - 2026-03-14 -> Opravy kritickรฝch chyb: migrace schรฉmatu databรกze, naฤรญtรกnรญ spouลกtฤ›cรญho prostล™edรญ, mazรกnรญ chyb poskytovatele a oprava popiskลฏ i18n. Vylepลกenรญ kvality kรณdu nad kaลพdรฝm PR. +> Critical bugfixes: DB schema migration, startup env loading, provider error state clearing, and i18n tooltip fix. Code quality improvements on top of each PR. -### ๐Ÿ› Opravy chyb (PR #369, #371, #372, #373 od @kfiramar) +### ๐Ÿ› Bug Fixes (PRs #369, #371, #372, #373 by @kfiramar) -- **oprava(db) #373** : Pล™idรกnรญ sloupce `provider_connections.group` do zรกkladnรญho schรฉmatu + migrace zpฤ›tnรฉho doplnฤ›nรญ pro existujรญcรญ databรกze โ€” sloupec byl pouลพit ve vลกech dotazech, ale chybฤ›l v definici schรฉmatu -- **fix(i18n) #371** : Nahrazenรญ neexistujรญcรญho klรญฤe `t("deleteConnection")` existujรญcรญm `providers.delete` โ€” oprava `MISSING_MESSAGE: providers.deleteConnection` na strรกnce s podrobnostmi o poskytovateli -- **oprava(auth) #372** : Vymazat zastaralรก chybovรก metadata ( `errorCode` , `lastErrorType` , `lastErrorSource` ) z รบฤtลฏ poskytovatelลฏ po skuteฤnรฉm zotavenรญ โ€“ dล™รญve se obnovenรฉ รบฤty zobrazovaly jako selhanรฉ -- **oprava(startup) #369** : Sjednocenรญ naฤรญtรกnรญ env napล™รญฤ `npm run start` , `run-standalone.mjs` a Electron s ohledem na prioritu `DATA_DIR/.env โ†’ ~/.omniroute/.env โ†’ ./.env` โ€” zabrรกnฤ›nรญ generovรกnรญ novรฉho `STORAGE_ENCRYPTION_KEY` pล™es existujรญcรญ ลกifrovanou databรกzi +- **fix(db) #373**: Add `provider_connections.group` column to base schema + backfill migration for existing databases โ€” column was used in all queries but missing from schema definition +- **fix(i18n) #371**: Replace non-existent `t("deleteConnection")` key with existing `providers.delete` key โ€” fixes `MISSING_MESSAGE: providers.deleteConnection` runtime error on provider detail page +- **fix(auth) #372**: Clear stale error metadata (`errorCode`, `lastErrorType`, `lastErrorSource`) from provider accounts after genuine recovery โ€” previously, recovered accounts kept appearing as failed +- **fix(startup) #369**: Unify env loading across `npm run start`, `run-standalone.mjs`, and Electron to respect `DATA_DIR/.env โ†’ ~/.omniroute/.env โ†’ ./.env` priority โ€” prevents generating a new `STORAGE_ENCRYPTION_KEY` over an existing encrypted database -### ๐Ÿ”ง Kvalita kรณdu +### ๐Ÿ”ง Code Quality -- Zdokumentovanรฉ vzory `result.success` vs. `response?.ok` v `auth.ts` (oba รบmyslnรฉ, nynรญ vysvฤ›tlenรฉ) -- Normalizovanรฉ `overridePath?.trim()` v `electron/main.js` pro shodu s `bootstrap-env.mjs` -- Pล™idรกn komentรกล™ k objednรกvce slouฤenรญ `preferredEnv` pล™i spuลกtฤ›nรญ Electronu +- Documented `result.success` vs `response?.ok` patterns in `auth.ts` (both intentional, now explained) +- Normalized `overridePath?.trim()` in `electron/main.js` to match `bootstrap-env.mjs` +- Added `preferredEnv` merge order comment in Electron startup -> Oprava kvรณt pro รบฤty Codex s automatickou rotacรญ, rychlรฝm pล™epรญnรกnรญm รบrovnรญ, modelem gpt-5.4 a oznaฤenรญm analytickรฝch nรกstrojลฏ. +> Codex account quota policy with auto-rotation, fast tier toggle, gpt-5.4 model, and analytics label fix. -### โœจ Novรฉ funkce (PR #366, #367, #368) +### โœจ New Features (PRs #366, #367, #368) -- **Zรกsady kvรณt Codexu (PR #366)** : Okno kvรณty 5 hodin/tรฝden pro รบฤet se pล™epรญnรก v dashboardu poskytovatele. รšฤty jsou automaticky pล™eskoฤeny, kdyลพ povolenรก okna dosรกhnou prahovรฉ hodnoty 90 %, a znovu povoleny po `resetAt` . Zahrnuje `quotaCache.ts` s vedlejลกรญm efektem pro zรญskรกvรกnรญ statusu zdarma. -- **Pล™epรญnรกnรญ rychlรฉ รบrovnฤ› Codexu (PR #367)** : Dashboard โ†’ Nastavenรญ โ†’ รšroveลˆ sluลพeb Codexu. Pล™epรญnรกnรญ ve vรฝchozรญm nastavenรญ vklรกdรก `service_tier: "flex"` pouze pro poลพadavky Codexu, coลพ sniลพuje nรกklady o ~80 %. Celรฝ stack: karta UI + koncovรฝ bod API + exekutor + pล™ekladaฤ + obnovenรญ po spuลกtฤ›nรญ. -- **Model gpt-5.4 (PR #368)** : Pล™idรกvรก `cx/gpt-5.4` a `codex/gpt-5.4` do registru modelลฏ Codex. Regresnรญ test je souฤรกstรญ. +- **Codex Quota Policy (PR #366)**: Per-account 5h/weekly quota window toggles in Provider dashboard. Accounts are automatically skipped when enabled windows reach 90% threshold and re-admitted after `resetAt`. Includes `quotaCache.ts` with side-effect free status getter. +- **Codex Fast Tier Toggle (PR #367)**: Dashboard โ†’ Settings โ†’ Codex Service Tier. Default-off toggle injects `service_tier: "flex"` only for Codex requests, reducing cost ~80%. Full stack: UI tab + API endpoint + executor + translator + startup restore. +- **gpt-5.4 Model (PR #368)**: Adds `cx/gpt-5.4` and `codex/gpt-5.4` to the Codex model registry. Regression test included. -### ๐Ÿ› Opravy chyb +### ๐Ÿ› Bug Fixes -- **oprava ฤ. 356** : Analytickรฉ grafy (Nejlepลกรญ poskytovatel, Podle รบฤtu, Rozdฤ›lenรญ poskytovatelลฏ) nynรญ zobrazujรญ lidsky ฤitelnรฉ nรกzvy/ลกtรญtky poskytovatelลฏ namรญsto nezpracovanรฝch internรญch ID u poskytovatelลฏ kompatibilnรญch s OpenAI. +- **fix #356**: Analytics charts (Top Provider, By Account, Provider Breakdown) now display human-readable provider names/labels instead of raw internal IDs for OpenAI-compatible providers. -> Hlavnรญ vydรกnรญ: strategie striktnฤ› nรกhodnรฉho smฤ›rovรกnรญ, ล™รญzenรญ pล™รญstupu k klรญฤลฏm API, skupiny pล™ipojenรญ, synchronizace externรญch cen a opravy kritickรฝch chyb pro modely myลกlenรญ, kombinovanรฉ testovรกnรญ a validaci nรกzvลฏ nรกstrojลฏ. +> Major release: strict-random routing strategy, API key access controls, connection groups, external pricing sync, and critical bug fixes for thinking models, combo testing, and tool name validation. -### โœจ Novรฉ funkce (PR #363 a #365) +### โœจ New Features (PRs #363 & #365) -- **Strategie striktnฤ› nรกhodnรฉho smฤ›rovรกnรญ** : Fisher-Yatesลฏv nรกhodnรฝ balรญฤek s garancรญ neopakovรกnรญ a serializacรญ mutexลฏ pro soubฤ›ลพnรฉ poลพadavky. Nezรกvislรฉ balรญฤky pro kaลพdรฉ kombo a providera. -- **ล˜รญzenรญ pล™รญstupu ke klรญฤลฏm API** : `allowedConnections` (omezenรญ pล™ipojenรญ, kterรก mลฏลพe klรญฤ pouลพรญvat), `is_active` (povolenรญ/zakรกzรกnรญ klรญฤe s kรณdem 403), `accessSchedule` (ล™รญzenรญ pล™รญstupu na zรกkladฤ› ฤasu), pล™epรญnรกnรญ `autoResolve` , pล™ejmenovรกnรญ klรญฤลฏ pomocรญ PATCH. -- **Skupiny pล™ipojenรญ** : Seskupovรกnรญ pล™ipojenรญ poskytovatelลฏ podle prostล™edรญ. Harmonickรฉ zobrazenรญ na strรกnce Limity s perzistencรญ localStorage a inteligentnรญm automatickรฝm pล™epรญnรกnรญm. -- **Synchronizace externรญch cen (LiteLLM)** : 3stupลˆovรฉ rozliลกenรญ cen (uลพivatelskรฉ pล™epsรกnรญ โ†’ synchronizace โ†’ vรฝchozรญ hodnoty). Moลพnost pล™ihlรกลกenรญ pล™es `PRICING_SYNC_ENABLED=true` . Nรกstroj MCP `omniroute_sync_pricing` . 23 novรฝch testลฏ. -- **i18n** : 30 jazykลฏ aktualizovรกno strategiรญ striktnรญ nรกhodnosti, ล™etฤ›zce pro sprรกvu klรญฤลฏ API. pt-BR plnฤ› pล™eloลพeno. +- **Strict-Random Routing Strategy**: Fisher-Yates shuffle deck with anti-repeat guarantee and mutex serialization for concurrent requests. Independent decks per combo and per provider. +- **API Key Access Controls**: `allowedConnections` (restrict which connections a key can use), `is_active` (enable/disable key with 403), `accessSchedule` (time-based access control), `autoResolve` toggle, rename keys via PATCH. +- **Connection Groups**: Group provider connections by environment. Accordion view in Limits page with localStorage persistence and smart auto-switch. +- **External Pricing Sync (LiteLLM)**: 3-tier pricing resolution (user overrides โ†’ synced โ†’ defaults). Opt-in via `PRICING_SYNC_ENABLED=true`. MCP tool `omniroute_sync_pricing`. 23 new tests. +- **i18n**: 30 languages updated with strict-random strategy, API key management strings. pt-BR fully translated. -### ๐Ÿ› Opravy chyb +### ๐Ÿ› Bug Fixes -- **Oprava ฤ. 355** : ฤŒasovรฝ limit neฤinnosti streamu zvรฝลกen z 60 s na 300 s โ€“ zabraลˆuje pล™eruลกenรญ modelลฏ s rozลกรญล™enรฝm myลกlenรญm (claude-opus-4-6, o3 atd.) bฤ›hem dlouhรฝch fรกzรญ uvaลพovรกnรญ. Konfigurovatelnรฉ pomocรญ `STREAM_IDLE_TIMEOUT_MS` . -- **Oprava ฤ. 350** : Kombinovanรฝ test nynรญ obchรกzรญ `REQUIRE_API_KEY=true` pomocรญ internรญ hlaviฤky a univerzรกlnฤ› pouลพรญvรก formรกt kompatibilnรญ s OpenAI. ฤŒasovรฝ limit prodlouลพen z 15 s na 20 s. -- **oprava #346** : Nรกstroje s prรกzdnรฝm `function.name` (pล™eposlรกno Claudem Code) jsou nynรญ filtrovรกny pล™edtรญm, neลพ je obdrลพรญ upstreamovรญ poskytovatelรฉ, ฤรญmลพ se zabrรกnรญ chybรกm โ€žNeplatnรฝ vstup[N].name: prรกzdnรฝ ล™etฤ›zecโ€œ. +- **fix #355**: Stream idle timeout increased from 60s to 300s โ€” prevents aborting extended-thinking models (claude-opus-4-6, o3, etc.) during long reasoning phases. Configurable via `STREAM_IDLE_TIMEOUT_MS`. +- **fix #350**: Combo test now bypasses `REQUIRE_API_KEY=true` using internal header, and uses OpenAI-compatible format universally. Timeout extended from 15s to 20s. +- **fix #346**: Tools with empty `function.name` (forwarded by Claude Code) are now filtered before upstream providers receive them, preventing "Invalid input[N].name: empty string" errors. -### ๐Ÿ—‘๏ธ Uzavล™enรฉ problรฉmy +### ๐Ÿ—‘๏ธ Closed Issues -- **#341** : Sekce ladฤ›nรญ odstranฤ›na โ€“ nahrazena je `/dashboard/logs` a `/dashboard/health` . +- **#341**: Debug section removed โ€” replacement is `/dashboard/logs` and `/dashboard/health`. -> Podpora API Key Round-Robin pro nastavenรญ poskytovatelลฏ s vรญce klรญฤi a potvrzenรญ jiลพ zavedenรฉho smฤ›rovรกnรญ zรกstupnรฝch znakลฏ a rolovรกnรญ oken kvรณt. +> API Key Round-Robin support for multi-key provider setups, and confirmation of wildcard routing and quota window rolling already in place. -### โœจ Novรฉ funkce +### โœจ New Features -- **Round-Robin klรญฤลฏ API (T07)** : Pล™ipojenรญ poskytovatelลฏ nynรญ mohou obsahovat vรญce klรญฤลฏ API (Upravit pล™ipojenรญ โ†’ Dalลกรญ klรญฤe API). Poลพadavky rotujรญ round-robin mezi primรกrnรญmi a dalลกรญmi klรญฤi pomocรญ `providerSpecificData.extraApiKeys[]` . Klรญฤe jsou uchovรกvรกny v pamฤ›ti indexovanรฉ pro kaลพdรฉ pล™ipojenรญ โ€“ nejsou nutnรฉ ลพรกdnรฉ zmฤ›ny schรฉmatu databรกze. +- **API Key Round-Robin (T07)**: Provider connections can now hold multiple API keys (Edit Connection โ†’ Extra API Keys). Requests rotate round-robin between primary + extra keys via `providerSpecificData.extraApiKeys[]`. Keys are held in-memory indexed per connection โ€” no DB schema changes required. -### ๐Ÿ“ Jiลพ implementovรกno (potvrzeno auditem) +### ๐Ÿ“ Already Implemented (confirmed in audit) -- **Smฤ›rovรกnรญ modelu sย wildcard znaky (T13)** : soubor `wildcardRouter.ts` sย porovnรกvรกnรญm zรกstupnรฝch znakลฏ ve stylu glob ( `gpt*` , `claude-?-sonnet` atd.) je jiลพ integrovรกn do `model.ts` sย hodnocenรญm specificity. -- **Posunovรกnรญ okna kvรณt (T08)** : `accountFallback.ts:isModelLocked()` jiลพ automaticky posouvรก okno vpล™ed โ€“ pokud `Date.now() > entry.until` , zรกmek se okamลพitฤ› smaลพe (ลพรกdnรฉ blokovรกnรญ zastaralรฝch funkcรญ). +- **Wildcard Model Routing (T13)**: `wildcardRouter.ts` with glob-style wildcard matching (`gpt*`, `claude-?-sonnet`, etc.) is already integrated into `model.ts` with specificity ranking. +- **Quota Window Rolling (T08)**: `accountFallback.ts:isModelLocked()` already auto-advances the window โ€” if `Date.now() > entry.until`, lock is deleted immediately (no stale blocking). -> Vylepลกenรญ uลพivatelskรฉho rozhranรญ, doplnฤ›nรญ strategiรญ smฤ›rovรกnรญ a elegantnรญ zpracovรกnรญ chyb pro omezenรญ vyuลพitรญ. +> UI polish, routing strategy additions, and graceful error handling for usage limits. -### โœจ Novรฉ funkce +### โœจ New Features -- **Strategie smฤ›rovรกnรญ Fill-First a P2C** : Do vรฝbฤ›ru kombinovanรฉ strategie pล™idรกny strategie `fill-first` (vyฤerpรกnรญ kvรณty pล™ed pล™esunem) a `p2c` (vรฝbฤ›r Power-of-Two-Choices s nรญzkou latencรญ) s kompletnรญmi panely s pokyny a barevnฤ› odliลกenรฝmi odznaky. -- **Pล™ednastavenรฉ modely Free Stack** : Vytvoล™enรญ kombinace pomocรญ ลกablony Free Stack nynรญ automaticky vyplnรญ 7 nejlepลกรญch modelลฏ bezplatnรฝch poskytovatelลฏ ve svรฉ tล™รญdฤ› (Gemini CLI, Kiro, Qoderร—2, Qwen, NVIDIA NIM, Groq). Uลพivatelรฉ staฤรญ aktivovat poskytovatele a ihned zรญskajรญ kombinaci 0 $/mฤ›sรญc. -- **ล irลกรญ kombo modรกlnรญ okno** : Modรกlnรญ okno pro vytvoล™enรญ/รบpravu komba nynรญ pouลพรญvรก `max-w-4xl` pro pohodlnou รบpravu velkรฝch komb. +- **Fill-First & P2C Routing Strategies**: Added `fill-first` (drain quota before moving on) and `p2c` (Power-of-Two-Choices low-latency selection) to combo strategy picker, with full guidance panels and color-coded badges. +- **Free Stack Preset Models**: Creating a combo with the Free Stack template now auto-fills 7 best-in-class free provider models (Gemini CLI, Kiro, Qoderร—2, Qwen, NVIDIA NIM, Groq). Users just activate the providers and get a $0/month combo out-of-the-box. +- **Wider Combo Modal**: Create/Edit combo modal now uses `max-w-4xl` for comfortable editing of large combos. -### ๐Ÿ› Opravy chyb +### ๐Ÿ› Bug Fixes -- **Strรกnka s limity HTTP 500 pro Codex a GitHub** : `getCodexUsage()` a `getGitHubUsage()` nynรญ vracejรญ uลพivatelsky pล™รญvฤ›tivou zprรกvu, kdyลพ poskytovatel vrรกtรญ 401/403 (vyprลกelรฝ token), mรญsto aby vyvolaly chybu 500 na strรกnce s limity. -- **Faleลกnฤ› pozitivnรญ MaintenanceBanner** : Banner jiลพ pล™i naฤรญtรกnรญ strรกnky faleลกnฤ› nezobrazuje โ€žServer je nedostupnรฝโ€œ. Opraveno okamลพitรฝm volรกnรญm `checkHealth()` pล™i pล™ipojenรญ a odstranฤ›nรญm zastaralรฉho uzavล™enรญ `show` -state. -- **Popisky ikon poskytovatele** : Tlaฤรญtka s ikonami pro รบpravu (tuลพka) a odstranฤ›nรญ v ล™รกdku pล™ipojenรญ poskytovatele nynรญ obsahujรญ nativnรญ HTML popisky โ€“ vลกech 6 ikon akcรญ je nynรญ samodokumentovanรฝch. +- **Limits page HTTP 500 for Codex & GitHub**: `getCodexUsage()` and `getGitHubUsage()` now return a user-friendly message when the provider returns 401/403 (expired token), instead of throwing and causing a 500 error on the Limits page. +- **MaintenanceBanner false-positive**: Banner no longer shows "Server is unreachable" spuriously on page load. Fixed by calling `checkHealth()` immediately on mount and removing stale `show`-state closure. +- **Provider icon tooltips**: Edit (pencil) and delete icon buttons in the provider connection row now have native HTML tooltips โ€” all 6 action icons are now self-documented. -> Nฤ›kolik vylepลกenรญ z analรฝzy problรฉmลฏ komunity, podpora novรฝch poskytovatelลฏ, opravy chyb pro sledovรกnรญ tokenลฏ, smฤ›rovรกnรญ modelลฏ a spolehlivost streamovรกnรญ. +> Multiple improvements from community issue analysis, new provider support, bug fixes for token tracking, model routing, and streaming reliability. -### โœจ Novรฉ funkce +### โœจ New Features -- **Inteligentnรญ smฤ›rovรกnรญ s ohledem na รบlohy (T05)** : Automatickรฝ vรฝbฤ›r modelu na zรกkladฤ› typu obsahu poลพadavku โ€” kรณdovรกnรญ โ†’ deepseek-chat, analรฝza โ†’ gemini-2.5-pro, vision โ†’ gpt-4o, sumarizace โ†’ gemini-2.5-flash. Konfigurovatelnรฉ v Nastavenรญ. Novรฉ API `GET/PUT/POST /api/settings/task-routing` . -- **Poskytovatel HuggingFace** : Pล™idรกn HuggingFace Router jako poskytovatel kompatibilnรญ s OpenAI s Llama 3.1 70B/8B, Qwen 2.5 72B, Mistral 7B, Phi-3.5 Mini. -- **Poskytovatel Vertex AI** : Pล™idรกn poskytovatel Vertex AI (Google Cloud) s Gemini 2.5 Pro/Flash, Gemma 2 27B, Claude pล™es Vertex. -- **Nahrรกvรกnรญ souborลฏ do Playgroundu** : Nahrรกvรกnรญ zvuku pro pล™epis, nahrรกvรกnรญ obrรกzkลฏ pro modely vidฤ›nรญ (automatickรก detekce podle nรกzvu modelu), inline vykreslovรกnรญ obrรกzkลฏ pro vรฝsledky generovรกnรญ obrรกzkลฏ. -- **Vizuรกlnรญ zpฤ›tnรก vazba pล™i vรฝbฤ›ru modelu** : Jiลพ pล™idanรฉ modely v kombinovanรฉm vรฝbฤ›ru nynรญ zobrazujรญ zelenรฝ odznak โœ“ โ€“ zabraลˆuje zรกmฤ›nฤ› duplicitnรญch modelลฏ. -- **Kompatibilita s Qwen (PR #352)** : Aktualizovรกno nastavenรญ otiskลฏ uลพivatelskรฉho agenta a rozhranรญ CLI pro kompatibilitu s poskytovateli Qwen. -- **Sprรกva stavu round-robin (PR #349)** : Vylepลกenรก logika round-robin pro zpracovรกnรญ vylouฤenรฝch รบฤtลฏ a sprรกvnรฉ udrลพovรกnรญ stavu rotace. -- **Uลพivatelskรก zkuลกenost se schrรกnkou (PR #360)** : Vylepลกenรฉ operace se schrรกnkou s moลพnostรญ zรกlohovรกnรญ pro nezabezpeฤenรฉ kontexty; vylepลกenรญ normalizace nรกstroje Claude. +- **Task-Aware Smart Routing (T05)**: Automatic model selection based on request content type โ€” coding โ†’ deepseek-chat, analysis โ†’ gemini-2.5-pro, vision โ†’ gpt-4o, summarization โ†’ gemini-2.5-flash. Configurable via Settings. New `GET/PUT/POST /api/settings/task-routing` API. +- **HuggingFace Provider**: Added HuggingFace Router as an OpenAI-compatible provider with Llama 3.1 70B/8B, Qwen 2.5 72B, Mistral 7B, Phi-3.5 Mini. +- **Vertex AI Provider**: Added Vertex AI (Google Cloud) provider with Gemini 2.5 Pro/Flash, Gemma 2 27B, Claude via Vertex. +- **Playground File Uploads**: Audio upload for transcription, image upload for vision models (auto-detect by model name), inline image rendering for image generation results. +- **Model Select Visual Feedback**: Already-added models in combo picker now show โœ“ green badge โ€” prevents duplicate confusion. +- **Qwen Compatibility (PR #352)**: Updated User-Agent and CLI fingerprint settings for Qwen provider compatibility. +- **Round-Robin State Management (PR #349)**: Enhanced round-robin logic to handle excluded accounts and maintain rotation state correctly. +- **Clipboard UX (PR #360)**: Hardened clipboard operations with fallback for non-secure contexts; Claude tool normalization improvements. -### ๐Ÿ› Opravy chyb +### ๐Ÿ› Bug Fixes -- **Oprava ฤ. 302 โ€“ OpenAI SDK stream=False zanechรกvรก tool_calls** : T01 Accept header negotiation jiลพ nevynucuje streamovรกnรญ, pokud je `body.stream` explicitnฤ› `false` . Zpลฏsobovalo to tichรฉ zanechรกvรกnรญ tool_calls pล™i pouลพitรญ OpenAI Python SDK v reลพimu bez streamovรกnรญ. -- **Oprava ฤ. 73 โ€” Claude Haiku smฤ›rovรกn do OpenAI bez prefixu poskytovatele** : modely `claude-*` odeslanรฉ bez prefixu poskytovatele nynรญ sprรกvnฤ› smฤ›rujรญ k poskytovateli `antigravity` (antropickรฉmu). Pล™idรกna takรฉ heuristika `gemini-*` / `gemma-*` โ†’ `gemini` . -- **Oprava ฤ. 74 โ€“ Poฤet tokenลฏ je pro streamovรกnรญ Antigravity/Claude vลพdy 0** : Udรกlost SSE `message_start` , kterรก obsahuje `input_tokens` nebyla analyzovรกna funkcรญ `extractUsage()` , coลพ zpลฏsobovalo pokles vลกech poฤtลฏ vstupnรญch tokenลฏ. Sledovรกnรญ vstupnรญch/vรฝstupnรญch tokenลฏ nynรญ funguje sprรกvnฤ› pro streamovanรฉ odpovฤ›di. -- **Oprava ฤ. 180 โ€“ Duplikรกty importovanรฝch modelลฏ bez zpฤ›tnรฉ vazby** : `ModelSelectModal` nynรญ zobrazuje โœ“ zelenรฉ zvรฝraznฤ›nรญ u modelลฏ, kterรฉ jsou jiลพ v kombinaci, takลพe je zล™ejmรฉ, ลพe jsou jiลพ pล™idรกny. -- **Chyby generovรกnรญ mediรกlnรญch strรกnek** : Vรฝsledky obrรกzkลฏ se nynรญ vykreslujรญ jako tagy `` mรญsto nezpracovanรฉho JSON. Vรฝsledky pล™episu se zobrazujรญ jako ฤitelnรฝ text. Chyby pล™ihlaลกovacรญch รบdajลฏ zobrazujรญ oranลพovรฝ banner mรญsto tichรฉ chyby. -- **Tlaฤรญtko pro obnovenรญ tokenu na strรกnce poskytovatele** : Pro poskytovatele OAuth bylo pล™idรกno uลพivatelskรฉ rozhranรญ pro ruฤnรญ obnovenรญ tokenu. +- **Fix #302 โ€” OpenAI SDK stream=False drops tool_calls**: T01 Accept header negotiation no longer forces streaming when `body.stream` is explicitly `false`. Was causing tool_calls to be silently dropped when using the OpenAI Python SDK in non-streaming mode. +- **Fix #73 โ€” Claude Haiku routed to OpenAI without provider prefix**: `claude-*` models sent without a provider prefix now correctly route to the `antigravity` (Anthropic) provider. Added `gemini-*`/`gemma-*` โ†’ `gemini` heuristic as well. +- **Fix #74 โ€” Token counts always 0 for Antigravity/Claude streaming**: The `message_start` SSE event which carries `input_tokens` was not being parsed by `extractUsage()`, causing all input token counts to drop. Input/output token tracking now works correctly for streaming responses. +- **Fix #180 โ€” Model import duplicates with no feedback**: `ModelSelectModal` now shows โœ“ green highlight for models already in the combo, making it obvious they're already added. +- **Media page generation errors**: Image results now render as `` tags instead of raw JSON. Transcription results shown as readable text. Credential errors show an amber banner instead of silent failure. +- **Token refresh button on provider page**: Manual token refresh UI added for OAuth providers. -### ๐Ÿ”ง Vylepลกenรญ +### ๐Ÿ”ง Improvements -- **Registr poskytovatelลฏ** : Do `providerRegistry.ts` a `providers.ts` (frontend) pล™idรกny prvky HuggingFace a Vertex AI. -- **ฤŒtenรญ mezipamฤ›ti** : Novรฝ `src/lib/db/readCache.ts` pro efektivnรญ uklรกdรกnรญ do mezipamฤ›ti ฤtenรญ databรกze. -- **Mezipamฤ›ลฅ kvรณt** : Vylepลกenรก mezipamฤ›ลฅ kvรณt s vyล™azenรญm na zรกkladฤ› TTL. +- **Provider Registry**: HuggingFace and Vertex AI added to `providerRegistry.ts` and `providers.ts` (frontend). +- **Read Cache**: New `src/lib/db/readCache.ts` for efficient DB read caching. +- **Quota Cache**: Improved quota cache with TTL-based eviction. -### ๐Ÿ“ฆ Zรกvislosti +### ๐Ÿ“ฆ Dependencies - `dompurify` โ†’ 3.3.3 (PR #347) - `undici` โ†’ 7.24.2 (PR #348, #361) - `docker/setup-qemu-action` โ†’ v4 (PR #342) - `docker/setup-buildx-action` โ†’ v4 (PR #343) -### ๐Ÿ“ Novรฉ soubory +### ๐Ÿ“ New Files -| Soubor | รšฤel | -| --------------------------------------------- | ------------------------------------------------- | -| `open-sse/services/taskAwareRouter.ts` | Logika smฤ›rovรกnรญ s ohledem na รบlohy (7 typลฏ รบloh) | -| `src/app/api/settings/task-routing/route.ts` | API pro konfiguraci smฤ›rovรกnรญ รบloh | -| `src/app/api/providers/[id]/refresh/route.ts` | Ruฤnรญ aktualizace tokenu OAuth | -| `src/lib/db/readCache.ts` | Efektivnรญ mezipamฤ›ลฅ pro ฤtenรญ databรกze | -| `src/shared/utils/clipboard.ts` | Zpevnฤ›nรก schrรกnka sย funkcรญ | +| File | Purpose | +| --------------------------------------------- | --------------------------------------- | +| `open-sse/services/taskAwareRouter.ts` | Task-aware routing logic (7 task types) | +| `src/app/api/settings/task-routing/route.ts` | Task routing config API | +| `src/app/api/providers/[id]/refresh/route.ts` | Manual OAuth token refresh | +| `src/lib/db/readCache.ts` | Efficient DB read cache | +| `src/shared/utils/clipboard.ts` | Hardened clipboard with fallback | -## [2.4.1] - 13. 3. 2026 +## [2.4.1] - 2026-03-13 -### ๐Ÿ› Oprava +### ๐Ÿ› Fix -- **Modรกlnรญ okno s kombinacemi: ล ablona Volnรฝ zรกsobnรญk viditelnรก a vรฝraznรก** โ€“ ล ablona Volnรฝ zรกsobnรญk byla skrytรก (4. v mล™รญลพce se 3 sloupci). Opraveno: pล™esunuto na pozici 1, pล™epnuto na mล™รญลพku 2x2, takลพe jsou viditelnรฉ vลกechny 4 ลกablony, zelenรฝ okraj + zvรฝraznฤ›nรญ odznaku ZDARMA. +- **Combos modal: Free Stack visible and prominent** โ€” Free Stack template was hidden (4th in 3-column grid). Fixed: moved to position 1, switched to 2x2 grid so all 4 templates are visible, green border + FREE badge highlight. -## [2.4.0] - 13. 3. 2026 +## [2.4.0] - 2026-03-13 -> **Hlavnรญ vydรกnรญ** โ€“ ekosystรฉm Free Stack, pล™epracovanรฉ transkripฤnรญ hล™iลกtฤ›, vรญce neลพ 44 poskytovatelลฏ, komplexnรญ dokumentace k bezplatnรฉ รบrovni a vylepลกenรญ uลพivatelskรฉho rozhranรญ napล™รญฤ vลกemi oblastmi. +> **Major release** โ€” Free Stack ecosystem, transcription playground overhaul, 44+ providers, comprehensive free tier documentation, and UI improvements across the board. -### โœจ Funkce +### Funkce -- **Kombinace: ล ablona Free Stack** โ€” Novรก 4. ลกablona โ€žFree Stack (0 $)โ€œ vyuลพรญvajรญcรญ round-robin napล™รญฤ Kiro + Qoder + Qwen + Gemini CLI. Pล™i prvnรญm pouลพitรญ doporuฤuje pล™edpล™ipravenou kombinaci s nulovรฝmi nรกklady. -- **Mรฉdia/Pล™epis: Deepgram jako vรฝchozรญ** โ€“ Deepgram (Nova 3, 200 dolarลฏ zdarma) je nynรญ vรฝchozรญm poskytovatelem pล™episu. AssemblyAI (50 dolarลฏ zdarma) a Groq Whisper (navลพdy zdarma) jsou zobrazeny s odznaky bezplatnรฉho kreditu. -- **README: Sekce โ€žZaฤรญt zdarmaโ€œ** โ€“ Novรก tabulka s 5 kroky v pล™edbฤ›ลพnรฉm souboru README, kterรก ukazuje, jak nastavit umฤ›lou inteligenci s nulovรฝmi nรกklady bฤ›hem nฤ›kolika minut. -- **README: Kombinace bezplatnรฉho pล™episu** โ€“ Novรก sekce s nรกvrhem kombinacรญ Deepgram/AssemblyAI/Groq a informacemi o bezplatnรฉm kreditu pro kaลพdรฉho poskytovatele. -- **providers.ts: pล™รญznak hasFree** โ€” NVIDIA NIM, Cerebras a Groq oznaฤenรฉ odznakem hasFree a freeNote pro uลพivatelskรฉ rozhranรญ poskytovatelลฏ. -- **i18n: klรญฤe templateFreeStack** โ€” kombinovanรก ลกablona Free Stack pล™eloลพenรก a synchronizovanรก do vลกech 30 jazykลฏ. +- **Combos: Free Stack template** โ€” New 4th template "Free Stack ($0)" using round-robin across Kiro + Qoder + Qwen + Gemini CLI. Suggests the pre-built zero-cost combo on first use. +- **Media/Transcription: Deepgram as default** โ€” Deepgram (Nova 3, $200 free) is now the default transcription provider. AssemblyAI ($50 free) and Groq Whisper (free forever) shown with free credit badges. +- **README: "Start Free" section** โ€” New early-README 5-step table showing how to set up zero-cost AI in minutes. +- **README: Free Transcription Combo** โ€” New section with Deepgram/AssemblyAI/Groq combo suggestion and per-provider free credit details. +- **providers.ts: hasFree flag** โ€” NVIDIA NIM, Cerebras, and Groq marked with hasFree badge and freeNote for the providers UI. +- **i18n: templateFreeStack keys** โ€” Free Stack combo template translated and synced to all 30 languages. -## [2.3.16] - 13. 3. 2026 +## [2.3.16] - 2026-03-13 -### ๐Ÿ“– Dokumentace +### Dokumentace -- **README: 44+ poskytovatelลฏ** โ€” Vลกechny 3 vรฝskyty vรฝrazu โ€ž36+ poskytovatelลฏโ€œ byly aktualizovรกny na โ€ž44+โ€œ, coลพ odrรกลพรญ skuteฤnรฝ poฤet kรณdovรฉ zรกkladny (44 poskytovatelลฏ v souboru providers.ts). -- **README: Novรก sekce โ€ž๐Ÿ†“ Bezplatnรฉ modely โ€“ Co skuteฤnฤ› zรญskรกteโ€œ** โ€“ Pล™idรกna tabulka 7 poskytovatelลฏ s limity rychlosti pro kaลพdรฝ model pro: Kiro (Claude neomezenฤ› pล™es AWS Builder ID), Qoder (5 modelลฏ neomezenฤ›), Qwen (4 modely neomezenฤ›), Gemini CLI (180K/mฤ›sรญc), NVIDIA NIM (~40 RPM dev-forever), Cerebras (1M tok/den / 60K TPM), Groq (30 RPM / 14.4K RPD). Zahrnuje doporuฤenรญ pro kombinaci /usr/bin/bash Ultimate Free Stack. -- **Soubor README: Aktualizace cenovรฉ tabulky** โ€“ pล™idรกn Cerebras do รบrovnฤ› API KEY, opravena zmฤ›na NVIDIA z โ€ž1000 kreditลฏโ€œ na โ€žnavลพdy zdarma pro vรฝvojรกล™eโ€œ, aktualizovรกny poฤty a nรกzvy modelลฏ Qoder/Qwen -- **README: Modely Qoder 8โ†’5** (s nรกzvy: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2) -- **README: Modely Qwen 3โ†’4** (s nรกzvy: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model) +- **README: 44+ Providers** โ€” Updated all 3 occurrences of "36+ providers" to "44+" reflecting the actual codebase count (44 providers in providers.ts) +- **README: New Section "๐Ÿ†“ Free Models โ€” What You Actually Get"** โ€” Added 7-provider table with per-model rate limits for: Kiro (Claude unlimited via AWS Builder ID), Qoder (5 models unlimited), Qwen (4 models unlimited), Gemini CLI (180K/mo), NVIDIA NIM (~40 RPM dev-forever), Cerebras (1M tok/day / 60K TPM), Groq (30 RPM / 14.4K RPD). Includes the \/usr/bin/bash Ultimate Free Stack combo recommendation. +- **README: Pricing Table Updated** โ€” Added Cerebras to API KEY tier, fixed NVIDIA from "1000 credits" to "dev-forever free", updated Qoder/Qwen model counts and names +- **README: Qoder 8โ†’5 models** (named: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2) +- **README: Qwen 3โ†’4 models** (named: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model) -## [2.3.15] - 13. 3. 2026 +## [2.3.15] - 2026-03-13 -### โœจ Funkce +### Funkce -- **Panel automatickรฝch kombinacรญ (priorita รบrovnฤ›)** : Pล™idรกna `๐Ÿท๏ธ Tier` jako 7. faktor bodovรกnรญ v zobrazenรญ rozpisu faktorลฏ `/dashboard/auto-combo` โ€“ nynรญ je viditelnรฝch vลกech 7 faktorลฏ bodovรกnรญ automatickรฝch kombinacรญ. -- **i18n โ€” sekce autoCombo** : Pro panel Auto-Combo bylo pล™idรกno 20 novรฝch pล™ekladovรฝch klรญฤลฏ ( `title` , `status` , `modePack` , `providerScores` , `factorTierPriority` atd.) do vลกech 30 jazykovรฝch souborลฏ. +- **Auto-Combo Dashboard (Tier Priority)**: Added `๐Ÿท๏ธ Tier` as the 7th scoring factor label in the `/dashboard/auto-combo` factor breakdown display โ€” all 7 Auto-Combo scoring factors are now visible. +- **i18n โ€” autoCombo section**: Added 20 new translation keys for the Auto-Combo dashboard (`title`, `status`, `modePack`, `providerScores`, `factorTierPriority`, etc.) to all 30 language files. -## [2.3.14] - 13. 3. 2026 +## [2.3.14] - 2026-03-13 -### ๐Ÿ› Opravy chyb +### ๐Ÿ› Bug Fixes -- **Qoder OAuth (#339)** : Obnoven platnรฝ vรฝchozรญ `clientSecret` โ€“ dล™รญve to byl prรกzdnรฝ ล™etฤ›zec, kterรฝ pล™i kaลพdรฉm pokusu o pล™ipojenรญ zpลฏsoboval chybu โ€žChybnรฉ pล™ihlaลกovacรญ รบdaje klientaโ€œ. Veล™ejnรฉ pล™ihlaลกovacรญ รบdaje jsou nynรญ vรฝchozรญm zรกloลพnรญm nastavenรญm (lze je pล™epsat pomocรญ promฤ›nnรฉ prostล™edรญ `QODER_OAUTH_CLIENT_SECRET` ). -- **MITM server nenalezen (#335)** : `prepublish.mjs` nynรญ kompiluje `src/mitm/*.ts` do JavaScriptu pomocรญ `tsc` pล™ed zkopรญrovรกnรญm do npm balรญฤku. Dล™รญve se kopรญrovaly pouze nezpracovanรฉ soubory `.ts` โ€“ coลพ znamenalo, ลพe `server.js` nikdy neexistoval v globรกlnรญch instalacรญch npm/Volta. -- **Chybรญ projectId v GeminiCLI (#338)** : Namรญsto vyvolรกnรญ hardwarovรฉ chyby 500, kdyลพ v uloลพenรฝch pล™ihlaลกovacรญch รบdajรญch chybรญ `projectId` (napล™. po restartu Dockeru), OmniRoute nynรญ zaznamenรก varovรกnรญ a pokusรญ se o poลพadavek โ€“ vrรกtรญ smysluplnou chybu na stranฤ› poskytovatele mรญsto pรกdu OmniRoute. -- **Neshoda verzรญ balรญฤku Electron (#323)** : Synchronizovรกna verze `electron/package.json` s verzรญ `2.3.13` (dล™รญve `2.0.13` ), takลพe binรกrnรญ verze pro stolnรญ poฤรญtaฤe odpovรญdรก balรญฤku npm. +- **Qoder OAuth (#339)**: Restored the valid default `clientSecret` โ€” was previously an empty string, causing "Bad client credentials" on every connect attempt. The public credential is now the default fallback (overridable via `QODER_OAUTH_CLIENT_SECRET` env var). +- **MITM server not found (#335)**: `prepublish.mjs` now compiles `src/mitm/*.ts` to JavaScript using `tsc` before copying to the npm bundle. Previously only raw `.ts` files were copied โ€” meaning `server.js` never existed in npm/Volta global installs. +- **GeminiCLI missing projectId (#338)**: Instead of throwing a hard 500 error when `projectId` is missing from stored credentials (e.g. after Docker restart), OmniRoute now logs a warning and attempts the request โ€” returning a meaningful provider-side error instead of an OmniRoute crash. +- **Electron version mismatch (#323)**: Synced `electron/package.json` version to `2.3.13` (was `2.0.13`) so the desktop binary version matches the npm package. -### โœจ Novรฉ modely (#334) +### โœจ New Models (#334) -- **Kiro** : `claude-sonnet-4` , `claude-opus-4.6` , `deepseek-v3.2` , `minimax-m2.1` , `qwen3-coder-next` , `auto` -- **Kodex** : `gpt5.4` +- **Kiro**: `claude-sonnet-4`, `claude-opus-4.6`, `deepseek-v3.2`, `minimax-m2.1`, `qwen3-coder-next`, `auto` +- **Codex**: `gpt5.4` -### ๐Ÿ”ง Vylepลกenรญ +### ๐Ÿ”ง Improvements -- **Bodovรฉ hodnocenรญ (API + validace)** : Do schรฉmatu Zod `ScoringWeights` a trasy API `combos/auto` pล™idรกna `tierPriority` (vรกha `0.05` ) โ€“ 7. faktor bodovรกnรญ je nynรญ plnฤ› akceptovรกn rozhranรญm REST API a ovฤ›ล™ovรกn na vstupu. Vรกha `stability` upravena z `0.10` na `0.05` , aby celkovรฝ souฤet zลฏstal `1.0` . +- **Tier Scoring (API + Validation)**: Added `tierPriority` (weight `0.05`) to the `ScoringWeights` Zod schema and the `combos/auto` API route โ€” the 7th scoring factor is now fully accepted by the REST API and validated on input. `stability` weight adjusted from `0.10` to `0.05` to keep total sum = `1.0`. -### โœจ Novรฉ funkce +### โœจ New Features -- **Vรญceรบrovลˆovรฉ bodovรกnรญ kvรณt (automatickรฉ kombinovรกnรญ)** : Pล™idรกna `tierPriority` jako 7. faktor bodovรกnรญ โ€“ รบฤty s รบrovnฤ›mi Ultra/Pro jsou nynรญ upล™ednostลˆovรกny pล™ed รบrovnฤ›mi Free, pokud jsou ostatnรญ faktory stejnรฉ. Novรก volitelnรก pole `accountTier` a `quotaResetIntervalSecs` u `ProviderCandidate` . Vลกechny 4 balรญฤky reลพimลฏ byly aktualizovรกny ( `ship-fast` , `cost-saver` , `quality-first` , `offline-friendly` ). -- **Zรกloลพnรญ model v rรกmci rodiny (T5)** : Pokud model nenรญ k dispozici (404/400/403), OmniRoute se nynรญ automaticky vrรกtรญ k sourozeneckรฝm modelลฏm ze stejnรฉ rodiny, neลพ vrรกtรญ chybu ( `modelFamilyFallback.ts` ). -- **Konfigurovatelnรฝ ฤasovรฝ limit API Bridge** : Promฤ›nnรก prostล™edรญ `API_BRIDGE_PROXY_TIMEOUT_MS` umoลพลˆuje operรกtorลฏm ladit ฤasovรฝ limit proxy (vรฝchozรญ hodnota 30 s). Opravuje chyby 504 pล™i pomalรฝch odezvรกch upstreamu. (#332) -- **Historie hvฤ›zd** : Widget star-history.com byl ve vลกech 30 souborech README nahrazen widgetem starchart.cc ( `?variant=adaptive` ) โ€“ pล™izpลฏsobuje se svฤ›tlรฉmu/tmavรฉmu tรฉmatu a aktualizacรญm v reรกlnรฉm ฤase. +- **Tiered Quota Scoring (Auto-Combo)**: Added `tierPriority` as a 7th scoring factor โ€” accounts with Ultra/Pro tiers are now preferred over Free tiers when other factors are equal. New optional fields `accountTier` and `quotaResetIntervalSecs` on `ProviderCandidate`. All 4 mode packs updated (`ship-fast`, `cost-saver`, `quality-first`, `offline-friendly`). +- **Intra-Family Model Fallback (T5)**: When a model is unavailable (404/400/403), OmniRoute now automatically falls back to sibling models from the same family before returning an error (`modelFamilyFallback.ts`). +- **Configurable API Bridge Timeout**: `API_BRIDGE_PROXY_TIMEOUT_MS` env var lets operators tune the proxy timeout (default 30s). Fixes 504 errors on slow upstream responses. (#332) +- **Star History**: Replaced star-history.com widget with starchart.cc (`?variant=adaptive`) in all 30 READMEs โ€” adapts to light/dark theme, real-time updates. -### ๐Ÿ› Opravy chyb +### ๐Ÿ› Bug Fixes -- **Auth โ€” Prvnรญ heslo** : Pล™i nastavovรกnรญ prvnรญho hesla pro dashboard je nynรญ akceptovรกna promฤ›nnรก prostล™edรญ `INITIAL_PASSWORD` . Pouลพรญvรก `timingSafeEqual` pro porovnรกvรกnรญ v konstantnรญm ฤase, ฤรญmลพ se zabraลˆuje รบtokลฏm na ฤasovรกnรญ. (#333) -- **Zkrรกcenรญ souboru README** : Opraven chybฤ›jรญcรญ uzavรญracรญ tag `` v sekci ล˜eลกenรญ problรฉmลฏ, kterรฝ zpลฏsoboval, ลพe GitHub zastavil vykreslovรกnรญ vลกeho pod nรญm (Tech Stack, Dokumentace, Plรกn, Pล™ispฤ›vatelรฉ). -- **Instalace pnpm** : Z `package.json` byl odstranฤ›n redundantnรญ pล™epis `@swc/helpers` , kterรฝ kolidoval s pล™รญmou zรกvislostรญ a zpลฏsoboval chyby `EOVERRIDE` na pnpm. Pล™idรกna konfigurace `pnpm.onlyBuiltDependencies` . -- **Vloลพenรญ cesty do CLI (T12)** : V `cliRuntime.ts` byl pล™idรกn validรกtor `isSafePath()` pro blokovรกnรญ prochรกzenรญ cesty a metaznakลฏ shellu v promฤ›nnรฝch prostล™edรญ `CLI_*_BIN` . -- **CI** : Po odstranฤ›nรญ pล™epsรกnรญ byl obnoven `package-lock.json` pro opravu chyb `npm ci` v akcรญch GitHubu. +- **Auth โ€” First-time password**: `INITIAL_PASSWORD` env var is now accepted when setting the first dashboard password. Uses `timingSafeEqual` for constant-time comparison, preventing timing attacks. (#333) +- **README Truncation**: Fixed a missing `` closing tag in the Troubleshooting section that caused GitHub to stop rendering everything below it (Tech Stack, Docs, Roadmap, Contributors). +- **pnpm install**: Removed redundant `@swc/helpers` override from `package.json` that conflicted with the direct dependency, causing `EOVERRIDE` errors on pnpm. Added `pnpm.onlyBuiltDependencies` config. +- **CLI Path Injection (T12)**: Added `isSafePath()` validator in `cliRuntime.ts` to block path traversal and shell metacharacters in `CLI_*_BIN` env vars. +- **CI**: Regenerated `package-lock.json` after override removal to fix `npm ci` failures on GitHub Actions. -### ๐Ÿ”ง Vylepลกenรญ +### ๐Ÿ”ง Improvements -- **Formรกt odpovฤ›di (T1)** : `response_format` (json_schema/json_object) se nynรญ vklรกdรก jako systรฉmovรฝ vรฝzva pro Claude, coลพ umoลพลˆuje kompatibilitu strukturovanรฉho vรฝstupu. -- **429 Opakovรกnรญ (T2)** : Opakovรกnรญ odpovฤ›dรญ 429 v rรกmci URL (2ร— pokusy s 2s zpoลพdฤ›nรญm) pล™ed nรกvratem k dalลกรญ URL. -- **Zรกhlavรญ rozhranรญ pล™รญkazovรฉho ล™รกdku Gemini (T3)** : Pล™idรกny zรกhlavรญ otiskลฏ prstลฏ `User-Agent` a `X-Goog-Api-Client` pro kompatibilitu s rozhranรญm pล™รญkazovรฉho ล™รกdku Gemini. -- **Cenovรฝ katalog (T9)** : Pล™idรกny cenรญky pro `deepseek-3.1` , `deepseek-3.2` a `qwen3-coder-next` . +- **Response Format (T1)**: `response_format` (json_schema/json_object) now injected as a system prompt for Claude, enabling structured output compatibility. +- **429 Retry (T2)**: Intra-URL retry for 429 responses (2ร— attempts with 2s delay) before falling back to next URL. +- **Gemini CLI Headers (T3)**: Added `User-Agent` and `X-Goog-Api-Client` fingerprint headers for Gemini CLI compatibility. +- **Pricing Catalog (T9)**: Added `deepseek-3.1`, `deepseek-3.2`, and `qwen3-coder-next` pricing entries. -### ๐Ÿ“ Novรฉ soubory +### ๐Ÿ“ New Files -| Soubor | รšฤel | -| ------------------------------------------ | ------------------------------------------------------------------ | -| `open-sse/services/modelFamilyFallback.ts` | Definice modelovรฝch rodin a logika zรกloลพnรญch ล™eลกenรญ v rรกmci rodiny | +| File | Purpose | +| ------------------------------------------ | -------------------------------------------------------- | +| `open-sse/services/modelFamilyFallback.ts` | Model family definitions and intra-family fallback logic | -### Opraveno +### Fixed -- **KiloCode** : ฤasovรฝ limit kontroly stavu kilocode jiลพ byl opraven ve verzi 2.3.11. -- **OpenCode** : Pล™idรกnรญ opencode do registru cliRuntime s 15sekundovรฝm ฤasovรฝm limitem pro kontrolu stavu -- **OpenClaw / Cursor** : Prodlouลพenรญ ฤasovรฉho limitu kontroly stavu na 15 sekund pro varianty s pomalรฝm startem. -- **VPS** : Nainstalujte npm balรญฤky pro droid a openclaw; aktivujte CLI_EXTRA_PATHS pro kiro-cli -- **cliRuntime** : Pล™idรกna registrace nรกstroje opencode a prodlouลพena ฤasovรก prodleva pro pokraฤovรกnรญ +- **KiloCode**: kilocode healthcheck timeout already fixed in v2.3.11 +- **OpenCode**: Add opencode to cliRuntime registry with 15s healthcheck timeout +- **OpenClaw / Cursor**: Increase healthcheck timeout to 15s for slow-start variants +- **VPS**: Install droid and openclaw npm packages; activate CLI_EXTRA_PATHS for kiro-cli +- **cliRuntime**: Add opencode tool registration and increase timeout for continue -## [2.3.11] - 12. 3. 2026 +## [2.3.11] - 2026-03-12 -### Opraveno +### Fixed -- **KiloCode healthcheck** : Zvรฝลกenรญ `healthcheckTimeoutMs` z 4000 ms na 15000 ms โ€” kilocode pล™i spuลกtฤ›nรญ vykreslรญ banner s logem ASCII, coลพ v prostล™edรญch s pomalรฝm/studenรฝm startem zpลฏsobรญ chybu `healthcheck_failed` +- **KiloCode healthcheck**: Increase `healthcheckTimeoutMs` from 4000ms to 15000ms โ€” kilocode renders an ASCII logo banner on startup causing false `healthcheck_failed` on slow/cold-start environments -## [2.3.10] - 12. 3. 2026 +## [2.3.10] - 2026-03-12 -### Opraveno +### Fixed -- **Lint** : Oprava chyby `check:any-budget:t11` โ€” nahrazenรญ `as any` za `as Record` v OAuthModal.tsx (3 vรฝskyty) +- **Lint**: Fix `check:any-budget:t11` failure โ€” replace `as any` with `as Record` in OAuthModal.tsx (3 occurrences) -### Dokumenty +### Docs -- **CLI-TOOLS.md** : Kompletnรญ prลฏvodce vลกemi 11 nรกstroji CLI (claude, codex, gemini, opencode, cline, kilocode, continue, kiro-cli, cursor, droid, openclaw) -- **i18n** : CLI-TOOLS.md synchronizovanรฝ do 30 jazykลฏ s pล™eloลพenรฝm nรกzvem a รบvodem +- **CLI-TOOLS.md**: Complete guide for all 11 CLI tools (claude, codex, gemini, opencode, cline, kilocode, continue, kiro-cli, cursor, droid, openclaw) +- **i18n**: CLI-TOOLS.md synced to 30 languages with translated title + intro -## [2.3.8] - 12. 3. 2026 +## [2.3.8] - 2026-03-12 -## [2.3.9] - 12. 3. 2026 +## [2.3.9] - 2026-03-12 -### Pล™idรกno +### Added -- **/v1/completions** : Novรฝ starลกรญ endpoint pro dokonฤenรญ OpenAI โ€“ pล™ijรญmรก jak ล™etฤ›zec `prompt` , tak pole `messages` , automaticky se normalizuje do formรกtu chatu -- **EndpointPage** : Nynรญ zobrazuje vลกechny 3 typy koncovรฝch bodลฏ kompatibilnรญch s OpenAI: Dokonฤovรกnรญ chatu, API odpovฤ›dรญ a Legacy Dokonฤovรกnรญ. -- **i18n** : Pล™idรกn `completionsLegacy/completionsLegacyDesc` do 30 jazykovรฝch souborลฏ. +- **/v1/completions**: New legacy OpenAI completions endpoint โ€” accepts both `prompt` string and `messages` array, normalizes to chat format automatically +- **EndpointPage**: Now shows all 3 OpenAI-compatible endpoint types: Chat Completions, Responses API, and Legacy Completions +- **i18n**: Added `completionsLegacy/completionsLegacyDesc` to 30 language files -### Opraveno +### Fixed -- **OAuthModal** : Oprava zobrazenรญ objektu `[object Object]` u vลกech chyb pล™ipojenรญ OAuth โ€“ sprรกvnฤ› extrahovat `.message` z objektลฏ odpovฤ›dรญ na chyby ve vลกech 3 `throw new Error(data.error)` (exchange, device-code, authorize) -- Ovlivลˆuje Cline, Codex, GitHub, Qwen, Kiro a vลกechny ostatnรญ poskytovatele OAuth. +- **OAuthModal**: Fix `[object Object]` displayed on all OAuth connection errors โ€” properly extract `.message` from error response objects in all 3 `throw new Error(data.error)` calls (exchange, device-code, authorize) +- Affects Cline, Codex, GitHub, Qwen, Kiro, and all other OAuth providers -## [2.3.7] - 12. 3. 2026 +## [2.3.7] - 2026-03-12 -### Opraveno +### Fixed -- **Cline OAuth** : Pล™ed dekรณdovรกnรญ base64 pล™idรกna `decodeURIComponent` , aby autorizaฤnรญ kรณdy kรณdovanรฉ pomocรญ URL z URL zpฤ›tnรฉho volรกnรญ byly sprรกvnฤ› analyzovรกny, opraveny chyby โ€žneplatnรฝ nebo vyprลกenรฝ autorizaฤnรญ kรณdโ€œ ve vzdรกlenรฝch instalacรญch (LAN IP). -- **Cline OAuth** : `mapTokens` nynรญ vyplลˆuje `name = firstName + lastName || email` , takลพe รบฤty Cline zobrazujรญ skuteฤnรก uลพivatelskรก jmรฉna mรญsto โ€žAccount #IDโ€œ. -- **Nรกzvy รบฤtลฏ OAuth** : Vลกechny toky vรฝmฤ›ny OAuth (exchange, poll, poll-callback) nynรญ normalizujรญ `name = email` pokud nรกzev chybรญ, takลพe kaลพdรฝ รบฤet OAuth zobrazuje svลฏj e-mail jako zobrazovanรฝ popisek v dashboardu Poskytovatelรฉ. -- **Nรกzvy รบฤtลฏ OAuth** : V souboru `db/providers.ts` byla odstranฤ›na sekvenฤnรญ zรกloลพnรญ moลพnost โ€žรšฤet Nโ€œ โ€“ รบฤty bez e-mailu/jmรฉna nynรญ pouลพรญvajรญ stabilnรญ popisek zaloลพenรฝ na ID pomocรญ `getAccountDisplayName()` namรญsto sekvenฤnรญho ฤรญsla, kterรฉ se mฤ›nรญ pล™i smazรกnรญ รบฤtลฏ. +- **Cline OAuth**: Add `decodeURIComponent` before base64 decode so URL-encoded auth codes from the callback URL are parsed correctly, fixing "invalid or expired authorization code" errors on remote (LAN IP) setups +- **Cline OAuth**: `mapTokens` now populates `name = firstName + lastName || email` so Cline accounts show real user names instead of "Account #ID" +- **OAuth account names**: All OAuth exchange flows (exchange, poll, poll-callback) now normalize `name = email` when name is missing, so every OAuth account shows its email as the display label in the Providers dashboard +- **OAuth account names**: Removed sequential "Account N" fallback in `db/providers.ts` โ€” accounts with no email/name now use a stable ID-based label via `getAccountDisplayName()` instead of a sequential number that changes when accounts are deleted -## [2.3.6] - 12. 3. 2026 +## [2.3.6] - 2026-03-12 -### Opraveno +### Fixed -- **Dรกvkovรฝ test poskytovatele** : Opraveno schรฉma Zod pro akceptovรกnรญ `providerId: null` (frontend odesรญlรก null pro reลพimy bez poskytovatele); nesprรกvnฤ› vracelo โ€žNeplatnรฝ poลพadavekโ€œ pro vลกechny dรกvkovรฉ testy. -- **Modรกlnรญ okno testovรกnรญ poskytovatele** : Opraveno zobrazenรญ `[object Object]` normalizacรญ objektลฏ chyb API na ล™etฤ›zce pล™ed vykreslenรญm v `setTestResults` a `ProviderTestResultsView` -- **i18n** : Do `en.json` pล™idรกny chybฤ›jรญcรญ klรญฤe `cliTools.toolDescriptions.opencode` , `cliTools.toolDescriptions.kiro` , `cliTools.guides.opencode` , `cliTools.guides.kiro` -- **i18n** : Synchronizovรกno chybฤ›jรญcรญ 1111 klรญฤลฏ ve vลกech 29 souborech v neanglickรฝch jazycรญch s pouลพitรญm anglickรฝch hodnot jako zรกloลพnรญch hodnot. +- **Provider test batch**: Fixed Zod schema to accept `providerId: null` (frontend sends null for non-provider modes); was incorrectly returning "Invalid request" for all batch tests +- **Provider test modal**: Fixed `[object Object]` display by normalizing API error objects to strings before rendering in `setTestResults` and `ProviderTestResultsView` +- **i18n**: Added missing keys `cliTools.toolDescriptions.opencode`, `cliTools.toolDescriptions.kiro`, `cliTools.guides.opencode`, `cliTools.guides.kiro` to `en.json` +- **i18n**: Synchronized 1111 missing keys across all 29 non-English language files using English values as fallbacks -## [2.3.5] - 11. 3. 2026 +## [2.3.5] - 2026-03-11 -### Opraveno +### Fixed -- **@swc/helpers** : Pล™idรกna trvalรก oprava `postinstall` pro kopรญrovรกnรญ `@swc/helpers` do `node_modules` samostatnรฉ aplikace โ€“ zabraลˆuje pรกdu MODULE_NOT_FOUND pล™i globรกlnรญch instalacรญch npm. +- **@swc/helpers**: Added permanent `postinstall` fix to copy `@swc/helpers` into the standalone app's `node_modules` โ€” prevents MODULE_NOT_FOUND crash on global npm installs -## [2.3.4] - 10. 3. 2026 +## [2.3.4] - 2026-03-10 -### Pล™idรกno +### Added -- Integrace vรญce poskytovatelลฏ a vylepลกenรญ dashboardu +- Multiple provider integrations and dashboard improvements diff --git a/docs/i18n/cs/CLI-TOOLS.md b/docs/i18n/cs/CLI-TOOLS.md deleted file mode 100644 index 9d0c0899fb..0000000000 --- a/docs/i18n/cs/CLI-TOOLS.md +++ /dev/null @@ -1,344 +0,0 @@ -# Prลฏvodce nastavenรญm nรกstrojลฏ CLI โ€” OmniRoute - -Tato pล™รญruฤka vysvฤ›tluje, jak nainstalovat a nakonfigurovat vลกechny podporovanรฉ nรกstroje CLI pro kรณdovรกnรญ umฤ›lรฉ inteligence -tak, aby **OmniRoute** fungoval jako jednotnรฝ backend, coลพ vรกm umoลพnรญ centralizovanou sprรกvu klรญฤลฏ, -sledovรกnรญ nรกkladลฏ, pล™epรญnรกnรญ modelลฏ a protokolovรกnรญ poลพadavkลฏ napล™รญฤ vลกemi nรกstroji. - ---- - -## Jak to funguje - -``` -Claude / Codex / OpenCode / Cline / KiloCode / Continue / Kiro / Cursor / Copilot - โ”‚ - โ–ผ (vลกechny ukazujรญ na OmniRoute) - http://VASE_SERVER:20128/v1 - โ”‚ - โ–ผ (OmniRoute smฤ›ruje ke sprรกvnรฉmu poskytovateli) - Anthropic / OpenAI / Gemini / DeepSeek / Groq / Mistral / ... -``` - -**Vรฝhody:** - -- Jeden API klรญฤ pro sprรกvu vลกech nรกstrojลฏ -- Sledovรกnรญ nรกkladลฏ napล™รญฤ vลกemi CLI v dashboardu -- Pล™epรญnรกnรญ modelลฏ bez nutnosti pล™ekonfigurovรกnรญ kaลพdรฉho nรกstroje -- Funguje lokรกlnฤ› i na vzdรกlenรฝch serverech (VPS) - ---- - -## Podporovanรฉ nรกstroje (Zdroj pravdy v dashboardu) - -Karty dashboardu v `/dashboard/cli-tools` jsou generovรกny z `src/shared/constants/cliTools.ts`. -Aktuรกlnรญ seznam (v3.0.0-rc.16): - -| Nรกstroj | ID | Pล™รญkaz | Reลพim nastavenรญ | Metoda instalace | -| ------------------ | ------------- | ------------ | --------------- | ---------------- | -| **Claude Code** | `claude` | `claude` | env | npm | -| **OpenAI Codex** | `codex` | `codex` | custom | npm | -| **Factory Droid** | `droid` | `droid` | custom | bundled/CLI | -| **OpenClaw** | `openclaw` | `openclaw` | custom | bundled/CLI | -| **Cursor** | `cursor` | aplikace | guide | desktop app | -| **Cline** | `cline` | `cline` | custom | npm | -| **Kilo Code** | `kilo` | `kilocode` | custom | npm | -| **Continue** | `continue` | rozลกรญล™enรญ | guide | VS Code | -| **Antigravity** | `antigravity` | internรญ | mitm | OmniRoute | -| **GitHub Copilot** | `copilot` | rozลกรญล™enรญ | custom | VS Code | -| **OpenCode** | `opencode` | `opencode` | guide | npm | -| **Kiro AI** | `kiro` | aplikace/CLI | mitm | desktop/CLI | - -### Synchronizace otiskลฏ CLI (Agenti + Nastavenรญ) - -`/dashboard/agents` a `Nastavenรญ > CLI Otisk` pouลพรญvajรญ `src/shared/constants/cliCompatProviders.ts`. -To udrลพuje ID poskytovatelลฏ v souladu s kartami CLI a starลกรญmi ID. - -| CLI ID | ID poskytovatele otisku | -| ---------------------------------------------------------------------------------------------------- | ----------------------- | -| `kilo` | `kilocode` | -| `copilot` | `github` | -| `claude` / `codex` / `antigravity` / `kiro` / `cursor` / `cline` / `opencode` / `droid` / `openclaw` | stejnรฉ ID | - -Starลกรญ ID jsou stรกle pล™ijรญmรกna pro kompatibilitu: `copilot`, `kimi-coding`, `qwen`. - ---- - -## Krok 1 โ€” Zรญskejte OmniRoute API klรญฤ - -1. Otevล™ete OmniRoute dashboard โ†’ **Sprรกvce API** (`/dashboard/api-manager`) -2. Kliknฤ›te na **Vytvoล™it API klรญฤ** -3. Dejte mu nรกzev (napล™. `cli-tools`) a vyberte vลกechna oprรกvnฤ›nรญ -4. Zkopรญrujte klรญฤ โ€” budete ho potล™ebovat pro kaลพdรฝ CLI nรญลพe - -> Vรกลก klรญฤ vypadรก takto: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` - ---- - -## Krok 2 โ€” Nainstalujte nรกstroje CLI - -Vลกechny nรกstroje zaloลพenรฉ na npm vyลพadujรญ Node.js 18+: - -```bash -# Claude Code (Anthropic) -npm install -g @anthropic-ai/claude-code - -# OpenAI Codex -npm install -g @openai/codex - -# OpenCode -npm install -g opencode-ai - -# Cline -npm install -g cline - -# KiloCode -npm install -g kilocode - -# Kiro CLI (Amazon โ€” vyลพaduje curl + unzip) -apt-get install -y unzip # na Debian/Ubuntu -curl -fsSL https://cli.kiro.dev/install | bash -export PATH="$HOME/.local/bin:$PATH" # pล™idat do ~/.bashrc -``` - -**Ovฤ›ล™enรญ:** - -```bash -claude --version # 2.x.x -codex --version # 0.x.x -opencode --version # x.x.x -cline --version # 2.x.x -kilocode --version # x.x.x (nebo: kilo --version) -kiro-cli --version # 1.x.x -``` - ---- - -## Krok 3 โ€” Nastavte globรกlnรญ promฤ›nnรฉ prostล™edรญ - -Pล™idejte do `~/.bashrc` (nebo `~/.zshrc`), pak spusลฅte `source ~/.bashrc`: - -```bash -# OmniRoute Univerzรกlnรญ koncovรฝ bod -export OPENAI_BASE_URL="http://localhost:20128/v1" -export OPENAI_API_KEY="sk-vase-omniroute-klic" -export ANTHROPIC_BASE_URL="http://localhost:20128/v1" -export ANTHROPIC_API_KEY="sk-vase-omniroute-klic" -export GEMINI_BASE_URL="http://localhost:20128/v1" -export GEMINI_API_KEY="sk-vase-omniroute-klic" -``` - -> Pro **vzdรกlenรฝ server** nahraฤte `localhost:20128` IP adresou nebo domรฉnou serveru, -> napล™. `http://192.168.0.15:20128`. - ---- - -## Krok 4 โ€” Nakonfigurujte kaลพdรฝ nรกstroj - -### Claude Code - -```bash -# Via CLI: -claude config set --global api-base-url http://localhost:20128/v1 - -# Nebo vytvoล™te ~/.claude/settings.json: -mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF -{ - "apiBaseUrl": "http://localhost:20128/v1", - "apiKey": "sk-vase-omniroute-klic" -} -EOF -``` - -**Test:** `claude "say hello"` - ---- - -### OpenAI Codex - -```bash -mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF -model: auto -apiKey: sk-vase-omniroute-klic -apiBaseUrl: http://localhost:20128/v1 -EOF -``` - -**Test:** `codex "what is 2+2?"` - ---- - -### OpenCode - -```bash -mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF -[provider.openai] -base_url = "http://localhost:20128/v1" -api_key = "sk-vase-omniroute-klic" -EOF -``` - -**Test:** `opencode` - ---- - -### Cline (CLI nebo VS Code) - -**Reลพim CLI:** - -```bash -mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF -{ - "apiProvider": "openai", - "openAiBaseUrl": "http://localhost:20128/v1", - "openAiApiKey": "sk-vase-omniroute-klic" -} -EOF -``` - -**Reลพim VS Code:** -Nastavenรญ rozลกรญล™enรญ Cline โ†’ API Provider: `OpenAI Compatible` โ†’ Base URL: `http://localhost:20128/v1` - -Nebo pouลพijte OmniRoute dashboard โ†’ **CLI Nรกstroje โ†’ Cline โ†’ Pouลพรญt konfiguraci**. - ---- - -### KiloCode (CLI nebo VS Code) - -**Reลพim CLI:** - -```bash -kilocode --api-base http://localhost:20128/v1 --api-key sk-vase-omniroute-klic -``` - -**Nastavenรญ VS Code:** - -```json -{ - "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", - "kilo-code.apiKey": "sk-vase-omniroute-klic" -} -``` - -Nebo pouลพijte OmniRoute dashboard โ†’ **CLI Nรกstroje โ†’ KiloCode โ†’ Pouลพรญt konfiguraci**. - ---- - -### Continue (Rozลกรญล™enรญ VS Code) - -Upravte `~/.continue/config.yaml`: - -```yaml -models: - - name: OmniRoute - provider: openai - model: auto - apiBase: http://localhost:20128/v1 - apiKey: sk-vase-omniroute-klic - default: true -``` - -Po รบpravฤ› restartujte VS Code. - ---- - -### Kiro CLI (Amazon) - -```bash -# Pล™ihlaste se ke svรฉmu AWS/Kiro รบฤtu: -kiro-cli login - -# CLI pouลพรญvรก vlastnรญ autentifikaci โ€” OmniRoute nenรญ potล™eba jako backend pro samotnรฝ Kiro CLI. -# Pouลพรญvejte kiro-cli spoleฤnฤ› s OmniRoute pro ostatnรญ nรกstroje. -kiro-cli status -``` - ---- - -### Cursor (Desktop aplikace) - -> **Poznรกmka:** Cursor smฤ›ruje poลพadavky pล™es svลฏj cloud. Pro integraci s OmniRoute, -> povolte **Cloud Endpoint** v nastavenรญ OmniRoute a pouลพijte vaลกi veล™ejnou domรฉnu. - -Via GUI: **Settings โ†’ Models โ†’ OpenAI API Key** - -- Base URL: `https://vase-domena.com/v1` -- API Key: vรกลก OmniRoute klรญฤ - ---- - -## Automatickรก konfigurace v dashboardu - -OmniRoute dashboard automatizuje konfiguraci vฤ›tลกiny nรกstrojลฏ: - -1. Jdฤ›te na `http://localhost:20128/dashboard/cli-tools` -2. Rozbalte libovolnou kartu nรกstroje -3. Vyberte svลฏj API klรญฤ z rozbalovacรญho seznamu -4. Kliknฤ›te na **Pouลพรญt konfiguraci** (pokud je nรกstroj detekovรกn jako nainstalovanรฝ) -5. Nebo ruฤnฤ› zkopรญrujte vygenerovanรฝ konfiguraฤnรญ snippet - ---- - -## Vestavฤ›nรฝ agenti: Droid & OpenClaw - -**Droid** a **OpenClaw** jsou AI agenti vestavฤ›nรญ pล™รญmo do OmniRoute โ€” nenรญ potล™eba ลพรกdnรก instalace. -Bฤ›ลพรญ jako internรญ trasy a automaticky pouลพรญvajรญ smฤ›rovรกnรญ modelลฏ OmniRoute. - -- Pล™รญstup: `http://localhost:20128/dashboard/agents` -- Konfigurace: stejnรฉ kombinace a poskytovatelรฉ jako vลกechny ostatnรญ nรกstroje -- Nenรญ potล™eba API klรญฤ ani instalace CLI - ---- - -## Dostupnรฉ API koncovรฉ body - -| Koncovรฝ bod | Popis | Pouลพitรญ pro | -| -------------------------- | --------------------------------------- | ------------------------------------- | -| `/v1/chat/completions` | Standardnรญ chat (vลกichni poskytovatelรฉ) | Vลกechny modernรญ nรกstroje | -| `/v1/responses` | Responses API (formรกt OpenAI) | Codex, agentnรญ workflowy | -| `/v1/completions` | Legacy textovรฉ dokonฤenรญ | Starลกรญ nรกstroje pouลพรญvajรญcรญ `prompt:` | -| `/v1/embeddings` | Textovรฉ vloลพenรญ | RAG, vyhledรกvรกnรญ | -| `/v1/images/generations` | Generovรกnรญ obrรกzkลฏ | DALL-E, Flux, atd. | -| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS | -| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI | - ---- - -## ล˜eลกenรญ problรฉmลฏ - -| Chyba | Pล™รญฤina | Oprava | -| ----------------------------- | ----------------------- | -------------------------------------------------------- | -| `Connection refused` | OmniRoute nebฤ›ลพรญ | `pm2 start omniroute` | -| `401 Unauthorized` | ล patnรฝ API klรญฤ | Zkontrolujte v `/dashboard/api-manager` | -| `No combo configured` | ลฝรกdnรก aktivnรญ kombinace | Nastavte v `/dashboard/combos` | -| `invalid model` | Model nenรญ v katalogu | Pouลพijte `auto` nebo zkontrolujte `/dashboard/providers` | -| CLI zobrazuje "not installed" | Binรกrka nenรญ v PATH | Zkontrolujte `which ` | -| `kiro-cli: not found` | Nenรญ v PATH | `export PATH="$HOME/.local/bin:$PATH"` | - ---- - -## Rychlรฝ skript pro nastavenรญ (jeden pล™รญkaz) - -```bash -# Nainstalujte vลกechny CLI a nakonfigurujte pro OmniRoute (nahraฤte svรฝm klรญฤem a URL serveru) -OMNIROUTE_URL="http://localhost:20128/v1" -OMNIROUTE_KEY="sk-vase-omniroute-klic" - -npm install -g @anthropic-ai/claude-code @openai/codex opencode-ai cline kilocode - -# Kiro CLI -apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash - -# Zรกpis konfiguracรญ -mkdir -p ~/.claude ~/.codex ~/.config/opencode ~/.continue - -cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" -cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" -cat >> ~/.bashrc << EOF -export OPENAI_BASE_URL="$OMNIROUTE_URL" -export OPENAI_API_KEY="$OMNIROUTE_KEY" -export ANTHROPIC_BASE_URL="$OMNIROUTE_URL" -export ANTHROPIC_API_KEY="$OMNIROUTE_KEY" -EOF - -source ~/.bashrc -echo "โœ… Vลกechny CLI nainstalovรกny a nakonfigurovรกny pro OmniRoute" -``` diff --git a/docs/i18n/cs/CODEBASE_DOCUMENTATION.md b/docs/i18n/cs/CODEBASE_DOCUMENTATION.md deleted file mode 100644 index 55b277e345..0000000000 --- a/docs/i18n/cs/CODEBASE_DOCUMENTATION.md +++ /dev/null @@ -1,589 +0,0 @@ -# omniroute โ€” Dokumentace kรณdovรฉ zรกkladny - -๐ŸŒ **Jazyky:** ๐Ÿ‡บ๐Ÿ‡ธ [angliฤtina](CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brazรญlie)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡จ๐Ÿ‡ณ[ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฏ๐Ÿ‡ต[ๆ—ฅๆœฌ่ชž](i18n/ja/CODEBASE_DOCUMENTATION.md)| ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dรกnsko](i18n/da/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ญ๐Ÿ‡บ [maฤarลกtina](i18n/hu/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonรฉsie](i18n/id/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nizozemsko](i18n/nl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugalsko)](i18n/pt/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipรญnec](i18n/phi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](i18n/cs/CODEBASE_DOCUMENTATION.md) - -> Komplexnรญ prลฏvodce pro zaฤรกteฤnรญky s vyuลพitรญm multiproviderovรฉho proxy routeru s umฤ›lou inteligencรญ **od OmniRoute** . - ---- - -## 1. Co je to omniroute? - -Omniroute je **proxy router** , kterรฝ se nachรกzรญ mezi klienty umฤ›lรฉ inteligence (Claude CLI, Codex, Cursor IDE atd.) a poskytovateli umฤ›lรฉ inteligence (Anthropic, Google, OpenAI, AWS, GitHub atd.). ล˜eลกรญ jeden velkรฝ problรฉm: - -> **Rลฏznรญ klienti AI hovoล™รญ rลฏznรฝmi โ€žjazykyโ€œ (formรกty API) a rลฏznรญ poskytovatelรฉ AI takรฉ oฤekรกvajรญ rลฏznรฉ โ€žjazykyโ€œ.** Omniroute mezi nimi automaticky pล™eklรกdรก. - -Pล™edstavte si to jako univerzรกlnรญho pล™ekladatele v Organizaci spojenรฝch nรกrodลฏ โ€“ kterรฝkoli delegรกt mลฏลพe mluvit jakรฝmkoli jazykem a pล™ekladatel ho pro kterรฉhokoli jinรฉho delegรกta pล™evede. - ---- - -## 2. Pล™ehled architektury - -```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 -``` - -### Zรกkladnรญ princip: Pล™eklad typu โ€žhub-and-spokeโ€œ - -Veลกkerรฝ pล™eklad formรกtลฏ prochรกzรญ **formรกtem OpenAI jako centrem** : - -``` -Client Format โ†’ [OpenAI Hub] โ†’ Provider Format (request) -Provider Format โ†’ [OpenAI Hub] โ†’ Client Format (response) -``` - -To znamenรก, ลพe potล™ebujete pouze **N pล™ekladaฤลฏ** (jeden na formรกt) mรญsto **Nยฒ** (kaลพdรฝ pรกr). - ---- - -## 3. Struktura projektu - -``` -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. Rozdฤ›lenรญ podle modulลฏ - -### 4.1 Konfigurace ( `open-sse/config/` ) - -Jedinรฝ **zdroj pravdivรฝch informacรญ** pro vลกechny konfigurace poskytovatelลฏ. - -| Soubor | รšฤel | -| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `constants.ts` | Objekt `PROVIDERS` se zรกkladnรญmi URL adresami, pล™ihlaลกovacรญmi รบdaji OAuth (vรฝchozรญ), zรกhlavรญmi a vรฝchozรญmi systรฉmovรฝmi vรฝzvami pro kaลพdรฉho poskytovatele. Definuje takรฉ `HTTP_STATUS` , `ERROR_TYPES` , `COOLDOWN_MS` , `BACKOFF_CONFIG` a `SKIP_PATTERNS` . | -| `credentialLoader.ts` | Naฤte externรญ pล™ihlaลกovacรญ รบdaje z `data/provider-credentials.json` a slouฤรญ je s pevnฤ› zakรณdovanรฝmi vรฝchozรญmi hodnotami v `PROVIDERS` . Uchovรกvรก tajnรฉ รบdaje mimo kontrolu zdrojovรฉho kรณdu a zรกroveลˆ zachovรกvรก zpฤ›tnou kompatibilitu. | -| `providerModels.ts` | Centrรกlnรญ registr modelลฏ: mapuje aliasy poskytovatelลฏ โ†’ ID modelลฏ. Funkce jako `getModels()` , `getProviderByAlias()` . | -| `codexInstructions.ts` | Systรฉmovรฉ instrukce vloลพenรฉ do poลพadavkลฏ Codexu (omezenรญ รบprav, pravidla sandboxu, zรกsady schvalovรกnรญ). | -| `defaultThinkingSignature.ts` | Vรฝchozรญ โ€žmyลกlenkovรฉโ€œ podpisy pro modely Claude a Gemini. | -| `ollamaModels.ts` | Definice schรฉmatu pro lokรกlnรญ Ollama modely (nรกzev, velikost, rodina, kvantizace). | - -#### Postup naฤรญtรกnรญ pล™ihlaลกovacรญch รบdajลฏ - -```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 Vykonavatelรฉ ( `open-sse/executors/` ) - -Provรกdฤ›cรญ metody zapouzdล™ujรญ **logiku specifickou pro poskytovatele** pomocรญ **vzoru strategie** . Kaลพdรฝ provรกdฤ›cรญ metody podle potล™eby pล™episujรญ zรกkladnรญ metody. - -```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 -``` - -| Vykonavatel | Poskytovatel | Klรญฤovรฉ specializace | -| ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | -| `base.ts` | โ€” | Abstraktnรญ zรกklad: tvorba URL adres, hlaviฤky, logika opakovรกnรญ, aktualizace pล™ihlaลกovacรญch รบdajลฏ | -| `default.ts` | Claude, Gemini, OpenAI, GLM, Kimi, MiniMax | Aktualizace generickรฉho tokenu OAuth pro standardnรญ poskytovatele | -| `antigravity.ts` | Kรณd Google Cloud | Generovรกnรญ ID projektu/relace, zรกloลพnรญ vรญce URL adres, vlastnรญ analรฝza opakovanรฝch pokusลฏ z chybovรฝch zprรกv (โ€žreset po 2h7m23sโ€œ) | -| `cursor.ts` | IDE kurzoru | **Nejsloลพitฤ›jลกรญ** : autorizace kontrolnรญho souฤtu SHA-256, kรณdovรกnรญ poลพadavkลฏ Protobuf, analรฝza binรกrnรญch EventStream โ†’ SSE odpovฤ›dรญ | -| `codex.ts` | OpenAI Codex | Vklรกdรก systรฉmovรฉ instrukce, spravuje รบrovnฤ› myลกlenรญ, odstraลˆuje nepodporovanรฉ parametry | -| `gemini-cli.ts` | Google Gemini CLI | Vytvoล™enรญ vlastnรญ URL adresy ( `streamGenerateContent` ), aktualizace tokenu Google OAuth | -| `github.ts` | GitHub Copilot | Systรฉm duรกlnรญch tokenลฏ (GitHub OAuth + Copilot token), napodobovรกnรญ hlaviฤek VSCode | -| `kiro.ts` | AWS CodeWhisperer | Binรกrnรญ parsovรกnรญ AWS EventStream, rรกmce udรกlostรญ AMZN, odhad tokenลฏ | -| `index.ts` | โ€” | Tovรกrna: nรกzev poskytovatele map โ†’ tล™รญda exekutoru s vรฝchozรญm zรกloลพnรญm nastavenรญm | - ---- - -### 4.3 Obsluลพnรฉ rutiny ( `open-sse/handlers/` ) - -**Orchestraฤnรญ vrstva** โ€“ koordinuje pล™eklad, provรกdฤ›nรญ, streamovรกnรญ a zpracovรกnรญ chyb. - -| Soubor | รšฤel | -| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `chatCore.ts` | **Centrรกlnรญ orchestrรกtor** (~600 ล™รกdkลฏ). Zvlรกdรก kompletnรญ ลพivotnรญ cyklus poลพadavku: detekce formรกtu โ†’ pล™eklad โ†’ odeslรกnรญ exekutoru โ†’ streamovanรก/nestreamovanรก odpovฤ›ฤ โ†’ aktualizace tokenu โ†’ zpracovรกnรญ chyb โ†’ protokolovรกnรญ vyuลพitรญ. | -| `responsesHandler.ts` | Adaptรฉr pro OpenAI Responses API: pล™evรกdรญ formรกt odpovฤ›dรญ โ†’ Dokonฤenรญ chatu โ†’ odesรญlรก do `chatCore` โ†’ pล™evรกdรญ SSE zpฤ›t do formรกtu odpovฤ›dรญ. | -| `embeddings.ts` | Obsluลพnรก rutina generovรกnรญ embeddingu: ล™eลกรญ model embeddingu โ†’ poskytovatele, odesรญlรก do API poskytovatele, vracรญ odpovฤ›ฤ na embedding kompatibilnรญ s OpenAI. Podporuje 6+ poskytovatelลฏ. | -| `imageGeneration.ts` | Obsluลพnรก rutina generovรกnรญ obrรกzkลฏ: ล™eลกรญ model obrรกzku โ†’ poskytovatele, podporuje reลพimy kompatibilnรญ s OpenAI, Gemini-image (Antigravity) a fallback (Nebius). Vracรญ obrรกzky v base64 nebo URL. | - -#### ลฝivotnรญ cyklus poลพadavku (chatCore.ts) - -```mermaid -sequenceDiagram - participant Client - participant chatCore - participant Translator - participant Executor - participant Provider - - Client->>chatCore: Request (any format) - chatCore->>chatCore: Detect source format - chatCore->>chatCore: Check bypass patterns - chatCore->>chatCore: Resolve model & provider - chatCore->>Translator: Translate request (source โ†’ OpenAI โ†’ target) - chatCore->>Executor: Get executor for provider - Executor->>Executor: Build URL, headers, transform request - Executor->>Executor: Refresh credentials if needed - Executor->>Provider: HTTP fetch (streaming or non-streaming) - - alt Streaming - Provider-->>chatCore: SSE stream - chatCore->>chatCore: Pipe through SSE transform stream - Note over chatCore: Transform stream translates
each chunk: target โ†’ OpenAI โ†’ source - chatCore-->>Client: Translated SSE stream - else Non-streaming - Provider-->>chatCore: JSON response - chatCore->>Translator: Translate response - chatCore-->>Client: Translated JSON - end - - alt Error (401, 429, 500...) - chatCore->>Executor: Retry with credential refresh - chatCore->>chatCore: Account fallback logic - end -``` - ---- - -### 4.4 Sluลพby ( `open-sse/services/` ) - -Obchodnรญ logika, kterรก podporuje obsluลพnรฉ rutiny a vykonavatele. - -| Soubor | รšฤel | -| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `provider.ts` | **Detekce formรกtu** ( `detectFormat` ): analyzuje strukturu tฤ›la poลพadavku a identifikuje formรกty Claude/OpenAI/Gemini/Antigravity/Responses (vฤetnฤ› heuristiky `max_tokens` pro Claude). Dรกle: tvorba URL, tvorba hlaviฤek, normalizace konfigurace thinking. Podporuje dynamickรฉ poskytovatele kompatibilnรญ `openai-compatible-*` a `anthropic-compatible-*` . | -| `model.ts` | Analรฝza ล™etฤ›zcลฏ modelu ( `claude/model-name` โ†’ `{provider: "claude", model: "model-name"}` ), rozliลกenรญ aliasลฏ s detekcรญ kolizรญ, sanitizace vstupu (odmรญtรก prลฏchod cestou/ล™รญdicรญ znaky) a rozliลกenรญ informacรญ o modelu s podporou asynchronnรญch metod pro zรญskรกvรกnรญ aliasลฏ. | -| `accountFallback.ts` | Ovlรกdรกnรญ limitลฏ rychlosti: exponenciรกlnรญ upomรญnka (1 s โ†’ 2 s โ†’ 4 s โ†’ max. 2 min), sprรกva doby zpoลพdฤ›nรญ รบฤtu, klasifikace chyb (kterรฉ chyby spouลกtฤ›jรญ fallback a kterรฉ ne). | -| `tokenRefresh.ts` | Aktualizace tokenu OAuth pro **vลกechny poskytovatele** : Google (Gemini, Antigravity), Claude, Codex, Qwen, Qoder, GitHub (duรกlnรญ token OAuth + Copilot), Kiro (AWS SSO OIDC + sociรกlnรญ ovฤ›ล™ovรกnรญ). Zahrnuje mezipamฤ›ลฅ deduplikace promise za provozu a opakovรกnรญ s exponenciรกlnรญm zpoลพdฤ›nรญm. | -| `combo.ts` | **Kombinovanรฉ modely** : ล™etฤ›zce zรกloลพnรญch modelลฏ. Pokud model A selลพe s chybou zpลฏsobilou pro zรกloลพnรญ model, zkuste model B, potรฉ C atd. Vracรญ skuteฤnรฉ stavovรฉ kรณdy upstreamu. | -| `usage.ts` | Naฤรญtรก data o kvรณtรกch/vyuลพitรญ z API poskytovatelลฏ (kvรณty GitHub Copilot, kvรณty modelu Antigravity, limity rychlosti Codexu, rozpisy vyuลพitรญ Kiro, nastavenรญ Claude). | -| `accountSelector.ts` | Inteligentnรญ vรฝbฤ›r รบฤtu s algoritmem bodovรกnรญ: pro vรฝbฤ›r optimรกlnรญho รบฤtu pro kaลพdรฝ poลพadavek se zohledลˆuje priorita, zdravotnรญ stav, pozice v systรฉmu round robin a stav ochlazovรกnรญ. | -| `contextManager.ts` | Sprรกva ลพivotnรญho cyklu kontextu poลพadavku: vytvรกล™รญ a sleduje objekty kontextu pro kaลพdรฝ poลพadavek s metadaty (ID poลพadavku, ฤasovรก razรญtka, informace o poskytovateli) pro ladฤ›nรญ a protokolovรกnรญ. | -| `ipFilter.ts` | ล˜รญzenรญ pล™รญstupu zaloลพenรฉ na IP adrese: podporuje reลพimy povolenรฝch seznamลฏ a blokovanรฝch seznamลฏ. Pล™ed zpracovรกnรญm poลพadavkลฏ API ovฤ›ล™uje IP adresu klienta podle nakonfigurovanรฝch pravidel. | -| `sessionManager.ts` | Sledovรกnรญ relacรญ s otisky prstลฏ klientลฏ: sleduje aktivnรญ relace pomocรญ haลกovanรฝch identifikรกtorลฏ klientลฏ, monitoruje poฤty poลพadavkลฏ a poskytuje metriky relacรญ. | -| `signatureCache.ts` | Mezipamฤ›ลฅ deduplikace na zรกkladฤ› signatur poลพadavkลฏ: zabraลˆuje duplicitnรญm poลพadavkลฏm uklรกdรกnรญm nedรกvnรฝch signatur poลพadavkลฏ do mezipamฤ›ti a vrรกcenรญm odpovฤ›dรญ z mezipamฤ›ti pro identickรฉ poลพadavky v rรกmci ฤasovรฉho okna. | -| `systemPrompt.ts` | Globรกlnรญ vloลพenรญ systรฉmovรฉho vรฝzvy: pล™idรก konfigurovatelnou systรฉmovou vรฝzvu ke vลกem poลพadavkลฏm s moลพnostรญ kompatibility pro jednotlivรฉ poskytovatele. | -| `thinkingBudget.ts` | Sprรกva rozpoฤtu tokenลฏ uvaลพovรกnรญ: podporuje reลพimy prลฏchodu, automatickรฝ (konfigurace strip thinking), vlastnรญ (pevnรฝ rozpoฤet) a adaptivnรญ (mฤ›ล™รญtko sloลพitosti) pro ล™รญzenรญ tokenลฏ myลกlenรญ/uvaลพovรกnรญ. | -| `wildcardRouter.ts` | Smฤ›rovรกnรญ podle vzorลฏ zรกstupnรฝch znakลฏ: rozpoznรกvรก vzory zรกstupnรฝch znakลฏ (napล™. `*/claude-*` ) na konkrรฉtnรญ pรกry poskytovatel/model na zรกkladฤ› dostupnosti a priority. | - -#### Deduplikace obnovenรญ tokenลฏ - -```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 -``` - -#### Zรกloลพnรญ stavovรฝ automat รบฤtu - -```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 - } -``` - -#### ล˜etฤ›zec kombinovanรฝch modelลฏ - -```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 Pล™ekladaฤ ( `open-sse/translator/` ) - -**Modul pro pล™eklad formรกtลฏ** vyuลพรญvajรญcรญ systรฉm samoregistrujรญcรญch se pluginลฏ. - -#### Architektura - -```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 -``` - -| Adresรกล™ | Soubory | Popis | -| ------------ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `request/` | 8 pล™ekladatelลฏ | Pล™evod tฤ›l poลพadavkลฏ mezi formรกty. Kaลพdรฝ soubor se pล™i importu sรกm zaregistruje pomocรญ `register(from, to, fn)` . | -| `response/` | 7 pล™ekladatelลฏ | Pล™evรกdรญ bloky odpovฤ›dรญ streamovanรฝch dat mezi formรกty. Zpracovรกvรก typy udรกlostรญ SSE, myลกlenkovรฉ bloky a volรกnรญ nรกstrojลฏ. | -| `helpers/` | 6 pomocnรญkลฏ | Sdรญlenรฉ utility: `claudeHelper` (extrakce systรฉmovรฝch prompts, thinking config), `geminiHelper` (mapovรกnรญ ฤรกstรญ/obsahu), `openaiHelper` (filtrovรกnรญ formรกtลฏ), `toolCallHelper` (generovรกnรญ ID, vklรกdรกnรญ chybฤ›jรญcรญch odpovฤ›dรญ), `maxTokensHelper` , `responsesApiHelper` . | -| `index.ts` | โ€” | Pล™ekladovรฝ engine: `translateRequest()` , `translateResponse()` , sprรกva stavu, registr. | -| `formats.ts` | โ€” | Formรกtovacรญ konstanty: `OPENAI` , `CLAUDE` , `GEMINI` , `ANTIGRAVITY` , `KIRO` , `CURSOR` , `OPENAI_RESPONSES` . | - -#### Klรญฤovรฝ design: Samoregistrujรญcรญ se pluginy - -```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 Nรกstroje ( `open-sse/utils/` ) - -| Soubor | รšฤel | -| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `error.ts` | Vytvรกล™enรญ chybovรฉ odezvy (formรกt kompatibilnรญ s OpenAI), parsovรกnรญ chyb v upstreamu, extrakce doby opakovรกnรญ Antigravity z chybovรฝch zprรกv, streamovรกnรญ chyb SSE. | -| `stream.ts` | **SSE Transform Stream** โ€” zรกkladnรญ streamovacรญ kanรกl. Dva reลพimy: `TRANSLATE` (plnรฝ pล™eklad formรกtu) a `PASSTHROUGH` (normalizace + extrakce vyuลพitรญ). Zpracovรกvรก uklรกdรกnรญ blokลฏ do vyrovnรกvacรญ pamฤ›ti, odhad vyuลพitรญ a sledovรกnรญ dรฉlky obsahu. Instance kodรฉru/dekodรฉru pro kaลพdรฝ stream se vyhรฝbajรญ sdรญlenรฉmu stavu. | -| `streamHelpers.ts` | Nรญzkoรบrovลˆovรฉ utility SSE: `parseSSELine` (tolerantnรญ k bรญlรฝm znakลฏm), `hasValuableContent` (filtruje prรกzdnรฉ segmenty pro OpenAI/Claude/Gemini), `fixInvalidId` , `formatSSE` (serializace SSE s ohledem na formรกt s ฤiลกtฤ›nรญm `perf_metrics` ). | -| `usageTracking.ts` | Extrakce vyuลพitรญ tokenลฏ z libovolnรฉho formรกtu (Claude/OpenAI/Gemini/Responses), odhad s oddฤ›lenรฝmi pomฤ›ry znakลฏ na token pro jednotlivรฉ nรกstroje/zprรกvy, pล™idรกnรญ vyrovnรกvacรญ pamฤ›ti (bezpeฤnostnรญ rezerva 2000 tokenลฏ), filtrovรกnรญ polรญ specifickรฝch pro formรกt, protokolovรกnรญ konzole s barvami ANSI. | -| `requestLogger.ts` | Protokolovรกnรญ poลพadavkลฏ na zรกkladฤ› souborลฏ (pล™ihlรกลกenรญ pomocรญ `ENABLE_REQUEST_LOGS=true` ). Vytvรกล™รญ sloลพky relacรญ s oฤรญslovanรฝmi soubory: `1_req_client.json` โ†’ `7_res_client.txt` . Veลกkerรฉ I/O operace jsou asynchronnรญ (aktivnรญ a zapomenutรฝ). Maskuje citlivรฉ hlaviฤky. | -| `bypassHandler.ts` | Zachycuje specifickรฉ vzory z Claude CLI (extrakce nรกzvu, zahล™รญvรกnรญ, poฤet) a vracรญ faleลกnรฉ odpovฤ›di bez volรกnรญ jakรฉhokoli poskytovatele. Podporuje streamovรกnรญ i nestreamovรกnรญ. Zรกmฤ›rnฤ› omezeno na rozsah Claude CLI. | -| `networkProxy.ts` | Rozpoznรก URL odchozรญ proxy pro danรฉho poskytovatele s prioritou: konfigurace specifickรก pro poskytovatele โ†’ globรกlnรญ konfigurace โ†’ promฤ›nnรฉ prostล™edรญ ( `HTTPS_PROXY` / `HTTP_PROXY` / `ALL_PROXY` ). Podporuje vรฝjimky `NO_PROXY` . Uklรกdรก konfiguraci do mezipamฤ›ti po dobu 30 sekund. | - -#### Streamovacรญ kanรกl SSE - -```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 -``` - -#### Struktura relace protokolovรกnรญ poลพadavkลฏ - -``` -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 Aplikaฤnรญ vrstva ( `src/` ) - -| Adresรกล™ | รšฤel | -| ------------- | ------------------------------------------------------------------------------------------------- | -| `src/app/` | Webovรฉ uลพivatelskรฉ rozhranรญ, trasy API, middleware Express, obsluลพnรฉ rutiny zpฤ›tnรฝch volรกnรญ OAuth | -| `src/lib/` | Pล™รญstup k databรกzi ( `localDb.ts` , `usageDb.ts` ), ovฤ›ล™ovรกnรญ, sdรญlenรญ | -| `src/mitm/` | Nรกstroje proxy typu โ€žman-in-the-middleโ€œ pro zachycenรญ provozu poskytovatelลฏ | -| `src/models/` | Definice modelลฏ databรกze | -| `src/shared/` | Obรกlky kolem funkcรญ open-sse (provider, stream, error atd.) | -| `src/sse/` | Obsluลพnรฉ rutiny koncovรฝch bodลฏ SSE, kterรฉ propojujรญ knihovnu open-sse s trasami Express | -| `src/store/` | Sprรกva stavu aplikacรญ | - -#### Vรฝznamnรฉ trasy API - -| Trasa | Metody | รšฤel | -| --------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------ | -| `/api/provider-models` | GET/POST/DELETE | CRUD pro vlastnรญ modely na poskytovatele | -| `/api/models/catalog` | GET | Agregovanรฝ katalog vลกech modelลฏ (chat, embedding, image, custom) seskupenรฝch podle poskytovatele | -| `/api/settings/proxy` | GET/PUT/DELETE | Konfigurace hierarchickรฉ odchozรญ proxy ( `global/providers/combos/keys` ) | -| `/api/settings/proxy/test` | POST | Ovฤ›ล™uje pล™ipojenรญ proxy a vracรญ veล™ejnou IP adresu/latenci | -| `/v1/providers/[provider]/chat/completions` | POST | Vyhrazenรฉ dokonฤovรกnรญ chatu pro jednotlivรฉ poskytovatele s ovฤ›ล™ovรกnรญm modelu | -| `/v1/providers/[provider]/embeddings` | POST | Vyhrazenรฉ vklรกdรกnรญ pro jednotlivรฉ poskytovatele s ovฤ›ล™ovรกnรญm modelu | -| `/v1/providers/[provider]/images/generations` | POST | Vyhrazenรฉ generovรกnรญ obrรกzkลฏ pro kaลพdรฉho poskytovatele s ovฤ›ล™ovรกnรญm modelu | -| `/api/settings/ip-filter` | GET/PUT | Sprรกva povolenรฝch/blokovanรฝch IP adres | -| `/api/settings/thinking-budget` | GET/PUT | Konfigurace rozpoฤtu tokenลฏ zdลฏvodnฤ›nรญ (prลฏchozรญ/automatickรก/vlastnรญ/adaptivnรญ) | -| `/api/settings/system-prompt` | GET/PUT | Globรกlnรญ vloลพenรญ systรฉmovรฉho promptu pro vลกechny poลพadavky | -| `/api/sessions` | GET | Sledovรกnรญ a metriky aktivnรญch relacรญ | -| `/api/rate-limits` | GET | Stav limitu sazby na รบฤet | - ---- - -## 5. Klรญฤovรฉ nรกvrhovรฉ vzory - -### 5.1 Pล™eklad typu Hub-and-Spoke - -Vลกechny formรกty se pล™eklรกdajรญ prostล™ednictvรญm **formรกtu OpenAI jako รบstล™edny** . Pล™idรกnรญ novรฉho poskytovatele vyลพaduje napsรกnรญ pouze **jednoho pรกru** pล™ekladaฤลฏ (do/z OpenAI), nikoli N pรกrลฏ. - -### 5.2 Vzor strategie exekutora - -Kaลพdรฝ poskytovatel mรก vyhrazenou tล™รญdu exekutoru, kterรก dฤ›dรญ z `BaseExecutor` . Tovรกrna v `executors/index.ts` vybere ten sprรกvnรฝ za bฤ›hu. - -### 5.3 Systรฉm samoregistraฤnรญch pluginลฏ - -Moduly pล™ekladaฤe se pล™i importu registrujรญ pomocรญ `register()` . Pล™idรกnรญ novรฉho pล™ekladaฤe znamenรก pouze vytvoล™enรญ souboru a jeho import. - -### 5.4 Zรกloลพnรญ รบฤet s exponenciรกlnรญm oddluลพenรญm - -Kdyลพ poskytovatel vrรกtรญ 429/401/500, systรฉm mลฏลพe pล™epnout na dalลกรญ รบฤet s exponenciรกlnรญm zpoลพdฤ›nรญm (1s โ†’ 2s โ†’ 4s โ†’ max. 2min). - -### 5.5 Kombinovanรฉ modelovรฉ ล™etฤ›zy - -โ€žKombinaceโ€œ seskupuje vรญce ล™etฤ›zcลฏ `provider/model` . Pokud prvnรญ selลพe, automaticky se vrรกtรญ k dalลกรญmu. - -### 5.6 Stavovรฝ streamovacรญ pล™eklad - -Pล™eklad odpovฤ›dรญ udrลพuje stav napล™รญฤ bloky SSE (sledovรกnรญ myลกlenkovรฝch blokลฏ, akumulace volรกnรญ nรกstrojลฏ, indexovรกnรญ blokลฏ obsahu) prostล™ednictvรญm mechanismu `initState()` . - -### 5.7 Bezpeฤnostnรญ vyrovnรกvacรญ pamฤ›ลฅ pro pouลพitรญ - -K hlรกลกenรฉmu vyuลพitรญ je pล™idรกna vyrovnรกvacรญ pamฤ›ลฅ o kapacitฤ› 2000 tokenลฏ, aby se zabrรกnilo tomu, ลพe klienti dosรกhnou limitลฏ kontextovรฉho okna v dลฏsledku reลพijnรญch nรกkladลฏ systรฉmovรฝch vรฝzev a pล™ekladu formรกtu. - ---- - -## 6. Podporovanรฉ formรกty - -| Formรกt | Smฤ›r | Identifikรกtor | -| ----------------------- | ----------- | ------------------ | -| OpenAI Chat Completions | zdroj + cรญl | `openai` | -| OpenAI Responses API | zdroj + cรญl | `openai-responses` | -| Anthropic Claude | zdroj + cรญl | `claude` | -| Google Gemini | zdroj + cรญl | `gemini` | -| Google Gemini CLI | jen cรญl | `gemini-cli` | -| Antigravity | zdroj + cรญl | `antigravity` | -| AWS Kiro | jen cรญl | `kiro` | -| Cursor | jen cรญl | `cursor` | - ---- - -## 7. Podporovanรญ poskytovatelรฉ - -| Poskytovatel | Metoda ovฤ›ล™ovรกnรญ | Vykonavatel | Klรญฤovรฉ poznรกmky | -| ------------------------ | ------------------------ | ----------- | -------------------------------------------- | -| Anthropic Claude | API klรญฤ nebo OAuth | Vรฝchozรญ | Pouลพรญvรก hlaviฤku `x-api-key` | -| Google Gemini | API klรญฤ nebo OAuth | Vรฝchozรญ | Pouลพรญvรก hlaviฤku `x-goog-api-key` | -| Google Gemini CLI | OAuth | GeminiCLI | Pouลพรญvรก koncovรฝ bod `streamGenerateContent` | -| Antigravity | OAuth | Antigravity | Zรกloลพnรญ vรญce URL, analรฝza opakovanรฝch pokusลฏ | -| OpenAI | API klรญฤ | Vรฝchozรญ | Autorizace standardnรญho nosiฤe | -| Codex | OAuth | Codex | Vklรกdรก systรฉmovรฉ instrukce, ล™รญdรญ myลกlenรญ | -| GitHub Copilot | OAuth + Copilot token | Github | Duรกlnรญ token, napodobovรกnรญ zรกhlavรญ VSCode | -| Kiro (AWS) | AWS SSO OIDC nebo Social | Kiro | Analรฝza binรกrnรญho EventStreamu | -| Cursor IDE | Checksum auth | Cursor | Kรณdovรกnรญ Protobuf, kontrolnรญ souฤty SHA-256 | -| Qwen | OAuth | Vรฝchozรญ | Standardnรญ ovฤ›ล™ovรกnรญ | -| Qoder | OAuth (Basic + Bearer) | Vรฝchozรญ | Duรกlnรญ hlaviฤka pro autorizaci | -| OpenRouter | API klรญฤ | Vรฝchozรญ | Autorizace standardnรญho nosiฤe | -| GLM, Kimi, MiniMax | API klรญฤ | Vรฝchozรญ | Kompatibilnรญ s Claude, pouลพijte `x-api-key` | -| `openai-compatible-*` | API klรญฤ | Vรฝchozรญ | Dynamickรฉ: jakรฝkoli OpenAI kompatibilnรญ | -| `anthropic-compatible-*` | API klรญฤ | Vรฝchozรญ | Dynamickรฉ: jakรฝkoli Claude kompatibilnรญ | - ---- - -## 8. Souhrn datovรฉho toku - -### ลฝรกdost o streamovรกnรญ - -```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()"] -``` - -### ลฝรกdost o nestreamovรกnรญ - -```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"] -``` - -### Obtokovรฝ tok (Claude CLI) - -```mermaid -flowchart LR - A["Claude CLI request"] --> B{"Match bypass\npattern?"} - B -->|"Title/Warmup/Count"| C["Generate fake\nOpenAI response"] - B -->|"No match"| D["Normal flow"] - C --> E["Translate to\nsource format"] - E --> F["Return without\ncalling provider"] -``` diff --git a/docs/i18n/cs/CONTRIBUTING.md b/docs/i18n/cs/CONTRIBUTING.md index c5032002c9..4a85334808 100644 --- a/docs/i18n/cs/CONTRIBUTING.md +++ b/docs/i18n/cs/CONTRIBUTING.md @@ -1,18 +1,22 @@ -# Pล™ispรญvรกnรญ k OmniRoute +# Contributing to OmniRoute (ฤŒeลกtina) -Dฤ›kujeme za vรกลก zรกjem o pล™ispฤ›nรญ! Tato pล™รญruฤka obsahuje vลกe, co potล™ebujete k zahรกjenรญ. +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CONTRIBUTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CONTRIBUTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CONTRIBUTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CONTRIBUTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CONTRIBUTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CONTRIBUTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CONTRIBUTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CONTRIBUTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CONTRIBUTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CONTRIBUTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CONTRIBUTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CONTRIBUTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CONTRIBUTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CONTRIBUTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CONTRIBUTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CONTRIBUTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CONTRIBUTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CONTRIBUTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CONTRIBUTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CONTRIBUTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CONTRIBUTING.md) --- -## Nastavenรญ vรฝvoje +Thank you for your interest in contributing! This guide covers everything you need to get started. -### Pล™edpoklady +--- -- **Node.js** 20+ (doporuฤeno: 22 LTS) +## Development Setup + +### Prerequisites + +- **Node.js** >= 18 < 24 (recommended: 22 LTS) - **npm** 10+ - **Git** -### Klonovat a instalovat +### Clone & Install ```bash git clone https://github.com/diegosouzapw/OmniRoute.git @@ -20,7 +24,7 @@ cd OmniRoute npm install ``` -### Promฤ›nnรฉ prostล™edรญ +### Environment Variables ```bash # Create your .env from the template @@ -31,17 +35,28 @@ echo "JWT_SECRET=$(openssl rand -base64 48)" >> .env echo "API_KEY_SECRET=$(openssl rand -hex 32)" >> .env ``` -Klรญฤovรฉ promฤ›nnรฉ pro vรฝvoj: +Key variables for development: -Promฤ›nnรก | Vรฝchozรญ nastavenรญ pro vรฝvoj | Popis ---- | --- | --- -`PORT` | `3000` | Port serveru -`NEXT_PUBLIC_BASE_URL` | `http://localhost:3000` | Zรกkladnรญ URL pro frontend -`JWT_SECRET` | (vygenerovat vรฝลกe) | Tajemstvรญ podpisu JWT -`INITIAL_PASSWORD` | `123456` | Prvnรญ pล™ihlaลกovacรญ heslo -`ENABLE_REQUEST_LOGS` | `false` | Povolit protokoly poลพadavkลฏ na ladฤ›nรญ +| Variable | Development Default | Description | +| ---------------------- | ------------------------ | --------------------- | +| `PORT` | `20128` | Server port | +| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | Base URL for frontend | +| `JWT_SECRET` | (generate above) | JWT signing secret | +| `INITIAL_PASSWORD` | `CHANGEME` | First login password | +| `APP_LOG_LEVEL` | `info` | Log verbosity level | -### Spuลกtฤ›no lokรกlnฤ› +### Dashboard Settings + +The dashboard provides UI toggles for features that can also be configured via environment variables: + +| Setting Location | Toggle | Description | +| ------------------- | ------------------ | ------------------------------ | +| Settings โ†’ Advanced | Debug Mode | Enable debug request logs (UI) | +| Settings โ†’ General | Sidebar Visibility | Show/hide sidebar sections | + +These settings are stored in the database and persist across restarts, overriding env var defaults when set. + +### Running Locally ```bash # Development mode (hot reload) @@ -55,16 +70,16 @@ npm run start PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev ``` -Vรฝchozรญ adresy URL: +Default URLs: -- **Dashboard** : `http://localhost:3000/dashboard` -- **API** : `http://localhost:3000/v1` +- **Dashboard**: `http://localhost:20128/dashboard` +- **API**: `http://localhost:20128/v1` --- -## Pracovnรญ postup Gitu +## Git Workflow -> โš ๏ธ **NIKDY se necommitujte pล™รญmo do `main` .** Vลพdy pouลพรญvejte vฤ›tve feature. +> โš ๏ธ **NEVER commit directly to `main`.** Always use feature branches. ```bash git checkout -b feat/your-feature-name @@ -74,20 +89,20 @@ git push -u origin feat/your-feature-name # Open a Pull Request on GitHub ``` -### Pojmenovรกnรญ poboฤek +### Branch Naming -Pล™edpona | รšฤel ---- | --- -`feat/` | Novรฉ funkce -`fix/` | Opravy chyb -`refactor/` | Restrukturalizace kรณdu -`docs/` | Zmฤ›ny dokumentace -`test/` | Doplnฤ›nรญ/opravy testลฏ -`chore/` | Nรกstroje, CI, zรกvislosti +| Prefix | Purpose | +| ----------- | ------------------------- | +| `feat/` | New features | +| `fix/` | Bug fixes | +| `refactor/` | Code restructuring | +| `docs/` | Documentation changes | +| `test/` | Test additions/fixes | +| `chore/` | Tooling, CI, dependencies | -### Zprรกvy o potvrzenรญ +### Commit Messages -Postupujte podle [konvenฤnรญch commitลฏ](https://www.conventionalcommits.org/) : +Follow [Conventional Commits](https://www.conventionalcommits.org/): ``` feat: add circuit breaker for provider calls @@ -97,177 +112,188 @@ test: add observability unit tests refactor(db): consolidate rate limit tables ``` -Rozsahy: `db` , `sse` , `oauth` , `dashboard` , `api` , `cli` , `docker` , `ci` . +Scopes: `db`, `sse`, `oauth`, `dashboard`, `api`, `cli`, `docker`, `ci`, `mcp`, `a2a`, `memory`, `skills`. --- -## Spouลกtฤ›nรญ testลฏ +## Running Tests ```bash -# All unit tests -npm test -npm run test:unit +# All tests (unit + vitest + ecosystem + e2e) +npm run test:all -# Specific test suites -npm run test:security # Security tests -npm run test:fixes # Fix verification tests +# Single test file (Node.js native test runner โ€” most tests use this) +node --import tsx/esm --test tests/unit/your-file.test.mjs -# With coverage -npm run test:coverage +# Vitest (MCP server, autoCombo, cache) +npm run test:vitest # E2E tests (requires Playwright) npm run test:e2e +# Protocol clients E2E (MCP transports, A2A) +npm run test:protocols:e2e + +# Ecosystem compatibility tests +npm run test:ecosystem + +# Coverage (55% min statements/lines/functions; 60% branches) +npm run test:coverage +npm run coverage:report + # Lint + format check npm run lint npm run check ``` -Aktuรกlnรญ stav testovรกnรญ: **368+ jednotkovรฝch testลฏ** zahrnujรญcรญch: +Coverage notes: -- Poskytovatelรฉ pล™ekladลฏ a konverze formรกtลฏ -- Omezenรญ rychlosti, jistiฤ a odolnost -- Sรฉmantickรก mezipamฤ›ลฅ, idempotence, sledovรกnรญ prลฏbฤ›hu -- Databรกzovรฉ operace a schรฉma -- Toky a ovฤ›ล™ovรกnรญ OAuth -- Ovฤ›ล™enรญ koncovรฉho bodu API +- `npm run test:coverage` measures source coverage for the main unit test suite, excludes `tests/**`, and includes `open-sse/**` +- `npm run coverage:report` prints the detailed file-by-file report from the latest coverage run +- `npm run test:coverage:legacy` preserves the older metric for historical comparison +- See `docs/COVERAGE_PLAN.md` for the phased coverage improvement roadmap + +Current test status: **122 unit test files** covering: + +- Provider translators and format conversion +- Rate limiting, circuit breaker, and resilience +- Semantic cache, idempotency, progress tracking +- Database operations and schema (21 DB modules) +- OAuth flows and authentication +- API endpoint validation (Zod v4) +- MCP server tools and scope enforcement +- Memory and Skills systems --- -## Styl kรณdu +## Code Style -- **ESLint** โ€” Spustรญ `npm run lint` pล™ed commitem -- **Hezฤรญ** โ€“ Automaticky naformรกtovรกno pomocรญ `lint-staged` pล™i commitu -- **TypeScript** โ€” Veลกkerรฝ kรณd `src/` pouลพรญvรก `.ts` / `.tsx` ; dokument s TSDoc ( `@param` , `@returns` , `@throws` ) -- **No `eval()`** โ€” ESLint vynucuje `no-eval` , `no-implied-eval` , `no-new-func` -- **Ovฤ›ล™enรญ Zod** โ€” Pouลพitรญ schรฉmat Zod pro ovฤ›ล™ovรกnรญ vstupu API +- **ESLint** โ€” Run `npm run lint` before committing +- **Prettier** โ€” Auto-formatted via `lint-staged` on commit (2 spaces, semicolons, double quotes, 100 char width, es5 trailing commas) +- **TypeScript** โ€” All `src/` code uses `.ts`/`.tsx`; `open-sse/` uses `.ts`/`.js`; document with TSDoc (`@param`, `@returns`, `@throws`) +- **No `eval()`** โ€” ESLint enforces `no-eval`, `no-implied-eval`, `no-new-func` +- **Zod validation** โ€” Use Zod v4 schemas for all API input validation +- **Naming**: Files = camelCase/kebab-case, components = PascalCase, constants = UPPER_SNAKE --- -## Struktura projektu +## Project Structure ``` src/ # TypeScript (.ts / .tsx) -โ”œโ”€โ”€ app/ # Next.js App Router -โ”‚ โ”œโ”€โ”€ (dashboard)/ # Dashboard pages (.tsx) -โ”‚ โ”œโ”€โ”€ api/ # API routes (.ts) +โ”œโ”€โ”€ app/ # Next.js 16 App Router +โ”‚ โ”œโ”€โ”€ (dashboard)/ # Dashboard pages (23 sections) +โ”‚ โ”œโ”€โ”€ api/ # API routes (51 directories) โ”‚ โ””โ”€โ”€ login/ # Auth pages (.tsx) -โ”œโ”€โ”€ domain/ # Domain types and response helpers (.ts) +โ”œโ”€โ”€ domain/ # Policy engine (policyEngine, comboResolver, costRules, etc.) โ”œโ”€โ”€ lib/ # Core business logic (.ts) -โ”‚ โ”œโ”€โ”€ db/ # SQLite database layer -โ”‚ โ”œโ”€โ”€ oauth/ # OAuth services per provider -โ”‚ โ”œโ”€โ”€ cacheLayer.ts # LRU cache -โ”‚ โ”œโ”€โ”€ semanticCache.ts # Semantic response cache -โ”‚ โ”œโ”€โ”€ idempotencyLayer.ts # Request deduplication -โ”‚ โ””โ”€โ”€ localDb.ts # Settings facade (LowDB for config, SQLite for domain data) +โ”‚ โ”œโ”€โ”€ a2a/ # Agent-to-Agent v0.3 protocol server +โ”‚ โ”œโ”€โ”€ acp/ # Agent Communication Protocol registry +โ”‚ โ”œโ”€โ”€ compliance/ # Compliance policy engine +โ”‚ โ”œโ”€โ”€ db/ # SQLite database layer (21 modules + 16 migrations) +โ”‚ โ”œโ”€โ”€ memory/ # Persistent conversational memory +โ”‚ โ”œโ”€โ”€ oauth/ # OAuth providers, services, and utilities +โ”‚ โ”œโ”€โ”€ skills/ # Extensible skill framework +โ”‚ โ”œโ”€โ”€ usage/ # Usage tracking and cost calculation +โ”‚ โ””โ”€โ”€ localDb.ts # Re-export layer only โ€” never add logic here +โ”œโ”€โ”€ middleware/ # Request middleware (promptInjectionGuard) +โ”œโ”€โ”€ mitm/ # MITM proxy (cert, DNS, target routing) โ”œโ”€โ”€ shared/ โ”‚ โ”œโ”€โ”€ components/ # React components (.tsx) -โ”‚ โ”œโ”€โ”€ middleware/ # Correlation IDs, etc. -โ”‚ โ”œโ”€โ”€ utils/ # Circuit breaker, sanitizer, etc. -โ”‚ โ””โ”€โ”€ validation/ # Zod schemas -โ””โ”€โ”€ sse/ # SSE chat handlers (.ts) +โ”‚ โ”œโ”€โ”€ constants/ # Provider definitions (60+), MCP scopes, routing strategies +โ”‚ โ”œโ”€โ”€ utils/ # Circuit breaker, sanitizer, auth helpers +โ”‚ โ””โ”€โ”€ validation/ # Zod v4 schemas +โ””โ”€โ”€ sse/ # SSE proxy pipeline -open-sse/ # @omniroute/open-sse workspace (JavaScript) -โ”œโ”€โ”€ handlers/ # chatCore.js โ€” main request handler -โ”œโ”€โ”€ services/ # Rate limit, fallback -โ”œโ”€โ”€ translators/ # Format converters (OpenAI โ†” Claude โ†” Gemini) -โ””โ”€โ”€ utils/ # Progress tracker, stream helpers +open-sse/ # @omniroute/open-sse workspace +โ”œโ”€โ”€ executors/ # 14 provider-specific request executors +โ”œโ”€โ”€ handlers/ # 11 request handlers (chat, responses, embeddings, images, etc.) +โ”œโ”€โ”€ mcp-server/ # MCP server (25 tools, 3 transports, 10 scopes) +โ”œโ”€โ”€ services/ # 36+ services (combo, autoCombo, rateLimitManager, etc.) +โ”œโ”€โ”€ translator/ # Format translators (OpenAI โ†” Claude โ†” Gemini โ†” Responses โ†” Ollama) +โ”œโ”€โ”€ transformer/ # Responses API transformer +โ””โ”€โ”€ utils/ # 22 utility modules (stream, TLS, proxy, logging) + +electron/ # Electron desktop app (cross-platform) tests/ -โ”œโ”€โ”€ unit/ # Node.js test runner (.test.mjs) -โ””โ”€โ”€ e2e/ # Playwright tests +โ”œโ”€โ”€ unit/ # Node.js test runner (122 test files) +โ”œโ”€โ”€ integration/ # Integration tests +โ”œโ”€โ”€ e2e/ # Playwright tests +โ”œโ”€โ”€ security/ # Security tests +โ”œโ”€โ”€ translator/ # Translator-specific tests +โ””โ”€โ”€ load/ # Load tests docs/ # Documentation -โ”œโ”€โ”€ USER_GUIDE.md # Provider setup, CLI integration -โ”œโ”€โ”€ API_REFERENCE.md # All endpoints -โ”œโ”€โ”€ TROUBLESHOOTING.md # Common issues โ”œโ”€โ”€ ARCHITECTURE.md # System architecture +โ”œโ”€โ”€ API_REFERENCE.md # All endpoints +โ”œโ”€โ”€ USER_GUIDE.md # Provider setup, CLI integration +โ”œโ”€โ”€ TROUBLESHOOTING.md # Common issues +โ”œโ”€โ”€ MCP-SERVER.md # MCP server (25 tools) +โ”œโ”€โ”€ A2A-SERVER.md # A2A agent protocol +โ”œโ”€โ”€ AUTO-COMBO.md # Auto-combo engine +โ”œโ”€โ”€ CLI-TOOLS.md # CLI tools integration +โ”œโ”€โ”€ COVERAGE_PLAN.md # Test coverage improvement plan +โ”œโ”€โ”€ openapi.yaml # OpenAPI specification โ””โ”€โ”€ adr/ # Architecture Decision Records ``` --- -## Pล™idรกnรญ novรฉho poskytovatele +## Adding a New Provider -### Krok 1: Sluลพba OAuth (pokud pouลพรญvรกte OAuth) +### Step 1: Register Provider Constants -Vytvoล™te `src/lib/oauth/services/your-provider.ts` rozลกiล™ujรญcรญ `OAuthService` : +Add to `src/shared/constants/providers.ts` โ€” Zod-validated at module load. -```typescript -import { OAuthService } from "../OAuthService"; +### Step 2: Add Executor (if custom logic needed) -export class YourProviderService extends OAuthService { - constructor() { - super({ - name: "your-provider", - authUrl: "https://provider.com/oauth/authorize", - tokenUrl: "https://provider.com/oauth/token", - clientId: "...", - scopes: ["..."], - }); - } -} -``` +Create executor in `open-sse/executors/your-provider.ts` extending the base executor. -### Krok 2: Registrace poskytovatele +### Step 3: Add Translator (if non-OpenAI format) -Pล™idat do `src/lib/oauth/providers.ts` : +Create request/response translators in `open-sse/translator/`. -```typescript -import { YourProviderService } from "./services/your-provider"; -// Add to the providers map -``` +### Step 4: Add OAuth Config (if OAuth-based) -### Krok 3: Pล™idรกnรญ konstant +Add OAuth credentials in `src/lib/oauth/constants/oauth.ts` and service in `src/lib/oauth/services/`. -Pล™idejte konstanty poskytovatele do `src/lib/providerConstants.ts` : +### Step 5: Register Models -- Pล™edpona poskytovatele (napล™. `yp/` ) -- Vรฝchozรญ modely -- Informace o cenรกch +Add model definitions in `open-sse/config/providerRegistry.ts`. -### Krok 4: Pล™idรกnรญ pล™ekladaฤe (pokud se nejednรก o formรกt OpenAI) +### Step 6: Add Tests -Pokud poskytovatel pouลพรญvรก vlastnรญ formรกt API, vytvoล™te pล™ekladaฤ v `open-sse/translators/` . +Write unit tests in `tests/unit/` covering at minimum: -### Krok 5: Pล™idรกnรญ ฤasovรฉho limitu - -Pล™idejte konfiguraci ฤasovรฉho limitu poลพadavku do `src/shared/utils/requestTimeout.ts` . - -### Krok 6: Pล™idรกnรญ testลฏ - -Piลกte jednotkovรฉ testy v `tests/unit/` kterรฉ pokrรฝvajรญ minimรกlnฤ›: - -- Registrace poskytovatele -- Pล™eklad ลพรกdostรญ/odpovฤ›dรญ -- Oลกetล™enรญ chyb +- Provider registration +- Request/response translation +- Error handling --- -## Kontrolnรญ seznam ลพรกdostรญ o nataลพenรญ +## Pull Request Checklist -- [ ] Testy proลกly ( `npm test` ) -- [ ] Prลฏchody pro linting ( `npm run lint` ) -- [ ] Sestavenรญ probฤ›hlo รบspฤ›ลกnฤ› ( `npm run build` ) -- [ ] Pro novรฉ veล™ejnรฉ funkce a rozhranรญ pล™idรกny typy TypeScript -- [ ] ลฝรกdnรฉ pevnฤ› zakรณdovanรฉ tajnรฉ kรณdy ani zรกloลพnรญ hodnoty -- [ ] Aktualizovรกn CHANGELOG (pokud se zmฤ›na tรฝkรก uลพivatele) -- [ ] Aktualizovanรก dokumentace (pokud je to relevantnรญ) +- [ ] 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 +- [ ] All inputs validated with Zod schemas +- [ ] CHANGELOG updated (if user-facing change) +- [ ] Documentation updated (if applicable) --- -## Uvolnฤ›nรญ +## Releasing -Kdyลพ je vytvoล™ena novรก verze GitHubu (napล™. `v0.4.0` ), balรญฤek je **automaticky publikovรกn do npm** prostล™ednictvรญm akcรญ GitHubu: - -```bash -gh release create v0.4.0 --title "v0.4.0" --generate-notes -``` +Releases are managed via the `/generate-release` workflow. When a new GitHub Release is created, the package is **automatically published to npm** via GitHub Actions. --- -## Zรญskรกnรญ pomoci +## Getting Help -- **Architektura** : Viz [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) -- **Problรฉmy** : [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **ADR** : Viz `docs/adr/` +- **Architecture**: See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) +- **API Reference**: See [`docs/API_REFERENCE.md`](docs/API_REFERENCE.md) +- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **ADRs**: See `docs/adr/` for architectural decision records diff --git a/docs/i18n/cs/FEATURES.md b/docs/i18n/cs/FEATURES.md deleted file mode 100644 index 9bc266b440..0000000000 --- a/docs/i18n/cs/FEATURES.md +++ /dev/null @@ -1,143 +0,0 @@ -# OmniRoute โ€” Galerie funkcรญ ล™รญdicรญho panelu - -๐ŸŒ **Jazyky:** ๐Ÿ‡บ๐Ÿ‡ธ [angliฤtina](FEATURES.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brazรญlie)](i18n/pt-BR/FEATURES.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/FEATURES.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/FEATURES.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/FEATURES.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/FEATURES.md) | ๐Ÿ‡จ๐Ÿ‡ณ[ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/FEATURES.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/FEATURES.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/FEATURES.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/FEATURES.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/FEATURES.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/FEATURES.md) | ๐Ÿ‡ฏ๐Ÿ‡ต[ๆ—ฅๆœฌ่ชž](i18n/ja/FEATURES.md)| ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/FEATURES.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/FEATURES.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dรกnsko](i18n/da/FEATURES.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/FEATURES.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/FEATURES.md) | ๐Ÿ‡ญ๐Ÿ‡บ [maฤarลกtina](i18n/hu/FEATURES.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonรฉsie](i18n/id/FEATURES.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/FEATURES.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/FEATURES.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nizozemsko](i18n/nl/FEATURES.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/FEATURES.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugalsko)](i18n/pt/FEATURES.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/FEATURES.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/FEATURES.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/FEATURES.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/FEATURES.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipรญnec](i18n/phi/FEATURES.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](i18n/cs/FEATURES.md) - -Vizuรกlnรญ prลฏvodce vลกemi ฤรกstmi ovlรกdacรญho panelu OmniRoute. - ---- - -## ๐Ÿ”Œ Poskytovatelรฉ - -Spravujte pล™ipojenรญ poskytovatelลฏ AI: poskytovatelรฉ OAuth (Claude Code, Codex, Gemini CLI), poskytovatelรฉ klรญฤลฏ API (Groq, DeepSeek, OpenRouter) a bezplatnรญ poskytovatelรฉ (Qoder, Qwen, Kiro). รšฤty Kiro zahrnujรญ sledovรกnรญ zลฏstatku kreditลฏ โ€“ zbรฝvajรญcรญ kredity, celkovรฝ limit a datum obnovenรญ jsou viditelnรฉ v Dashboard โ†’ Usage. - -![Dashboard poskytovatelลฏ](screenshots/01-providers.png) - ---- - -## ๐ŸŽจ Kombinace - -Vytvรกล™ejte kombinace smฤ›rovรกnรญ modelลฏ pomocรญ 6 strategiรญ: prioritnรญ, vรกลพenรก, kruhovรก, nรกhodnรก, nejmรฉnฤ› pouลพรญvanรก a nรกkladovฤ› optimalizovanรก. Kaลพdรก kombinace ล™etฤ›zรญ vรญce modelลฏ s automatickรฝm pล™epรญnรกnรญm mezi nimi a zahrnuje rychlรฉ ลกablony a kontroly pล™ipravenosti. - -![Dashboard kombinacรญ](screenshots/02-combos.png) - ---- - -## ๐Ÿ“Š Analytika - -Komplexnรญ analรฝzy vyuลพitรญ se spotล™ebou tokenลฏ, odhady nรกkladลฏ, mapami aktivit, tรฝdennรญmi distribuฤnรญmi grafy a rozpisy podle jednotlivรฝch poskytovatelลฏ. - -![Analytickรฝ ล™รญdicรญ panel](screenshots/03-analytics.png) - ---- - -## ๐Ÿฅ Stav systรฉmu - -Monitorovรกnรญ v reรกlnรฉm ฤase: dostupnost, pamฤ›ลฅ, verze, percentily latence (p50/p95/p99), statistiky mezipamฤ›ti a stavy jistiฤลฏ poskytovatelลฏ. - -![Dashboard zdravรญ](screenshots/04-health.png) - ---- - -## ๐Ÿ”ง Pล™ekladatelskรฉ hล™iลกtฤ› - -ฤŒtyล™i reลพimy pro ladฤ›nรญ pล™ekladลฏ API: **Playground** (pล™evodnรญk formรกtลฏ), **Chat Tester** (ลพivรฉ poลพadavky), **Test Bench** (dรกvkovรฉ testy) a **Live Monitor** (stream v reรกlnรฉm ฤase). - -![Hล™iลกtฤ› pล™ekladatelลฏ](screenshots/05-translator.png) - ---- - -## ๐ŸŽฎ Modelovรฉ hล™iลกtฤ› _(v2.0.9+)_ - -Otestujte libovolnรฝ model pล™รญmo z ล™รญdicรญho panelu. Vyberte poskytovatele, model a koncovรฝ bod, piลกte vรฝzvy pomocรญ editoru Monaco, streamujte odpovฤ›di v reรกlnรฉm ฤase, pล™eruลกte stream a zobrazte metriky ฤasovรกnรญ. - ---- - -## ๐ŸŽจ Tรฉmata _(v2.0.5+)_ - -Pล™izpลฏsobitelnรก barevnรก tรฉmata pro celรฝ dashboard. Vyberte si ze 7 pล™ednastavenรฝch barev (korรกlovรก, modrรก, ฤervenรก, zelenรก, fialovรก, oranลพovรก, azurovรก) nebo si vytvoล™te vlastnรญ tรฉma vรฝbฤ›rem libovolnรฉ hexadecimรกlnรญ barvy. Podporuje svฤ›tlรฝ, tmavรฝ a systรฉmovรฝ reลพim. - ---- - -## โš™๏ธ Nastavenรญ - -Komplexnรญ panel nastavenรญ s kartami: - -- **Obecnรฉ** โ€“ Systรฉmovรฉ รบloลพiลกtฤ›, sprรกva zรกloh (export/import databรกze) -- **Vzhled** โ€“ Vรฝbฤ›r motivu (tmavรฝ/svฤ›tlรฝ/systรฉmovรฝ), pล™ednastavenรฉ barevnรฉ motivy a vlastnรญ barvy, viditelnost protokolu stavu -- **Zabezpeฤenรญ** โ€” ochrana koncovรฝch bodลฏ API, blokovรกnรญ vlastnรญch poskytovatelลฏ, filtrovรกnรญ IP adres, informace o relaci -- **Smฤ›rovรกnรญ** โ€” Aliasy modelลฏ, degradace รบloh na pozadรญ -- **Odolnost** โ€” Perzistence omezenรญ rychlosti, ladฤ›nรญ jistiฤe -- **Pokroฤilรฉ** โ€“ Pล™epsรกnรญ konfigurace - -![Ovlรกdacรญ panel nastavenรญ](screenshots/06-settings.png) - ---- - -## ๐Ÿ”ง Nรกstroje CLI - -Konfigurace nรกstrojลฏ pro kรณdovรกnรญ s umฤ›lou inteligencรญ jednรญm kliknutรญm: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor a Factory Droid. Nabรญzรญ automatickรฉ pouลพitรญ/resetovรกnรญ konfigurace, profily pล™ipojenรญ a mapovรกnรญ modelลฏ. - -![ล˜รญdicรญ panel nรกstrojลฏ CLI](screenshots/07-cli-tools.png) - ---- - -## ๐Ÿค– Agenti CLI _(v2.0.11+)_ - -Ovlรกdacรญ panel pro vyhledรกvรกnรญ a sprรกvu agentลฏ CLI. Zobrazuje mล™รญลพku 14 vestavฤ›nรฝch agentลฏ (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) s: - -- **Stav instalace** โ€” Nainstalovรกno / Nenalezeno s detekcรญ verze -- **Odznaky protokolลฏ** โ€“ stdio, HTTP atd. -- **Vlastnรญ agenti** โ€” Registrace libovolnรฉho nรกstroje CLI pomocรญ formulรกล™e (nรกzev, binรกrnรญ soubor, verze pล™รญkazu, argumenty spawn) -- **Porovnรกvรกnรญ otiskลฏ prstลฏ v pล™รญkazovรฉm ล™รกdku** โ€“ Pล™epรญnรกnรญ pro jednotlivรฉ poskytovatele pro porovnรกvรกnรญ nativnรญch podpisลฏ poลพadavkลฏ v pล™รญkazovรฉm ล™รกdku, ฤรญmลพ se sniลพuje riziko zablokovรกnรญ a zรกroveลˆ se zachovรกvรก IP adresa proxy. - ---- - -## ๐Ÿ–ผ๏ธ Mรฉdia _(v2.0.3+)_ - -Generujte obrรกzky, videa a hudbu z ล™รญdicรญho panelu. Podporuje OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open a MusicGen. - ---- - -## ๐Ÿ“ Vyลพรกdat si protokoly - -Protokolovรกnรญ poลพadavkลฏ v reรกlnรฉm ฤase s filtrovรกnรญm podle poskytovatele, modelu, รบฤtu a klรญฤe API. Zobrazuje stavovรฉ kรณdy, vyuลพitรญ tokenลฏ, latenci a podrobnosti o odpovฤ›di. - -![Protokoly pouลพรญvรกnรญ](screenshots/08-usage.png) - ---- - -## ๐ŸŒ Koncovรฝ bod API - -Vรกลก jednotnรฝ koncovรฝ bod API s rozpisem funkcรญ: Dokonฤovรกnรญ chatu, API odpovฤ›dรญ, vklรกdรกnรญ, generovรกnรญ obrรกzkลฏ, zmฤ›na poล™adรญ, pล™epis zvuku, pล™evod textu na ล™eฤ, moderovรกnรญ a registrovanรฉ klรญฤe API. Podpora cloudovรฉho proxy pro vzdรกlenรฝ pล™รญstup. - -![Dashboard koncovรฉho bodu](screenshots/09-endpoint.png) - ---- - -## ๐Ÿ”‘ Sprรกva klรญฤลฏ API - -Vytvรกล™ejte, upravujte rozsah a ruลกte klรญฤe API. Kaลพdรฝ klรญฤ lze omezit na konkrรฉtnรญ modely/poskytovatele s plnรฝm pล™รญstupem nebo oprรกvnฤ›nรญm pouze pro ฤtenรญ. Vizuรกlnรญ sprรกva klรญฤลฏ se sledovรกnรญm vyuลพitรญ. - ---- - -## ๐Ÿ“‹ Zรกznam auditu - -Sledovรกnรญ administrativnรญch akcรญ s filtrovรกnรญm podle typu akce, aktรฉra, cรญle, IP adresy a ฤasovรฉho razรญtka. รšplnรก historie bezpeฤnostnรญch udรกlostรญ. - ---- - -## ๐Ÿ–ฅ๏ธ Desktopovรก aplikace - -Desktopovรก aplikace Native Electron pro Windows, macOS a Linux. Spouลกtฤ›jte OmniRoute jako samostatnou aplikaci s integracรญ do systรฉmovรฉ liลกty, podporou offline, automatickรฝmi aktualizacemi a instalacรญ jednรญm kliknutรญm. - -Klรญฤovรฉ vlastnosti: - -- Dotazovรกnรญ pล™ipravenosti serveru (ลพรกdnรก prรกzdnรก obrazovka pล™i studenรฉm startu) -- Systรฉmovรฝ panel se sprรกvou portลฏ -- Zรกsady zabezpeฤenรญ obsahu -- Jednoinstanฤnรญ zรกmek -- Automatickรก aktualizace pล™i restartu -- Podmรญnฤ›nรฉ uลพivatelskรฉ rozhranรญ pro platformu (semafory pro macOS, vรฝchozรญ zรกhlavรญ okna pro Windows/Linux) -- Zpevnฤ›nรฉ balenรญ buildลฏ Electron โ€” symbolicky odkazovanรฉ `node_modules` v samostatnรฉm balรญฤku jsou detekovรกny a odmรญtnuty pล™ed balenรญm, ฤรญmลพ se zabrรกnรญ zรกvislosti na buildovacรญm stroji za bฤ›hu (v2.5.5+) - -๐Ÿ“– รšplnou dokumentaci naleznete v [`electron/README.md`](../electron/README.md) . diff --git a/docs/i18n/cs/MCP-SERVER.md b/docs/i18n/cs/MCP-SERVER.md deleted file mode 100644 index ee2df76e53..0000000000 --- a/docs/i18n/cs/MCP-SERVER.md +++ /dev/null @@ -1,83 +0,0 @@ -# Dokumentace k serveru OmniRoute MCP - -> Server protokolu kontextu modelu s 16 inteligentnรญmi nรกstroji - -## Instalace - -OmniRoute MCP je integrovanรฝ. Spusลฅte ho pomocรญ: - -```bash -omniroute --mcp -``` - -Nebo prostล™ednictvรญm open-sse transportu: - -```bash -# HTTP streamable transport (port 20130) -omniroute --dev # MCP auto-starts on /mcp endpoint -``` - -## Konfigurace IDE - -Viz [konfigurace IDE](integrations/ide-configs.md) pro nastavenรญ Antigravity, Cursoru, Copilota a Claude Desktopu. - ---- - -## Zรกkladnรญ nรกstroje (8) - -Nรกstroj | Popis -:-- | :-- -`omniroute_get_health` | Stav brรกny, jistiฤe, provozuschopnost -`omniroute_list_combos` | Vลกechny nakonfigurovanรฉ kombinace s modely -`omniroute_get_combo_metrics` | Metriky vรฝkonu pro konkrรฉtnรญ kombinaci -`omniroute_switch_combo` | Pล™epnout aktivnรญ kombinaci podle ID/jmรฉna -`omniroute_check_quota` | Stav kvรณty pro jednotlivรฉ poskytovatele nebo vลกechny -`omniroute_route_request` | Odeslรกnรญ dokonฤenรญ chatu pล™es OmniRoute -`omniroute_cost_report` | Analรฝza nรกkladลฏ za urฤitรฉ ฤasovรฉ obdobรญ -`omniroute_list_models_catalog` | Kompletnรญ katalog modelลฏ s funkcemi - -## Pokroฤilรฉ nรกstroje (8) - -Nรกstroj | Popis -:-- | :-- -`omniroute_simulate_route` | Simulace trasovรกnรญ na dryru s fallback stromem -`omniroute_set_budget_guard` | Rozpoฤet relace s akcemi degradace/blokovรกnรญ/upozornฤ›nรญ -`omniroute_set_resilience_profile` | Pouลพรญt konzervativnรญ/vyvรกลพenรฝ/agresivnรญ pล™edvolbu -`omniroute_test_combo` | ลฝivรฉ testovรกnรญ vลกech modelลฏ v kombinaci -`omniroute_get_provider_metrics` | Podrobnรฉ metriky pro jednoho poskytovatele -`omniroute_best_combo_for_task` | Doporuฤenรญ pro splnฤ›nรญ รบkolu a jeho vhodnosti s alternativami -`omniroute_explain_route` | Vysvฤ›tlete minulรฉ rozhodnutรญ o trase -`omniroute_get_session_snapshot` | Stav celรฉ relace: nรกklady, tokeny, chyby - -## Ovฤ›ล™ovรกnรญ - -Nรกstroje MCP jsou ovฤ›ล™ovรกny pomocรญ rozsahลฏ klรญฤลฏ API. Kaลพdรฝ nรกstroj vyลพaduje specifickรฉ rozsahy: - -Rozsah | Nรกstroje -:-- | :-- -`read:health` | get_health, get_provider_metrics -`read:combos` | seznam_kombinacรญ, zรญskรกnรญ_kombinovanรฝch_metrik -`write:combos` | pล™epรญnaฤ_kombinace -`read:quota` | check_quote -`write:route` | poลพadavek_trasy, simulace_trasy, testovacรญ_kombinace -`read:usage` | zprรกva_o_nรกkladech, zรญskรกnรญ_snรญmku_relace, vysvฤ›tlenรญ_trasy -`write:config` | set_budget_guard, set_resilience_profile -`read:models` | seznam_modelลฏ_katalog, nejlepลกรญ_kombinace_pro_รบkol - -## Protokolovรกnรญ auditu - -Kaลพdรฉ volรกnรญ nรกstroje je zaznamenรกno do `mcp_tool_audit` s touto funkcรญ: - -- Nรกzev nรกstroje, argumenty, vรฝsledek -- Trvรกnรญ (ms), รบspฤ›ch/neรบspฤ›ch -- Haลก klรญฤe API, ฤasovรฉ razรญtko - -## Soubory - -Soubor | รšฤel -:-- | :-- -`open-sse/mcp-server/server.ts` | Vytvoล™enรญ MCP serveru + 16 registracรญ nรกstrojลฏ -`open-sse/mcp-server/transport.ts` | Stdio + HTTP transport -`open-sse/mcp-server/auth.ts` | Ovฤ›ล™enรญ klรญฤe API + rozsahu -`open-sse/mcp-server/audit.ts` | Protokolovรกnรญ auditu volรกnรญ nรกstrojลฏ -`open-sse/mcp-server/tools/advancedTools.ts` | 8 pokroฤilรฝch manipulรกtorลฏ s nรกstroji diff --git a/docs/i18n/cs/README.md b/docs/i18n/cs/README.md index 67ad8c173f..5f1e13788d 100644 --- a/docs/i18n/cs/README.md +++ b/docs/i18n/cs/README.md @@ -1,145 +1,239 @@ -# ๐Ÿš€ OmniRoute โ€” Bezplatnรก brรกna umฤ›lรฉ inteligence +# ๐Ÿš€ OmniRoute โ€” The Free AI Gateway (ฤŒeลกtina) -### Nikdy nepล™estรกvejte s kรณdovรกnรญm. Chytrรฉ smฤ›rovรกnรญ k **BEZPLATNรM a levnรฝm modelลฏm AI** s automatickรฝm pล™epรญnรกnรญm mezi zรกloลพnรญmi systรฉmy. +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/README.md) -_Vรกลก univerzรกlnรญ API proxy โ€“ jeden endpoint, vรญce neลพ 44 poskytovatelลฏ, nulovรฉ vรฝpadky. Nynรญ s orchestracรญ agentลฏ **MCP a A2A** ._ +--- -**Dokonฤenรญ chatu โ€ข Vklรกdรกnรญ โ€ข Generovรกnรญ obrรกzkลฏ โ€ข Video โ€ข Hudba โ€ข Audio โ€ข Zmฤ›na poล™adรญ โ€ข **Vyhledรกvรกnรญ na webu** โ€ข MCP server โ€ข A2A protokol โ€ข 100% TypeScript** +### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback. + +_Your universal API proxy โ€” one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._ + +**Chat Completions โ€ข Embeddings โ€ข Image Generation โ€ข Video โ€ข Music โ€ข Audio โ€ข Reranking โ€ข **Web Search** โ€ข MCP Server โ€ข A2A Protocol โ€ข 100% TypeScript** ---
+ +[![npm version](https://img.shields.io/npm/v/omniroute?color=cb3837&logo=npm)](https://www.npmjs.com/package/omniroute) +[![npm downloads](https://img.shields.io/npm/dm/omniroute?color=cb3837&logo=npm&label=npm%20downloads)](https://www.npmjs.com/package/omniroute) +[![Docker Hub](https://img.shields.io/docker/v/diegosouzapw/omniroute?label=Docker%20Hub&logo=docker&color=2496ED)](https://hub.docker.com/r/diegosouzapw/omniroute) +[![Docker Pulls](https://img.shields.io/docker/pulls/diegosouzapw/omniroute?logo=docker&color=2496ED&label=docker%20pulls)](https://hub.docker.com/r/diegosouzapw/omniroute) +[![License](https://img.shields.io/github/license/diegosouzapw/OmniRoute)](https://github.com/diegosouzapw/OmniRoute/blob/main/LICENSE) +[![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online) +[![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) + +[๐ŸŒ Website](https://omniroute.online) โ€ข [๐Ÿš€ Quick Start](#-quick-start) โ€ข [๐Ÿ’ก Features](#-key-features) โ€ข [๐Ÿ“– Docs](#-documentation) โ€ข [๐Ÿ’ฐ Pricing](#-pricing-at-a-glance) โ€ข [๐Ÿ’ฌ WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) +
-

verze npmDocker HubLicenceWebovรฉ strรกnkyWhatsApp

-

๐ŸŒ Webovรฉ strรกnky โ€ข ๐Ÿš€ Rychlรฝ start โ€ข ๐Ÿ’ก Funkce โ€ข ๐Ÿ“– Dokumentace โ€ข ๐Ÿ’ฐ Cenรญk โ€ข ๐Ÿ’ฌ WhatsApp

-
-๐ŸŒ **Dostupnรฉ v:** ๐Ÿ‡บ๐Ÿ‡ธ [Angliฤtina](README.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brazรญlie)](docs/i18n/pt-BR/README.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](docs/i18n/es/README.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](docs/i18n/fr/README.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](docs/i18n/it/README.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](docs/i18n/ru/README.md) | ๐Ÿ‡จ๐Ÿ‡ณ[ไธญๆ–‡ (็ฎ€ไฝ“)](docs/i18n/zh-CN/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](docs/i18n/de/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](docs/i18n/in/README.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](docs/i18n/th/README.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](docs/i18n/uk-UA/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](docs/i18n/ar/README.md) | ๐Ÿ‡ฏ๐Ÿ‡ต[ๆ—ฅๆœฌ่ชž](docs/i18n/ja/README.md)| ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](docs/i18n/vi/README.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](docs/i18n/bg/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dรกnsko](docs/i18n/da/README.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](docs/i18n/fi/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](docs/i18n/he/README.md) | ๐Ÿ‡ญ๐Ÿ‡บ [maฤarลกtina](docs/i18n/hu/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonรฉsie](docs/i18n/id/README.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](docs/i18n/ko/README.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](docs/i18n/ms/README.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nizozemsko](docs/i18n/nl/README.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](docs/i18n/no/README.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugalsko)](docs/i18n/pt/README.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](docs/i18n/ro/README.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](docs/i18n/pl/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](docs/i18n/sk/README.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](docs/i18n/sv/README.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipรญnec](docs/i18n/phi/README.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](docs/i18n/cs/README.md) +๐ŸŒ **Available in:** ๐Ÿ‡บ๐Ÿ‡ธ [English](README.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](docs/i18n/pt-BR/README.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](docs/i18n/es/README.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](docs/i18n/fr/README.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](docs/i18n/it/README.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](docs/i18n/ru/README.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](docs/i18n/zh-CN/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](docs/i18n/de/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](docs/i18n/in/README.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](docs/i18n/th/README.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](docs/i18n/uk-UA/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](docs/i18n/ar/README.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](docs/i18n/ja/README.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](docs/i18n/vi/README.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](docs/i18n/bg/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](docs/i18n/da/README.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](docs/i18n/fi/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](docs/i18n/he/README.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](docs/i18n/hu/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](docs/i18n/id/README.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](docs/i18n/ko/README.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](docs/i18n/ms/README.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](docs/i18n/nl/README.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](docs/i18n/no/README.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](docs/i18n/pt/README.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](docs/i18n/ro/README.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](docs/i18n/pl/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](docs/i18n/sk/README.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](docs/i18n/sv/README.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](docs/i18n/phi/README.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](docs/i18n/cs/README.md) --- -### ๐Ÿ†• What's New in v3.0.0 +## Breaking Change: Unified Logging Upgrade -| Area | Change | -| ------------------------------- | --------------------------------------------------------------------------------- | -| ๐Ÿ”’ **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection | -| โœ… **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` | -| ๐Ÿ› **omniModel Tag Leak** | Internal `` tags no longer leak to clients in SSE streams (#585) | -| ๐Ÿ”‘ **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement | -| ๐Ÿ‘๏ธ **Scoped API Key Reveal** ๐Ÿ†• | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` | -| ๐ŸŽจ **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback | -| ๐Ÿ”„ **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers | -| ๐ŸŒ **OpenCode Zen/Go** | Two new providers: free tier + subscription tier | -| ๐Ÿ”ง **926 Tests** | Full test suite passes with 0 failures | - -### ๐Ÿ†• What's New in v3.0.0 - -| Area | Change | -| -------------------------- | --------------------------------------------------------------------------------- | -| ๐Ÿ”’ **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection | -| โœ… **Route Validation** | All 176 API routes validated with Zod schemas + `validateBody()` | -| ๐Ÿ› **omniModel Tag Leak** | Internal `` tags no longer leak to clients in SSE streams (#585) | -| ๐Ÿ”‘ **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with quota enforcement | -| ๐ŸŽจ **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG fallback | -| ๐Ÿ”„ **Model Auto-Sync** | 24h scheduler refreshes model lists for 16 providers | -| ๐ŸŒ **OpenCode Zen/Go** | Two new providers: free tier + subscription tier | -| ๐Ÿ”ง **926 Tests** | Full test suite passes with 0 failures | +> [!WARNING] +> **This release changes both the on-disk request log layout and the logging environment variables.** +> +> If you are upgrading an existing instance: +> +> - Request logs now live in `DATA_DIR/call_logs/YYYY-MM-DD/` as **one JSON artifact per request**. +> - The old `DATA_DIR/logs/` session folders and `DATA_DIR/log.txt` summary file are removed. +> - On the first startup after upgrading, OmniRoute creates a safety backup at `DATA_DIR/log_archives/*.zip` before removing the deprecated request log layout. +> - Legacy logging env vars such as `LOG_TO_FILE`, `LOG_FILE_PATH`, `LOG_MAX_FILE_SIZE`, `LOG_RETENTION_DAYS`, `LOG_LEVEL`, `LOG_FORMAT`, `ENABLE_REQUEST_LOGS`, `CALL_LOGS_MAX`, `CALL_LOG_PAYLOAD_MODE`, and `PROXY_LOG_MAX_ENTRIES` are no longer supported. +> - Use the new env model instead: +> - `APP_LOG_TO_FILE` +> - `APP_LOG_FILE_PATH` +> - `APP_LOG_MAX_FILE_SIZE` +> - `APP_LOG_RETENTION_DAYS` +> - `APP_LOG_MAX_FILES` +> - `APP_LOG_LEVEL` +> - `APP_LOG_FORMAT` +> - `CALL_LOG_RETENTION_DAYS` +> - `CALL_LOG_MAX_ENTRIES` +> +> For release details and upgrade notes, see the [CHANGELOG](CHANGELOG.md). --- -## ๐Ÿ–ผ๏ธ Hlavnรญ ovlรกdacรญ panel +## ๐Ÿ†• What's New -
ล˜รญdicรญ panel OmniRoute
+> **Upgrading from v2.9.5?** โ€” See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes. + +| Area | Change | +| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| ๐Ÿ”’ **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection remediation | +| โœ… **Route Validation** | All 176 API routes now validated with Zod schemas + `validateBody()` โ€” CI `check:route-validation:t06` passes | +| ๐Ÿ› **omniModel Tag Leak** | Internal `` tags no longer leak to clients in SSE streaming responses (#585) | +| ๐Ÿ”‘ **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with per-provider/account quota enforcement, idempotency, SHA-256 storage, and optional GitHub issue reporting | +| ๐ŸŽจ **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG โ†’ generic fallback chain | +| ๐Ÿ”„ **Model Auto-Sync** | 24h scheduler and manual UI toggle to sync model lists for built-in and custom OpenAI-compatible providers | +| ๐ŸŒ **OpenCode Zen/Go** | Two new providers from @kang-heewon via PR #530: free tier + subscription tier via `OpencodeExecutor` | +| ๐Ÿ› **Gemini CLI OAuth** | Actionable error when `GEMINI_OAUTH_CLIENT_SECRET` is missing in Docker (was cryptic Google error) | +| ๐Ÿ› **OpenCode config** | `saveOpenCodeConfig()` now correctly writes TOML to `XDG_CONFIG_HOME` | +| ๐Ÿ› **Pinned model override** | `body.model` correctly set to `pinnedModel` on context-cache protection | +| ๐Ÿ› **Codex/Claude loop** | `tool_result` blocks now converted to text to stop infinite loops | +| ๐Ÿ› **Login redirect** | Login no longer freezes after skipping password setup | +| ๐Ÿ› **Windows paths** | MSYS2/Git-Bash paths (`/c/...`) normalized to `C:\...` automatically | --- -## ๐Ÿ“ธ Nรกhled ล™รญdicรญho panelu +## ๐Ÿ–ผ๏ธ Main Dashboard + +
+ OmniRoute Dashboard +
+ +--- + +## ๐Ÿ“ธ Dashboard Preview
-Kliknutรญm zobrazรญte snรญmky obrazovky z ล™รญdicรญho panelu -
+Click to see dashboard screenshots -| Strana | Snรญmek obrazovky | -| ----------------------- | --------------------------------------------------- | -| **Poskytovatelรฉ** | ![Poskytovatelรฉ](docs/screenshots/01-providers.png) | -| **Kombinace** | ![Kombinace](docs/screenshots/02-combos.png) | -| **Analytika** | ![Analytika](docs/screenshots/03-analytics.png) | -| **Zdravรญ** | ![Zdravรญ](docs/screenshots/04-health.png) | -| **Pล™ekladatel** | ![Pล™ekladatel](docs/screenshots/05-translator.png) | -| **Nastavenรญ** | ![Nastavenรญ](docs/screenshots/06-settings.png) | -| **Nรกstroje CLI** | ![Nรกstroje CLI](docs/screenshots/07-cli-tools.png) | -| **Protokoly pouลพรญvรกnรญ** | ![Pouลพรญvรกnรญ](docs/screenshots/08-usage.png) | -| **Koncovรฉ body** | ![Koncovรฉ body](docs/screenshots/09-endpoint.png) | +| Page | Screenshot | +| -------------- | ------------------------------------------------- | +| **Providers** | ![Providers](docs/screenshots/01-providers.png) | +| **Combos** | ![Combos](docs/screenshots/02-combos.png) | +| **Analytics** | ![Analytics](docs/screenshots/03-analytics.png) | +| **Health** | ![Health](docs/screenshots/04-health.png) | +| **Translator** | ![Translator](docs/screenshots/05-translator.png) | +| **Settings** | ![Settings](docs/screenshots/06-settings.png) | +| **CLI Tools** | ![CLI Tools](docs/screenshots/07-cli-tools.png) | +| **Usage Logs** | ![Usage](docs/screenshots/08-usage.png) | +| **Endpoints** | ![Endpoints](docs/screenshots/09-endpoint.png) | + + --- -### ๐Ÿค– Bezplatnรฝ poskytovatel umฤ›lรฉ inteligence pro vaลกe oblรญbenรฉ programรกtory +### ๐Ÿค– Free AI Provider for your favorite coding agents -_Pล™ipojte libovolnรฝ nรกstroj IDE nebo CLI s umฤ›lou inteligencรญ pล™es OmniRoute โ€” bezplatnou API brรกnu pro neomezenรฉ kรณdovรกnรญ._ +_Connect any AI-powered IDE or CLI tool through OmniRoute โ€” free API gateway for unlimited coding._ - - - - - + + + + + - - - - - + + + + +
OpenClaw
OpenClaw
โญ 205 tisรญc 		NanoBot
NanoBot
โญ 20,9 tisรญc 		PicoClaw
PicoClaw
โญ 14,6 tisรญc 		ZeroClaw
ZeroClaw
โญ 9,9 tisรญc 		ลฝeleznรฝ drรกp
ลฝeleznรฝ drรกp
โญ 2,1 tisรญce 		+ + OpenClaw
+ OpenClaw +
+ โญ 205K + 		+ + NanoBot
+ NanoBot +
+ โญ 20.9K + 		+ + PicoClaw
+ PicoClaw +
+ โญ 14.6K + 		+ + ZeroClaw
+ ZeroClaw +
+ โญ 9.9K + 		+ + IronClaw
+ IronClaw +
+ โญ 2.1K +
OpenCode
OpenCode
โญ 106 tisรญc 		Codex CLI
Codex CLI
โญ 60,8 tisรญc 		Claude Code
Claude Code
โญ 67,3 tisรญc 		Gemini CLI
Gemini CLI
โญ 94,7 tisรญc 		Kilo kรณd
Kilo kรณd
โญ 15,5 tisรญc 		+ + OpenCode
+ OpenCode +
+ โญ 106K + 		+ + Codex CLI
+ Codex CLI +
+ โญ 60.8K + 		+ + Claude Code
+ Claude Code +
+ โญ 67.3K + 		+ + Gemini CLI
+ Gemini CLI +
+ โญ 94.7K + 		+ + Kilo Code
+ Kilo Code +
+ โญ 15.5K +
-๐Ÿ“ก Vลกichni agenti se pล™ipojujรญ pล™es http://localhost:20128/v1 nebo http://cloud.omniroute.online/v1 โ€” jedna konfigurace, neomezenรฉ modely a kvรณty +๐Ÿ“ก All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 โ€” one config, unlimited models and quota --- -## ๐Ÿค” Proฤ OmniRoute? +## ๐Ÿค” Why OmniRoute? -**Pล™estaลˆte plรฝtvat penฤ›zi a narรกลพet na limity:** +**Stop wasting money and hitting limits:** -- Kvรณta pล™edplatnรฉho vyprลกรญ kaลพdรฝ mฤ›sรญc -- Limity rychlosti vรกm zabrรกnรญ v kรณdovรกnรญ -- Drahรก API (20โ€“50 USD/mฤ›sรญc na poskytovatele) -- Ruฤnรญ pล™epรญnรกnรญ mezi poskytovateli +- Subscription quota expires unused every month +- Rate limits stop you mid-coding +- Expensive APIs ($20-50/month per provider) +- Manual switching between providers -**OmniRoute to ล™eลกรญ:** +**OmniRoute solves this:** -- โœ… **Maximalizujte pล™edplatnรฉ** โ€“ Sledujte kvรณtu, vyuลพijte kaลพdou ฤรกstku pล™ed resetovรกnรญm -- โœ… **Automatickรฉ zรกloลพnรญ** โ€“ Pล™edplatnรฉ โ†’ API klรญฤ โ†’ Levnรฉ โ†’ Zdarma, ลพรกdnรฉ vรฝpadky -- โœ… **Vรญce รบฤtลฏ** โ€“ Round-robin mezi รบฤty u jednotlivรฝch poskytovatelลฏ -- โœ… **Univerzรกlnรญ** - Funguje s Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw a jakรฝmkoli nรกstrojem CLI +- โœ… **Maximize subscriptions** - Track quota, use every bit before reset +- โœ… **Auto fallback** - Subscription โ†’ API Key โ†’ Cheap โ†’ Free, zero downtime +- โœ… **Multi-account** - Round-robin between accounts per provider +- โœ… **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool --- -## ๐Ÿ“ง Podpora +## ๐Ÿ“ง Support -> ๐Ÿ’ฌ **Pล™idejte se k naลกรญ komunitฤ›!** [Skupina WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) โ€” Zรญskejte pomoc, sdรญlejte tipy a buฤte v obraze. +> ๐Ÿ’ฌ **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) โ€” Get help, share tips, and stay updated. -- **Webovรก strรกnka** : [omniroute.online](https://omniroute.online) -- **GitHub** : [github.com/diegosouzapw/OmniRoute](https://github.com/diegosouzapw/OmniRoute) -- **Problรฉmy** : [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **WhatsApp** : [Komunitnรญ skupina](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) -- **Pล™ispรญvรกnรญ** : Viz [CONTRIBUTING.md](CONTRIBUTING.md) , otevล™ete ลพรกdost o pล™รญspฤ›vek nebo si vyberte `good first issue` -- **Pลฏvodnรญ projekt** : [9router od decolua](https://github.com/decolua/9router) +- **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) +- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) +- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue` +- **Original Project**: [9router by decolua](https://github.com/decolua/9router) -### ๐Ÿ› Hlรกsรญte chybu? +### ๐Ÿ› Reporting a Bug? -Pล™i otevรญrรกnรญ problรฉmu spusลฅte pล™รญkaz system-info a pล™iloลพte vygenerovanรฝ soubor: +When opening an issue, please run the system-info command and attach the generated file: ```bash npm run system-info ``` -Tรญm se vygeneruje soubor `system-info.txt` s verzรญ Node.js, verzรญ OmniRoute, podrobnostmi o operaฤnรญm systรฉmu, nainstalovanรฝmi nรกstroji CLI (qoder, gemini, claude, codex, antigravity, droid atd.), stavem Dockeru/PM2 a systรฉmovรฝmi balรญฤky โ€“ vลกe, co potล™ebujeme k rychlรฉ reprodukci vaลกeho problรฉmu. Soubor pล™iloลพte pล™รญmo k vaลกemu problรฉmu na GitHubu. +This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (qoder, gemini, claude, codex, antigravity, droid, etc.), Docker/PM2 status, and system packages โ€” everything we need to reproduce your issue quickly. Attach the file directly to your GitHub issue. --- -## ๐Ÿ”„ Jak to funguje +## ๐Ÿ”„ How It Works ``` โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” @@ -168,423 +262,453 @@ Result: Never stop coding, minimal cost --- -## ๐ŸŽฏ Co ล™eลกรญ OmniRoute โ€” 30 skuteฤnรฝch problรฉmลฏ a pล™รญpadลฏ pouลพitรญ +## ๐ŸŽฏ What OmniRoute Solves โ€” 30 Real Pain Points & Use Cases -> **Kaลพdรฝ vรฝvojรกล™ pouลพรญvajรญcรญ nรกstroje umฤ›lรฉ inteligence se s tฤ›mito problรฉmy setkรกvรก dennฤ›.** OmniRoute byl vytvoล™en tak, aby je vลกechny vyล™eลกil โ€“ od pล™ekroฤenรญ nรกkladลฏ po regionรกlnรญ bloky, od nefunkฤnรญch tokลฏ OAuth aลพ po operace s protokoly a sledovatelnost v podniku. +> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all โ€” from cost overruns to regional blocks, from broken OAuth flows to protocol operations and enterprise observability.
-๐Ÿ’ธ 1. โ€žPlatรญm si drahรฉ pล™edplatnรฉ, ale stรกle mฤ› ruลกรญ limityโ€œ +๐Ÿ’ธ 1. "I pay for an expensive subscription but still get interrupted by limits" + +Developers pay $20โ€“200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling โ€” 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity. + +**How OmniRoute solves it:** + +- **Smart 4-Tier Fallback** โ€” If subscription quota runs out, automatically redirects to API Key โ†’ Cheap โ†’ Free with zero manual intervention +- **Real-Time Quota Tracking** โ€” Shows token consumption in real-time with reset countdown (5h, daily, weekly) +- **Multi-Account Support** โ€” Multiple accounts per provider with auto round-robin โ€” when one runs out, switches to the next +- **Custom Combos** โ€” Customizable fallback chains with 9 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random) +- **Codex Business Quotas** โ€” Business/Team workspace quota monitoring directly in the dashboard +
-Vรฝvojรกล™i platรญ za Claude Pro, Codex Pro nebo GitHub Copilot 20โ€“200 dolarลฏ mฤ›sรญฤnฤ›. I pล™i platbฤ› mรก kvรณta strop โ€“ 5 hodin pouลพรญvรกnรญ, tรฝdennรญ limity nebo limity rychlosti za minutu. Uprostล™ed kรณdovacรญ relace poskytovatel pล™estane reagovat a vรฝvojรกล™ ztrรกcรญ plynulost a produktivitu. - -**Jak to OmniRoute ล™eลกรญ:** - -- **Inteligentnรญ ฤtyล™รบrovลˆovรก zรกloลพnรญ sluลพba** โ€“ Pokud dojde kvรณta pล™edplatnรฉho, โ€‹โ€‹automaticky se pล™esmฤ›ruje na API klรญฤ โ†’ Levnรฉ โ†’ Zdarma bez manuรกlnรญho zรกsahu -- **Sledovรกnรญ kvรณt v reรกlnรฉm ฤase** โ€“ Zobrazuje spotล™ebu tokenลฏ v reรกlnรฉm ฤase s odpoฤรญtรกvรกnรญm resetovรกnรญ (5 hodin, dennฤ›, tรฝdnฤ›) -- **Podpora vรญce รบฤtลฏ** โ€“ Vรญce รบฤtลฏ u jednoho poskytovatele s automatickรฝm pล™epรญnรกnรญm โ€“ kdyลพ jeden dojde, pล™epne se na dalลกรญ -- **Vlastnรญ kombinace** โ€” Pล™izpลฏsobitelnรฉ zรกloลพnรญ ล™etฤ›zce se 6 strategiemi vyvaลพovรกnรญ (fill-first, round robin, P2C, nรกhodnรฉ, nejmรฉnฤ› pouลพรญvanรฉ, nรกkladovฤ› optimalizovanรฉ) -- **Codex Business Quotas** โ€” Sledovรกnรญ kvรณt pracovnรญho prostoru firmy/tรฝmu pล™รญmo v dashboardu -
-๐Ÿ”Œ 2. โ€žPotล™ebuji pouลพรญt vรญce poskytovatelลฏ, ale kaลพdรฝ mรก jinรฉ APIโ€œ +๐Ÿ”Œ 2. "I need to use multiple providers but each has a different API" + +OpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints. + +**How OmniRoute solves it:** + +- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 60+ providers +- **Format Translation** โ€” Automatic and transparent: OpenAI โ†” Claude โ†” Gemini โ†” Responses API +- **Response Sanitization** โ€” Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+ +- **Role Normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI providers; `system` โ†’ `user` for GLM/ERNIE +- **Think Tag Extraction** โ€” Extracts `` blocks from models like DeepSeek R1 into standardized `reasoning_content` +- **Structured Output for Gemini** โ€” `json_schema` โ†’ `responseMimeType`/`responseSchema` automatic conversion +- **`stream` defaults to `false`** โ€” Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs +
-OpenAI pouลพรญvรก jeden formรกt, Claude (Anthropic) jinรฝ a Gemini jeลกtฤ› tล™etรญ. Pokud chce vรฝvojรกล™ testovat modely od rลฏznรฝch poskytovatelลฏ nebo mezi nimi pล™echรกzet, musรญ pล™ekonfigurovat SDK, zmฤ›nit koncovรฉ body a vypoล™รกdat se s nekompatibilnรญmi formรกty. Vlastnรญ poskytovatelรฉ (FriendLI, NIM) majรญ nestandardnรญ koncovรฉ body modelลฏ. - -**Jak to OmniRoute ล™eลกรญ:** - -- **Sjednocenรฝ koncovรฝ bod** โ€” Jeden `http://localhost:20128/v1` slouลพรญ jako proxy pro vลกech 67+ poskytovatelลฏ. -- **Pล™eklad formรกtu** โ€” Automatickรฝ a transparentnรญ: OpenAI โ†” Claude โ†” Gemini โ†” Responses API -- **Sanitizace odpovฤ›dรญ** โ€” Odstraลˆuje nestandardnรญ pole ( `x_groq` , `usage_breakdown` , `service_tier` ), kterรก poruลกujรญ OpenAI SDK v1.83+ -- **Normalizace rolรญ** โ€” Pล™evรกdรญ `developer` โ†’ `system` pro poskytovatele bez OpenAI; `system` โ†’ `user` pro GLM/ERNIE -- **Extrakce tagลฏ Think** โ€” Extrahuje bloky `` z modelลฏ, jako je DeepSeek R1, do standardizovanรฉho `reasoning_content` -- **Strukturovanรฝ vรฝstup pro Gemini** โ€” `json_schema` โ†’ automatickรก konverze `responseMimeType` / `responseSchema` -- **Vรฝchozรญ hodnota `stream` je `false`** โ€“ Odpovรญdรก specifikaci OpenAI, ฤรญmลพ se zabrรกnรญ neoฤekรกvanรฉmu SSE v Python/Rust/Go SDK. -
-๐ŸŒ 3. โ€žMลฏj poskytovatel AI blokuje mลฏj region/zemiโ€œ +๐ŸŒ 3. "My AI provider blocks my region/country" + +Providers like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries. + +**How OmniRoute solves it:** + +- **3-Level Proxy Config** โ€” Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key +- **Color-Coded Proxy Badges** โ€” Visual indicators: ๐ŸŸข global proxy, ๐ŸŸก provider proxy, ๐Ÿ”ต connection proxy, always showing the IP +- **OAuth Token Exchange Through Proxy** โ€” OAuth flow also goes through the proxy, solving `unsupported_country_region_territory` +- **Connection Tests via Proxy** โ€” Connection tests use the configured proxy (no more direct bypass) +- **SOCKS5 Support** โ€” Full SOCKS5 proxy support for outbound routing +- **TLS Fingerprint Spoofing** โ€” Browser-like TLS fingerprint via `wreq-js` to bypass bot detection +- **๐Ÿ” CLI Fingerprint Matching** โ€” Reorders headers and body fields to match native CLI binary signatures, drastically reducing account flagging risk. The proxy IP is preserved โ€” you get both stealth **and** IP masking simultaneously +
-Poskytovatelรฉ jako OpenAI/Codex blokujรญ pล™รญstup z urฤitรฝch geografickรฝch oblastรญ. Uลพivatelรฉ se bฤ›hem pล™ipojenรญ OAuth a API dostรกvajรญ k chybรกm jako `unsupported_country_region_territory` . To je obzvlรกลกtฤ› frustrujรญcรญ pro vรฝvojรกล™e z rozvojovรฝch zemรญ. - -**Jak to OmniRoute ล™eลกรญ:** - -- **3รบrovลˆovรก konfigurace proxy** โ€“ Konfigurovatelnรก proxy na 3 รบrovnรญch: globรกlnรญ (veลกkerรฝ provoz), pro jednotlivรฉ poskytovatele (pouze jeden poskytovatel) a pro jednotlivรฉ pล™ipojenรญ/klรญฤ -- **Barevnฤ› kรณdovanรฉ odznaky proxy** โ€“ Vizuรกlnรญ indikรกtory: ๐ŸŸข globรกlnรญ proxy, ๐ŸŸก proxy poskytovatele, ๐Ÿ”ต proxy pล™ipojenรญ, vลพdy zobrazujรญcรญ IP adresu -- **Vรฝmฤ›na tokenลฏ OAuth prostล™ednictvรญm proxy** โ€“ tok OAuth takรฉ prochรกzรญ pล™es proxy, ฤรญmลพ se ล™eลกรญ `unsupported_country_region_territory` -- **Testy pล™ipojenรญ pล™es proxy** โ€“ Testy pล™ipojenรญ pouลพรญvajรญ nakonfigurovanรฝ proxy (jiลพ ลพรกdnรฉ pล™รญmรฉ obchรกzenรญ) -- **Podpora SOCKS5** โ€” Plnรก podpora proxy SOCKS5 pro odchozรญ smฤ›rovรกnรญ -- **TLS Fingerprint Spoofing** โ€” Otisk prstu TLS podobnรฝ prohlรญลพeฤi pomocรญ `wreq-js` pro obchรกzenรญ detekce botลฏ -- **๐Ÿ” Porovnรกvรกnรญ otiskลฏ prstลฏ v CLI** โ€” Zmฤ›nรญ poล™adรญ zรกhlavรญ a polรญ v tฤ›le serveru tak, aby odpovรญdala nativnรญm binรกrnรญm podpisลฏm v CLI, ฤรญmลพ drasticky sniลพuje riziko nahlaลกovรกnรญ รบฤtu. IP adresa proxy je zachovรกna โ€” zรญskรกte souฤasnฤ› stealth **i** maskovรกnรญ IP adresy. -
-๐Ÿ†“ 4. โ€žChci pouลพรญvat umฤ›lou inteligenci pro kรณdovรกnรญ, ale nemรกm penรญzeโ€œ +๐Ÿ†“ 4. "I want to use AI for coding but I have no money" + +Not everyone can pay $20โ€“200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost. + +**How OmniRoute solves it:** + +- **Free Tier Providers Built-in** โ€” Native support for 100% free providers: Qoder (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free) +- **Ollama Cloud** โ€” Cloud-hosted Ollama models at `api.ollama.com` with free "Light usage" tier; use `ollamacloud/` prefix +- **Free-Only Combos** โ€” Chain `gc/gemini-3-flash โ†’ if/kimi-k2-thinking โ†’ qw/qwen3-coder-plus` = $0/month with zero downtime +- **NVIDIA NIM Free Access** โ€” ~40 RPM dev-forever free access to 70+ models at build.nvidia.com (transitioning from credits to pure rate limits) +- **Cost Optimized Strategy** โ€” Routing strategy that automatically chooses the cheapest available provider +
-Ne kaลพdรฝ si mลฏลพe dovolit zaplatit 20โ€“200 dolarลฏ mฤ›sรญฤnฤ› za pล™edplatnรฉ AI. Studenti, vรฝvojรกล™i z rozvรญjejรญcรญch se zemรญ, amatรฉล™i a freelanceล™i potล™ebujรญ pล™รญstup ke kvalitnรญm modelลฏm za nulovou cenu. - -**Jak to OmniRoute ล™eลกรญ:** - -- **Vestavฤ›nรญ poskytovatelรฉ bezplatnรฉ รบrovnฤ›** โ€” Nativnรญ podpora pro 100% bezplatnรฉ poskytovatele: Qoder (5 neomezenรฝch modelลฏ pล™es OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 neomezenรฉ modely: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID zdarma), Gemini CLI (180 tisรญc tokenลฏ/mฤ›sรญc zdarma) -- **Ollama Cloud** โ€” Cloudovฤ› hostovanรฉ modely Ollama na `api.ollama.com` s bezplatnou รบrovnรญ โ€žLight usageโ€œ; pouลพijte prefix `ollamacloud/` -- **Kombinace pouze zdarma** โ€” Chain `gc/gemini-3-flash โ†’ if/kimi-k2-thinking โ†’ qw/qwen3-coder-plus` = 0 $/mฤ›sรญc s nulovรฝmi prostoji -- **NVIDIA NIM Free Access** โ€” ~40 RPM developerskรฝ pล™รญstup k vรญce neลพ 70 modelลฏm na build.nvidia.com (pล™echod z kreditลฏ na ฤistรฉ limity rychlosti) -- **Strategie optimalizace nรกkladลฏ** โ€“ Strategie smฤ›rovรกnรญ, kterรก automaticky vybere nejlevnฤ›jลกรญho dostupnรฉho poskytovatele -
-๐Ÿ”’ 5. โ€žPotล™ebuji chrรกnit svou brรกnu umฤ›lรฉ inteligence pล™ed neoprรกvnฤ›nรฝm pล™รญstupemโ€œ +๐Ÿ”’ 5. "I need to protect my AI gateway from unauthorized access" + +When exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse. + +**How OmniRoute solves it:** + +- **API Key Management** โ€” Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page +- **Model-Level Permissions** โ€” Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle +- **API Endpoint Protection** โ€” Require a key for `/v1/models` and block specific providers from the listing +- **Auth Guard + CSRF Protection** โ€” All dashboard routes protected with `withAuth` middleware + CSRF tokens +- **Rate Limiter** โ€” Per-IP rate limiting with configurable windows +- **IP Filtering** โ€” Allowlist/blocklist for access control +- **Prompt Injection Guard** โ€” Sanitization against malicious prompt patterns +- **AES-256-GCM Encryption** โ€” Credentials encrypted at rest +
-Pล™i zpล™รญstupnฤ›nรญ brรกny umฤ›lรฉ inteligence sรญti (LAN, VPS, Docker) mลฏลพe kdokoli s adresou spotล™ebovat tokeny/kvรณtu vรฝvojรกล™e. Bez ochrany jsou API zranitelnรก vลฏฤi zneuลพitรญ, prompt injection a dalลกรญmu zneuลพitรญ. - -**Jak to OmniRoute ล™eลกรญ:** - -- **Sprรกva klรญฤลฏ API** โ€“ generovรกnรญ, rotace a vymezovรกnรญ rozsahu pro kaลพdรฉho poskytovatele s vyhrazenou strรกnkou `/dashboard/api-manager` -- **Oprรกvnฤ›nรญ na รบrovni modelu** โ€“ Omezenรญ klรญฤลฏ API na konkrรฉtnรญ modely ( `openai/*` , zรกstupnรฉ znaky) pomocรญ pล™epรญnaฤe Povolit vลกe/Omezit -- **Ochrana koncovรฝch bodลฏ API** โ€“ Vyลพaduje klรญฤ pro `/v1/models` a blokuje konkrรฉtnรญ poskytovatele ze seznamu -- **Auth Guard + CSRF Protection** โ€” Vลกechny trasy dashboardu chrรกnฤ›nรฉ middlewarem `withAuth` + tokeny CSRF -- **Omezovaฤ rychlosti** โ€” Omezovรกnรญ rychlosti na IP s konfigurovatelnรฝmi okny -- **Filtrovรกnรญ IP adres** โ€” Seznam povolenรฝch/blokovanรฝch adres pro ล™รญzenรญ pล™รญstupu -- **Ochrana proti vklรกdรกnรญ vรฝzev** โ€“ Sanitizace proti ลกkodlivรฝm vzorcลฏm vรฝzev -- **ล ifrovรกnรญ AES-256-GCM** โ€“ pล™ihlaลกovacรญ รบdaje jsou v klidovรฉm stavu ลกifrovรกny -
-๐Ÿ›‘ 6. โ€žMลฏj poskytovatel selhal a jรก ztratil/a programovacรญ tokโ€œ +๐Ÿ›‘ 6. "My provider went down and I lost my coding flow" + +AI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application. + +**How OmniRoute solves it:** + +- **Circuit Breaker per-model** โ€” Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open), scoped per-model to avoid cascading blocks +- **Exponential Backoff** โ€” Progressive retry delays +- **Anti-Thundering Herd** โ€” Mutex + semaphore protection against concurrent retry storms +- **Combo Fallback Chains** โ€” If the primary provider fails, automatically falls through the chain with no intervention +- **Combo Circuit Breaker** โ€” Auto-disables failing providers within a combo chain +- **Health Dashboard** โ€” Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency +
-Poskytovatelรฉ umฤ›lรฉ inteligence se mohou stรกt nestabilnรญmi, vracet chyby 5xx nebo dosรกhnout doฤasnรฝch limitลฏ rychlosti. Pokud je vรฝvojรกล™ zรกvislรฝ na jedinรฉm poskytovateli, je jeho prรกce pล™eruลกena. Bez jistiฤลฏ mลฏลพe opakovanรฉ pokusy vรฉst k pรกdu aplikace. - -**Jak to OmniRoute ล™eลกรญ:** - -- **Jistiฤ pro kaลพdรฝ model** โ€“ Automatickรฉ otevรญrรกnรญ/zavรญrรกnรญ s konfigurovatelnรฝmi prahovรฝmi hodnotami a dobou ochlazovรกnรญ (Zavล™eno/Otevล™eno/Poloviฤnรญ otevล™enรญ), rozsah definovanรฝ pro kaลพdรฝ model, aby se zabrรกnilo kaskรกdovรกnรญ blokลฏ -- **Exponenciรกlnรญ odklad** โ€” Progresivnรญ zpoลพdฤ›nรญ opakovรกnรญ -- **Anti-Thundering Herd** โ€” ochrana Mutex + semafor proti soubฤ›ลพnรฝm bouล™รญm s opakovanรฝmi pokusy -- **Kombinovanรฉ zรกloลพnรญ ล™etฤ›zce** โ€“ Pokud primรกrnรญ poskytovatel selลพe, automaticky se propadne ล™etฤ›zcem bez zรกsahu. -- **Kombinovanรฝ jistiฤ** โ€“ Automaticky deaktivuje selhรกvajรญcรญho poskytovatele v rรกmci kombinovanรฉho ล™etฤ›zce -- **Dashboard stavu** โ€” Monitorovรกnรญ provozuschopnosti, stavy jistiฤลฏ, uzamฤenรญ, statistiky mezipamฤ›ti, latence p50/p95/p99 -
-๐Ÿ”ง 7. โ€žKonfigurace kaลพdรฉho nรกstroje umฤ›lรฉ inteligence je zdlouhavรก a opakujรญcรญ seโ€œ +๐Ÿ”ง 7. "Configuring each AI tool is tedious and repetitive" + +Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time. + +**How OmniRoute solves it:** + +- **CLI Tools Dashboard** โ€” Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline +- **GitHub Copilot Config Generator** โ€” Generates `chatLanguageModels.json` for VS Code with bulk model selection +- **Onboarding Wizard** โ€” Guided 4-step setup for first-time users +- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 60+ providers +
-Vรฝvojรกล™i pouลพรญvajรญ Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Kaลพdรฝ nรกstroj potล™ebuje jinou konfiguraci (API endpoint, klรญฤ, model). Pล™ekonfigurovรกnรญ pล™i zmฤ›nฤ› poskytovatele nebo modelu je ztrรกta ฤasu. - -**Jak to OmniRoute ล™eลกรญ:** - -- **Panel nรกstrojลฏ CLI** โ€” Vyhrazenรก strรกnka s nastavenรญm jednรญm kliknutรญm pro Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity a Cline -- **Generรกtor konfigurace GitHub Copilot** โ€“ Generuje `chatLanguageModels.json` pro VS Code s hromadnรฝm vรฝbฤ›rem modelu -- **Prลฏvodce zavรกdฤ›nรญm** โ€“ 4krokovรฉ nastavenรญ pro zaฤรญnajรญcรญ uลพivatele -- **Jeden koncovรฝ bod, vลกechny modely** โ€“ jednou nakonfigurujte `http://localhost:20128/v1` a zรญskejte pล™รญstup k vรญce neลพ 44 poskytovatelลฏm -
-๐Ÿ”‘ 8. โ€žSprรกva OAuth tokenลฏ od vรญce poskytovatelลฏ je pekloโ€œ +๐Ÿ”‘ 8. "Managing OAuth tokens from multiple providers is hell" + +Claude Code, Codex, Gemini CLI, Copilot โ€” all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic. + +**How OmniRoute solves it:** + +- **Auto Token Refresh** โ€” OAuth tokens refresh in background before expiration +- **OAuth 2.0 (PKCE) Built-in** โ€” Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, Qoder +- **Multi-Account OAuth** โ€” Multiple accounts per provider via JWT/ID token extraction +- **OAuth LAN/Remote Fix** โ€” Private IP detection for `redirect_uri` + manual URL mode for remote servers +- **OAuth Behind Nginx** โ€” Uses `window.location.origin` for reverse proxy compatibility +- **Remote OAuth Guide** โ€” Step-by-step guide for Google Cloud credentials on VPS/Docker +
-Claude Code, Codex, Gemini CLI, Copilot โ€“ vลกechny pouลพรญvajรญ OAuth 2.0 s tokeny s vyprลกenรญm platnosti. Vรฝvojรกล™i se musรญ neustรกle znovu autentizovat, ล™eลกit chyby `client_secret is missing` , `redirect_uri_mismatch` a chyby na vzdรกlenรฝch serverech. Obzvlรกลกtฤ› problematickรฝ je OAuth v LAN/VPS. - -**Jak to OmniRoute ล™eลกรญ:** - -- **Automatickรก aktualizace tokenลฏ** โ€“ Tokeny OAuth se obnovujรญ na pozadรญ pล™ed vyprลกenรญm platnosti. -- **Vestavฤ›nรฝ OAuth 2.0 (PKCE)** โ€“ Automatickรฝ tok pro Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, Qoder -- **Multi-Account OAuth** โ€” Vรญce รบฤtลฏ na poskytovatele prostล™ednictvรญm extrakce tokenลฏ JWT/ID -- **OAuth LAN/Remote Fix** โ€” Detekce privรกtnรญ IP adresy pro `redirect_uri` + manuรกlnรญ reลพim URL pro vzdรกlenรฉ servery -- **OAuth Behind Nginx** โ€” Pouลพรญvรก `window.location.origin` pro kompatibilitu s reverznรญ proxy -- **Prลฏvodce vzdรกlenรฝm OAuth** โ€“ Podrobnรฝ nรกvod k pล™ihlaลกovacรญm รบdajลฏm Google Cloud na VPS/Dockeru -
-๐Ÿ“Š 9. โ€žNevรญm, kolik utrรกcรญm ani kdeโ€œ +๐Ÿ“Š 9. "I don't know how much I'm spending or where" + +Developers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up. + +**How OmniRoute solves it:** + +- **Cost Analytics Dashboard** โ€” Per-token cost tracking and budget management per provider +- **Budget Limits per Tier** โ€” Spending ceiling per tier that triggers automatic fallback +- **Per-Model Pricing Configuration** โ€” Configurable prices per model +- **Usage Statistics Per API Key** โ€” Request count and last-used timestamp per key +- **Analytics Dashboard** โ€” Stat cards, model usage chart, provider table with success rates and latency +
-Vรฝvojรกล™i pouลพรญvajรญ vรญce placenรฝch poskytovatelลฏ, ale nemajรญ jednotnรฝ pล™ehled o vรฝdajรญch. Kaลพdรฝ poskytovatel mรก svลฏj vlastnรญ fakturaฤnรญ panel, ale neexistuje ลพรกdnรฝ konsolidovanรฝ pล™ehled. Mohou se hromadit neoฤekรกvanรฉ nรกklady. - -**Jak to OmniRoute ล™eลกรญ:** - -- **Dashboard pro analรฝzu nรกkladลฏ** โ€“ Sledovรกnรญ nรกkladลฏ na token a sprรกva rozpoฤtu pro kaลพdรฉho poskytovatele -- **Rozpoฤtovรฉ limity na รบroveลˆ** โ€“ Strop vรฝdajลฏ na รบroveลˆ, kterรฝ spouลกtรญ automatickรฝ zรกloลพnรญ reลพim -- **Konfigurace cen podle modelu** โ€“ Konfigurovatelnรฉ ceny podle modelu -- **Statistiky pouลพitรญ pro kaลพdรฝ klรญฤ API** โ€” Poฤet poลพadavkลฏ a ฤasovรฉ razรญtko poslednรญho pouลพitรญ pro kaลพdรฝ klรญฤ -- **Analytickรฝ panel** โ€“ Statistickรฉ karty, graf vyuลพitรญ modelu, tabulka poskytovatelลฏ s mรญrou รบspฤ›ลกnosti a latencรญ -
-๐Ÿ› 10. โ€žNedokรกลพu diagnostikovat chyby a problรฉmy ve volรกnรญ umฤ›lรฉ inteligence.โ€œ +๐Ÿ› 10. "I can't diagnose errors and problems in AI calls" + +When a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error. + +**How OmniRoute solves it:** + +- **Unified Logs Dashboard** โ€” 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console +- **Console Log Viewer** โ€” Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter +- **SQLite Proxy Logs** โ€” Persistent logs that survive server restarts +- **Translator Playground** โ€” 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time) +- **Request Telemetry** โ€” p50/p95/p99 latency + X-Request-Id tracing +- **File-Based Logging with Rotation** โ€” App logs rotate by size, retention days, and archive count; call log artifacts rotate by retention days and file count +- **System Info Report** โ€” `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage. +
-Kdyลพ volรกnรญ selลพe, vรฝvojรกล™ nevรญ, zda se jednalo o limit rychlosti, vyprลกelรฝ token, ลกpatnรฝ formรกt nebo chybu poskytovatele. Fragmentovanรฉ protokoly napล™รญฤ rลฏznรฝmi terminรกly. Bez sledovatelnosti je ladฤ›nรญ metodou pokus-omyl. - -**Jak to OmniRoute ล™eลกรญ:** - -- **Panel jednotnรฝch protokolลฏ** โ€“ 4 karty: Protokoly poลพadavkลฏ, Protokoly proxy, Protokoly auditu, Konzole -- **Prohlรญลพeฤ protokolลฏ konzole** โ€” Prohlรญลพeฤ protokolลฏ v reรกlnรฉm ฤase ve stylu terminรกlu s barevnฤ› kรณdovanรฝmi รบrovnฤ›mi, automatickรฝm posouvรกnรญm, vyhledรกvรกnรญm a filtrovรกnรญm -- **Protokoly proxy SQLite** โ€“ trvalรฉ protokoly, kterรฉ pล™eลพijรญ restart serveru -- **Pล™ekladaฤskรฉ hล™iลกtฤ›** โ€” 4 reลพimy ladฤ›nรญ: Hล™iลกtฤ› (pล™eklad formรกtu), Tester chatu (okruลพnรญ), Testovacรญ stลฏl (dรกvkovรฝ), ลฝivรฝ monitor (v reรกlnรฉm ฤase) -- **Telemetrie poลพadavkลฏ** โ€” latence p50/p95/p99 + trasovรกnรญ X-Request-Id -- **Souborovรฉ protokolovรกnรญ s rotacรญ** โ€“ Konzolovรฝ interceptor zachycuje vลกe do protokolu JSON s rotacรญ na zรกkladฤ› velikosti -- **Zprรกva o systรฉmovรฝch informacรญch** โ€” pล™รญkaz `npm run system-info` vygeneruje `system-info.txt` s kompletnรญm popisem vaลกeho prostล™edรญ (verze uzlu, verze OmniRoute, operaฤnรญ systรฉm, nรกstroje CLI, stav Dockeru/PM2). Pล™iloลพte jej pล™i hlรกลกenรญ problรฉmลฏ pro okamลพitรฉ tล™รญdฤ›nรญ. -
-๐Ÿ—๏ธ 11. โ€žNasazenรญ a รบdrลพba brรกny je sloลพitรกโ€œ +๐Ÿ—๏ธ 11. "Deploying and maintaining the gateway is complex" + +Installing, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction. + +**How OmniRoute solves it:** + +- **npm global install** โ€” `npm install -g omniroute && omniroute` โ€” done +- **Docker Multi-Platform** โ€” AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi) +- **Docker Compose Profiles** โ€” `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw) +- **Electron Desktop App** โ€” Native app for Windows/macOS/Linux with system tray, auto-start, offline mode +- **Split-Port Mode** โ€” API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking) +- **Cloud Sync** โ€” Config synchronization across devices via Cloudflare Workers +- **DB Backups** โ€” Automatic backup, restore, export and import of all settings, with `DISABLE_SQLITE_AUTO_BACKUP` for externally managed backups +
-Instalace, konfigurace a รบdrลพba AI proxy v rลฏznรฝch prostล™edรญch (lokรกlnรญ, VPS, Docker, cloud) je pracnรก. Problรฉmy, jako jsou pevnฤ› zakรณdovanรฉ cesty, `EACCES` u adresรกล™ลฏ, konflikty portลฏ a multiplatformnรญ sestavenรญ, pล™ispรญvajรญ k obtรญลพรญm. - -**Jak to OmniRoute ล™eลกรญ:** - -- **npm globรกlnรญ instalace** โ€” `npm install -g omniroute && omniroute` โ€” hotovo -- **Docker Multi-Platform** โ€” AMD64 + nativnรญ ARM64 (Apple Silicon, AWS Graviton, Raspberry Pi) -- **Profily Docker Compose** โ€” `base` (bez nรกstrojลฏ CLI) a `cli` (s Claude Code, Codex, OpenClaw) -- **Desktopovรก aplikace Electron** โ€” Nativnรญ aplikace pro Windows/macOS/Linux se systรฉmovou liลกtou, automatickรฝm spuลกtฤ›nรญm a offline reลพimem -- **Reลพim rozdฤ›lenรฝch portลฏ** โ€“ API a ล™รญdicรญ panel na samostatnรฝch portech pro pokroฤilรฉ scรฉnรกล™e (reverznรญ proxy, sรญลฅovรกnรญ kontejnerลฏ) -- **Cloud Sync** โ€“ Konfigurace synchronizace mezi zaล™รญzenรญmi pomocรญ Cloudflare Workers -- **Zรกlohy databรกzรญ** โ€” Automatickรฉ zรกlohovรกnรญ, obnovenรญ, export a import vลกech nastavenรญ -
-๐ŸŒ 12. โ€žRozhranรญ je pouze v angliฤtinฤ› a mลฏj tรฝm nemluvรญ anglickyโ€œ +๐ŸŒ 12. "The interface is English-only and my team doesn't speak English" + +Teams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors. + +**How OmniRoute solves it:** + +- **Dashboard i18n โ€” 30 Languages** โ€” All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English +- **RTL Support** โ€” Right-to-left support for Arabic and Hebrew +- **Multi-Language READMEs** โ€” 30 complete documentation translations +- **Language Selector** โ€” Globe icon in header for real-time switching +
-Tรฝmy v neanglicky mluvรญcรญch zemรญch, zejmรฉna v Latinskรฉ Americe, Asii a Evropฤ›, se potรฝkajรญ s rozhranรญmi pouze v angliฤtinฤ›. Jazykovรฉ bariรฉry sniลพujรญ mรญru pล™ijetรญ a zvyลกujรญ chyby v konfiguraci. - -**Jak to OmniRoute ล™eลกรญ:** - -- **Dashboard i18n โ€” 30 jazykลฏ** โ€” Vลกech 500+ klรกves je pล™eloลพeno vฤetnฤ› arabลกtiny, bulharลกtiny, dรกnลกtiny, nฤ›mฤiny, ลกpanฤ›lลกtiny, finลกtiny, francouzลกtiny, hebrejลกtiny, hindลกtiny, maฤarลกtiny, indonรฉลกtiny, italลกtiny, japonลกtiny, korejลกtiny, malajลกtiny, holandลกtiny, norลกtiny, polลกtiny, portugalลกtiny (PT/BR), rumunลกtiny, ruลกtiny, slovenลกtiny, ลกvรฉdลกtiny, thajลกtiny, ukrajinลกtiny, vietnamลกtiny, ฤรญnลกtiny, filipรญnลกtiny a angliฤtiny -- **Podpora RTL** โ€“ Podpora psanรญ zprava doleva pro arabลกtinu a hebrejลกtinu -- **Vรญcejazyฤnรฉ soubory README** โ€” 30 kompletnรญch pล™ekladลฏ dokumentace -- **Vรฝbฤ›r jazyka** โ€” Ikona glรณbu v zรกhlavรญ pro pล™epรญnรกnรญ v reรกlnรฉm ฤase -
-๐Ÿ”„ 13. โ€žPotล™ebuji vรญc neลพ jen chat โ€“ potล™ebuji vloลพenรฉ soubory, obrรกzky, zvuk.โ€œ +๐Ÿ”„ 13. "I need more than chat โ€” I need embeddings, images, audio" + +AI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format. + +**How OmniRoute solves it:** + +- **Embeddings** โ€” `/v1/embeddings` with 6 providers and 9+ models +- **Image Generation** โ€” `/v1/images/generations` with 10 providers and 20+ models (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI) +- **Text-to-Video** โ€” `/v1/videos/generations` โ€” ComfyUI (AnimateDiff, SVD) and SD WebUI +- **Text-to-Music** โ€” `/v1/music/generations` โ€” ComfyUI (Stable Audio Open, MusicGen) +- **Audio Transcription** โ€” `/v1/audio/transcriptions` โ€” Whisper + Nvidia NIM, HuggingFace, Qwen3 +- **Text-to-Speech** โ€” `/v1/audio/speech` โ€” ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld**, **Cartesia**, **PlayHT**, + existing providers +- **Moderations** โ€” `/v1/moderations` โ€” Content safety checks +- **Reranking** โ€” `/v1/rerank` โ€” Document relevance reranking +- **Responses API** โ€” Full `/v1/responses` support for Codex +
-Umฤ›lรก inteligence nenรญ jen dokonฤovรกnรญ chatu. Vรฝvojรกล™i potล™ebujรญ generovat obrรกzky, pล™episovat zvuk, vytvรกล™et embeddedy pro RAG, mฤ›nit poล™adรญ dokumentลฏ a moderovat obsah. Kaลพdรฉ API mรก jinรฝ koncovรฝ bod a formรกt. - -**Jak to OmniRoute ล™eลกรญ:** - -- **Vklรกdรกnรญ** โ€” `/v1/embeddings` s 6 poskytovateli a 9+ modely -- **Generovรกnรญ obrรกzkลฏ** โ€” `/v1/images/generations` s 10 poskytovateli a vรญce neลพ 20 modely (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI) -- **Pล™evod textu na video** โ€” `/v1/videos/generations` โ€” ComfyUI (AnimateDiff, SVD) a SD WebUI -- **Pล™evod textu na hudbu** โ€” `/v1/music/generations` โ€” ComfyUI (Stable Audio Open, MusicGen) -- **Pล™epis zvuku** โ€” `/v1/audio/transcriptions` โ€” Whisper + Nvidia NIM, HuggingFace, Qwen3 -- **Pล™evod textu na ล™eฤ** โ€” `/v1/audio/speech` โ€” ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld** , **Cartesia** , **PlayHT** a dalลกรญ stรกvajรญcรญ poskytovatelรฉ -- **Moderovรกnรญ** โ€” `/v1/moderations` โ€” Kontroly bezpeฤnosti obsahu -- **Zmฤ›na poล™adรญ** โ€” `/v1/rerank` โ€” Zmฤ›na poล™adรญ relevance dokumentu -- **Responses API** โ€” Plnรก podpora `/v1/responses` pro Codex -
-๐Ÿงช 14. โ€žNemรกm zpลฏsob, jak testovat a porovnรกvat kvalitu napล™รญฤ modely.โ€œ +๐Ÿงช 14. "I have no way to test and compare quality across models" + +Developers want to know which model is best for their use case โ€” code, translation, reasoning โ€” but comparing manually is slow. No integrated eval tools exist. + +**How OmniRoute solves it:** + +- **LLM Evaluations** โ€” Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal +- **4 Match Strategies** โ€” `exact`, `contains`, `regex`, `custom` (JS function) +- **Translator Playground Test Bench** โ€” Batch testing with multiple inputs and expected outputs, cross-provider comparison +- **Chat Tester** โ€” Full round-trip with visual response rendering +- **Live Monitor** โ€” Real-time stream of all requests flowing through the proxy +
-Vรฝvojรกล™i chtฤ›jรญ vฤ›dฤ›t, kterรฝ model je pro jejich pล™รญpad pouลพitรญ nejlepลกรญ โ€“ kรณd, pล™eklad, uvaลพovรกnรญ โ€“ ale ruฤnรญ porovnรกvรกnรญ je pomalรฉ. Neexistujรญ ลพรกdnรฉ integrovanรฉ nรกstroje pro vyhodnocovรกnรญ. - -**Jak to OmniRoute ล™eลกรญ:** - -- **Hodnocenรญ LLM** โ€” Testovรกnรญ Golden setu s 10 pล™edinstalovanรฝmi pล™รญpady zahrnujรญcรญmi pozdravy, matematiku, geografii, generovรกnรญ kรณdu, dodrลพovรกnรญ JSON, pล™eklad, markdown, odmรญtnutรญ bezpeฤnostnรญch poลพadavkลฏ -- **4 strategie shody** โ€” `exact` , `contains` , `regex` , `custom` (JS funkce) -- **Testovacรญ lavice pro pล™ekladatelskรฉ hล™iลกtฤ›** โ€” Dรกvkovรฉ testovรกnรญ s vรญce vstupy a oฤekรกvanรฝmi vรฝstupy, porovnรกnรญ napล™รญฤ poskytovateli -- **Tester chatu** โ€” Kompletnรญ okruลพnรญ cesta s vizuรกlnรญm vykreslovรกnรญm odpovฤ›dรญ -- **ลฝivรฝ monitor** โ€” Stream vลกech poลพadavkลฏ prochรกzejรญcรญch proxy serverem v reรกlnรฉm ฤase -
-๐Ÿ“ˆ 15. โ€žPotล™ebuji ลกkรกlovat bez ztrรกty vรฝkonuโ€œ +๐Ÿ“ˆ 15. "I need to scale without losing performance" + +As request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected. + +**How OmniRoute solves it:** + +- **Semantic Cache** โ€” Two-tier cache (signature + semantic) reduces cost and latency +- **Request Idempotency** โ€” 5s deduplication window for identical requests +- **Rate Limit Detection** โ€” Per-provider RPM, min gap, and max concurrent tracking +- **Editable Rate Limits** โ€” Configurable defaults in Settings โ†’ Resilience with persistence +- **API Key Validation Cache** โ€” 3-tier cache for production performance +- **Health Dashboard with Telemetry** โ€” p50/p95/p99 latency, cache stats, uptime +
-S rostoucรญm objemem poลพadavkลฏ generujรญ stejnรฉ otรกzky bez uklรกdรกnรญ do mezipamฤ›ti duplicitnรญ nรกklady. Bez idempotence duplicitnรญ poลพadavky plรฝtvajรญ zpracovรกnรญm. Je nutnรฉ dodrลพovat limity rychlosti na poskytovatele. - -**Jak to OmniRoute ล™eลกรญ:** - -- **Sรฉmantickรก mezipamฤ›ลฅ** โ€” Dvouvrstvรก mezipamฤ›ลฅ (signatura + sรฉmantika) sniลพuje nรกklady a latenci -- **Idempotence poลพadavku** โ€” 5s deduplikaฤnรญ okno pro identickรฉ poลพadavky -- **Detekce limitu rychlosti** โ€“ sledovรกnรญ otรกฤek za minutu (RPM), minimรกlnรญ mezera a maximรกlnรญ soubฤ›ลพnรฉ sledovรกnรญ pro kaลพdรฉho poskytovatele -- **Upravitelnรฉ limity rychlosti** โ€” Konfigurovatelnรฉ vรฝchozรญ hodnoty v Nastavenรญ โ†’ Odolnost s perzistencรญ -- **Mezipamฤ›ลฅ pro ovฤ›ล™enรญ klรญฤลฏ API** โ€” tล™รญvrstvรก mezipamฤ›ลฅ pro vรฝkon produkฤnรญho prostล™edรญ -- **Dashboard s telemetriรญ** โ€“ latence p50/p95/p99, statistiky mezipamฤ›ti, dostupnost -
-๐Ÿค– 16. โ€žChci mรญt chovรกnรญ modelลฏ globรกlnฤ› pod kontrolouโ€œ +๐Ÿค– 16. "I want to control model behavior globally" + +Developers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical. + +**How OmniRoute solves it:** + +- **System Prompt Injection** โ€” Global prompt applied to all requests +- **Thinking Budget Validation** โ€” Reasoning token allocation control per request (passthrough, auto, custom, adaptive) +- **9 Routing Strategies** โ€” Global strategies that determine how requests are distributed +- **Wildcard Router** โ€” `provider/*` patterns route dynamically to any provider +- **Combo Enable/Disable Toggle** โ€” Toggle combos directly from the dashboard +- **Provider Toggle** โ€” Enable/disable all connections for a provider with one click +- **Blocked Providers** โ€” Exclude specific providers from `/v1/models` listing +
-Vรฝvojรกล™i, kteล™รญ chtฤ›jรญ vลกechny odpovฤ›di v urฤitรฉm jazyce, se specifickรฝm tรณnem nebo chtฤ›jรญ omezit tokeny pro uvaลพovรกnรญ. Konfigurace tรฉto funkce v kaลพdรฉm nรกstroji/poลพadavku je nepraktickรก. - -**Jak to OmniRoute ล™eลกรญ:** - -- **Vloลพenรญ systรฉmovรฉho prompt** โ€“ Globรกlnรญ prompt aplikovanรฝ na vลกechny poลพadavky -- **Validace rozpoฤtu Thinking** โ€” ล˜รญzenรญ alokace tokenลฏ na poลพadavek (prลฏchozรญ, automatickรฉ, vlastnรญ, adaptivnรญ) -- **6 strategiรญ smฤ›rovรกnรญ** โ€“ Globรกlnรญ strategie, kterรฉ urฤujรญ, jak jsou poลพadavky distribuovรกny -- **Smฤ›rovaฤ se zรกstupnรฝmi znaky** โ€” vzory `provider/*` dynamicky smฤ›rujรญ k libovolnรฉmu poskytovateli -- **Pล™epรญnรกnรญ povolenรญ/zakรกzรกnรญ kombinacรญ** โ€“ Pล™epรญnรกnรญ kombinacรญ pล™รญmo z ล™รญdicรญho panelu -- **Pล™epรญnรกnรญ poskytovatele** โ€“ Povolenรญ/zakรกzรกnรญ vลกech pล™ipojenรญ pro poskytovatele jednรญm kliknutรญm -- **Blokovanรญ poskytovatelรฉ** โ€“ Vylouฤenรญ konkrรฉtnรญch poskytovatelลฏ ze seznamu `/v1/models` -
-๐Ÿงฐ 17. โ€žPotล™ebuji nรกstroje MCP jako prvotล™รญdnรญ produktovรฉ funkce.โ€œ +๐Ÿงฐ 17. "I need MCP tools as first-class product capabilities" + +Many AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer. + +**How OmniRoute solves it:** + +- MCP appears in the dashboard navigation and endpoint protocol tab +- Dedicated MCP management page with process, tools, scopes, and audit +- Built-in quick-start for `omniroute --mcp` and client onboarding +
-Mnoho bran umฤ›lรฉ inteligence odhaluje MCP pouze jako skrytรฝ implementaฤnรญ detail. Tรฝmy potล™ebujรญ viditelnou a spravovatelnou operaฤnรญ vrstvu. - -**Jak to OmniRoute ล™eลกรญ:** - -- MCP se zobrazuje v navigaci na ล™รญdicรญm panelu a na kartฤ› protokolu koncovรฉho bodu. -- Vyhrazenรก strรกnka pro sprรกvu MCP s procesy, nรกstroji, rozsahy a auditem -- Vestavฤ›nรฝ rychlรฝ start pro `omniroute --mcp` a onboarding klienta -
-๐Ÿง  18. โ€žPotล™ebuji orchestraci A2A se synchronizacรญ a cestami รบloh streamu.โ€œ +๐Ÿง  18. "I need A2A orchestration with sync + stream task paths" + +Agent workflows need both direct replies and long-running streamed execution with lifecycle control. + +**How OmniRoute solves it:** + +- A2A JSON-RPC endpoint (`POST /a2a`) with `message/send` and `message/stream` +- SSE streaming with terminal state propagation +- Task lifecycle APIs for `tasks/get` and `tasks/cancel` +
-Pracovnรญ postupy agentลฏ vyลพadujรญ jak pล™รญmรฉ odpovฤ›di, tak dlouhodobรฉ streamovanรฉ provรกdฤ›nรญ s kontrolou ลพivotnรญho cyklu. - -**Jak to OmniRoute ล™eลกรญ:** - -- Koncovรฝ bod A2A JSON-RPC ( `POST /a2a` ) s `message/send` `message/stream` -- Streamovรกnรญ SSE s ลกรญล™enรญm stavu terminรกlu -- Rozhranรญ API ลพivotnรญho cyklu รบloh pro `tasks/get` a `tasks/cancel` -
-๐Ÿ›ฐ๏ธ 19. โ€žPotล™ebuji skuteฤnรฝ stav procesu MCP, ne odhadovanรฝ stav.โ€œ +๐Ÿ›ฐ๏ธ 19. "I need real MCP process health, not guessed status" + +Operational teams need to know if MCP is actually alive, not just whether an API is reachable. + +**How OmniRoute solves it:** + +- Runtime heartbeat file with PID, timestamps, transport, tool count, and scope mode +- MCP status API combining heartbeat + recent activity +- UI status cards for process/uptime/heartbeat freshness +
-Provoznรญ tรฝmy potล™ebujรญ vฤ›dฤ›t, zda je MCP skuteฤnฤ› aktivnรญ, nejen zda je API dosaลพitelnรฉ. - -**Jak to OmniRoute ล™eลกรญ:** - -- Soubor bฤ›hovรฉho heartbeatu s PID, ฤasovรฝmi razรญtky, transportem, poฤtem nรกstrojลฏ a reลพimem rozsahu -- API stavu MCP kombinujรญcรญ prezenฤnรญ signรกl a nedรกvnou aktivitu -- Karty stavu uลพivatelskรฉho rozhranรญ pro zobrazenรญ aktuรกlnosti procesลฏ/provozuschopnosti/prezenฤnรญho signรกlu -
-๐Ÿ“‹ 20. โ€žPotล™ebuji auditovatelnรฉ provedenรญ nรกstroje MCPโ€œ +๐Ÿ“‹ 20. "I need auditable MCP tool execution" + +When tools mutate config or trigger ops actions, teams need forensic traceability. + +**How OmniRoute solves it:** + +- SQLite-backed audit logging for MCP tool calls +- Filters by tool, success/failure, API key, and pagination +- Dashboard audit table + stats endpoints for automation +
-Kdyลพ nรกstroje mฤ›nรญ konfiguraci nebo spouลกtฤ›jรญ operaฤnรญ akce, tรฝmy potล™ebujรญ forenznรญ sledovatelnost. - -**Jak to OmniRoute ล™eลกรญ:** - -- Protokolovรกnรญ auditu pro volรกnรญ nรกstrojลฏ MCP s podporou SQLite -- Filtruje podle nรกstroje, รบspฤ›chu/neรบspฤ›chu, klรญฤe API a strรกnkovรกnรญ -- Tabulka auditu dashboardu + koncovรฉ body statistik pro automatizaci -
-๐Ÿ” 21. โ€žPotล™ebuji omezenรก oprรกvnฤ›nรญ MCP pro kaลพdou integraci.โ€œ +๐Ÿ” 21. "I need scoped MCP permissions per integration" + +Different clients should have least-privilege access to tool categories. + +**How OmniRoute solves it:** + +- 10 granular MCP scopes for controlled tool access +- Scope enforcement and visibility in MCP management UI +- Safe default posture for operational tooling +
-Rลฏznรญ klienti by mฤ›li mรญt pล™รญstup ke kategoriรญm nรกstrojลฏ s nejniลพลกรญmi oprรกvnฤ›nรญmi. - -**Jak to OmniRoute ล™eลกรญ:** - -- 9 detailnรญch MCP sond pro kontrolovanรฝ pล™รญstup k nรกstrojลฏm -- Vynucenรญ rozsahu a viditelnost v uลพivatelskรฉm rozhranรญ sprรกvy MCP -- Bezpeฤnรก vรฝchozรญ poloha pro provoznรญ nรกstroje -
-โš™๏ธ 22. โ€žPotล™ebuji provoznรญ kontroly bez nutnosti pล™esouvรกnรญโ€œ +โš™๏ธ 22. "I need operational controls without redeploying" + +Teams need quick runtime changes during incidents or cost events. + +**How OmniRoute solves it:** + +- Switch combo activation directly from MCP dashboard +- Apply resilience profiles from pre-defined policy packs +- Reset circuit breaker state from the same operations panel +
-Tรฝmy potล™ebujรญ rychlรฉ zmฤ›ny v bฤ›hovรฉm prostล™edรญ bฤ›hem incidentลฏ nebo nรกkladovรฝch udรกlostรญ. - -**Jak to OmniRoute ล™eลกรญ:** - -- Pล™epnฤ›te aktivaci komba pล™รญmo z ล™รญdicรญho panelu MCP -- Pouลพรญvejte profily odolnosti z pล™eddefinovanรฝch balรญฤkลฏ zรกsad -- Resetujte stav jistiฤe ze stejnรฉho ovlรกdacรญho panelu -
-๐Ÿ”„ 23. โ€žPotล™ebuji ลพivรฝ pล™ehled o ลพivotnรญm cyklu รบkolลฏ A2A a jejich zruลกenรญ.โ€œ +๐Ÿ”„ 23. "I need live A2A task lifecycle visibility and cancellation" + +Without lifecycle visibility, task incidents become hard to triage. + +**How OmniRoute solves it:** + +- Task listing/filtering by state/skill with pagination +- Drill-down on task metadata, events, and artifacts +- Task cancellation endpoint and UI action with confirmation +
-Bez pล™ehledu o ลพivotnรญm cyklu je obtรญลพnรฉ tล™รญdit incidenty รบkolลฏ. - -**Jak to OmniRoute ล™eลกรญ:** - -- Vรฝpis/filtrovรกnรญ รบkolลฏ podle stรกtu/dovednosti s strรกnkovรกnรญm -- Podrobnรฝ pล™ehled metadat รบloh, udรกlostรญ a artefaktลฏ -- Koncovรฝ bod zruลกenรญ รบlohy a akce uลพivatelskรฉho rozhranรญ s potvrzenรญm -
-๐ŸŒŠ 24. โ€žPotล™ebuji metriky aktivnรญho streamu pro A2A zรกtฤ›ลพโ€œ +๐ŸŒŠ 24. "I need active stream metrics for A2A load" + +Streaming workflows require operational insight into concurrency and live connections. + +**How OmniRoute solves it:** + +- Active stream counters integrated into A2A status +- Last task timestamp and per-state counts +- A2A dashboard cards for real-time ops monitoring +
-Streamovacรญ pracovnรญ postupy vyลพadujรญ provoznรญ pล™ehled o soubฤ›ลพnosti a ลพivรฝch pล™ipojenรญch. - -**Jak to OmniRoute ล™eลกรญ:** - -- ฤŒรญtaฤe aktivnรญch streamลฏ integrovanรฉ do stavu A2A -- ฤŒasovรฉ razรญtko poslednรญho รบkolu a poฤty pro jednotlivรฉ stavy -- Karty A2A dashboardu pro monitorovรกnรญ provozu v reรกlnรฉm ฤase -
-๐Ÿชช 25. โ€žPotล™ebuji standardnรญ vyhledรกvรกnรญ agentลฏ pro klientyโ€œ +๐Ÿชช 25. "I need standard agent discovery for clients" + +External clients and orchestrators need machine-readable metadata for onboarding. + +**How OmniRoute solves it:** + +- Agent Card exposed at `/.well-known/agent.json` +- Capabilities and skills shown in management UI +- A2A status API includes discovery metadata for automation +
-Externรญ klienti a orchestratoล™i potล™ebujรญ pro onboarding strojovฤ› ฤitelnรก metadata. - -**Jak to OmniRoute ล™eลกรญ:** - -- Karta agenta je k dispozici v souboru `/.well-known/agent.json` -- Schopnosti a dovednosti zobrazenรฉ v uลพivatelskรฉm rozhranรญ pro sprรกvu -- API pro stav A2A zahrnuje metadata pro zjiลกลฅovรกnรญ pro automatizaci -
-๐Ÿงญ 26. โ€žPotล™ebuji v uลพivatelskรฉm rozhranรญ produktu zjistitelnost protokolu.โ€œ +๐Ÿงญ 26. "I need protocol discoverability in the product UX" + +If users cannot discover protocol surfaces, adoption and support quality drop. + +**How OmniRoute solves it:** + +- Consolidated **Endpoints** page with tabs for Proxy, MCP, A2A, and API Endpoints +- Inline service status toggles (Online/Offline) for MCP and A2A +- Links from overview to dedicated management tabs +
-Pokud uลพivatelรฉ nemohou objevit protokolovรฉ povrchy, kvalita pล™ijetรญ a podpory klesรก. - -**Jak to OmniRoute ล™eลกรญ:** - -- Strรกnka Konsolidovanรฉ **koncovรฉ body** s kartami pro koncovรฉ body Proxy, MCP, A2A a API -- Pล™epรญnรกnรญ stavu inline sluลพby (Online/Offline) pro MCP a A2A -- Odkazy z pล™ehledu na vyhrazenรฉ karty pro sprรกvu -
-๐Ÿงช 27. โ€žPotล™ebuji komplexnรญ ovฤ›ล™enรญ protokolu se skuteฤnรฝmi klienty.โ€œ +๐Ÿงช 27. "I need end-to-end protocol validation with real clients" + +Mock tests are not enough to validate protocol compatibility before release. + +**How OmniRoute solves it:** + +- E2E suite that boots app and uses real MCP SDK client transport +- A2A client tests for discovery, send, stream, get, and cancel flows +- Cross-check assertions against MCP audit and A2A tasks APIs +
-Simulovanรฉ testy nestaฤรญ k ovฤ›ล™enรญ kompatibility protokolu pล™ed vydรกnรญm. - -**Jak to OmniRoute ล™eลกรญ:** - -- Sada E2E, kterรก spouลกtรญ aplikaci a pouลพรญvรก skuteฤnรฝ transport klienta MCP SDK. -- Klientskรฉ testy A2A pro toky zjiลกลฅovรกnรญ, odesรญlรกnรญ, streamovรกnรญ, naฤรญtรกnรญ a zruลกenรญ -- Kล™รญลพovรก kontrola tvrzenรญ oproti API pro audit MCP a รบkoly A2A -
-๐Ÿ“ก 28. โ€žPotล™ebuji jednotnou pozorovatelnost napล™รญฤ vลกemi rozhranรญmiโ€œ +๐Ÿ“ก 28. "I need unified observability across all interfaces" + +Splitting observability by protocol creates blind spots and longer MTTR. + +**How OmniRoute solves it:** + +- Unified dashboards/logs/analytics in one product +- Health + audit + request telemetry across OpenAI, MCP, and A2A layers +- Operational APIs for status and automation +
-Rozdฤ›lenรญ pozorovatelnosti podle protokolu vytvรกล™รญ slepรก mรญsta a delลกรญ MTTR. - -**Jak to OmniRoute ล™eลกรญ:** - -- Sjednocenรฉ dashboardy/logy/analytiky v jednom produktu -- Stav + audit + telemetrie poลพadavkลฏ napล™รญฤ vrstvami OpenAI, MCP a A2A -- Provoznรญ API pro stav a automatizaci -
-๐Ÿ’ผ 29. โ€žPotล™ebuji jeden runtime pro proxy + nรกstroje + orchestraci agentลฏโ€œ +๐Ÿ’ผ 29. "I need one runtime for proxy + tools + agent orchestration" + +Running many separate services increases operational cost and failure modes. + +**How OmniRoute solves it:** + +- OpenAI-compatible proxy, MCP server, and A2A server in one stack +- Shared auth, resilience, data store, and observability +- Consistent policy model across all interaction surfaces +
-Spouลกtฤ›nรญ mnoha samostatnรฝch sluลพeb zvyลกuje provoznรญ nรกklady a poฤet poruch. - -**Jak to OmniRoute ล™eลกรญ:** - -- Proxy, MCP server a A2A server kompatibilnรญ s OpenAI v jednom balรญฤku -- Sdรญlenรฉ ovฤ›ล™ovรกnรญ, odolnost, รบloลพiลกtฤ› dat a pozorovatelnost -- Konzistentnรญ model politik napล™รญฤ vลกemi interakฤnรญmi plochami -
-๐Ÿš€ 30. โ€žPotล™ebuji agentskรฉ pracovnรญ postupy bez slepenรญ kรณdu.โ€œ +๐Ÿš€ 30. "I need to ship agentic workflows without glue-code sprawl" + +Teams lose velocity when stitching multiple ad-hoc services and scripts. + +**How OmniRoute solves it:** + +- Unified endpoint strategy for clients and agents +- Built-in protocol management UIs and smoke validation paths +- Production-ready foundations (security, logging, resilience, backup) +
-Tรฝmy ztrรกcejรญ rychlost pล™i spojovรกnรญ vรญce ad-hoc sluลพeb a skriptลฏ. +### Example Playbooks (Integrated Use Cases) -**Jak to OmniRoute ล™eลกรญ:** - -- Sjednocenรก strategie koncovรฝch bodลฏ pro klienty a agenty -- Vestavฤ›nรก uลพivatelskรก rozhranรญ pro sprรกvu protokolลฏ a cesty pro ovฤ›ล™ovรกnรญ kouล™e -- Zรกklady pล™ipravenรฉ pro produkฤnรญ prostล™edรญ (zabezpeฤenรญ, protokolovรกnรญ, odolnost, zรกlohovรกnรญ) - -### Pล™รญklady hernรญch plรกnลฏ (integrovanรฉ pล™รญpady uลพitรญ) - -**Pล™รญruฤka A: Maximalizace placenรฉho pล™edplatnรฉho + levnรฉ zรกlohovรกnรญ** +**Playbook A: Maximize paid subscription + cheap backup** ```txt Combo: "maximize-claude" @@ -596,7 +720,7 @@ Monthly cost: $20 + small backup spend Outcome: higher quality, near-zero interruption ``` -**Pล™รญruฤka B: Kรณdovacรญ stack s nulovรฝmi nรกklady** +**Playbook B: Zero-cost coding stack** ```txt Combo: "free-forever" @@ -608,7 +732,7 @@ Monthly cost: $0 Outcome: stable free coding workflow ``` -**Pล™รญruฤka C: Nonstop zรกloลพnรญ ล™etฤ›zec** +**Playbook C: 24/7 always-on fallback chain** ```txt Combo: "always-on" @@ -621,7 +745,7 @@ Combo: "always-on" Outcome: deep fallback depth for deadline-critical workloads ``` -**Pล™รญruฤka D: Operace agentลฏ s MCP + A2A** +**Playbook D: Agent ops with MCP + A2A** ```txt 1) Start MCP transport (`omniroute --mcp`) for tool-driven operations @@ -632,32 +756,32 @@ Outcome: deep fallback depth for deadline-critical workloads --- -## ๐Ÿ†“ Zaฤnฤ›te zdarma โ€” Nulovรฉ nรกklady na konfiguraci +## ๐Ÿ†“ Start Free โ€” Zero Configuration Cost -> Nastavte si kรณdovรกnรญ s umฤ›lou inteligencรญ bฤ›hem nฤ›kolika minut za **0 $/mฤ›sรญc** . Propojte tyto bezplatnรฉ รบฤty a vyuลพijte vestavฤ›nou kombinaci **Free Stack** . +> Setup AI coding in minutes at **$0/month**. Connect these free accounts and use the built-in **Free Stack** combo. -| Krok | Akce | Poskytovatelรฉ odemฤeni | -| ---- | -------------------------------------------------------------- | ----------------------------------------------------------------- | -| 1 | Pล™ipojenรญ **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 โ€“ **neomezenฤ›** | -| 2 | Pล™ipojenรญ k **Qoder** (Google OAuth) | kimi-k2-myลกlenรญ, qwen3-coder-plus, deepseek-r1... โ€” **neomezenฤ›** | -| 3 | Pล™ipojenรญ **Qwen** (kรณd zaล™รญzenรญ) | qwen3-coder-plus, qwen3-coder-flash... โ€” **neomezenฤ›** | -| 4 | Pล™ipojenรญ **rozhranรญ pล™รญkazovรฉho ล™รกdku Gemini** (Google OAuth) | gemini-3-flash, gemini-2.5-pro โ€” **180 000 GBP/mฤ›sรญc zdarma** | -| 5 | `/dashboard/combos` โ†’ ล ablona **Free Stack (0 $)** | Automatickรฉ zaล™azenรญ vลกech bezplatnรฝch poskytovatelลฏ do routingu | +| Step | Action | Providers Unlocked | +| ---- | -------------------------------------------------- | ------------------------------------------------------------------ | +| 1 | Connect **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 โ€” **unlimited** | +| 2 | Connect **Qoder** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... โ€” **unlimited** | +| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... โ€” **unlimited** | +| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro โ€” **180K/mo free** | +| 5 | `/dashboard/combos` โ†’ **Free Stack ($0)** template | Round-robin all free providers automatically | -**V libovolnรฉm IDE/CLI naveฤte:** `http://localhost:20128/v1` ยท Klรญฤ API: `any-string` ยท Hotovo. +**Point any IDE/CLI to:** `http://localhost:20128/v1` ยท API Key: `any-string` ยท Done. -> **Volitelnรฉ doplลˆkovรฉ krytรญ (takรฉ zdarma):** Groq API klรญฤ (30 RPM zdarma), NVIDIA NIM (40 RPM zdarma, 70+ modelลฏ), Cerebras (1 milion tok/den). +> **Optional extra coverage (also free):** Groq API key (30 RPM free), NVIDIA NIM (40 RPM free, 70+ models), Cerebras (1M tok/day), LongCat API key (50M tokens/day!), Cloudflare Workers AI (10K Neurons/day, 50+ models). -## โšก Rychlรฝ start +## Rychlรฝ start -### 1) Nainstalujte a spusลฅte +### 1) Install and run ```bash npm install -g omniroute omniroute ``` -> **Uลพivatelรฉ pnpm:** Po instalaci spusลฅte `pnpm approve-builds -g` , abyste povolili nativnรญ skripty pro sestavenรญ vyลพadovanรฉ programy `better-sqlite3` a `@swc/core` : +> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`: > > ```bash > pnpm install -g omniroute @@ -665,17 +789,17 @@ omniroute > omniroute > ``` -Dashboard se otevรญrรก na `http://localhost:20128` a zรกkladnรญ URL API je `http://localhost:20128/v1` . +Dashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`. -| Pล™รญkaz | Popis | -| ----------------------- | ------------------------------------------------------------------- | -| `omniroute` | Spuลกtฤ›nรญ serveru ( `PORT=20128` , API a dashboard na stejnรฉm portu) | -| `omniroute --port 3000` | Nastavte kanonickรฝ/API port na 3000 | -| `omniroute --mcp` | Spuลกtฤ›nรญ MCP serveru (transport stdio) | -| `omniroute --no-open` | Neotevรญrat prohlรญลพeฤ automaticky | -| `omniroute --help` | Zobrazit nรกpovฤ›du | +| Command | Description | +| ----------------------- | ----------------------------------------------------------- | +| `omniroute` | Start server (`PORT=20128`, API and dashboard on same port) | +| `omniroute --port 3000` | Set canonical/API port to 3000 | +| `omniroute --mcp` | Start MCP server (stdio transport) | +| `omniroute --no-open` | Don't auto-open browser | +| `omniroute --help` | Show help | -Volitelnรฝ reลพim s rozdฤ›lenรฝm portem: +Optional split-port mode: ```bash PORT=20128 DASHBOARD_PORT=20129 omniroute @@ -683,13 +807,13 @@ PORT=20128 DASHBOARD_PORT=20129 omniroute # Dashboard: http://localhost:20129 ``` -### 2) Pล™ipojte poskytovatele a vytvoล™te si klรญฤ API +### 2) Connect providers and create your API key -1. Otevล™ete Dashboard โ†’ `Providers` a pล™ipojte alespoลˆ jednoho poskytovatele (klรญฤ OAuth nebo API). -2. Otevล™ete Dashboard โ†’ `Endpoints` a vytvoล™te API klรญฤ. -3. (Volitelnรฉ) Otevล™ete Dashboard โ†’ `Combos` a nastavte zรกloลพnรญ ล™etฤ›zec. +1. Open Dashboard โ†’ `Providers` and connect at least one provider (OAuth or API key). +2. Open Dashboard โ†’ `Endpoints` and create an API key. +3. (Optional) Open Dashboard โ†’ `Combos` and set your fallback chain. -### 3) Nasmฤ›rujte svลฏj kรณdovacรญ nรกstroj na OmniRoute +### 3) Point your coding tool to OmniRoute ```txt Base URL: http://localhost:20128/v1 @@ -697,22 +821,22 @@ API Key: [copy from Endpoint page] Model: if/kimi-k2-thinking (or any provider/model prefix) ``` -Funguje s Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode a SDK kompatibilnรญmi s OpenAI. +Works with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs. -### 4) Povolenรญ a ovฤ›ล™enรญ protokolลฏ (v2.0) +### 4) Enable and validate protocols (v2.0) -**MCP (pro operace ล™รญzenรฉ nรกstroji):** +**MCP (for tool-driven operations):** ```bash omniroute --mcp ``` -Pak pล™ipojte svรฉho MCP klienta pล™es `stdio` a otestujte nรกstroje jako: +Then connect your MCP client over `stdio` and test tools like: - `omniroute_get_health` - `omniroute_list_combos` -**A2A (pro pracovnรญ postupy mezi agenty):** +**A2A (for agent-to-agent workflows):** ```bash curl http://localhost:20128/.well-known/agent.json @@ -724,15 +848,15 @@ curl -X POST http://localhost:20128/a2a \ -d '{"jsonrpc":"2.0","id":"quickstart","method":"message/send","params":{"skill":"quota-management","messages":[{"role":"user","content":"Give me a short quota summary."}]}}' ``` -### 5) Ovฤ›ล™te vลกe od zaฤรกtku do konce (doporuฤeno) +### 5) Validate everything end-to-end (recommended) ```bash npm run test:protocols:e2e ``` -Tato sada ovฤ›ล™uje skuteฤnรฉ toky klientลฏ MCP a A2A v porovnรกnรญ se spuลกtฤ›nou aplikacรญ. +This suite validates real MCP and A2A client flows against a running app. -### Alternativa: spustit ze zdroje +### Alternative: run from source ```bash cp .env.example .env @@ -740,13 +864,120 @@ npm install PORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev ``` +
+Void Linux (`xbps-src` template) + +For Void Linux users, you can build a native package using `xbps-src`. Save this block as `srcpkgs/omniroute/template`: + +```bash +# Template file for 'omniroute' +pkgname=omniroute +version=3.4.1 +revision=1 +hostmakedepends="nodejs python3 make" +depends="openssl" +short_desc="Universal AI gateway with smart routing for multiple LLM providers" +maintainer="zenobit " +license="MIT" +homepage="https://github.com/diegosouzapw/OmniRoute" +distfiles="https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz" +checksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b +system_accounts="_omniroute" +omniroute_homedir="/var/lib/omniroute" +export NODE_ENV=production +export npm_config_engine_strict=false +export npm_config_loglevel=error +export npm_config_fund=false +export npm_config_audit=false + +do_build() { + # Determine target CPU arch for node-gyp + local _gyp_arch + case "$XBPS_TARGET_MACHINE" in + aarch64*) _gyp_arch=arm64 ;; + armv7*|armv6*) _gyp_arch=arm ;; + i686*) _gyp_arch=ia32 ;; + *) _gyp_arch=x64 ;; + esac + + # 1) Install all deps โ€“ skip scripts (no network in do_build, native modules + # compiled separately below; better-sqlite3 is serverExternalPackage so + # Next.js does not execute it during next build) + NODE_ENV=development npm ci --ignore-scripts + + # 2) Build the Next.js standalone bundle + npm run build + + # 3) Copy static assets into standalone + cp -r .next/static .next/standalone/.next/static + [ -d public ] && cp -r public .next/standalone/public || true + + # 4) Compile better-sqlite3 native binding for the target architecture. + # Use node-gyp directly so CC/CXX from xbps-src cross-toolchain are used + # without npm altering them. + local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js + (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch") + + # 5) Place the compiled binding into the standalone bundle + local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release + mkdir -p "$_bs3_release" + cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/" + + # 6) Remove arch-specific sharp bundles โ€“ upstream sets images.unoptimized=true + # so sharp is not used at runtime; x64 .so files would break aarch64 strip + rm -rf .next/standalone/node_modules/@img + + # 7) Copy pino runtime deps omitted by Next.js static analysis: + # pino-abstract-transport โ€“ required by pino's worker thread + # split2 โ€“ dep of pino-abstract-transport + # process-warning โ€“ dep of pino itself + for _mod in pino-abstract-transport split2 process-warning; do + cp -r "node_modules/$_mod" .next/standalone/node_modules/ + done +} + +do_check() { + npm run test:unit +} + +do_install() { + vmkdir usr/lib/omniroute/.next + + vcopy .next/standalone/. usr/lib/omniroute/.next/standalone + + # Prevent removal of empty Next.js app router dirs by the post-install hook + for _d in \ + .next/standalone/.next/server/app/dashboard \ + .next/standalone/.next/server/app/dashboard/settings \ + .next/standalone/.next/server/app/dashboard/providers; do + touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep" + done + + cat > "${WRKDIR}/omniroute" <<'EOF' +#!/bin/sh +export PORT="${PORT:-20128}" +export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}" +export LOG_TO_FILE="${LOG_TO_FILE:-false}" +mkdir -p "${DATA_DIR}" +exec node /usr/lib/omniroute/.next/standalone/server.js "$@" +EOF + vbin "${WRKDIR}/omniroute" +} + +post_install() { + vlicense LICENSE +} +``` + +
+ --- ## ๐Ÿณ Docker -OmniRoute je k dispozici jako veล™ejnรฝ obraz Dockeru na [Docker Hubu](https://hub.docker.com/r/diegosouzapw/omniroute) . +OmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute). -**Rychlรฝ bฤ›h:** +**Quick run:** ```bash docker run -d \ @@ -757,7 +988,7 @@ docker run -d \ diegosouzapw/omniroute:latest ``` -**Se souborem prostล™edรญ:** +**With environment file:** ```bash # Copy and edit .env first @@ -772,7 +1003,7 @@ docker run -d \ diegosouzapw/omniroute:latest ``` -**Pouลพรญvรกnรญ Docker Compose:** +**Using Docker Compose:** ```bash # Base profile (no CLI tools) @@ -782,24 +1013,62 @@ docker compose --profile base up -d docker compose --profile cli up -d ``` -| Obraz | ล tรญtek | Velikost | Popis | -| ------------------------ | -------- | -------- | ------------------------- | -| `diegosouzapw/omniroute` | `latest` | ~250 MB | Nejnovฤ›jลกรญ stabilnรญ verze | -| `diegosouzapw/omniroute` | `1.0.3` | ~250 MB | Aktuรกlnรญ verze | +Dashboard support for Docker deployments now includes a one-click **Cloudflare Quick Tunnel** on `Dashboard โ†’ Endpoints`. The first enable downloads `cloudflared` only when needed, starts a temporary tunnel to your current `/v1` endpoint, and shows the generated `https://*.trycloudflare.com/v1` URL directly below your normal public URL. + +Notes: + +- Quick Tunnel URLs are temporary and change after every restart. +- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`. +- Docker images bundle system CA roots and pass them to managed `cloudflared`, which avoids TLS trust failures when the tunnel bootstraps inside the container. +- Set `CLOUDFLARED_BIN=/absolute/path/to/cloudflared` if you want OmniRoute to use an existing binary instead of downloading one. + +**Using Docker Compose with Caddy (HTTPS Auto-TLS):** + +OmniRoute can be securely exposed using Caddy's automatic SSL provisioning. Ensure your domain's DNS A record points to your server's IP. + +```yaml +services: + omniroute: + image: diegosouzapw/omniroute:latest + container_name: omniroute + restart: unless-stopped + volumes: + - omniroute-data:/app/data + environment: + - PORT=20128 + - NEXT_PUBLIC_BASE_URL=https://your-domain.com + + caddy: + image: caddy:latest + container_name: caddy + restart: unless-stopped + ports: + - "80:80" + - "443:443" + command: caddy reverse-proxy --from https://your-domain.com --to http://omniroute:20128 + +volumes: + omniroute-data: +``` + +| Image | Tag | Size | Description | +| ------------------------ | -------- | ------ | --------------------- | +| `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release | +| `diegosouzapw/omniroute` | `1.0.3` | ~250MB | Current version | --- -## ๐Ÿ–ฅ๏ธ Desktopovรก aplikace โ€“ offline a vลพdy zapnutรก +## ๐Ÿ–ฅ๏ธ Desktop App โ€” Offline & Always-On -> ๐Ÿ†• **NOVINKA!** OmniRoute je nynรญ k dispozici jako **nativnรญ desktopovรก aplikace** pro Windows, macOS a Linux. +> ๐Ÿ†• **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux. -Spusลฅte OmniRoute jako samostatnou desktopovou aplikaci โ€“ pro lokรกlnรญ modely nenรญ potล™eba ลพรกdnรฝ terminรกl, prohlรญลพeฤ ani internet. Aplikace zaloลพenรก na platformฤ› Electron obsahuje: +Run OmniRoute as a standalone desktop app โ€” no terminal, no browser, no internet required for local models. The Electron-based app includes: -- ๐Ÿ–ฅ๏ธ **Nativnรญ okno** โ€” Vyhrazenรฉ okno aplikace s integracรญ do systรฉmovรฉ liลกty -- ๐Ÿ”„ **Automatickรฉ spuลกtฤ›nรญ** โ€” Spuลกtฤ›nรญ OmniRoute po pล™ihlรกลกenรญ do systรฉmu -- ๐Ÿ”” **Nativnรญ oznรกmenรญ** โ€“ Zรญskejte upozornฤ›nรญ na vyฤerpรกnรญ kvรณty nebo problรฉmy s poskytovateli -- โšก **Instalace jednรญm kliknutรญm** โ€” NSIS (Windows), DMG (macOS), AppImage (Linux) -- ๐ŸŒ **Offline reลพim** โ€” Funguje plnฤ› offline s pล™iloลพenรฝm serverem +- ๐Ÿ–ฅ๏ธ **Native Window** โ€” Dedicated app window with system tray integration +- ๐Ÿ”„ **Auto-Start** โ€” Launch OmniRoute on system login +- ๐Ÿ”” **Native Notifications** โ€” Get alerts for quota exhaustion or provider issues +- โšก **One-Click Install** โ€” NSIS (Windows), DMG (macOS), AppImage (Linux) +- ๐ŸŒ **Offline Mode** โ€” Works fully offline with bundled server ### Rychlรฝ start @@ -814,47 +1083,51 @@ npm run electron:build:mac # macOS (.dmg) โ€” x64 & arm64 npm run electron:build:linux # Linux (.AppImage) ``` -### Systรฉmovรฝ zรกsobnรญk +### System Tray -Po minimalizaci se OmniRoute nachรกzรญ v systรฉmovรฉ liลกtฤ› a nabรญzรญ rychlรฉ akce: +When minimized, OmniRoute lives in your system tray with quick actions: -- Otevล™รญt ล™รญdicรญ panel -- Zmฤ›nit port serveru -- Ukonฤit aplikaci +- Open dashboard +- Change server port +- Quit application -๐Ÿ“– รšplnรก dokumentace: [`electron/README.md`](electron/README.md) +๐Ÿ“– Full documentation: [`electron/README.md`](electron/README.md) --- -## ๐Ÿ’ฐ Pล™ehled cen +## ๐Ÿ’ฐ Pricing at a Glance -| รšroveลˆ | Poskytovatel | Nรกklady | Obnovenรญ kvรณty | Nejlepลกรญ pro | -| --------------------------- | -------------------------------- | ------------------------------------ | ------------------------------------------ | --------------------------------------------------------- | -| **๐Ÿ’ณ Pล˜EDPLATNร‰** | Claude Code (profesionรกl) | 20 dolarลฏ mฤ›sรญฤnฤ› | 5 hodin + tรฝdnฤ› | Jiลพ pล™ihlรกลกen/a k odbฤ›ru | -| Kodex (Plus/Pro) | 20โ€“200 USD/mฤ›sรญc | 5 hodin + tรฝdnฤ› | Uลพivatelรฉ OpenAI | -| Gemini CLI | **UVOLNIT** | 180 tisรญc mฤ›sรญฤnฤ› + 1 tisรญc dennฤ› | Kaลพdรฝ! | -| GitHub Copilot | 10โ€“19 USD/mฤ›sรญc | Mฤ›sรญฤnรญ | Uลพivatelรฉ GitHubu | -| **๐Ÿ”‘ KLรฤŒ API** | NVIDIA NIM | **ZDARMA** (vรฝvoj navลพdy) | ~40 ot./min | 70+ otevล™enรฝch modelลฏ | -| Mozky | **ZDARMA** (1 milion tok/den) | 60 000 otรกฤek za minutu / 30 ot./min | Nejrychlejลกรญ na svฤ›tฤ› | -| Groq | **ZDARMA** (30 ot./min.) | 14,4 tisรญc otรกฤek za minutu | Ultrarychlรก lama/gema | -| DeepSeek V3.2 | 0,27/1,10 USD za 1 milion | ลฝรกdnรฝ | Nejlepลกรญ zdลฏvodnฤ›nรญ ceny a kvality | -| xAI Grok-4 Rychlรฝ | **0,20/0,50 USD za 1 milion** ๐Ÿ†• | ลฝรกdnรฝ | Nejrychlejลกรญ + volรกnรญ nรกstroje, ultranรญzkรฉ | -| xAI Grok-4 (standardnรญ) | 0,20/1,50 USD za 1 milion ๐Ÿ†• | ลฝรกdnรฝ | Vlajkovรก loฤ Reasoning od xAI | -| Mistral | Zkuลกebnรญ verze zdarma + placenรฉ | Omezenรก sazba | Evropskรก umฤ›lรก inteligence | -| OpenRouter | Platba za pouลพitรญ | ลฝรกdnรฝ | Vรญce neลพ 100 modelลฏ agregovรกno. | -| **๐Ÿ’ฐ LEVNร‰** | GLM-5 (pล™es Z.AI) ๐Ÿ†• | 0,5 USD/1 milion | Dennฤ› v 10:00 | Vรฝstup 128 tisรญc obrazovรฝch bodลฏ, nejnovฤ›jลกรญ vlajkovรก loฤ | -| GLM-4.7 | 0,6 USD/1 milion | Dennฤ› v 10:00 | Zรกloha rozpoฤtu | -| MiniMax M2.5 ๐Ÿ†• | Vstup 0,3 USD/1 milion | 5hodinovรฉ vรกlcovรกnรญ | รšvaha + agentnรญ รบkoly | -| MiniMax M2.1 | 0,2 USD/1 milion | 5hodinovรฉ vรกlcovรกnรญ | Nejlevnฤ›jลกรญ varianta | -| Kimi K2.5 (Moonshot API) ๐Ÿ†• | Platba za pouลพitรญ | ลฝรกdnรฝ | Pล™รญmรฝ pล™รญstup k Moonshot API | -| Kimi K2 | 9 dolarลฏ mฤ›sรญฤnฤ› bez zรกvazkลฏ | 10 milionลฏ tokenลฏ/mฤ›sรญc | Pล™edvรญdatelnรฉ nรกklady | -| **๐Ÿ†“ ZDARMA** | Qoder | **0 dolarลฏ** | Neomezenรฝ | 5 modelลฏ neomezenฤ› | -| Qwen | **0 dolarลฏ** | Neomezenรฝ | 4 modely neomezenฤ› | -| Kiro | **0 dolarลฏ** | Neomezenรฝ | Claude Sonnet/Haiku (tvorce AWS) | +| 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** | NVIDIA NIM | **FREE** (dev forever) | ~40 RPM | 70+ open models | +| | Cerebras | **FREE** (1M tok/day) | 60K TPM / 30 RPM | World's fastest | +| | Groq | **FREE** (30 RPM) | 14.4K RPD | Ultra-fast Llama/Gemma | +| | DeepSeek V3.2 | $0.27/$1.10 per 1M | None | Best price/quality reasoning | +| | xAI Grok-4 Fast | **$0.20/$0.50 per 1M** ๐Ÿ†• | None | Fastest + tool calling, ultralow | +| | xAI Grok-4 (standard) | $0.20/$1.50 per 1M ๐Ÿ†• | None | Reasoning flagship from xAI | +| | Mistral | Free trial + paid | Rate limited | European AI | +| | OpenRouter | Pay-per-use | None | 100+ models aggr. | +| **๐Ÿ’ฐ CHEAP** | GLM-5 (via Z.AI) ๐Ÿ†• | $0.5/1M | Daily 10AM | 128K output, newest flagship | +| | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup | +| | MiniMax M2.5 ๐Ÿ†• | $0.3/1M input | 5-hour rolling | Reasoning + agentic tasks | +| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option | +| | Kimi K2.5 (Moonshot API) ๐Ÿ†• | Pay-per-use | None | Direct Moonshot API access | +| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost | +| **๐Ÿ†“ FREE** | Qoder | **$0** | Unlimited | 5 models unlimited | +| | Qwen | **$0** | Unlimited | 4 models unlimited | +| | Kiro | **$0** | Unlimited | Claude Sonnet/Haiku (AWS Builder) | +| | LongCat Flash-Lite ๐Ÿ†• | **$0** (50M tok/day ๐Ÿ”ฅ) | 1 RPS | Largest free quota on Earth | +| | Pollinations AI ๐Ÿ†• | **$0** (no key needed) | 1 req/15s | GPT-5, Claude, DeepSeek, Llama 4 | +| | Cloudflare Workers AI ๐Ÿ†• | **$0** (10K Neurons/day) | ~150 resp/day | 50+ models, global edge | +| | Scaleway AI ๐Ÿ†• | **$0** (1M tokens total) | Rate limited | EU/GDPR, Qwen3 235B, Llama 70B | -> ๐Ÿ†• **Pล™idรกny novรฉ modely (bล™ezen 2026):** ล™ada Grok-4 Fast za 0,20 USD/0,50 USD/M (benchmarkovรกno na 1143 ms โ€“ o 30 % rychlejลกรญ neลพ Gemini 2.5 Flash), GLM-5 pล™es Z.AI s vรฝstupem 128K, uvaลพovรกnรญ MiniMax M2.5, aktualizovanรฉ ceny DeepSeek V3.2, Kimi K2.5 pล™es Moonshot Direct API. +> ๐Ÿ†• **New models added (Mar 2026):** Grok-4 Fast family at $0.20/$0.50/M (benchmarked at 1143ms โ€” 30% faster than Gemini 2.5 Flash), GLM-5 via Z.AI with 128K output, MiniMax M2.5 reasoning, DeepSeek V3.2 updated pricing, Kimi K2.5 via Moonshot direct API. -**๐Ÿ’ก Kombinovanรฝ balรญk za 0 $ โ€” Kompletnรญ bezplatnรก instalace:** +**๐Ÿ’ก $0 Combo Stack โ€” The Complete Free Setup:** ``` # ๐Ÿ†“ Ultimate Free Stack 2026 โ€” 11 Providers, $0 Forever @@ -871,99 +1144,146 @@ NVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever Cerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day ``` -**Nulovรฉ nรกklady. Nikdy nepล™estรกvejte s kรณdovรกnรญm.** Nakonfigurujte si to jako jednu kombinaci OmniRoute a vลกechny zรกloลพnรญ reลพimy se provede automaticky โ€“ ลพรกdnรฉ ruฤnรญ pล™epรญnรกnรญ. +**Zero cost. Never stops coding.** Configure this as one OmniRoute combo and all fallbacks happen automatically โ€” no manual switching ever. --- --- -## ๐Ÿ†“ Bezplatnรฉ modely โ€“ Co skuteฤnฤ› zรญskรกte +## ๐Ÿ†“ Free Models โ€” What You Actually Get -> Vลกechny nรญลพe uvedenรฉ modely jsou **100% zdarma a nevyลพadujรญ ลพรกdnou kreditnรญ kartu** . OmniRoute mezi nimi automaticky propojรญ trasy, kdyลพ dojde jedna kvรณta โ€“ zkombinujte je vลกechny a zรญskejte tak nerozluฤnou kombinaci za 0 dolarลฏ. +> All models below are **100% free with zero credit card required**. OmniRoute auto-routes between them when one quota runs out โ€” combine them all for an unbreakable $0 combo. -### ๐Ÿ”ต CLAUDE MODELS (pล™es Kiro โ€” AWS Builder ID) +### ๐Ÿ”ต CLAUDE MODELS (via Kiro โ€” AWS Builder ID) -| Model | Pล™edpona | Omezit | Limit rychlosti | -| ------------------- | -------- | ------------- | ------------------------- | -| `claude-sonnet-4.5` | `kr/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ dennรญ limit | -| `claude-haiku-4.5` | `kr/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ dennรญ limit | -| `claude-opus-4.6` | `kr/` | **Neomezenรฝ** | Nejnovฤ›jลกรญ opus od Kira | +| Model | Prefix | Limit | Rate Limit | +| ------------------- | ------ | ------------- | --------------------- | +| `claude-sonnet-4.5` | `kr/` | **Unlimited** | No reported daily cap | +| `claude-haiku-4.5` | `kr/` | **Unlimited** | No reported daily cap | +| `claude-opus-4.6` | `kr/` | **Unlimited** | Latest Opus via Kiro | -### ๐ŸŸข MODELY QODER (Bezplatnรฉ OAuth โ€” bez nutnosti platit kreditnรญ kartou) +### ๐ŸŸข QODER MODELS (Free OAuth โ€” No Credit Card) -| Model | Pล™edpona | Omezit | Limit rychlosti | -| ------------------ | -------- | ------------- | ------------------- | -| `kimi-k2-thinking` | `if/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop | -| `qwen3-coder-plus` | `if/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop | -| `deepseek-r1` | `if/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop | -| `minimax-m2.1` | `if/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop | -| `kimi-k2` | `if/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop | +| Model | Prefix | Limit | Rate Limit | +| ------------------ | ------ | ------------- | --------------- | +| `kimi-k2-thinking` | `if/` | **Unlimited** | No reported cap | +| `qwen3-coder-plus` | `if/` | **Unlimited** | No reported cap | +| `deepseek-r1` | `if/` | **Unlimited** | No reported cap | +| `minimax-m2.1` | `if/` | **Unlimited** | No reported cap | +| `kimi-k2` | `if/` | **Unlimited** | No reported cap | -### ๐ŸŸก MODELY QWEN (Ovฤ›ล™enรญ kรณdu zaล™รญzenรญ) +### ๐ŸŸก QWEN MODELS (Device Code Auth) -| Model | Pล™edpona | Omezit | Limit rychlosti | -| ------------------- | -------- | ------------- | ---------------------- | -| `qwen3-coder-plus` | `qw/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop | -| `qwen3-coder-flash` | `qw/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop | -| `qwen3-coder-next` | `qw/` | **Neomezenรฝ** | ลฝรกdnรฝ hlรกลกenรฝ strop | -| `vision-model` | `qw/` | **Neomezenรฝ** | Multimodรกlnรญ (obrรกzky) | +| Model | Prefix | Limit | Rate Limit | +| ------------------- | ------ | ------------- | ------------------- | +| `qwen3-coder-plus` | `qw/` | **Unlimited** | No reported cap | +| `qwen3-coder-flash` | `qw/` | **Unlimited** | No reported cap | +| `qwen3-coder-next` | `qw/` | **Unlimited** | No reported cap | +| `vision-model` | `qw/` | **Unlimited** | Multimodal (images) | -### ๐ŸŸฃ Rozhranรญ GEMINI CLI (Google OAuth) +### ๐ŸŸฃ GEMINI CLI (Google OAuth) -| Model | Pล™edpona | Omezit | Limit rychlosti | -| ------------------------ | -------- | ------------------------------------- | --------------- | -| `gemini-3-flash-preview` | `gc/` | **180 tisรญc tok/mฤ›sรญc** + 1 tisรญc/den | Mฤ›sรญฤnรญ reset | -| `gemini-2.5-pro` | `gc/` | 180 tisรญc mฤ›sรญฤnฤ› (sdรญlenรฝ bazรฉn) | Vysokรก kvalita | +| Model | Prefix | Limit | Rate Limit | +| ------------------------ | ------ | --------------------------- | ------------- | +| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset | +| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality | -### โšซ NVIDIA NIM (Bezplatnรฝ klรญฤ API โ€” build.nvidia.com) +### โšซ NVIDIA NIM (Free API Key โ€” build.nvidia.com) -| รšroveลˆ | Dennรญ limit | Limit rychlosti | Poznรกmky | -| ---------------- | ------------------ | --------------- | ---------------------------------------------------------------------- | -| Zdarma (vรฝvojรกล™) | ลฝรกdnรฝ limit tokenลฏ | **~40 ot./min** | Vรญce neลพ 70 modelลฏ; pล™echod na ฤistรฉ limity sazeb v polovinฤ› roku 2025 | +| Tier | Daily Limit | Rate Limit | Notes | +| ---------- | ------------ | ----------- | ------------------------------------------------------ | +| Free (Dev) | No token cap | **~40 RPM** | 70+ models; transitioning to pure rate limits mid-2025 | -Oblรญbenรฉ bezplatnรฉ modely: `moonshotai/kimi-k2.5` (Kimi K2.5), `z-ai/glm4.7` (GLM 4.7), `deepseek-ai/deepseek-v3.2` (DeepSeek V3.2), `nvidia/llama-3.3-70b-instruct` , `deepseek/deepseek-r1` +Popular free models: `moonshotai/kimi-k2.5` (Kimi K2.5), `z-ai/glm4.7` (GLM 4.7), `deepseek-ai/deepseek-v3.2` (DeepSeek V3.2), `nvidia/llama-3.3-70b-instruct`, `deepseek/deepseek-r1` -### โšช CEREBRAS (Bezplatnรฝ klรญฤ API โ€” inference.cerebras.ai) +### โšช CEREBRAS (Free API Key โ€” inference.cerebras.ai) -| รšroveลˆ | Dennรญ limit | Limit rychlosti | Poznรกmky | -| ------- | ----------------------- | ------------------------------------ | ------------------------------------------------------ | -| Uvolnit | **1 milion tokenลฏ/den** | 60 000 otรกฤek za minutu / 30 ot./min | Nejrychlejลกรญ inference LLM na svฤ›tฤ›; dennฤ› se resetuje | +| Tier | Daily Limit | Rate Limit | Notes | +| ---- | ----------------- | ---------------- | ------------------------------------------- | +| Free | **1M tokens/day** | 60K TPM / 30 RPM | World's fastest LLM inference; resets daily | -Dostupnรฉ zdarma: `llama-3.3-70b` , `llama-3.1-8b` , `deepseek-r1-distill-llama-70b` +Available free: `llama-3.3-70b`, `llama-3.1-8b`, `deepseek-r1-distill-llama-70b` -### ๐Ÿ”ด GROQ (Bezplatnรฝ API klรญฤ โ€” console.groq.com) +### ๐Ÿ”ด GROQ (Free API Key โ€” console.groq.com) -| รšroveลˆ | Dennรญ limit | Limit rychlosti | Poznรกmky | -| ------- | ------------------------------- | ------------------- | ------------------------------------------- | -| Uvolnit | **14,4 tisรญc otรกฤek za minutu** | 30 ot./min na model | ลฝรกdnรก kreditnรญ karta; limit 429, neรบฤtovรกno | +| Tier | Daily Limit | Rate Limit | Notes | +| ---- | ------------- | ---------------- | ----------------------------------------- | +| Free | **14.4K RPD** | 30 RPM per model | No credit card; 429 on limit, not charged | -K dispozici zdarma: `llama-3.3-70b-versatile` , `gemma2-9b-it` , `mixtral-8x7b` , `whisper-large-v3` +Available free: `llama-3.3-70b-versatile`, `gemma2-9b-it`, `mixtral-8x7b`, `whisper-large-v3` -> **๐Ÿ’ก Ultimรกtnรญ bezplatnรฝ zรกsobnรญk:** +### ๐Ÿ”ด LONGCAT AI (Free API Key โ€” longcat.chat) ๐Ÿ†• + +| Model | Prefix | Daily Free Quota | Notes | +| ----------------------------- | ------ | ----------------- | ----------------------- | +| `LongCat-Flash-Lite` | `lc/` | **50M tokens** ๐Ÿ’ฅ | Largest free quota ever | +| `LongCat-Flash-Chat` | `lc/` | 500K tokens | Multi-turn chat | +| `LongCat-Flash-Thinking` | `lc/` | 500K tokens | Reasoning / CoT | +| `LongCat-Flash-Thinking-2601` | `lc/` | 500K tokens | Jan 2026 version | +| `LongCat-Flash-Omni-2603` | `lc/` | 500K tokens | Multimodal | + +> 100% free while in public beta. Sign up at [longcat.chat](https://longcat.chat) with email or phone. Resets daily 00:00 UTC. + +### ๐ŸŸข POLLINATIONS AI (No API Key Required) ๐Ÿ†• + +| Model | Prefix | Rate Limit | Provider Behind | +| ---------- | ------ | ---------- | ------------------ | +| `openai` | `pol/` | 1 req/15s | GPT-5 | +| `claude` | `pol/` | 1 req/15s | Anthropic Claude | +| `gemini` | `pol/` | 1 req/15s | Google Gemini | +| `deepseek` | `pol/` | 1 req/15s | DeepSeek V3 | +| `llama` | `pol/` | 1 req/15s | Meta Llama 4 Scout | +| `mistral` | `pol/` | 1 req/15s | Mistral AI | + +> โœจ **Zero friction:** No signup, no API key. Add the Pollinations provider with an empty key field and it works immediately. + +### ๐ŸŸ  CLOUDFLARE WORKERS AI (Free API Key โ€” cloudflare.com) ๐Ÿ†• + +| Tier | Daily Neurons | Equivalent Usage | Notes | +| ---- | ------------- | --------------------------------------- | ----------------------- | +| Free | **10,000** | ~150 LLM resp / 500s audio / 15K embeds | Global edge, 50+ models | + +Popular free models: `@cf/meta/llama-3.3-70b-instruct`, `@cf/google/gemma-3-12b-it`, `@cf/openai/whisper-large-v3-turbo` (free audio!), `@cf/qwen/qwen2.5-coder-15b-instruct` + +> Requires API Token + Account ID from [dash.cloudflare.com](https://dash.cloudflare.com). Store Account ID in provider settings. + +### ๐ŸŸฃ SCALEWAY AI (1M Free Tokens โ€” scaleway.com) ๐Ÿ†• + +| Tier | Free Quota | Location | Notes | +| ---- | ------------- | ------------ | ----------------------------------- | +| Free | **1M tokens** | ๐Ÿ‡ซ๐Ÿ‡ท Paris, EU | No credit card needed within limits | + +Available free: `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct`, `mistral-small-3.2-24b-instruct-2506`, `deepseek-v3-0324` + +> EU/GDPR compliant. Get API key at [console.scaleway.com](https://console.scaleway.com). + +> **๐Ÿ’ก The Ultimate Free Stack (11 Providers, $0 Forever):** > > ``` -> Kiro (Claude, unlimited) -> โ†’ Qoder (5 models, unlimited) -> โ†’ Qwen (4 models, unlimited) -> โ†’ Gemini CLI (180K/mo) -> โ†’ Cerebras (1M tok/day) -> โ†’ Groq (14.4K req/day) -> โ†’ NVIDIA NIM (40 RPM, 70+ models) +> Kiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED +> Qoder (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED +> LongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ +> Pollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed +> Qwen (qw/) โ†’ qwen3-coder models UNLIMITED +> Gemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free +> Cloudflare AI (cf/) โ†’ 50+ models โ€” 10K Neurons/day +> Scaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU) +> Groq (groq/) โ†’ Llama/Gemma โ€” 14.4K req/day ultra-fast +> NVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever +> Cerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day > ``` -> -> Nakonfigurujte si to jako kombinaci OmniRoute a uลพ nikdy nebudete platit za umฤ›lou inteligenci. -## ๐ŸŽ™๏ธ Kombinovanรก transkripce zdarma +## ๐ŸŽ™๏ธ Free Transcription Combo -> Pล™episujte libovolnรฉ audio/video za **0 $** โ€“ Deepgram leady za 200 $ zdarma, AssemblyAI za 50 $ jako zรกloลพnรญ nรกstroj, Groq Whisper jako neomezenรก nouzovรก zรกloha. +> Transcribe any audio/video for **$0** โ€” Deepgram leads with $200 free, AssemblyAI $50 fallback, Groq Whisper as unlimited emergency backup. -| Poskytovatel | Bezplatnรฉ kredity | Nejlepลกรญ model | Limit rychlosti | -| ----------------- | ---------------------------------- | ----------------------------------------------------- | ---------------------------------- | -| ๐ŸŸข **Deepgram** | **200 dolarลฏ zdarma** (registrace) | `nova-3` โ€” nejvyลกลกรญ pล™esnost, vรญce neลพ 30 jazykลฏ | ลฝรกdnรฝ limit RPM pro kredity zdarma | -| ๐Ÿ”ต **AssemblyAI** | **50 dolarลฏ zdarma** (registrace) | `universal-3-pro` โ€” kapitoly, sentiment, osobnรญ รบdaje | ลฝรกdnรฝ limit RPM pro kredity zdarma | -| ๐Ÿ”ด **Groq** | **Navลพdy zdarma** | `whisper-large-v3` โ€” OpenAI ล epot | 30 ot./min (omezenรก rychlost) | +| Provider | Free Credits | Best Model | Rate Limit | +| ----------------- | ---------------------- | -------------------------------------------- | ---------------------------- | +| ๐ŸŸข **Deepgram** | **$200 free** (signup) | `nova-3` โ€” best accuracy, 30+ languages | No RPM limit on free credits | +| ๐Ÿ”ต **AssemblyAI** | **$50 free** (signup) | `universal-3-pro` โ€” chapters, sentiment, PII | No RPM limit on free credits | +| ๐Ÿ”ด **Groq** | **Free forever** | `whisper-large-v3` โ€” OpenAI Whisper | 30 RPM (rate limited) | -**Navrhovanรก kombinace v `/dashboard/combos` :** +**Suggested combo in `/dashboard/combos`:** ``` Name: free-transcription @@ -974,109 +1294,145 @@ Nodes: [3] groq/whisper-large-v3 โ†’ free forever, emergency fallback ``` -Pak v `/dashboard/media` โ†’ zรกloลพka **Pล™epis** : nahrajte libovolnรฝ zvukovรฝ nebo video soubor โ†’ vyberte kombinovanรฝ koncovรฝ bod โ†’ zรญskejte pล™epis v podporovanรฝch formรกtech. +Then in `/dashboard/media` โ†’ **Transcription** tab: upload any audio or video file โ†’ select your combo endpoint โ†’ get transcription in supported formats. -## ๐Ÿ’ก Klรญฤovรฉ vlastnosti +## ๐Ÿ’ก Key Features -OmniRoute v2.0 je navrลพen jako operaฤnรญ platforma, nikoli pouze jako proxy pro relรฉ. +OmniRoute v2.0 is built as an operational platform, not just a relay proxy. -### ๐Ÿค– Operace s agenty a protokoly (v2.0) +### ๐Ÿ†• New โ€” ClawRouter-Inspired Improvements (Mar 2026) -| Funkce | Co to dฤ›lรก | -| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | -| ๐Ÿ”ง **MCP Server (16 nรกstrojลฏ)** | Nรกstroje IDE/agent prostล™ednictvรญm 3 transportลฏ: stdio, SSE ( `/api/mcp/sse` ), Streamovatelnรฝ HTTP ( `/api/mcp/stream` ) | -| ๐Ÿค **A2A server (JSON-RPC + SSE)** | Spouลกtฤ›nรญ รบloh mezi agenty se synchronizacรญ a streamovรกnรญm | -| ๐Ÿงญ **Konsolidovanรก strรกnka koncovรฝch bodลฏ** | Strรกnka pro sprรกvu s kartami Endpoint Proxy, MCP, A2A a API Endpoints | -| ๐ŸŽš๏ธ **Pล™epรญnaฤe pro povolenรญ/zakรกzรกnรญ sluลพby** | Pล™epรญnaฤe ZAP/VYP pro MCP a A2A s trvalรฝm nastavenรญm (vรฝchozรญ: VYP) | -| ๐Ÿ›ฐ๏ธ **Srdeฤnรญ tep za bฤ›hu MCP** | Skuteฤnรฝ stav procesu (pid, doba provozuschopnosti, stรกล™รญ heartbeatu, transport, reลพim rozsahu) | -| ๐Ÿ“‹ **Auditnรญ zรกznam MCP** | Filtrovatelnรฉ protokoly auditu s hodnocenรญm รบspฤ›chu/neรบspฤ›chu a klรญฤovรฝm pล™iล™azenรญm | -| ๐Ÿ” **Vynucovรกnรญ rozsahu MCP** | 9 podrobnรฝch oprรกvnฤ›nรญ pro ล™รญzenรฝ pล™รญstup k nรกstrojลฏm | -| ๐Ÿ“ก **Sprรกva ลพivotnรญho cyklu รบkolลฏ A2A** | Seznam/filtrovรกnรญ รบloh, kontrola udรกlostรญ/artefaktลฏ, zruลกenรญ spuลกtฤ›nรฝch รบloh | -| ๐Ÿ“‹ **Objevenรญ karty agenta** | `/.well-known/agent.json` pro automatickรฉ vyhledรกvรกnรญ klientลฏ | -| ๐Ÿงช **Testovacรญ postroj Protocol E2E** | Skuteฤnรฉ MCP SDK + toky klientลฏ A2A v `test:protocols:e2e` | -| โš™๏ธ **Provoznรญ kontroly** | Kombinace pล™epรญnaฤลฏ, pouลพitรญ profilลฏ odolnosti, resetovรกnรญ jistiฤลฏ z jednoho ovlรกdacรญho panelu | +| Feature | What It Does | +| ------------------------------------ | ------------------------------------------------------------------------------------------- | +| โšก **Grok-4 Fast Family** | xAI models at $0.20/$0.50/M โ€” benchmarked 1143ms (30% faster than Gemini 2.5 Flash) | +| ๐Ÿง  **GLM-5 via Z.AI** | 128K output context, $0.5/1M โ€” newest flagship from the GLM family | +| ๐Ÿ”ฎ **MiniMax M2.5** | Reasoning + agentic tasks at $0.30/1M โ€” significant upgrade from M2.1 | +| ๐ŸŽฏ **toolCalling Flag per Model** | Per-model `toolCalling: true/false` in registry โ€” AutoCombo skips non-tool-capable models | +| ๐ŸŒ **Multilingual Intent Detection** | PT/ZH/ES/AR keywords in AutoCombo scoring โ€” better model selection for non-English content | +| ๐Ÿ“Š **Benchmark-Driven Fallbacks** | Real p95 latency from live requests feeds combo scoring โ€” AutoCombo learns from actual data | +| ๐Ÿ” **Request Deduplication** | Content-hash based dedup window โ€” multi-agent safe, prevents duplicate charges | +| ๐Ÿ”Œ **Pluggable RouterStrategy** | Extensible `RouterStrategy` interface โ€” add custom routing logic as plugins | -### ๐Ÿง  Smฤ›rovรกnรญ a inteligence +### ๐Ÿš€ Previous v2.0.9+ โ€” Playground, CLI Fingerprints & ACP -| Funkce | Co to dฤ›lรก | -| ----------------------------------------------- | ----------------------------------------------------------------------------- | -| ๐ŸŽฏ **Inteligentnรญ ฤtyล™รบrovลˆovรฝ zรกloลพnรญ systรฉm** | Automatickรก trasa: Pล™edplatnรฉ โ†’ API klรญฤ โ†’ Levnรฉ โ†’ Zdarma | -| ๐Ÿ“Š **Sledovรกnรญ kvรณt v reรกlnรฉm ฤase** | Poฤet tokenลฏ v reรกlnรฉm ฤase + odpoฤet resetovรกnรญ pro kaลพdรฉho poskytovatele | -| ๐Ÿ”„ **Pล™eklad formรกtu** | OpenAI โ†” Claude โ†” Gemini โ†” Odpovฤ›di s konverzemi bezpeฤnรฝmi pro schรฉma | -| ๐Ÿ‘ฅ **Podpora vรญce รบฤtลฏ** | Vรญce รบฤtลฏ na poskytovatele s inteligentnรญm vรฝbฤ›rem | -| ๐Ÿ”„ **Automatickรก aktualizace tokenลฏ** | Tokeny OAuth se automaticky obnovujรญ pล™i opakovanรฉm pokusu. | -| ๐ŸŽจ **Vlastnรญ kombinace** | 6 vyvaลพovacรญch strategiรญ + ล™รญzenรญ zรกloลพnรญho ล™etฤ›zce | -| ๐ŸŒ **Smฤ›rovaฤ se zรกstupnรฝmi znaky** | dynamickรฉ smฤ›rovรกnรญ `provider/*` | -| ๐Ÿง  **Pล™emรฝลกlenรญ o rozpoฤtovรฝch kontrolรกch** | Limity pro prลฏchozรญ, automatickรฉ, vlastnรญ a adaptivnรญ uvaลพovรกnรญ | -| ๐Ÿ”€ **Aliasy modelลฏ** | Vestavฤ›nรฉ + vlastnรญ aliasovรกnรญ modelลฏ a bezpeฤnost migrace | -| โšก **Degradace pozadรญ** | Smฤ›rujte รบlohy na pozadรญ s nรญzkou prioritou na levnฤ›jลกรญ modely | -| ๐Ÿงช **Chytrรฉ smฤ›rovรกnรญ s ohledem na รบkoly** | Automatickรฝ vรฝbฤ›r modelu podle typu obsahu (kรณdovรกnรญ/vize/analรฝza/sumarizace) | -| ๐Ÿ’ฌ **Vstล™ikovรกnรญ do systรฉmu** | Globรกlnรญ kontroly chovรกnรญ uplatลˆovanรฉ konzistentnฤ› | -| ๐Ÿ“„ **Kompatibilita API pro odpovฤ›di** | Plnรก podpora `/v1/responses` pro Codex a pokroฤilรฉ agentickรฉ pracovnรญ postupy | +| Feature | What It Does | +| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| ๐ŸŽฎ **Model Playground** | Dashboard page to test any model directly โ€” provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing | +| ๐Ÿ” **CLI Fingerprint Matching** | Per-provider header/body ordering to match native CLI signatures โ€” toggle per provider in Settings > Security. **Your proxy IP is preserved** | +| ๐Ÿค **ACP Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint | +| ๐Ÿค– **ACP Agents Dashboard** | Debug โ€บ Agents page โ€” grid of 14 agents with install status, version, custom agent form for any CLI tool. **OpenCode** users get a "Download opencode.json" button that auto-generates a ready-to-use config with all available models. | +| ๐Ÿ”ง **Custom Model `apiFormat` Routing** | Custom models with `apiFormat: "responses"` now correctly route to the Responses API translator | +| ๐Ÿข **Codex Workspace Isolation** | Multiple Codex workspaces per email โ€” OAuth correctly separates connections by workspace ID | +| ๐Ÿ”„ **Electron Auto-Update** | Desktop app checks for updates + auto-install on restart | -### ๐ŸŽต Multimodรกlnรญ API +### ๐Ÿค– Agent & Protocol Operations (v2.0) -| Funkce | Co to dฤ›lรก | -| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -| ๐Ÿ–ผ๏ธ **Generovรกnรญ obrรกzkลฏ** | `/v1/images/generations` s cloudovรฝm a lokรกlnรญm backendem | -| ๐Ÿ“ **Vloลพenรญ** | `/v1/embeddings` pro vyhledรกvรกnรญ a RAG pipelines | -| ๐ŸŽค **Pล™epis zvuku** | `/v1/audio/transcriptions` (Whisper a dalลกรญ poskytovatelรฉ) | -| ๐Ÿ”Š **Pล™evod textu na ล™eฤ** | `/v1/audio/speech` (vรญce enginลฏ/poskytovatelลฏ) | -| ๐ŸŽฌ **Generovรกnรญ videa** | `/v1/videos/generations` (pracovnรญ postupy ComfyUI + SD WebUI) | -| ๐ŸŽต **Hudebnรญ generace** | `/v1/music/generations` (pracovnรญ postupy ComfyUI) | -| ๐Ÿ›ก๏ธ **Moderovรกnรญ** | Bezpeฤnostnรญ kontroly `/v1/moderations` | -| ๐Ÿ”€ **Zmฤ›na poล™adรญ** | `/v1/rerank` pro hodnocenรญ relevance | -| ๐Ÿ” **Vyhledรกvรกnรญ na webu** ๐Ÿ†• | `/v1/search` โ€” 5 poskytovatelลฏ (Serper, Brave, Perplexity, Exa, Tavily), vรญce neลพ 6 500 zdarma/mฤ›sรญc, automatickรฉ pล™epnutรญ na zรกloลพnรญ systรฉm, mezipamฤ›ลฅ | +| Feature | What It Does | +| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| ๐Ÿ”ง **MCP Server (25 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools | +| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | +| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | +| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | +| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | +| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | +| ๐Ÿ” **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access | +| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | +| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | +| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | +| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | -### ๐Ÿ›ก๏ธ Odolnost, bezpeฤnost a sprรกva vฤ›cรญ veล™ejnรฝch +### ๐Ÿง  Routing & Intelligence -| Funkce | Co to dฤ›lรก | -| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | -| ๐Ÿ”Œ **Jistiฤe** | Vypnutรญ/obnovenรญ pro kaลพdรฝ model s ovlรกdรกnรญm prahovรฝch hodnot | -| ๐ŸŽฏ **Modely s ohledem na koncovรฉ body** | Vlastnรญ modely deklarujรญ podporovanรฉ koncovรฉ body + formรกt API | -| ๐Ÿ›ก๏ธ **Stรกdo proti hromลฏm** | Ochrana mutexu a semaforu pล™i udรกlostech opakovรกnรญ/rychlosti | -| ๐Ÿง  **Sรฉmantickรก + podpisovรก mezipamฤ›ลฅ** | Snรญลพenรญ nรกkladลฏ/latence dรญky dvฤ›ma vrstvรกm mezipamฤ›ti | -| โšก **ลฝรกdost o idempotenci** | Okno ochrany proti duplikacรญm | -| ๐Ÿ”’ **Falลกovรกnรญ otiskลฏ prstลฏ pomocรญ TLS** | Otisk TLS podobnรฝ prohlรญลพeฤi โ€“ **sniลพuje detekci botลฏ a nahlaลกovรกnรญ รบฤtลฏ** | -| ๐Ÿ” **Porovnรกvรกnรญ otiskลฏ prstลฏ v CLI** | Shoduje se s nativnรญmi podpisy poลพadavkลฏ CLI โ€“ **sniลพuje riziko zablokovรกnรญ a zรกroveลˆ zachovรกvรก IP adresu proxy** | -| ๐ŸŒ **Filtrovรกnรญ IP adres** | Ovlรกdรกnรญ seznamu povolenรฝch/blokovanรฝch poloลพek pro odhalenรก nasazenรญ | -| ๐Ÿ“Š **Upravitelnรฉ limity rychlosti** | Konfigurovatelnรฉ globรกlnรญ/na รบrovni poskytovatele limity s perzistencรญ | -| ๐Ÿ”‘ **Sprรกva klรญฤลฏ API a stanovenรญ rozsahu** | Bezpeฤnรฉ vydรกvรกnรญ/rotace klรญฤลฏ a kontroly modelu/poskytovatele | -| ๐Ÿ›ก๏ธ **Chrรกnฤ›nรฉ `/models`** | Volitelnรฉ ovฤ›ล™ovรกnรญ a skrytรญ poskytovatele pro katalog modelลฏ | +| Feature | What It Does | +| ---------------------------------- | ------------------------------------------------------------------------ | +| ๐ŸŽฏ **Smart 4-Tier Fallback** | Auto-route: Subscription โ†’ API Key โ†’ Cheap โ†’ Free | +| ๐Ÿ“Š **Real-Time Quota Tracking** | Live token count + reset countdown per provider | +| ๐Ÿ”„ **Format Translation** | OpenAI โ†” Claude โ†” Gemini โ†” Responses with schema-safe conversions | +| ๐Ÿ‘ฅ **Multi-Account Support** | Multiple accounts per provider with intelligent selection | +| ๐Ÿ”„ **Auto Token Refresh** | OAuth tokens refresh automatically with retry | +| ๐ŸŽจ **Custom Combos** | 9 balancing strategies + fallback chain control | +| ๐ŸŒ **Wildcard Router** | `provider/*` dynamic routing | +| ๐Ÿง  **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits | +| ๐Ÿ”€ **Model Aliases** | Built-in + custom model aliasing and migration safety | +| โšก **Background Degradation** | Route low-priority background tasks to cheaper models | +| ๐Ÿงช **Task-Aware Smart Routing** | Auto-select model by content type (coding/vision/analysis/summarization) | +| ๐Ÿ”„ **A2A Agent Workflows** | Deterministic FSM orchestrator for stateful multi-step agent executions | +| ๐Ÿ”€ **Adaptive Routing** | Dynamic strategy override based on token volume and prompt complexity | +| ๐ŸŽฒ **Provider Diversity** | Shannon entropy scoring balancing auto-combo traffic distribution | +| ๐Ÿ’ฌ **System Prompt Injection** | Global behavior controls applied consistently | +| ๐Ÿ“„ **Responses API Compatibility** | Full `/v1/responses` support for Codex and advanced agentic workflows | -### ๐Ÿ“Š Pozorovatelnost a analytika +### ๐ŸŽต Multi-Modal APIs -| Funkce | Co to dฤ›lรก | -| ----------------------------------- | ---------------------------------------------------------------------- | -| ๐Ÿ“ **ลฝรกdost + protokolovรกnรญ proxy** | รšplnรฉ protokolovรกnรญ poลพadavkลฏ/odpovฤ›dรญ a proxy | -| ๐Ÿ“‰ **Streamed Detailed Logs** ๐Ÿ†• | Reconstructs SSE payload streams cleanly into the UI | -| ๐Ÿ“‹ **Sjednocenรฝ panel protokolลฏ** | Zobrazenรญ poลพadavkลฏ, proxy, auditu a konzole na jednรฉ strรกnce | -| ๐Ÿ” **Vyลพรกdat si telemetrii** | Latence p50/p95/p99 a trasovรกnรญ poลพadavkลฏ | -| ๐Ÿฅ **Panel zdravรญ** | Doba provozuschopnosti, stavy jistiฤลฏ, uzamฤenรญ, statistiky mezipamฤ›ti | -| ๐Ÿ’ฐ **Sledovรกnรญ nรกkladลฏ** | Kontrola rozpoฤtu a pล™ehled o cenรกch pro jednotlivรฉ modely | -| ๐Ÿ“ˆ **Analytickรฉ vizualizace** | Pล™ehledy vyuลพitรญ modelลฏ/poskytovatelลฏ a zobrazenรญ trendลฏ | -| ๐Ÿงช **Rรกmec hodnocenรญ** | Testovรกnรญ zlatรฉ sady s konfigurovatelnรฝmi strategiemi shody | +| Feature | What It Does | +| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| ๐Ÿ–ผ๏ธ **Image Generation** | `/v1/images/generations` with cloud and local backends | +| ๐Ÿ“ **Embeddings** | `/v1/embeddings` for search and RAG pipelines | +| ๐ŸŽค **Audio Transcription** | `/v1/audio/transcriptions` โ€” 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support | +| ๐Ÿ”Š **Text-to-Speech** | `/v1/audio/speech` โ€” 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) with correct error messages | +| ๐ŸŽฌ **Video Generation** | `/v1/videos/generations` (ComfyUI + SD WebUI workflows) | +| ๐ŸŽต **Music Generation** | `/v1/music/generations` (ComfyUI workflows) | +| ๐Ÿ›ก๏ธ **Moderations** | `/v1/moderations` safety checks | +| ๐Ÿ”€ **Reranking** | `/v1/rerank` for relevance scoring | +| ๐Ÿ” **Web Search** ๐Ÿ†• | `/v1/search` โ€” 5 providers (Serper, Brave, Perplexity, Exa, Tavily), 6,500+ free/month, auto-failover, cache | -### โ˜๏ธ Nasazenรญ a platforma +### ๐Ÿ›ก๏ธ Resilience, Security & Governance -| Funkce | Co to dฤ›lรก | -| ----------------------------------------------- | ------------------------------------------------------------------------- | -| ๐ŸŒ **Nasazenรญ kdekoli** | Localhost, VPS, Docker, cloudovรก prostล™edรญ | -| ๐Ÿ’พ **Synchronizace s cloudem** | Synchronizace konfigurace pล™es cloud worker | -| ๐Ÿ”„ **Zรกlohovรกnรญ/Obnovenรญ** | Toky exportu/importu a obnovy po havรกrii | -| ๐Ÿง™ **Prลฏvodce nรกstupem** | Prลฏvodce prvnรญm spuลกtฤ›nรญm | -| ๐Ÿ”ง **Panel nรกstrojลฏ CLI** | Nastavenรญ oblรญbenรฝch kรณdovacรญch nรกstrojลฏ jednรญm kliknutรญm | -| ๐ŸŽฎ **Modelovรฉ hล™iลกtฤ›** | Otestujte libovolnรฉho poskytovatele/model/koncovรฝ bod z ล™รญdicรญho panelu | -| ๐Ÿ” **Pล™epรญnaฤ otiskลฏ prstลฏ v pล™รญkazovรฉm ล™รกdku** | Porovnรกvรกnรญ otiskลฏ prstลฏ podle poskytovatele v Nastavenรญ > Zabezpeฤenรญ | -| ๐ŸŒ **i18n (30 jazykลฏ)** | Plnรก jazykovรก podpora dashboardu a dokumentace s psanรญm zprava doleva | -| ๐Ÿงน **Clear All Models** | One-click model list clearing in provider details | -| ๐Ÿ‘๏ธ **Sidebar Controls** ๐Ÿ†• | Hide components and integrations from Appearance Settings | -| ๐Ÿ“‹ **Issue Templates** | Standardized GitHub templates for bugs and features | -| ๐Ÿ“‚ **Adresรกล™ vlastnรญch dat** | Pล™epsรกnรญ `DATA_DIR` pro umรญstฤ›nรญ รบloลพiลกtฤ› | +| Feature | What It Does | +| ----------------------------------- | -------------------------------------------------------------------------------------- | +| ๐Ÿ”Œ **Circuit Breakers** | Per-model trip/recover with threshold controls | +| ๐ŸŽฏ **Endpoint-Aware Models** | Custom models declare supported endpoints + API format | +| ๐Ÿ›ก๏ธ **Anti-Thundering Herd** | Mutex + semaphore protections on retry/rate events | +| ๐Ÿง  **Semantic + Signature Cache** | Cost/latency reduction with two cache layers | +| โšก **Request Idempotency** | Duplicate protection window | +| ๐Ÿ”’ **TLS Fingerprint Spoofing** | Browser-like TLS fingerprint โ€” **reduces bot detection and account flagging** | +| ๐Ÿ” **CLI Fingerprint Matching** | Matches native CLI request signatures โ€” **reduces ban risk while preserving proxy IP** | +| ๐ŸŒ **IP Filtering** | Allowlist/blocklist control for exposed deployments | +| ๐Ÿ“Š **Editable Rate Limits** | Configurable global/provider-level limits with persistence | +| ๐Ÿ“‰ **Graceful Degradation** | Multi-layer capability fallbacks protecting core gateway operations | +| ๐Ÿ“œ **Config Audit Trail** | Diff-based change tracking preventing operational drift with simple rollbacks | +| โณ **Provider Health Sync** | Proactive token expiration monitoring triggering alerts before authorization failures | +| ๐Ÿšช **Auto-Disable Banned Accounts** | Operational circuit breaker sealing permanently blocked token accounts automatically | +| ๐Ÿ”‘ **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls | +| ๐Ÿ‘๏ธ **Scoped API Key Reveal** ๐Ÿ†• | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` | +| ๐Ÿ›ก๏ธ **Protected `/models`** | Optional auth gating and provider hiding for model catalog | -### Hlubokรฝ pohled na funkce +### ๐Ÿ“Š Observability & Analytics -#### Chytrรก zรกloลพnรญ funkce s praktickou kontrolou nรกkladลฏ +| Feature | What It Does | +| -------------------------------- | ----------------------------------------------------- | +| ๐Ÿ“ **Request + Proxy Logging** | Full request/response and proxy logging | +| ๐Ÿ“‰ **Streamed Detailed Logs** ๐Ÿ†• | Reconstructs SSE payload streams cleanly into the UI | +| ๐Ÿ“‹ **Unified Logs Dashboard** | Request, proxy, audit, and console views in one page | +| ๐Ÿ” **Request Telemetry** | p50/p95/p99 latency and request tracing | +| ๐Ÿฅ **Health Dashboard** | Uptime, breaker states, lockouts, cache stats | +| ๐Ÿ’ฐ **Cost Tracking** | Budget controls and per-model pricing visibility | +| ๐Ÿ“ˆ **Analytics Visualizations** | Model/provider usage insights and trend views | +| ๐Ÿงช **Evaluation Framework** | Golden set testing with configurable match strategies | +| ๐Ÿ“ก **Live Diagnostics** ๐Ÿ†• | Semantic cache bypass for accurate combo live testing | + +### โ˜๏ธ Deployment & Platform + +| Feature | What It Does | +| ------------------------------ | --------------------------------------------------------------------- | +| ๐ŸŒ **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments | +| ๐Ÿš‡ **Cloudflare Tunnel** ๐Ÿ†• | One-click Quick Tunnel integration from the dashboard | +| ๐Ÿ”‘ **API Key Model Filtering** | Native /v1/models response filtered via assigned Bearer context roles | +| โšก **Smart Cache Bypass** | Configurable TTL heuristics and forced refetch controls | +| ๐Ÿ”„ **Backup/Restore** | Export/import and disaster recovery flows | +| ๐Ÿง™ **Onboarding Wizard** | First-run guided setup | +| ๐Ÿ”ง **CLI Tools Dashboard** | One-click setup for popular coding tools | +| ๐ŸŽฎ **Model Playground** | Test any provider/model/endpoint from the dashboard | +| ๐Ÿ” **CLI Fingerprint Toggle** | Per-provider fingerprint matching in Settings > Security | +| ๐ŸŒ **i18n (30 languages)** | Full dashboard + docs language support with RTL coverage | +| ๐Ÿงน **Clear All Models** | One-click model list clearing in provider details | +| ๐Ÿ‘๏ธ **Sidebar Controls** ๐Ÿ†• | Hide components and integrations from Appearance Settings | +| ๐Ÿ“‹ **Issue Templates** | Standardized GitHub templates for bugs and features | +| ๐Ÿ“‚ **Custom Data Directory** | `DATA_DIR` override for storage location | + +### Feature Deep Dive + +#### Smart fallback with practical cost control ```txt Combo: "my-coding-stack" @@ -1086,91 +1442,91 @@ Combo: "my-coding-stack" 4. if/kimi-k2-thinking ``` -Kdyลพ selลพe kvรณta, rychlost nebo stav, OmniRoute automaticky pล™ejde k dalลกรญmu kandidรกtovi bez nutnosti ruฤnรญho pล™epรญnรกnรญ. +When quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching. -#### Sprรกva protokolลฏ, kterรก je viditelnรก a ovladatelnรก +#### Protocol management that is visible and operable -- MCP + A2A jsou viditelnรฉ v uลพivatelskรฉm rozhranรญ a dokumentaci (nejsou skrytรฉ) -- API pro stav protokolu zpล™รญstupลˆujรญ ลพivรก provoznรญ data ( `/api/mcp/*` , `/api/a2a/*` ) -- Dashboardy zahrnujรญ akce pro operace 2. dne (pล™epรญnรกnรญ kombinacรญ, resetovรกnรญ jistiฤลฏ, zruลกenรญ รบkolลฏ) +- MCP + A2A are discoverable in UI and docs (not hidden) +- Protocol status APIs expose live operational data (`/api/mcp/*`, `/api/a2a/*`) +- Dashboards include actions for day-2 ops (combo toggles, breaker resets, task cancellation) -#### Pracovnรญ postup pล™ekladatele + validace +#### Translator + validation workflow -Oblast pล™ekladatele zahrnuje: +The Translator area includes: -- **Hล™iลกtฤ›** : kontroly transformace poลพadavkลฏ -- **Tester chatu** : kompletnรญ okruลพnรญ cesta poลพadavku/odpovฤ›di -- **Testovacรญ stolice** : vรญce pล™รญpadลฏ v jednom bฤ›hu -- **ลฝivรฝ monitor** : zobrazenรญ provozu v reรกlnรฉm ฤase +- **Playground**: request transformation checks +- **Chat Tester**: full request/response round-trip +- **Test Bench**: multiple cases in one run +- **Live Monitor**: real-time traffic view -Plus validace protokolu se skuteฤnรฝmi klienty pomocรญ `npm run test:protocols:e2e` . +Plus protocol validation with real clients via `npm run test:protocols:e2e`. -> ๐Ÿ“– **[Soubor README pro MCP Server](open-sse/mcp-server/README.md)** โ€” Referenฤnรญ informace o nรกstrojรญch, konfigurace IDE a pล™รญklady klientลฏ +> ๐Ÿ“– **[MCP Server README](open-sse/mcp-server/README.md)** โ€” Tool reference, IDE configs, and client examples > -> ๐Ÿ“– **[Soubor README pro A2A Server](src/lib/a2a/README.md)** โ€” Dovednosti, metody JSON-RPC, streamovรกnรญ a ลพivotnรญ cyklus รบloh +> ๐Ÿ“– **[A2A Server README](src/lib/a2a/README.md)** โ€” Skills, JSON-RPC methods, streaming, and task lifecycle -## ๐Ÿงช Hodnocenรญ (Evals) +## ๐Ÿงช Evaluations (Evals) -OmniRoute obsahuje vestavฤ›nรฝ hodnotรญcรญ rรกmec pro testovรกnรญ kvality odpovฤ›dรญ LLM v porovnรกnรญ se zlatou sadou. Pล™รญstup k nฤ›mu je moลพnรฝ pล™es **Analรฝzy โ†’ Hodnocenรญ** v dashboardu. +OmniRoute includes a built-in evaluation framework to test LLM response quality against a golden set. Access it via **Analytics โ†’ Evals** in the dashboard. -### Vestavฤ›nรก zlatรก sada +### Built-in Golden Set -Pล™edinstalovanรก sada โ€žOmniRoute Golden Setโ€œ obsahuje testovacรญ pล™รญpady pro: +The pre-loaded "OmniRoute Golden Set" contains test cases for: -- Zdravรญm, matematika, zemฤ›pis, generovรกnรญ kรณdu -- Shoda s formรกtem JSON, pล™eklad, generovรกnรญ markdownลฏ -- Bezpeฤnostnรญ odmรญtnutรญ (ลกkodlivรฝ obsah), poฤรญtรกnรญ, booleovskรก logika +- Greetings, math, geography, code generation +- JSON format compliance, translation, markdown generation +- Safety refusal (harmful content), counting, boolean logic -### Strategie hodnocenรญ +### Evaluation Strategies -| Strategie | Popis | Pล™รญklad | -| ---------- | ------------------------------------------------------------------------ | -------------------------------- | -| `exact` | Vรฝstup se musรญ pล™esnฤ› shodovat | `"4"` | -| `contains` | Vรฝstup musรญ obsahovat podล™etฤ›zec (bez rozliลกenรญ velkรฝch a malรฝch pรญsmen) | `"Paris"` | -| `regex` | Vรฝstup musรญ odpovรญdat vzoru regulรกrnรญch vรฝrazลฏ | `"1.*2.*3"` | -| `custom` | Vlastnรญ JS funkce vracรญ true/false | `(output) => output.length > 10` | +| Strategy | Description | Example | +| ---------- | ------------------------------------------------ | -------------------------------- | +| `exact` | Output must match exactly | `"4"` | +| `contains` | Output must contain substring (case-insensitive) | `"Paris"` | +| `regex` | Output must match regex pattern | `"1.*2.*3"` | +| `custom` | Custom JS function returns true/false | `(output) => output.length > 10` | --- -## ๐Ÿ“– Prลฏvodce nastavenรญm +## ๐Ÿ“– Setup Guide -### Nastavenรญ protokolu (MCP + A2A) +### Protocol Setup (MCP + A2A)
-๐Ÿงฉ Nastavenรญ MCP (Model Context Protocol) -
+๐Ÿงฉ MCP Setup (Model Context Protocol) -Spuลกtฤ›nรญ MCP transportu v reลพimu stdio: +Start MCP transport in stdio mode: ```bash omniroute --mcp ``` -Doporuฤenรฝ postup ovฤ›ล™enรญ: +Recommended validation flow: -1. Pล™ipojte svรฉho MCP klienta pล™es stdio. -2. Spusลฅte `omniroute_get_health` . -3. Spusลฅte `omniroute_list_combos` . -4. Otevล™ete `/dashboard/mcp` pro ovฤ›ล™enรญ prezenฤnรญho signรกlu, aktivity a auditu. +1. Connect your MCP client over stdio. +2. Run `omniroute_get_health`. +3. Run `omniroute_list_combos`. +4. Open `/dashboard/mcp` to confirm heartbeat, activity, and audit. -Uลพiteฤnรก API pro automatizaci: +Useful APIs for automation: - `GET /api/mcp/status` - `GET /api/mcp/tools` - `GET /api/mcp/audit` - `GET /api/mcp/audit/stats` -
-๐Ÿค Nastavenรญ A2A (Agent2Agent)
-Objevte agenta: +
+๐Ÿค A2A Setup (Agent2Agent) + +Discover the agent: ```bash curl http://localhost:20128/.well-known/agent.json ``` -Odeslat รบkol: +Send a task: ```bash curl -X POST http://localhost:20128/a2a \ @@ -1178,36 +1534,38 @@ curl -X POST http://localhost:20128/a2a \ -d '{"jsonrpc":"2.0","id":"setup-a2a","method":"message/send","params":{"skill":"quota-management","messages":[{"role":"user","content":"Summarize quota status."}]}}' ``` -Sprรกva ลพivotnรญho cyklu: +Manage lifecycle: - `GET /api/a2a/status` - `GET /api/a2a/tasks` - `GET /api/a2a/tasks/:id` - `POST /api/a2a/tasks/:id/cancel` -Provoznรญ uลพivatelskรฉ rozhranรญ: +Operational UI: -- `/dashboard/a2a` pro pozorovatelnost รบloh/stavลฏ/streamลฏ a akce kouล™enรญ +- `/dashboard/a2a` for task/state/stream observability and smoke actions -
-๐Ÿงช Komplexnรญ validace protokolu
-Ovฤ›ล™te oba protokoly se skuteฤnรฝmi klienty: +
+๐Ÿงช End-to-end protocol validation + +Validate both protocols with real clients: ```bash npm run test:protocols:e2e ``` -Tรญm se ovฤ›ล™uje: +This verifies: -- Pล™ipojenรญ/seznam/volรกnรญ klienta MCP SDK -- A2A objevovรกnรญ/odesรญlรกnรญ/streamovรกnรญ/zรญskรกvรกnรญ/zruลกenรญ -- Kล™รญลพovรก kontrola dat v auditu MCP a API pro sprรกvu รบloh A2A +- MCP SDK client connect/list/call +- A2A discovery/send/stream/get/cancel +- Cross-check data in MCP audit and A2A task management APIs + +
-๐Ÿ’ณ Poskytovatelรฉ pล™edplatnรฉho -
+๐Ÿ’ณ Subscription Providers ### Claude Code (Pro/Max) @@ -1222,7 +1580,7 @@ Models: cc/claude-haiku-4-5-20251001 ``` -**Tip pro profesionรกly:** Pro sloลพitรฉ รบkoly pouลพรญvejte Opus, pro rychlost Sonnet. OmniRoute sleduje kvรณtu pro kaลพdรฝ model! +**Pro Tip:** Use Opus for complex tasks, Sonnet for speed. OmniRoute tracks quota per model! ### OpenAI Codex (Plus/Pro) @@ -1236,24 +1594,24 @@ Models: cx/gpt-5.1-codex-max ``` -#### Sprรกva limitลฏ รบฤtu Codex (5h + tรฝdnฤ›) +#### Codex Account Limit Management (5h + Weekly) -Kaลพdรฝ รบฤet Codex mรก nynรญ pล™epรญnaฤe zรกsad v `Dashboard -> Providers` : +Each Codex account now has policy toggles in `Dashboard -> Providers`: -- `5h` (ZAP/VYP): vynutit politiku 5hodinovรฉho prahu okna. -- `Weekly` (ZAP/VYP): vynutit zรกsadu tรฝdennรญho prahu okna. -- Prahovรฉ chovรกnรญ: kdyลพ povolenรฉ okno dosรกhne vyuลพitรญ >=90 %, je danรฝ รบฤet pล™eskoฤen. -- Chovรกnรญ rotace: OmniRoute automaticky pล™esmฤ›ruje na dalลกรญ zpลฏsobilรฝ รบฤet Codex. -- Chovรกnรญ pล™i resetovรกnรญ: Po `resetAt` urฤitรฉ doby se รบฤet automaticky opฤ›t stane zpลฏsobilรฝm. +- `5h` (ON/OFF): enforce the 5-hour window threshold policy. +- `Weekly` (ON/OFF): enforce the weekly window threshold policy. +- Threshold behavior: when an enabled window reaches >=90% usage, that account is skipped. +- Rotation behavior: OmniRoute routes to the next eligible Codex account automatically. +- Reset behavior: when the provider `resetAt` time passes, the account becomes eligible again automatically. -Scรฉnรกล™e: +Scenarios: -- `5h ON` + `Weekly ON` : รบฤet je pล™eskoฤen, kdyลพ kterรฉkoli z oken dosรกhne prahovรฉ hodnoty. -- `5h OFF` + `Weekly ON` : รบฤet mลฏลพe bรฝt zablokovรกn pouze tรฝdennรญm pouลพรญvรกnรญm. -- `5h ON` + `Weekly OFF` : รบฤet mลฏลพe bรฝt zablokovรกn pouze pล™i 5hodinovรฉm pouลพรญvรกnรญ. -- `resetAt` passed: รบฤet se automaticky znovu zapne (bez ruฤnรญho opฤ›tovnรฉho povolenรญ). +- `5h ON` + `Weekly ON`: account is skipped when either window reaches threshold. +- `5h OFF` + `Weekly ON`: only weekly usage can block the account. +- `5h ON` + `Weekly OFF`: only 5-hour usage can block the account. +- `resetAt` passed: account re-enters rotation automatically (no manual re-enable). -### Gemini CLI (ZDARMA 180 000/mฤ›sรญc!) +### Gemini CLI (FREE 180K/month!) ```bash Dashboard โ†’ Providers โ†’ Connect Gemini CLI @@ -1265,7 +1623,7 @@ Models: gc/gemini-2.5-pro ``` -**Nejlepลกรญ hodnota:** Obrovskรก bezplatnรก รบroveลˆ! Pouลพijte ji pล™ed placenรฝmi รบrovnฤ›mi. +**Best Value:** Huge free tier! Use this before paid tiers. ### GitHub Copilot @@ -1280,88 +1638,93 @@ Models: gh/gemini-3-pro ``` -
-๐Ÿ”‘ Poskytovatelรฉ klรญฤลฏ API
-### NVIDIA NIM (BEZPLATNร pล™รญstup pro vรฝvojรกล™e โ€” vรญce neลพ 70 modelลฏ) - -1. Registrace: [build.nvidia.com](https://build.nvidia.com) -2. Zรญskejte zdarma klรญฤ API (vฤetnฤ› 1000 inferenฤnรญch kreditลฏ) -3. Ovlรกdacรญ panel โ†’ Pล™idat poskytovatele โ†’ NVIDIA NIM: - - Klรญฤ API: `nvapi-your-key` - -**Modely:** `nvidia/llama-3.3-70b-instruct` , `nvidia/mistral-7b-instruct` a vรญce neลพ 50 dalลกรญch - -**Tip pro profesionรกly:** API kompatibilnรญ s OpenAI โ€“ funguje bez problรฉmลฏ s pล™ekladem formรกtลฏ OmniRoute! - -### Hlubokรฉ vyhledรกvรกnรญ - -1. Registrace: [platform.deepseek.com](https://platform.deepseek.com) -2. Zรญskat klรญฤ API -3. Ovlรกdacรญ panel โ†’ Pล™idat poskytovatele โ†’ DeepSeek - -**Modely:** `deepseek/deepseek-chat` , `deepseek/deepseek-coder` - -### Groq (k dispozici je bezplatnรก รบroveลˆ!) - -1. Registrace: [console.groq.com](https://console.groq.com) -2. Zรญskejte klรญฤ API (vฤetnฤ› bezplatnรฉ รบrovnฤ›) -3. Ovlรกdacรญ panel โ†’ Pล™idat poskytovatele โ†’ Groq - -**Modely:** `groq/llama-3.3-70b` , `groq/mixtral-8x7b` - -**Tip pro profesionรกly:** Ultrarychlรก inference โ€“ nejlepลกรญ pro kรณdovรกnรญ v reรกlnรฉm ฤase! - -### OpenRouter (100+ modelลฏ) - -1. Registrace: [openrouter.ai](https://openrouter.ai) -2. Zรญskat klรญฤ API -3. Ovlรกdacรญ panel โ†’ Pล™idat poskytovatele โ†’ OpenRouter - -**Modely:** Zรญskejte pล™รญstup k vรญce neลพ 100 modelลฏm od vลกech hlavnรญch poskytovatelลฏ prostล™ednictvรญm jedinรฉho klรญฤe API. -
-๐Ÿ’ฐ Levnรญ poskytovatelรฉ (zรกloลพnรญ) +๐Ÿ”‘ API Key Providers + +### NVIDIA NIM (FREE developer access โ€” 70+ models) + +1. Sign up: [build.nvidia.com](https://build.nvidia.com) +2. Get free API key (1000 inference credits included) +3. Dashboard โ†’ Add Provider โ†’ NVIDIA NIM: + - API Key: `nvapi-your-key` + +**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more + +**Pro Tip:** OpenAI-compatible API โ€” works seamlessly with OmniRoute's format translation! + +### DeepSeek + +1. Sign up: [platform.deepseek.com](https://platform.deepseek.com) +2. Get API key +3. Dashboard โ†’ Add Provider โ†’ DeepSeek + +**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` + +### Groq (Free Tier Available!) + +1. Sign up: [console.groq.com](https://console.groq.com) +2. Get API key (free tier included) +3. Dashboard โ†’ Add Provider โ†’ Groq + +**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` + +**Pro Tip:** Ultra-fast inference โ€” best for real-time coding! + +### OpenRouter (100+ Models) + +1. Sign up: [openrouter.ai](https://openrouter.ai) +2. Get API key +3. Dashboard โ†’ Add Provider โ†’ OpenRouter + +**Models:** Access 100+ models from all major providers through a single API key. + +**Dashboard behavior:** OpenRouter models are managed from **Available Models**. Manual add, import, and auto-sync all update the same list. +
-### GLM-4.7 (Dennรญ reset, 0,6 USD/1 milion) - -1. Registrace: [Zhipu AI](https://open.bigmodel.cn/) -2. Zรญskejte klรญฤ API z kรณdovacรญho plรกnu -3. Nรกstฤ›nka โ†’ Pล™idat klรญฤ API: - - Poskytovatel: `glm` - - Klรญฤ API: `your-key` - -**Pouลพitรญ:** `glm/glm-4.7` - -**Tip pro profesionรกly:** Programovacรญ plรกn nabรญzรญ 3ร— kvรณtu za cenu 1/7! Obnovuje se dennฤ› v 10:00. - -### MiniMax M2.1 (5h reset, 0,20 $/1 milion) - -1. Registrace: [MiniMax](https://www.minimax.io/) -2. Zรญskat klรญฤ API -3. Nรกstฤ›nka โ†’ Pล™idat klรญฤ API - -**Pouลพitรญ:** `minimax/MiniMax-M2.1` - -**Tip pro profesionรกly:** Nejlevnฤ›jลกรญ varianta pro dlouhรฝ kontext (1 milion tokenลฏ)! - -### Kimi K2 (pauลกรกlnรญ poplatek 9 dolarลฏ mฤ›sรญฤnฤ›) - -1. Odebรญrat: [Moonshot AI](https://platform.moonshot.ai/) -2. Zรญskat klรญฤ API -3. Nรกstฤ›nka โ†’ Pล™idat klรญฤ API - -**Pouลพitรญ:** `kimi/kimi-latest` - -**Tip pro profesionรกly:** Fixnรญch 9 $/mฤ›sรญc za 10 milionลฏ tokenลฏ = efektivnรญ nรกklady 0,90 $/1 milion! -
-๐Ÿ†“ BEZPLATNร poskytovatelรฉ (nouzovรฉ zรกlohovรกnรญ) +๐Ÿ’ฐ Cheap Providers (Backup) + +### 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 +3. 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 +3. Dashboard โ†’ Add API Key + +**Use:** `kimi/kimi-latest` + +**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost! +
-### Qoder (5 BEZPLATNรCH modelลฏ pล™es OAuth) +
+๐Ÿ†“ FREE Providers (Emergency Backup) + +### Qoder (5 FREE models via OAuth) ```bash Dashboard โ†’ Connect Qoder @@ -1376,7 +1739,7 @@ Models: if/deepseek-r1 ``` -### Qwen (4 modely ZDARMA s kรณdem zaล™รญzenรญ) +### Qwen (4 FREE models via Device Code) ```bash Dashboard โ†’ Connect Qwen @@ -1388,7 +1751,7 @@ Models: qw/qwen3-coder-flash ``` -### Kiro (Claude ZDARMA) +### Kiro (Claude FREE) ```bash Dashboard โ†’ Connect Kiro @@ -1400,11 +1763,12 @@ Models: kr/claude-haiku-4.5 ``` -
-๐ŸŽจ Vytvoล™te kombinace
-### Pล™รญklad 1: Maximalizace pล™edplatnรฉho โ†’ Levnรฉ zรกlohovรกnรญ +
+๐ŸŽจ Create Combos + +### Example 1: Maximize Subscription โ†’ Cheap Backup ``` Dashboard โ†’ Combos โ†’ Create New @@ -1418,7 +1782,7 @@ Models: Use in CLI: premium-coding ``` -### Pล™รญklad 2: Pouze zdarma (nulovรฉ nรกklady) +### Example 2: Free-Only (Zero Cost) ``` Name: free-combo @@ -1430,11 +1794,12 @@ Models: Cost: $0 forever! ``` -
-๐Ÿ”ง Integrace s rozhranรญm pล™รญkazovรฉho ล™รกdku
-### IDE kurzoru +
+๐Ÿ”ง CLI Integration + +### Cursor IDE ``` Settings โ†’ Models โ†’ Advanced: @@ -1445,7 +1810,7 @@ Settings โ†’ Models โ†’ Advanced: ### Claude Code -Pro konfiguraci jednรญm kliknutรญm pouลพijte strรกnku **Nรกstroje CLI** na ล™รญdicรญm panelu nebo ruฤnฤ› upravte soubor `~/.claude/settings.json` . +Use the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually. ### Codex CLI @@ -1458,13 +1823,13 @@ codex "your prompt" ### OpenClaw -**Moลพnost 1 โ€“ Dashboard (doporuฤeno):** +**Option 1 โ€” Dashboard (recommended):** ``` Dashboard โ†’ CLI Tools โ†’ OpenClaw โ†’ Select Model โ†’ Apply ``` -**Moลพnost 2 โ€“ Manuรกlnรญ รบprava:** รšprava `~/.openclaw/openclaw.json` : +**Option 2 โ€” Manual:** Edit `~/.openclaw/openclaw.json`: ```json { @@ -1480,9 +1845,9 @@ Dashboard โ†’ CLI Tools โ†’ OpenClaw โ†’ Select Model โ†’ Apply } ``` -> **Poznรกmka:** OpenClaw funguje pouze s lokรกlnรญm OmniRoute. Mรญsto `localhost` pouลพijte `127.0.0.1` , abyste se vyhnuli problรฉmลฏm s rozliลกenรญm IPv6. +> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues. -### Cline / Pokraฤovat / RooCode +### Cline / Continue / RooCode ``` Settings โ†’ API Configuration: @@ -1494,7 +1859,7 @@ Settings โ†’ API Configuration: ### OpenCode -**Krok 1:** Pล™idรกnรญ OmniRoute jako vlastnรญho poskytovatele: +**Step 1:** Add OmniRoute as a custom provider: ```bash opencode @@ -1502,7 +1867,7 @@ opencode # Select "Other" โ†’ Enter ID: "omniroute" โ†’ Enter your OmniRoute API key ``` -**Krok 2:** Vytvoล™te/upravte `opencode.json` v koล™enovรฉm adresรกล™i projektu: +**Step 2:** Create/edit `opencode.json` in your project root: ```json { @@ -1524,121 +1889,126 @@ opencode } ``` -**Krok 3:** Vyberte model v OpenCode: +**Step 3:** Select the model in OpenCode: ```bash /models # Select any OmniRoute model from the list ``` -> **Tip:** Do sekce `models` pล™idejte jakรฝkoli model dostupnรฝ ve vaลกem koncovรฉm bodu OmniRoute `/v1/models` . Pouลพijte formรกt `provider/model-id` z vaลกeho dashboardu OmniRoute. +> **Tip:** Add any model available in your OmniRoute `/v1/models` endpoint to the `models` section. Use the format `provider/model-id` from your OmniRoute dashboard. + +
--- -## ๐Ÿ› ล˜eลกenรญ problรฉmลฏ +## ล˜eลกenรญ problรฉmลฏ
-Kliknutรญm rozbalรญte prลฏvodce ล™eลกenรญm problรฉmลฏ -
+Click to expand troubleshooting guide -**"Jazykovรฝ model neposkytoval zprรกvy"** +**"Language model did not provide messages"** -- Kvรณta poskytovatele vyฤerpรกna โ†’ Zkontrolujte sledovรกnรญ kvรณt na ล™รญdicรญm panelu -- ล˜eลกenรญ: Pouลพijte zรกloลพnรญ kombinovanou variantu nebo pล™ejdฤ›te na levnฤ›jลกรญ รบroveลˆ +- Provider quota exhausted โ†’ Check dashboard quota tracker +- Solution: Use combo fallback or switch to cheaper tier -**Omezenรญ rychlosti** +**Rate limiting** -- Kvรณta pล™edplatnรฉho vyฤerpรกna โ†’ Pล™echod na GLM/MiniMax -- Pล™idat kombo: `cc/claude-opus-4-6 โ†’ glm/glm-4.7 โ†’ if/kimi-k2-thinking` +- Subscription quota out โ†’ Fallback to GLM/MiniMax +- Add combo: `cc/claude-opus-4-6 โ†’ glm/glm-4.7 โ†’ if/kimi-k2-thinking` -**Platnost tokenu OAuth vyprลกela** +**OAuth token expired** -- Automaticky aktualizovรกno sluลพbou OmniRoute -- Pokud problรฉmy pล™etrvรกvajรญ: Ovlรกdacรญ panel โ†’ Poskytovatel โ†’ Znovu pล™ipojit +- Auto-refreshed by OmniRoute +- If issues persist: Dashboard โ†’ Provider โ†’ Reconnect -**Vysokรฉ nรกklady** +**High costs** -- Zkontrolujte statistiky vyuลพitรญ v sekci Nรกstฤ›nka โ†’ Nรกklady -- Pล™epnout primรกrnรญ model na GLM/MiniMax -- Pro nekritickรฉ รบlohy pouลพijte bezplatnou รบroveลˆ (Gemini CLI, Qoder). +- Check usage stats in Dashboard โ†’ Costs +- Switch primary model to GLM/MiniMax +- Use free tier (Gemini CLI, Qoder) for non-critical tasks -**Porty ล™รญdicรญho panelu/API jsou nesprรกvnรฉ** +**Dashboard/API ports are wrong** -- `PORT` je kanonickรฝ zรกkladnรญ port (a standardnฤ› port API) -- `API_PORT` pล™episuje pouze posluchaฤ API kompatibilnรญ s OpenAI. -- `DASHBOARD_PORT` pล™episuje pouze posluchaฤ dashboard/Next.js -- Nastavte `NEXT_PUBLIC_BASE_URL` na vaลกi veล™ejnou URL adresu ล™รญdicรญho panelu (pro zpฤ›tnรก volรกnรญ OAuth) +- `PORT` is the canonical base port (and API port by default) +- `API_PORT` overrides only OpenAI-compatible API listener +- `DASHBOARD_PORT` overrides only dashboard/Next.js listener +- Set `NEXT_PUBLIC_BASE_URL` to your dashboard/public URL (for OAuth callbacks) -**Chyby synchronizace s cloudem** +**Cloud sync errors** -- Ovฤ›ล™te, zda `BASE_URL` odkazuje na vaลกi spuลกtฤ›nou instanci. -- Ovฤ›ล™te, zda `CLOUD_URL` odkazuje na vรกลก oฤekรกvanรฝ cloudovรฝ koncovรฝ bod. -- Udrลพujte hodnoty `NEXT_PUBLIC_*` v souladu s hodnotami na stranฤ› serveru. +- Verify `BASE_URL` points to your running instance +- Verify `CLOUD_URL` points to your expected cloud endpoint +- Keep `NEXT_PUBLIC_*` values aligned with server-side values -**Prvnรญ pล™ihlรกลกenรญ nefunguje** +**First login not working** -- Zkontrolujte `INITIAL_PASSWORD` v souboru `.env` -- Pokud nenรญ nastaveno, zรกloลพnรญ heslo je `123456` +- Check `INITIAL_PASSWORD` in `.env` +- If unset, fallback password is `123456` -**ลฝรกdnรฉ protokoly poลพadavkลฏ** +**No request logs** -- Nastavte `ENABLE_REQUEST_LOGS=true` v `.env` +- Request artifacts are written to `DATA_DIR/call_logs/` as one JSON file per request +- Enable pipeline capture from Dashboard โ†’ Logs โ†’ Request Logs if you need detailed per-stage payloads +- Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log` +- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed -**Test pล™ipojenรญ ukazuje โ€žNeplatnรฉโ€œ pro poskytovatele kompatibilnรญ s OpenAI** +**Connection test shows "Invalid" for OpenAI-compatible providers** -- Mnoho poskytovatelลฏ nezpล™รญstupลˆuje koncovรฝ bod `/models` -- OmniRoute v1.0.6+ zahrnuje zรกloลพnรญ ovฤ›ล™enรญ pomocรญ dokonฤenรญ chatu -- Zajistฤ›te, aby zรกkladnรญ URL adresa obsahovala pล™รญponu `/v1` +- Many providers don't expose a `/models` endpoint +- OmniRoute v1.0.6+ includes fallback validation via chat completions +- Ensure base URL includes `/v1` suffix -### ๐Ÿ” OAuth na vzdรกlenรฉm serveru +### ๐Ÿ” OAuth on a Remote Server + -> **โš ๏ธ Dลฏleลพitรฉ pro uลพivatele, kteล™รญ provozujรญ OmniRoute na VPS, Dockeru nebo jakรฉmkoli vzdรกlenรฉm serveru** +> **โš ๏ธ Important for users running OmniRoute on a VPS, Docker, or any remote server** -#### Proฤ selhรกvรก OAuth v rozhranรญ CLI Antigravity / Gemini na vzdรกlenรฝch serverech? +#### Why does Antigravity / Gemini CLI OAuth fail on remote servers? -Poskytovatelรฉ rozhranรญ CLI **Antigravity** a **Gemini** pouลพรญvajรญ **Google OAuth 2.0** . Google vyลพaduje, aby se `redirect_uri` v toku OAuth pล™esnฤ› shodoval s jednรญm z pล™edregistrovanรฝch URI v konzoli Google Cloud Console aplikace. +The **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console. -Pล™ihlaลกovacรญ รบdaje OAuth, kterรฉ jsou souฤรกstรญ OmniRoute, jsou registrovรกny **pouze pro `localhost`** . Kdyลพ pล™istupujete k OmniRoute na vzdรกlenรฉm serveru (napล™. `https://omniroute.myserver.com` ), Google odmรญtne ovฤ›ล™enรญ pomocรญ: +The OAuth credentials bundled in OmniRoute are registered **for `localhost` only**. When you access OmniRoute on a remote server (e.g. `https://omniroute.myserver.com`), Google rejects the authentication with: ``` Error 400: redirect_uri_mismatch ``` -#### ล˜eลกenรญ: Nakonfigurujte si vlastnรญ pล™ihlaลกovacรญ รบdaje OAuth +#### Solution: Configure your own OAuth credentials -V Google Cloud Console je potล™eba vytvoล™it **ID klienta OAuth 2.0** s URI vaลกeho serveru. +You need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI. -#### Krok za krokem +#### Step-by-step -**1. Otevล™ete konzoli Google Cloud** +**1. Open Google Cloud Console** -Pล™ejdฤ›te na: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) +Go to: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) -**2. Vytvoล™te novรฉ ID klienta OAuth 2.0** +**2. Create a new OAuth 2.0 Client ID** -- Kliknฤ›te na **โ€ž+ Vytvoล™it pล™ihlaลกovacรญ รบdajeโ€œ** โ†’ **โ€žID klienta OAuthโ€œ** -- Typ aplikace: **โ€žWebovรก aplikaceโ€œ** -- Nรกzev: cokoli chcete (napล™. `OmniRoute Remote` ) +- Click **"+ Create Credentials"** โ†’ **"OAuth client ID"** +- Application type: **"Web application"** +- Name: anything you like (e.g. `OmniRoute Remote`) -**3. Pล™idejte autorizovanรฉ URI pro pล™esmฤ›rovรกnรญ** +**3. Add Authorized Redirect URIs** -Do pole **โ€žAutorizovanรฉ identifikรกtory URI pro pล™esmฤ›rovรกnรญโ€œ** pล™idejte: +In the **"Authorized redirect URIs"** field, add: ``` https://your-server.com/callback ``` -> Nahraฤte `your-server.com` domรฉnou nebo IP adresou vaลกeho serveru (v pล™รญpadฤ› potล™eby uveฤte i port, napล™. `http://45.33.32.156:20128/callback` ). +> Replace `your-server.com` with your server's domain or IP (include the port if needed, e.g. `http://45.33.32.156:20128/callback`). -**4. Uloลพte a zkopรญrujte pล™ihlaลกovacรญ รบdaje** +**4. Save and copy the credentials** -Po vytvoล™enรญ Google zobrazรญ **ID klienta** a **tajnรฝ kรณd klienta** . +After creating, Google will show the **Client ID** and **Client Secret**. -**5. Nastavenรญ promฤ›nnรฝch prostล™edรญ** +**5. Set environment variables** -Ve vaลกem souboru `.env` (nebo promฤ›nnรฝch prostล™edรญ Docker): +In your `.env` (or Docker environment variables): ```bash # For Antigravity: @@ -1651,7 +2021,7 @@ GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret ``` -**6. Restartujte OmniRoute** +**6. Restart OmniRoute** ```bash # npm: @@ -1661,125 +2031,206 @@ npm run dev docker restart omniroute ``` -**7. Zkuste se znovu pล™ipojit** +**7. Try connecting again** -ล˜รญdicรญ panel โ†’ Poskytovatelรฉ โ†’ Antigravity (nebo Gemini CLI) โ†’ OAuth +Dashboard โ†’ Providers โ†’ Antigravity (or Gemini CLI) โ†’ OAuth -Google nynรญ bude sprรกvnฤ› pล™esmฤ›rovรกvat na `https://your-server.com/callback` . +Google will now redirect correctly to `https://your-server.com/callback`. --- -#### Doฤasnรฉ ล™eลกenรญ (bez vlastnรญch pล™ihlaลกovacรญch รบdajลฏ) +#### Temporary workaround (without custom credentials) -Pokud si teฤ nechcete nastavovat vlastnรญ pล™ihlaลกovacรญ รบdaje, mลฏลพete stรกle pouลพรญt **ruฤnรญ postup pro URL** : +If you don't want to set up your own credentials right now, you can still use the **manual URL flow**: -1. OmniRoute otevรญrรก autorizaฤnรญ URL od Googlu -2. Po autorizaci se Google pokusรญ pล™esmฤ›rovat na `localhost` (coลพ selลพe na vzdรกlenรฉm serveru). -3. **Zkopรญrujte celou URL adresu** z adresnรญho ล™รกdku prohlรญลพeฤe (i kdyลพ se strรกnka nenaฤte) -4. Vloลพte tuto URL adresu do pole zobrazenรฉho v modรกlnรญm oknฤ› pล™ipojenรญ OmniRoute. -5. Kliknฤ›te na **โ€žPล™ipojitโ€œ** +1. OmniRoute opens the Google authorization URL +2. After authorizing, Google tries to redirect to `localhost` (which fails on the remote server) +3. **Copy the full URL** from your browser's address bar (even if the page doesn't load) +4. Paste that URL into the field shown in the OmniRoute connection modal +5. Click **"Connect"** -> To funguje, protoลพe autorizaฤnรญ kรณd v URL adrese je platnรฝ bez ohledu na to, zda se naฤetla pล™esmฤ›rovacรญ strรกnka. +> This works because the authorization code in the URL is valid regardless of whether the redirect page loaded. --- -#### Doฤasnรฉ ล™eลกenรญ (bez vlastnรญch pล™ihlaลกovacรญch รบdajลฏ) - -Chcete-li zรญskat pล™รญstup k pล™ihlaลกovacรญm รบdajลฏm bez vlastnรญ konfigurace, mลฏลพete pouลพรญt nรกsledujรญcรญ postup: - -1. OmniRoute otevล™e URL autorizace Google -2. Po autorizaci se Google pokusรญ pล™esmฤ›rovat na `localhost` (coลพ selลพe na vzdรกlenรฉm serveru) -3. **Zkopรญrujte celou URL adresu** z adresnรญho ล™รกdku prohlรญลพeฤe -4. Vloลพte tuto URL adresu do pole zobrazenรฉho v modรกlnรญm oknฤ› pล™ipojenรญ OmniRoute -5. Kliknฤ›te na **โ€žPล™ipojit"** - -> Toto ล™eลกenรญ funguje, protoลพe autorizaฤnรญ kรณd v URL adrese je platnรฝ bez ohledu na naฤtenรญ pล™esmฤ›rovacรญ strรกnky. - ---- - -## ๐Ÿ› ๏ธ Technologickรฝ stack -
-Kliknutรญm rozbalรญte podrobnosti o technologickรฉm stacku +๐Ÿ‡ง๐Ÿ‡ท Versรฃo em Portuguรชs + +#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos? + +Os provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticaรงรฃo. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs prรฉ-cadastradas no Google Cloud Console do aplicativo. + +As credenciais OAuth embutidas no OmniRoute estรฃo cadastradas **apenas para `localhost`**. Quando vocรช acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticaรงรฃo com: + +``` +Error 400: redirect_uri_mismatch +``` + +#### Soluรงรฃo: Configure suas prรณprias credenciais OAuth + +Vocรช precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor. + +#### Passo a passo + +**1. Acesse o Google Cloud Console** + +Abra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) + +**2. Crie um novo OAuth 2.0 Client ID** + +- Clique em **"+ Create Credentials"** โ†’ **"OAuth client ID"** +- Tipo de aplicativo: **"Web application"** +- Nome: escolha qualquer nome (ex: `OmniRoute Remote`) + +**3. Adicione as Authorized Redirect URIs** + +No campo **"Authorized redirect URIs"**, adicione: + +``` +https://seu-servidor.com/callback +``` + +> Substitua `seu-servidor.com` pelo domรญnio ou IP do seu servidor (inclua a porta se necessรกrio, ex: `http://45.33.32.156:20128/callback`). + +**4. Salve e copie as credenciais** + +Apรณs criar, o Google mostrarรก o **Client ID** e o **Client Secret**. + +**5. Configure as variรกveis de ambiente** + +No seu `.env` (ou nas variรกveis de ambiente do Docker): + +```bash +# Para Antigravity: +ANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com +ANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret + +# Para Gemini CLI: +GEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com +GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret +GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret +``` + +**6. Reinicie o OmniRoute** + +```bash +# Se usando npm: +npm run dev + +# Se usando Docker: +docker restart omniroute +``` + +**7. Tente conectar novamente** + +Dashboard โ†’ Providers โ†’ Antigravity (ou Gemini CLI) โ†’ OAuth + +Agora o Google redirecionarรก corretamente para `https://seu-servidor.com/callback` e a autenticaรงรฃo funcionarรก. + +--- + +#### Workaround temporรกrio (sem configurar credenciais prรณprias) + +Se nรฃo quiser criar credenciais prรณprias agora, ainda รฉ possรญvel usar o fluxo **manual de URL**: + +1. O OmniRoute abrirรก a URL de autorizaรงรฃo do Google +2. Apรณs vocรช autorizar, o Google tentarรก redirecionar para `localhost` (que falha no servidor remoto) +3. **Copie a URL completa** da barra de endereรงo do seu browser (mesmo que a pรกgina nรฃo carregue) +4. Cole essa URL no campo que aparece no modal de conexรฃo do OmniRoute +5. Clique em **"Connect"** + +> Este workaround funciona porque o cรณdigo de autorizaรงรฃo na URL รฉ vรกlido independente do redirect ter carregado ou nรฃo. +
-- **Runtime** : Node.js 18โ€“22 LTS (โš ๏ธ Node.js 24+ **nenรญ podporovรกn** โ€” nativnรญ binรกrnรญ soubory `better-sqlite3` jsou nekompatibilnรญ) -- **Jazyk** : TypeScript 5.9 โ€” **100% TypeScript** napล™รญฤ `src/` a `open-sse/` ( `any` v zรกkladnรญch modulech od verze 2.0) -- **Framework** : Next.js 16 + React 19 + Tailwind CSS 4 -- **Databรกze** : LowDB (JSON) + SQLite (stav domรฉny + protokoly proxy + audit MCP + rozhodnutรญ o smฤ›rovรกnรญ) -- **Schรฉmata** : Zod (validace I/O nรกstrojลฏ MCP, API smlouvy) -- **Protokoly** : MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE) -- **Streamovรกnรญ** : Udรกlosti odeslanรฉ serverem (SSE) -- **Autorizace** : OAuth 2.0 (PKCE) + JWT + API klรญฤe + autorizace s rozsahem MCP -- **Testovรกnรญ** : Node.js test runner + Vitest (900+ testลฏ vฤetnฤ› unit, integraฤnรญch, E2E) -- **CI/CD** : Akce GitHubu (automatickรฉ publikovรกnรญ v npm + Docker Hub pล™i vydรกnรญ) -- **Webovรก strรกnka** : [omniroute.online](https://omniroute.online) -- **Balรญฤek** : [npmjs.com/package/omniroute](https://www.npmjs.com/package/omniroute) -- **Docker** : [hub.docker.com/r/diegosouzapw/omniroute](https://hub.docker.com/r/diegosouzapw/omniroute) -- **Odolnost** : Jistiฤ, exponenciรกlnรญ odstavenรญ, ochrana proti hromลฏm, faleลกnรฉ TLS, automatickรฉ kombinovanรฉ samoopravovรกnรญ +--- + +
+ +## ๐Ÿ› ๏ธ Tech Stack + +
+Click to expand tech stack details + +- **Runtime**: Node.js 18โ€“22 LTS (โš ๏ธ Node.js 24+ is **not supported** โ€” `better-sqlite3` native binaries are incompatible) +- **Language**: TypeScript 5.9 โ€” **100% TypeScript** across `src/` and `open-sse/` (zero `any` in core modules since v2.0) +- **Framework**: Next.js 16 + React 19 + Tailwind CSS 4 +- **Database**: LowDB (JSON) + SQLite (domain state + proxy logs + MCP audit + routing decisions) +- **Schemas**: Zod (MCP tool I/O validation, API contracts) +- **Protocols**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE) +- **Streaming**: Server-Sent Events (SSE) +- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization +- **Testing**: Node.js test runner + Vitest (900+ tests including unit, integration, E2E) +- **CI/CD**: GitHub Actions (auto npm publish + Docker Hub on release) +- **Website**: [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) +- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing + +
--- -## ๐Ÿ“– Dokumentace +## Dokumentace -| Dokument | Popis | -| ------------------------------------------------------------ | ----------------------------------------------------------------------- | -| [Uลพivatelskรก pล™รญruฤka](docs/USER_GUIDE.md) | Poskytovatelรฉ, kombinace, integrace CLI, nasazenรญ | -| [Referenฤnรญ informace k API](docs/API_REFERENCE.md) | Vลกechny koncovรฉ body s pล™รญklady | -| [MCP server](open-sse/mcp-server/README.md) | 16 nรกstrojลฏ MCP, konfigurace IDE, klienti Python/TS/Go | -| [Server A2A](src/lib/a2a/README.md) | Protokol JSON-RPC 2.0, dovednosti, streamovรกnรญ, sprรกva รบloh | -| [Auto-Combo Engine](docs/auto-combo.md) | 6faktorovรฉ bodovรกnรญ, balรญฤky reลพimลฏ, samolรฉฤba | -| [Odstraลˆovรกnรญ problรฉmลฏ](docs/TROUBLESHOOTING.md) | Bฤ›ลพnรฉ problรฉmy a jejich ล™eลกenรญ | -| [Architektura](docs/ARCHITECTURE.md) | Architektura a internรญ prvky systรฉmu | -| [Pล™ispรญvรกnรญ](CONTRIBUTING.md) | Nastavenรญ a pokyny pro vรฝvoj | -| [Specifikace OpenAPI](docs/openapi.yaml) | Specifikace OpenAPI 3.0 | -| [Bezpeฤnostnรญ zรกsady](SECURITY.md) | Hlรกลกenรญ zranitelnostรญ a bezpeฤnostnรญ postupy | -| [Nasazenรญ virtuรกlnรญho poฤรญtaฤe](docs/VM_DEPLOYMENT_GUIDE.md) | Kompletnรญ prลฏvodce: Nastavenรญ virtuรกlnรญho poฤรญtaฤe + nginx + Cloudflare | -| [Galerie funkcรญ](docs/FEATURES.md) | Vizuรกlnรญ prohlรญdka ล™รญdicรญho panelu se snรญmky obrazovky | -| [Kontrolnรญ seznam vydรกnรญ](docs/RELEASE_CHECKLIST.md) | Kroky ovฤ›ล™enรญ pล™ed vydรกnรญm | +| Document | Description | +| ---------------------------------------------- | --------------------------------------------------- | +| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment | +| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples | +| [MCP Server](open-sse/mcp-server/README.md) | 16 MCP tools, IDE configs, Python/TS/Go clients | +| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt | +| [Auto-Combo Engine](docs/auto-combo.md) | 6-factor scoring, mode packs, self-healing | +| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions | +| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals | +| [Contributing](CONTRIBUTING.md) | Development setup and guidelines | +| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification | +| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices | +| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup | +| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots | +| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps | --- -## ๐Ÿ—บ๏ธ Plรกn +## ๐Ÿ—บ๏ธ Roadmap -OmniRoute mรก **v plรกnu vรญce neลพ 210 funkcรญ** v nฤ›kolika fรกzรญch vรฝvoje. Zde jsou klรญฤovรฉ oblasti: +OmniRoute has **210+ features planned** across multiple development phases. Here are the key areas: -| Kategorie | Plรกnovanรฉ funkce | Hlavnรญ body | -| ---------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------ | -| ๐Ÿง  **Smฤ›rovรกnรญ a inteligence** | 25+ | Smฤ›rovรกnรญ s nejniลพลกรญ latencรญ, smฤ›rovรกnรญ zaloลพenรฉ na tagech, kontrola kvรณt pล™ed vรฝstupem, vรฝbฤ›r รบฤtu P2C | -| ๐Ÿ”’ **Zabezpeฤenรญ a dodrลพovรกnรญ pล™edpisลฏ** | 20+ | Zpevnฤ›nรญ SSRF, maskovรกnรญ pล™ihlaลกovacรญch รบdajลฏ, limit rychlosti pro kaลพdรฝ koncovรฝ bod, stanovenรญ rozsahu klรญฤลฏ pro sprรกvu | -| ๐Ÿ“Š **Pozorovatelnost** | 15+ | Integrace OpenTelemetry, sledovรกnรญ kvรณt v reรกlnรฉm ฤase, sledovรกnรญ nรกkladลฏ podle modelu | -| ๐Ÿ”„ **Integrace poskytovatelลฏ** | 20+ | Dynamickรฝ registr modelลฏ, doba zchlazenรญ poskytovatelลฏ, Codex pro vรญce รบฤtลฏ, analรฝza kvรณt Copilota | -| โšก **Vรฝkon** | 15+ | Dvojitรก vrstva mezipamฤ›ti, mezipamฤ›ลฅ vรฝzev, mezipamฤ›ลฅ odpovฤ›dรญ, udrลพovรกnรญ streamovรกnรญ, dรกvkovรฉ API | -| ๐ŸŒ **Ekosystรฉm** | 10+ | WebSocket API, horkรฉ opฤ›tovnรฉ naฤรญtรกnรญ konfigurace, distribuovanรฉ รบloลพiลกtฤ› konfigurace, komerฤnรญ reลพim | +| Category | Planned Features | Highlights | +| ----------------------------- | ---------------- | -------------------------------------------------------------------------------------- | +| ๐Ÿง  **Routing & Intelligence** | 25+ | Lowest-latency routing, tag-based routing, quota preflight, P2C account selection | +| ๐Ÿ”’ **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping | +| ๐Ÿ“Š **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, cost tracking per model | +| ๐Ÿ”„ **Provider Integrations** | 20+ | Dynamic model registry, provider cooldowns, multi-account Codex, Copilot quota parsing | +| โšก **Performance** | 15+ | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API | +| ๐ŸŒ **Ecosystem** | 10+ | WebSocket API, config hot-reload, distributed config store, commercial mode | -### ๐Ÿ”œ Jiลพ brzy +### ๐Ÿ”œ Coming Soon -- ๐Ÿ”— **Integrace OpenCode** โ€” Nativnรญ podpora poskytovatelลฏ pro IDE kรณdovรกnรญ s AI v OpenCode -- ๐Ÿ”— **Integrace TRAE** โ€” Plnรก podpora vรฝvojovรฉho rรกmce TRAE pro umฤ›lou inteligenci -- ๐Ÿ“ฆ **Dรกvkovรฉ API** โ€” Asynchronnรญ dรกvkovรฉ zpracovรกnรญ hromadnรฝch poลพadavkลฏ -- ๐ŸŽฏ **Smฤ›rovรกnรญ na zรกkladฤ› tagลฏ** โ€” Smฤ›rovรกnรญ poลพadavkลฏ na zรกkladฤ› vlastnรญch tagลฏ a metadat -- ๐Ÿ’ฐ **Strategie nejniลพลกรญch nรกkladลฏ** โ€“ Automaticky vybere nejlevnฤ›jลกรญho dostupnรฉho poskytovatele +- ๐Ÿ”— **OpenCode Integration** โ€” Native provider support for the OpenCode AI coding IDE +- ๐Ÿ”— **TRAE Integration** โ€” Full support for the TRAE AI development framework +- ๐Ÿ“ฆ **Batch API** โ€” Asynchronous batch processing for bulk requests +- ๐ŸŽฏ **Tag-Based Routing** โ€” Route requests based on custom tags and metadata +- ๐Ÿ’ฐ **Lowest-Cost Strategy** โ€” Automatically select the cheapest available provider -> ๐Ÿ“ รšplnรฉ specifikace funkcรญ jsou k dispozici v [`docs/new-features/`](docs/new-features/) (217 podrobnรฝch specifikacรญ) +> ๐Ÿ“ Full feature specifications available in [`docs/new-features/`](docs/new-features/) (217 detailed specs) --- -## ๐Ÿ‘ฅ Pล™ispฤ›vatelรฉ +## ๐Ÿ‘ฅ Contributors -[](https://github.com/diegosouzapw/OmniRoute/graphs/contributors)![Pล™ispฤ›vatelรฉ](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1) +[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors) -### Jak pล™ispฤ›t +### How to Contribute -1. Vytvoล™enรญ forku repozitรกล™e -2. Vytvoล™te si vlastnรญ vฤ›tev feature ( `git checkout -b feature/amazing-feature` ) -3. Potvrฤte zmฤ›ny ( `git commit -m 'Add amazing feature'` ) -4. Odeslat do vฤ›tve ( `git push origin feature/amazing-feature` ) -5. Otevล™รญt ลพรกdost o zmฤ›ny (pull request) +1. Fork the repository +2. Create your feature branch (`git checkout -b feature/amazing-feature`) +3. Commit your changes (`git commit -m 'Add amazing feature'`) +4. Push to the branch (`git push origin feature/amazing-feature`) +5. Open a Pull Request -Podrobnรฉ pokyny naleznete na [CONTRIBUTING.md](CONTRIBUTING.md) . +See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines. -### Vydรกnรญ novรฉ verze +### Releasing a New Version ```bash # Create a release โ€” npm publish happens automatically @@ -1788,29 +2239,29 @@ gh release create v2.0.0 --title "v2.0.0" --generate-notes --- -## ๐Ÿ“Š Hvฤ›zdnรก historie +## ๐Ÿ“Š Star History -## Hvฤ›zdรกล™i v prลฏbฤ›hu ฤasu +## Stargazers over time -## [](https://starchart.cc/diegosouzapw/OmniRoute)![Hvฤ›zdรกล™i v prลฏbฤ›hu ฤasu](https://starchart.cc/diegosouzapw/OmniRoute.svg?variant=adaptive) +## [![Stargazers over time](https://starchart.cc/diegosouzapw/OmniRoute.svg?variant=adaptive)](https://starchart.cc/diegosouzapw/OmniRoute) -## ๐Ÿ™ Podฤ›kovรกnรญ +## ๐Ÿ™ Acknowledgments -Zvlรกลกtnรญ podฤ›kovรกnรญ patล™รญ **[9routeru](https://github.com/decolua/9router)** od **[decolua](https://github.com/decolua)** โ€“ pลฏvodnรญmu projektu, kterรฝ inspiroval tento fork. OmniRoute stavรญ na tomto neuvฤ›ล™itelnรฉm zรกkladu s dalลกรญmi funkcemi, multimodรกlnรญmi API a kompletnรญm pล™epsรกnรญm TypeScriptu. +Special thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** โ€” the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite. -Zvlรกลกtnรญ podฤ›kovรกnรญ patล™รญ **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** โ€“ pลฏvodnรญ implementaci Go, kterรก inspirovala tento JavaScriptovรฝ port. +Special thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** โ€” the original Go implementation that inspired this JavaScript port. --- -## ๐Ÿ“„ Licence +## Licence -Licence MIT - podrobnosti viz [LICENCE](LICENSE) . +MIT License - see [LICENSE](LICENSE) for details. ---
- Vytvoล™eno s โค๏ธ pro vรฝvojรกล™e, kteล™รญ programujรญ 24 hodin dennฤ›, 7 dnรญ v tรฝdnu -
-

omniroute.online

 + Built with โค๏ธ for developers who code 24/7 +
+ omniroute.online
diff --git a/docs/i18n/cs/RELEASE_CHECKLIST.md b/docs/i18n/cs/RELEASE_CHECKLIST.md deleted file mode 100644 index 0a1768134f..0000000000 --- a/docs/i18n/cs/RELEASE_CHECKLIST.md +++ /dev/null @@ -1,33 +0,0 @@ -# Kontrolnรญ seznam vydรกnรญ - -Tento kontrolnรญ seznam pouลพijte pล™ed oznaฤenรญm nebo publikovรกnรญm novรฉ verze OmniRoute. - -## Verze a seznam zmฤ›n - -1. Navรฝลกit verzi `package.json` ( `xyz` ) ve vฤ›tvi release. -2. Pล™esunout poznรกmky k vydรกnรญ z `## [Unreleased]` v `CHANGELOG.md` do sekce s datem vydรกnรญ: - - `## [x.y.z] โ€” YYYY-MM-DD` -3. Ponechte `## [Unreleased]` jako prvnรญ sekci changelogu pro nadchรกzejรญcรญ prรกci. -4. Ujistฤ›te se, ลพe nejnovฤ›jลกรญ sekce semver v `CHANGELOG.md` je rovna verzi `package.json` . - -## Dokumentace API - -1. Aktualizace `docs/openapi.yaml` : - - Soubor `info.version` se musรญ rovnat verzi `package.json` . -2. Ovฤ›ล™te pล™รญklady koncovรฝch bodลฏ, pokud se zmฤ›nily smlouvy API. - -## Dokumentace k bฤ›hovรฉmu prostล™edรญ - -1. Projdฤ›te si `docs/ARCHITECTURE.md` , zda nedochรกzรญ k posunu v รบloลพiลกti/bฤ›hovรฉm prostล™edรญ. -2. Projdฤ›te si soubor `docs/TROUBLESHOOTING.md` , kde naleznete informace o promฤ›nnรฉ prostล™edรญ a provoznรญm posunu. -3. Aktualizujte lokalizovanou dokumentaci, pokud se zdrojovรก dokumentace vรฝraznฤ› zmฤ›nila. - -## Automatickรก kontrola - -Pล™ed otevล™enรญm PR spusลฅte lokรกlnฤ› ochranu synchronizace: - -```bash -npm run check:docs-sync -``` - -CI takรฉ spouลกtรญ tuto kontrolu v `.github/workflows/ci.yml` (รบloha lint). diff --git a/docs/i18n/cs/SECURITY.md b/docs/i18n/cs/SECURITY.md index da9eece3fa..8aed7b6782 100644 --- a/docs/i18n/cs/SECURITY.md +++ b/docs/i18n/cs/SECURITY.md @@ -1,129 +1,138 @@ -# Bezpeฤnostnรญ zรกsady +# Security Policy (ฤŒeลกtina) -## Hlรกลกenรญ zranitelnostรญ - -Pokud v OmniRoute objevรญte bezpeฤnostnรญ zranitelnost, nahlaste ji prosรญm zodpovฤ›dnฤ›: - -1. **NEOTVรREJTE** veล™ejnรฝ problรฉm na GitHubu -2. Pouลพรญvejte [bezpeฤnostnรญ doporuฤenรญ GitHubu](https://github.com/diegosouzapw/OmniRoute/security/advisories/new) -3. Zahrลˆte: popis, kroky reprodukce a potenciรกlnรญ dopad - -## ฤŒasovรก osa odezvy - -Fรกze | Cรญl ---- | --- -Potvrzenรญ | 48 hodin -Triรกลพ a posouzenรญ | 5 pracovnรญch dnลฏ -Vydรกnรญ zรกplaty | 14 pracovnรญch dnลฏ (kritickรฉ) - -## Podporovanรฉ verze - -Verze | Stav podpory ---- | --- -1.0.x | โœ… Aktivnรญ -0.8.x | โœ… Bezpeฤnost -< 0,8,0 | โŒ Nepodporovรกno +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../SECURITY.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/SECURITY.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/SECURITY.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/SECURITY.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/SECURITY.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/SECURITY.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/SECURITY.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/SECURITY.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/SECURITY.md) --- -## Bezpeฤnostnรญ architektura +## Reporting Vulnerabilities -OmniRoute implementuje vรญcevrstvรฝ bezpeฤnostnรญ model: +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 | +| ------- | -------------- | +| 3.4.x | โœ… Active | +| 3.0.x | โœ… Security | +| < 3.0.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 ``` -### ๐Ÿ” Ovฤ›ล™ovรกnรญ a autorizace +### ๐Ÿ” Authentication & Authorization -Funkce | Implementace ---- | --- -**Pล™ihlรกลกenรญ do ovlรกdacรญho panelu** | Ovฤ›ล™ovรกnรญ na zรกkladฤ› hesla s tokeny JWT (soubory cookie HttpOnly) -**Autorizace klรญฤe API** | Klรญฤe podepsanรฉ HMAC s ovฤ›ล™enรญm CRC -**OAuth 2.0 + PKCE** | Bezpeฤnรฉ ovฤ›ล™ovรกnรญ poskytovatelลฏ (Claude, Codex, Gemini, Cursor atd.) -**Obnovenรญ tokenu** | Automatickรก aktualizace tokenu OAuth pล™ed vyprลกenรญm platnosti -**Bezpeฤnรฉ soubory cookie** | `AUTH_COOKIE_SECURE=true` pro prostล™edรญ HTTPS +| 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 | +| **MCP Scopes** | 10 granular scopes for MCP tool access control | -### ๐Ÿ›ก๏ธ ล ifrovรกnรญ v klidovรฉm stavu +### ๐Ÿ›ก๏ธ Encryption at Rest -Vลกechna citlivรก data uloลพenรก v SQLite jsou ลกifrovรกna pomocรญ **AES-256-GCM** s odvozenรญm klรญฤe scrypt: +All sensitive data stored in SQLite is encrypted using **AES-256-GCM** with scrypt key derivation: -- Klรญฤe API, pล™รญstupovรฉ tokeny, obnovovacรญ tokeny a ID tokeny -- Verzovanรฝ formรกt: `enc:v1:::` -- Reลพim prลฏchodu (prostรฝ text), pokud nenรญ nastaven `STORAGE_ENCRYPTION_KEY` +- API keys, access tokens, refresh tokens, and ID tokens +- Versioned format: `enc:v1:::` +- Passthrough mode (plaintext) when `STORAGE_ENCRYPTION_KEY` is not set ```bash # Generate encryption key: STORAGE_ENCRYPTION_KEY=$(openssl rand -hex 32) ``` -### ๐Ÿง  Ochrana pล™ed okamลพitou injekcรญ +### ๐Ÿง  Prompt Injection Guard -Middleware, kterรฝ detekuje a blokuje รบtoky prompt injection v poลพadavcรญch LLM: +Middleware that detects and blocks prompt injection attacks in LLM requests: -Typ vzoru | Zรกvaลพnost | Pล™รญklad ---- | --- | --- -Pล™epsรกnรญ systรฉmu | Vysokรฝ | "ignorovat vลกechny pล™edchozรญ pokyny" -รšnos role | Vysokรฝ | "Teฤ jsi DAN, dokรกลพeลก cokoli." -Vloลพenรญ oddฤ›lovaฤe | Stล™ednรญ | Kรณdovanรฉ oddฤ›lovaฤe pro pล™eruลกenรญ hranic kontextu -DAN/รštฤ›k z vฤ›zenรญ | Vysokรฝ | Znรกmรฉ vzory vรฝzev k jailbreaku -รšnik instrukcรญ | Stล™ednรญ | โ€žUkaลพ mi systรฉmovรฝ vรฝzvuโ€œ +| 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" | -Konfigurace pล™es ovlรกdacรญ panel (Nastavenรญ โ†’ Zabezpeฤenรญ) nebo `.env` : +Configure via dashboard (Settings โ†’ Security) or `.env`: ```env INPUT_SANITIZER_ENABLED=true INPUT_SANITIZER_MODE=block # warn | block | redact ``` -### ๐Ÿ”’ Redakฤnรญ รบprava osobnรญch รบdajลฏ +### ๐Ÿ”’ PII Redaction -Automatickรก detekce a volitelnรก redakce osobnรญch รบdajลฏ: +Automatic detection and optional redaction of personally identifiable information: -Typ osobnรญch รบdajลฏ | Vzor | Nahrazenรญ ---- | --- | --- -E-mail | `user@domain.com` | `[EMAIL_REDACTED]` -CPF (Brazรญlie) | `123.456.789-00` | `[CPF_REDACTED]` -CNPJ (Brazรญlie) | `12.345.678/0001-00` | `[CNPJ_REDACTED]` -Kreditnรญ karta | `4111-1111-1111-1111` | `[CC_REDACTED]` -Telefon | `+55 11 99999-9999` | `[PHONE_REDACTED]` -ฤŒรญslo sociรกlnรญho zabezpeฤenรญ (USA) | `123-45-6789` | `[SSN_REDACTED]` +| 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 ``` -### ๐ŸŒ Zabezpeฤenรญ sรญtฤ› +### ๐ŸŒ Network Security -Funkce | Popis ---- | --- -**CORS** | Konfigurovatelnรก kontrola pลฏvodu (promฤ›nnรก prostล™edรญ `CORS_ORIGIN` , vรฝchozรญ nastavenรญ `*` ) -**Filtrovรกnรญ IP adres** | Rozsahy IP adres na bรญlou/ฤernou listinu v dashboardu -**Omezenรญ rychlosti** | Limity sazeb na poskytovatele s automatickรฝm ukonฤenรญm -**Protihromovรฉ stรกdo** | Mutex + uzamฤenรญ pro kaลพdรฉ pล™ipojenรญ zabraลˆuje kaskรกdovรกnรญ 502. +| Feature | Description | +| ------------------------ | ---------------------------------------------------------------- | +| **CORS** | Configurable origin control (`CORS_ORIGIN` env var, default `*`) | +| **IP Filtering** | Allowlist/blocklist IP ranges in dashboard | +| **Rate Limiting** | Per-provider rate limits with automatic backoff | +| **Anti-Thundering Herd** | Mutex + per-connection locking prevents cascading 502s | +| **TLS Fingerprint** | Browser-like TLS fingerprint spoofing to reduce bot detection | +| **CLI Fingerprint** | Per-provider header/body ordering to match native CLI signatures | -### ๐Ÿ”Œ Odolnost a dostupnost +### ๐Ÿ”Œ Resilience & Availability -Funkce | Popis ---- | --- -**Jistiฤ** | 3 stavy (Zavล™eno โ†’ Otevล™eno โ†’ Polootevล™eno) na poskytovatele, trvalรฉ uloลพenรญ v SQLite -**ลฝรกdost o idempotenci** | 5sekundovรฉ okno pro odstranฤ›nรญ duplicitnรญch poลพadavkลฏ -**Exponenciรกlnรญ odklon** | Automatickรฉ opakovรกnรญ s rostoucรญm zpoลพdฤ›nรญm -**Dashboard zdravรญ** | Monitorovรกnรญ stavu poskytovatele v reรกlnรฉm ฤase +| 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 | -### ๐Ÿ“‹ Dodrลพovรกnรญ pล™edpisลฏ +### ๐Ÿ“‹ Compliance -Funkce | Popis ---- | --- -**Uchovรกvรกnรญ protokolลฏ** | Automatickรฉ ฤiลกtฤ›nรญ po `LOG_RETENTION_DAYS` -**Odhlรกลกenรญ bez uklรกdรกnรญ protokolลฏ** | Pล™รญznak `noLog` pro kaลพdรฝ klรญฤ API zakazuje protokolovรกnรญ poลพadavkลฏ. -**Protokol auditu** | Administrativnรญ akce sledovanรฉ v tabulce `audit_log` +| Feature | Description | +| ------------------ | ----------------------------------------------------------- | +| **Log Retention** | Automatic cleanup after `CALL_LOG_RETENTION_DAYS` | +| **No-Log Opt-out** | Per API key `noLog` flag disables request logging | +| **Audit Log** | Administrative actions tracked in `audit_log` table | +| **MCP Audit** | SQLite-backed audit logging for all MCP tool calls | +| **Zod Validation** | All API inputs validated with Zod v4 schemas at module load | --- -## Poลพadovanรฉ promฤ›nnรฉ prostล™edรญ +## Required Environment Variables -Vลกechny tajnรฉ kรณdy musรญ bรฝt nastaveny pล™ed spuลกtฤ›nรญm serveru. Server **rychle selลพe** , pokud chybรญ nebo jsou slabรฉ. +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: @@ -134,17 +143,17 @@ API_KEY_SECRET=$(openssl rand -hex 32) # min 16 chars STORAGE_ENCRYPTION_KEY=$(openssl rand -hex 32) ``` -Server aktivnฤ› odmรญtรก znรกmรฉ slabรฉ hodnoty, jako napล™รญklad `changeme` , `secret` nebo `password` . +The server actively rejects known-weak values like `changeme`, `secret`, or `password`. --- -## Zabezpeฤenรญ Dockeru +## Docker Security -- Pouลพitรญ uลพivatele bez oprรกvnฤ›nรญ root v produkฤnรญm prostล™edรญ -- Pล™ipojte tajnรฉ kรณdy jako svazky jen pro ฤtenรญ -- Nikdy nekopรญrujte soubory `.env` do imagรญ Dockeru -- Pouลพitรญ `.dockerignore` k vylouฤenรญ citlivรฝch souborลฏ -- Nastavit `AUTH_COOKIE_SECURE=true` pล™i pล™ipojenรญ za HTTPS +- 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 \ @@ -161,9 +170,10 @@ docker run -d \ --- -## Zรกvislosti +## Dependencies -- Pravidelnฤ› spouลกtฤ›jte `npm audit` -- Udrลพujte zรกvislosti aktualizovanรฉ -- Projekt pouลพรญvรก pro kontroly pล™ed commitem `husky` + `lint-staged` -- CI pipeline spouลกtรญ bezpeฤnostnรญ pravidla ESLint pล™i kaลพdรฉm odeslรกnรญ. +- 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 +- Provider constants validated at module load via Zod (`src/shared/validation/providerSchema.ts`) diff --git a/docs/i18n/cs/TROUBLESHOOTING.md b/docs/i18n/cs/TROUBLESHOOTING.md deleted file mode 100644 index 8463bf7909..0000000000 --- a/docs/i18n/cs/TROUBLESHOOTING.md +++ /dev/null @@ -1,254 +0,0 @@ -# Odstraลˆovรกnรญ problรฉmลฏ - -๐ŸŒ **Jazyky:** ๐Ÿ‡บ๐Ÿ‡ธ [angliฤtina](TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brazรญlie)](i18n/pt-BR/TROUBLESHOOTING.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/TROUBLESHOOTING.md) | ๐Ÿ‡จ๐Ÿ‡ณ[ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/TROUBLESHOOTING.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/TROUBLESHOOTING.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/TROUBLESHOOTING.md) | ๐Ÿ‡ฏ๐Ÿ‡ต[ๆ—ฅๆœฌ่ชž](i18n/ja/TROUBLESHOOTING.md)| ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dรกnsko](i18n/da/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/TROUBLESHOOTING.md) | ๐Ÿ‡ญ๐Ÿ‡บ [maฤarลกtina](i18n/hu/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonรฉsie](i18n/id/TROUBLESHOOTING.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/TROUBLESHOOTING.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nizozemsko](i18n/nl/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugalsko)](i18n/pt/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipรญnec](i18n/phi/TROUBLESHOOTING.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](i18n/cs/TROUBLESHOOTING.md) - -Bฤ›ลพnรฉ problรฉmy a ล™eลกenรญ pro OmniRoute. - ---- - -## Rychlรฉ opravy - -| Problรฉm | ล˜eลกenรญ | -| ----------------------------------------- | --------------------------------------------------------------------------------- | -| Prvnรญ pล™ihlรกลกenรญ nefunguje | Nastavit `INITIAL_PASSWORD` v `.env` (bez pevnฤ› zakรณdovanรฉho vรฝchozรญho nastavenรญ) | -| Dashboard se otevรญrรก na nesprรกvnรฉm portu | Nastavte `PORT=20128` a `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | -| ลฝรกdnรฉ protokoly poลพadavkลฏ v sekci `logs/` | Nastavte `ENABLE_REQUEST_LOGS=true` | -| Pล˜รSTUP: povolenรญ zamรญtnuto | Nastavenรญm `DATA_DIR=/path/to/writable/dir` pล™epรญลกete `~/.omniroute` | -| Strategie smฤ›rovรกnรญ se neuklรกdรก | Aktualizace na v1.4.11+ (oprava schรฉmatu Zod pro perzistenci nastavenรญ) | - ---- - -## Problรฉmy s poskytovateli - -### "Jazykovรฝ model neposkytoval zprรกvy" - -**Pล™รญฤina:** Vyฤerpรกnรญ kvรณty poskytovatele. - -**Opravit:** - -1. Zkontrolujte sledovaฤ kvรณt na ล™รญdicรญm panelu -2. Pouลพijte kombinaci se zรกloลพnรญmi รบrovnฤ›mi -3. Pล™epnout na levnฤ›jลกรญ/bezplatnou รบroveลˆ - -### Omezenรญ rychlosti - -**Pล™รญฤina:** Vyฤerpรกnรญ kvรณty pล™edplatnรฉho. - -**Opravit:** - -- Pล™idat zรกloลพnรญ variantu: `cc/claude-opus-4-6 โ†’ glm/glm-4.7 โ†’ if/kimi-k2-thinking` -- Pouลพijte GLM/MiniMax jako levnou zรกlohu - -### Platnost tokenu OAuth vyprลกela - -OmniRoute automaticky obnovuje tokeny. Pokud problรฉmy pล™etrvรกvajรญ: - -1. Ovlรกdacรญ panel โ†’ Poskytovatel โ†’ Znovu pล™ipojit -2. Odstranฤ›nรญ a opฤ›tovnรฉ pล™idรกnรญ pล™ipojenรญ poskytovatele - ---- - -## Problรฉmy s cloudem - -### Chyby synchronizace s cloudem - -1. Ovฤ›ล™te, zda `BASE_URL` odkazuje na vaลกi spuลกtฤ›nou instanci (napล™. `http://localhost:20128` ) -2. Ovฤ›ล™te, zda `CLOUD_URL` odkazuje na vรกลก cloudovรฝ koncovรฝ bod (napล™. `https://omniroute.dev` ). -3. Udrลพujte hodnoty `NEXT_PUBLIC_*` zarovnanรฉ s hodnotami na stranฤ› serveru. - -### Cloud `stream=false` Vracรญ 500 - -**Pล™รญznak:** `Unexpected token 'd'...` na cloudovรฉm koncovรฉm bodu pro nestreamovanรก volรกnรญ. - -**Pล™รญฤina:** Upstream vracรญ datovou ฤรกst SSE, zatรญmco klient oฤekรกvรก JSON. - -**ล˜eลกenรญ:** Pro pล™รญmรก volรกnรญ z cloudu pouลพijte `stream=true` . Lokรกlnรญ bฤ›hovรฉ prostล™edรญ zahrnuje zรกloลพnรญ SSEโ†’JSON. - -### Cloud hlรกsรญ pล™ipojenรญ, ale โ€žneplatnรฝ klรญฤ APIโ€œ. - -1. Vytvoล™te novรฝ klรญฤ z lokรกlnรญho dashboardu ( `/api/keys` ) -2. Spuลกtฤ›nรญ synchronizace s cloudem: Povolit cloud โ†’ Synchronizovat nynรญ -3. Starรฉ/nesynchronizovanรฉ klรญฤe mohou v cloudu stรกle vracet `401` - ---- - -## Problรฉmy s Dockerem - -### Nรกstroj CLI se zobrazuje jako nenainstalovanรฝ - -1. Zkontrolujte bฤ›hovรก pole: `curl http://localhost:20128/api/cli-tools/runtime/codex | jq` -2. Pro pล™enosnรฝ reลพim: pouลพijte cรญlovรฝ soubor image `runner-cli` (dodรกvanรฉ CLI) -3. Pro reลพim pล™ipojenรญ hostitele: nastavte `CLI_EXTRA_PATHS` a pล™ipojte adresรกล™ hostitele bin jako pouze pro ฤtenรญ. -4. Pokud `installed=true` a `runnable=false` : binรกrnรญ soubor byl nalezen, ale kontrola stavu selhala. - -### Rychlรฉ ovฤ›ล™enรญ za bฤ›hu - -```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}' -``` - ---- - -## Problรฉmy s nรกklady - -### Vysokรฉ nรกklady - -1. Zkontrolujte statistiky vyuลพitรญ v sekci Nรกstฤ›nka โ†’ Vyuลพitรญ -2. Pล™epnout primรกrnรญ model na GLM/MiniMax -3. Pro nekritickรฉ รบlohy pouลพijte bezplatnou รบroveลˆ (Gemini CLI, Qoder). -4. Nastavenรญ rozpoฤtลฏ nรกkladลฏ pro kaลพdรฝ klรญฤ API: Dashboard โ†’ API klรญฤe โ†’ Rozpoฤet - ---- - -## Ladฤ›nรญ - -### Povolit protokoly poลพadavkลฏ - -V souboru `.env` nastavte `ENABLE_REQUEST_LOGS=true` . Protokoly se zobrazujรญ v adresรกล™i `logs/` . - -### Zkontrolujte stav poskytovatele - -```bash -# Health dashboard -http://localhost:20128/dashboard/health - -# API health check -curl http://localhost:20128/api/monitoring/health -``` - -### Runtimovรฉ รบloลพiลกtฤ› - -- Hlavnรญ stav: `${DATA_DIR}/storage.sqlite` (poskytovatelรฉ, kombinace, aliasy, klรญฤe, nastavenรญ) -- Pouลพitรญ: SQLite tabulky v `storage.sqlite` ( `usage_history` , `call_logs` , `proxy_logs` ) + volitelnรฉ `${DATA_DIR}/log.txt` a `${DATA_DIR}/call_logs/` -- Zรกznamy poลพadavkลฏ: `/logs/...` (pokud `ENABLE_REQUEST_LOGS=true` ) - ---- - -## Problรฉmy s jistiฤi - -### Poskytovatel uvรญzl ve stavu OPEN (OTEVล˜ENO) - -Pokud je jistiฤ poskytovatele VYPNUTร, poลพadavky jsou blokovรกny, dokud neuplyne doba ochlazovรกnรญ. - -**Opravit:** - -1. Pล™ejdฤ›te do **nabรญdky Ovlรกdacรญ panel โ†’ Nastavenรญ โ†’ Odolnost** -2. Zkontrolujte kartu jistiฤe u dotฤenรฉho poskytovatele -3. Kliknutรญm na **Obnovit vลกe** vynulujete vลกechny jistiฤe nebo poฤkejte, aลพ vyprลกรญ doba zpoลพdฤ›nรญ. -4. Pล™ed resetovรกnรญm ovฤ›ล™te, zda je poskytovatel skuteฤnฤ› dostupnรฝ. - -### Poskytovatel neustรกle vypรญnรก jistiฤ - -Pokud poskytovatel opakovanฤ› pล™echรกzรญ do stavu OTEVล˜ENO: - -1. Zkontrolujte **v ฤรกsti Dashboard โ†’ Stav โ†’ Stav poskytovatele** vzorec selhรกnรญ. -2. Pล™ejdฤ›te do **Nastavenรญ โ†’ Odolnost โ†’ Profily poskytovatelลฏ** a zvyลกte prahovou hodnotu selhรกnรญ. -3. Zkontrolujte, zda poskytovatel zmฤ›nil limity API nebo vyลพaduje opฤ›tovnรฉ ovฤ›ล™enรญ. -4. Zkontrolujte telemetrii latence โ€“ vysokรก latence mลฏลพe zpลฏsobit selhรกnรญ z dลฏvodu ฤasovรฉho limitu. - ---- - -## Problรฉmy s pล™episem zvuku - -### Chyba โ€žNepodporovanรฝ modelโ€œ - -- Ujistฤ›te se, ลพe pouลพรญvรกte sprรกvnรฝ prefix: `deepgram/nova-3` nebo `assemblyai/best` -- Ovฤ›ล™te, zda je poskytovatel pล™ipojen v **nabรญdce Dashboard โ†’ Poskytovatelรฉ.** - -### Pล™epis vracรญ prรกzdnรฝ vรฝsledek nebo selลพe - -- Zkontrolujte podporovanรฉ zvukovรฉ formรกty: `mp3` , `wav` , `m4a` , `flac` , `ogg` , `webm` -- Ovฤ›ล™te, zda je velikost souboru v rรกmci limitลฏ poskytovatele (obvykle < 25 MB) -- Zkontrolujte platnost klรญฤe API poskytovatele v kartฤ› poskytovatele - ---- - -## Ladฤ›nรญ pล™ekladaฤe - -Pro ladฤ›nรญ problรฉmลฏ s pล™ekladem formรกtu pouลพijte **Dashboard โ†’ Translator** : - -| Reลพim | Kdy pouลพรญt | -| -------------------- | ---------------------------------------------------------------------------------------------------------- | -| **Dฤ›tskรฉ hล™iลกtฤ›** | Porovnejte vstupnรญ/vรฝstupnรญ formรกty vedle sebe โ€“ vloลพte neรบspฤ›ลกnรฝ poลพadavek a podรญvejte se, jak se pล™eloลพรญ | -| **Tester chatu** | Odesรญlejte ลพivรฉ zprรกvy a kontrolujte kompletnรญ datovou ฤรกst poลพadavkลฏ/odpovฤ›dรญ vฤetnฤ› zรกhlavรญ | -| **Zkuลกebnรญ stolice** | Spusลฅte dรกvkovรฉ testy napล™รญฤ kombinacemi formรกtลฏ a zjistฤ›te, kterรฉ pล™eklady jsou poลกkozenรฉ. | -| **ลฝivรฝ monitor** | Sledujte tok poลพadavkลฏ v reรกlnรฉm ฤase a zachyลฅte obฤasnรฉ problรฉmy s pล™ekladem | - -### Bฤ›ลพnรฉ problรฉmy s formรกtovรกnรญm - -- **ล tรญtky myลกlenรญ se nezobrazujรญ** โ€“ Zkontrolujte, zda cรญlovรฝ poskytovatel podporuje myลกlenรญ a nastavenรญ rozpoฤtu myลกlenรญ. -- **Volรกnรญ nรกstrojลฏ se vynechรกvajรญ** โ€“ Nฤ›kterรฉ pล™eklady formรกtลฏ mohou odstranit nepodporovanรก pole; ovฤ›ล™te v reลพimu Playground. -- **Chybรญ systรฉmovรก vรฝzva** โ€“ Claude a Gemini zpracovรกvajรญ systรฉmovรฉ vรฝzvy odliลกnฤ›; zkontrolujte pล™eklad vรฝstupu -- **SDK vracรญ nezpracovanรฝ ล™etฤ›zec mรญsto objektu** โ€“ Opraveno ve verzi 1.1.0: sanitizรฉr odpovฤ›dรญ nynรญ odstraลˆuje nestandardnรญ pole ( `x_groq` , `usage_breakdown` atd.), kterรก zpลฏsobujรญ selhรกnรญ validace OpenAI SDK v Pydantic. -- **GLM/ERNIE odmรญtรก `system` roli** โ€” Opraveno ve verzi 1.1.0: normalizรกtor rolรญ automaticky sluฤoval systรฉmovรฉ zprรกvy s uลพivatelskรฝmi zprรกvami pro nekompatibilnรญ modely. -- **role `developer` nebyla rozpoznรกna** โ€“ Opraveno ve verzi 1.1.0: automaticky pล™evedeno na `system` pro poskytovatele, kteล™รญ nepouลพรญvajรญ OpenAI -- **`json_schema` nefunguje s Gemini** โ€” Opraveno ve verzi 1.1.0: `response_format` se nynรญ pล™evรกdรญ na `responseMimeType` + `responseSchema` z Gemini. - ---- - -## Nastavenรญ odolnosti - -### Automatickรฉ omezenรญ rychlosti se nespouลกtรญ - -- Automatickรฉ omezenรญ rychlosti se vztahuje pouze na poskytovatele klรญฤลฏ API (ne na OAuth/pล™edplatnรฉ) -- Ovฤ›ล™te **Nastavenรญ โ†’ Odolnost โ†’ Profily poskytovatelลฏ** majรญ povoleno automatickรฉ omezenรญ rychlosti -- Zkontrolujte, zda poskytovatel vracรญ stavovรฉ kรณdy `429` nebo hlaviฤky `Retry-After` - -### Ladฤ›nรญ exponenciรกlnรญho poklesu - -Profily poskytovatelลฏ podporujรญ tato nastavenรญ: - -- **Zรกkladnรญ zpoลพdฤ›nรญ** โ€” Poฤรกteฤnรญ doba ฤekรกnรญ po prvnรญm selhรกnรญ (vรฝchozรญ: 1 s) -- **Max. zpoลพdฤ›nรญ** โ€” Maximรกlnรญ doba ฤekรกnรญ (vรฝchozรญ: 30 s) -- **Nรกsobitel** โ€” O kolik se mรก zvรฝลกit zpoลพdฤ›nรญ za kaลพdou po sobฤ› jdoucรญ chybu (vรฝchozรญ: 2x) - -### Stรกdo proti hromลฏm - -Kdyลพ se na poskytovatele s omezenou rychlostรญ odesรญlรก mnoho soubฤ›ลพnรฝch poลพadavkลฏ, OmniRoute pouลพije mutex + automatickรฉ omezenรญ rychlosti k serializaci poลพadavkลฏ a zabrรกnฤ›nรญ kaskรกdovรฝm selhรกnรญm. Toto je automatickรฉ pro poskytovatele klรญฤลฏ API. - ---- - -## Volitelnรก taxonomie selhรกnรญ RAG / LLM (16 problรฉmลฏ) - -Nฤ›kteล™รญ uลพivatelรฉ OmniRoute umisลฅujรญ brรกnu pล™ed RAG nebo agent stacky. V tฤ›chto nastavenรญch je bฤ›ลพnรฉ vidฤ›t zvlรกลกtnรญ vzorec: OmniRoute vypadรก v poล™รกdku (poskytovatelรฉ aktivnรญ, profily smฤ›rovรกnรญ v poล™รกdku, ลพรกdnรก upozornฤ›nรญ na limity rychlosti), ale koneฤnรก odpovฤ›ฤ je stรกle nesprรกvnรก. - -V praxi tyto incidenty obvykle pochรกzejรญ z nรกslednรฉho RAG kanรกlu, nikoli ze samotnรฉ brรกny. - -Pokud chcete sdรญlenou slovnรญ zรกsobu pro popis tฤ›chto selhรกnรญ, mลฏลพete pouลพรญt WFGY ProblemMap, externรญ textovรฝ zdroj s licencรญ MIT, kterรฝ definuje ลกestnรกct opakujรญcรญch se vzorcลฏ selhรกnรญ RAG / LLM. Na obecnรฉ รบrovni zahrnuje: - -- drift vyhledรกvรกnรญ a naruลกenรฉ hranice kontextu -- prรกzdnรฉ nebo zastaralรฉ indexy a vektorovรฉ รบloลพiลกtฤ› -- vklรกdรกnรญ versus sรฉmantickรฝ nesoulad -- problรฉmy s assembly promptu a kontextovรฝm oknem -- logickรฝ kolaps a pล™ehnanฤ› sebevฤ›domรฉ odpovฤ›di -- selhรกnรญ dlouhรฉho ล™etฤ›zce a koordinace agentลฏ -- pamฤ›ลฅ vรญce agentลฏ a posun rolรญ -- problรฉmy s nasazenรญm a objednรกvรกnรญm bootstrapลฏ - -Myลกlenka je jednoduchรก: - -1. Pล™i vyลกetล™ovรกnรญ ลกpatnรฉ odpovฤ›di zaznamenejte: - - รบkol a poลพadavek uลพivatele - - Kombinace trasy nebo poskytovatele v OmniRoute - - jakรฝkoli kontext RAG pouลพitรฝ v nรกslednรฝch fรกzรญch (naฤtenรฉ dokumenty, volรกnรญ nรกstrojลฏ atd.) -2. Namapujte incident na jedno nebo dvฤ› ฤรญsla z WFGY ProblemMap ( `No.1` โ€ฆ `No.16` ). -3. Uloลพte ฤรญslo do vlastnรญho ล™รญdicรญho panelu, runbooku nebo sledovaฤe incidentลฏ vedle protokolลฏ OmniRoute. -4. Pro rozhodnutรญ, zda je potล™eba zmฤ›nit RAG stack, retriever nebo smฤ›rovacรญ strategii, pouลพijte odpovรญdajรญcรญ strรกnku WFGY. - -Plnรฝ text a konkrรฉtnรญ recepty naleznete zde (licence MIT, pouze text): - -[Soubor README pro mapu problรฉmลฏ WFGY](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) - -Tuto ฤรกst mลฏลพete ignorovat, pokud za OmniRoute nespouลกtฤ›te RAG ani agenty. - ---- - -## Stรกle v koncรญch? - -- **Problรฉmy s GitHubem** : [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **Architektura** : Viz [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) pro internรญ podrobnosti -- **Referenฤnรญ informace k API** : Vลกechny koncovรฉ body naleznete v [`docs/API_REFERENCE.md`](API_REFERENCE.md) -- **Panel stavu** : Zkontrolujte **Panel stavu, kde** najdete stav systรฉmu v reรกlnรฉm ฤase. -- **Pล™ekladaฤ** : Pouลพijte **Dashboard โ†’ Pล™ekladaฤ** k ladฤ›nรญ problรฉmลฏ s formรกtem diff --git a/docs/i18n/cs/USER_GUIDE.md b/docs/i18n/cs/USER_GUIDE.md deleted file mode 100644 index ed29de006f..0000000000 --- a/docs/i18n/cs/USER_GUIDE.md +++ /dev/null @@ -1,808 +0,0 @@ -# Uลพivatelskรก pล™รญruฤka - -๐ŸŒ **Jazyky:** ๐Ÿ‡บ๐Ÿ‡ธ [angliฤtina](USER_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brazรญlie)](i18n/pt-BR/USER_GUIDE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/USER_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/USER_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/USER_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/USER_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ณ[ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/USER_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/USER_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/USER_GUIDE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/USER_GUIDE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/USER_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/USER_GUIDE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต[ๆ—ฅๆœฌ่ชž](i18n/ja/USER_GUIDE.md)| ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/USER_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/USER_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dรกnsko](i18n/da/USER_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/USER_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/USER_GUIDE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [maฤarลกtina](i18n/hu/USER_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonรฉsie](i18n/id/USER_GUIDE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/USER_GUIDE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/USER_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nizozemsko](i18n/nl/USER_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/USER_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugalsko)](i18n/pt/USER_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/USER_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/USER_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/USER_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/USER_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipรญnec](i18n/phi/USER_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](i18n/cs/USER_GUIDE.md) - -Kompletnรญ prลฏvodce konfiguracรญ poskytovatelลฏ, vytvรกล™enรญm kombinacรญ, integracรญ nรกstrojลฏ CLI a nasazenรญm OmniRoute. - ---- - -## Obsah - -- [Ceny v kostce](#-pricing-at-a-glance) -- [Pล™รญpady pouลพitรญ](#-use-cases) -- [Nastavenรญ poskytovatele](#-provider-setup) -- [Integrace s rozhranรญm CLI](#-cli-integration) -- [Nasazenรญ](#-deployment) -- [Dostupnรฉ modely](#-available-models) -- [Pokroฤilรฉ funkce](#-advanced-features) - ---- - -## ๐Ÿ’ฐ Pล™ehled cen - -| รšroveลˆ | Poskytovatel | Nรกklady | Obnovenรญ kvรณty | Nejlepลกรญ pro | -| ----------------- | ----------------- | ---------------- | ------------------- | -------------------------- | -| **๐Ÿ’ณ Pล˜EDPLATNร‰** | Claude Code (pro) | 20 USD mฤ›sรญc | 5h + tรฝdnฤ› | Jiลพ pล™ihlรกลกenรฉ | -| | Kodex (Plus/Pro) | 20โ€“200 USD/mฤ›sรญc | 5h + tรฝdnฤ› | Uลพivatele OpenAI | -| | Gemini CLI | **ZDARMA** | 180K/mo + 1K/den | Kaลพdรฉho! | -| | GitHub Copilot | 10โ€“19 USD/mฤ›sรญc | Mฤ›sรญฤnรญ | Uลพivatele GitHubu | -| **๐Ÿ”‘ KLรฤŒ API** | DeepSeek | Dle uลพitรญ | ลฝรกdnรฉ | Lacinรฉ uvaลพovรกnรญ | -| | Groq | Dle uลพitรญ | ลฝรกdnรฉ | Ultrarychlรก inference | -| | xAI (Grok) | Dle uลพitรญ | ลฝรกdnรฉ | Grok 4 uvaลพovรกnรญ | -| | Mistral | Dle uลพitรญ | ลฝรกdnรฉ | Modely hostovanรฉ v EU | -| | Perplexity | Dle uลพitรญ | ลฝรกdnรฉ | Rozลกรญล™enรฉ vyhledรกvรกnรญ | -| | Together AI | Dle uลพitรญ | ลฝรกdnรฉ | Open Source modely | -| | Fireworks AI | Dle uลพitรญ | ลฝรกdnรฉ | Rychlรฉ FLUX obrรกzky | -| | Cerebras | Dle uลพitรญ | ลฝรกdnรฉ | Rychlost destiฤkovรฉho ฤipu | -| | Cohere | Dle uลพitรญ | ลฝรกdnรฉ | Command R+ RAG | -| | NVIDIA NIM | Dle uลพitรญ | ลฝรกdnรฉ | Podnikovรฉ modely | -| **๐Ÿ’ฐ LEVNร‰** | GLM-4.7 | $0.6/1M | Dennฤ› 10:00 | Levnรก zรกloha | -| | MiniMax M2.1 | $0.2/1M | 5hodinovรฉ vรกlcovรกnรญ | Nejlevnฤ›jลกรญ varianta | -| | Kimi K2 | 9 USD mฤ›sรญc | 10M tokens/mฤ›sรญc | Pล™edvรญdatelnรฉ nรกklady | -| **๐Ÿ†“ ZDARMA** | Qoder | $0 | Neomezenรฝ | 8 modelลฏ zdarma | -| | Qwen | $0 | Neomezenรฝ | 3 modely zdarma | -| | Kiro | $0 | Neomezenรฝ | Claude zdarma | - -**๐Ÿ’ก Pro Tip:** Zaฤnฤ›te s kombinacรญ Gemini CLI (180K zdarma/mฤ›sรญc) + Qoder (neomezenฤ› zdarma) = $0! - ---- - -## ๐ŸŽฏ Pล™รญpady pouลพitรญ - -### Pล™รญpad 1: โ€žMรกm pล™edplatnรฉ Claude Proโ€œ - -**Problรฉm:** Kvรณta vyprลกรญ, nevyuลพitรก, limity rychlosti bฤ›hem nรกroฤnรฉho kรณdovรกnรญ - -``` -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 -``` - -### Pล™รญpad 2: โ€žChci nulovรฉ nรกkladyโ€œ - -**Problรฉm:** Nemลฏลพu si dovolit pล™edplatnรฉ, potล™ebuji spolehlivรฉ kรณdovรกnรญ s vyuลพitรญm umฤ›lรฉ inteligence - -``` -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 -``` - -### Pล™รญpad 3: โ€žPotล™ebuji kรณdovรกnรญ 24 hodin dennฤ›, 7 dnรญ v tรฝdnu, bez pล™eruลกenรญโ€œ - -**Problรฉm:** Termรญny, nemลฏลพeme si dovolit prostoje - -``` -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) -``` - -### Pล™รญpad 4: โ€žChci BEZPLATNOU AI v OpenClawโ€œ - -**Problรฉm:** Potล™ebujete asistenta s umฤ›lou inteligencรญ v aplikacรญch pro zasรญlรกnรญ zprรกv, zcela zdarma - -``` -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... -``` - ---- - -## ๐Ÿ“– Nastavenรญ poskytovatele - -### ๐Ÿ” Poskytovatelรฉ pล™edplatnรฉho - -#### 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 -``` - -**Tip pro profesionรกly:** Pro sloลพitรฉ รบkoly pouลพรญvejte Opus, pro rychlost Sonnet. OmniRoute sleduje kvรณtu pro kaลพdรฝ 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 (ZDARMA 180 000/mฤ›sรญc!) - -```bash -Dashboard โ†’ Providers โ†’ Connect Gemini CLI -โ†’ Google OAuth -โ†’ 180K completions/month + 1K/day - -Models: - gc/gemini-3-flash-preview - gc/gemini-2.5-pro -``` - -**Nejlepลกรญ hodnota:** Obrovskรก bezplatnรก รบroveลˆ! Pouลพijte ji pล™ed placenรฝmi รบrovnฤ›mi. - -#### 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 -``` - -### ๐Ÿ’ฐ Levnรญ poskytovatelรฉ - -#### GLM-4.7 (Dennรญ reset, 0,6 USD/1 milion) - -1. Registrace: [Zhipu AI](https://open.bigmodel.cn/) -2. Zรญskejte klรญฤ API z kรณdovacรญho plรกnu -3. Nรกstฤ›nka โ†’ Pล™idat klรญฤ API: Poskytovatel: `glm` , klรญฤ API: `your-key` - -**Pouลพitรญ:** `glm/glm-4.7` โ€” **Tip pro profesionรกly:** Coding Plan nabรญzรญ 3ร— kvรณtu za cenu 1/7! Resetovat dennฤ› v 10:00. - -#### MiniMax M2.1 (5h reset, 0,20 $/1 milion) - -1. Registrace: [MiniMax](https://www.minimax.io/) -2. Zรญskat API klรญฤ โ†’ Dashboard โ†’ Pล™idat API klรญฤ - -**Pouลพitรญ:** `minimax/MiniMax-M2.1` โ€” **Tip pro profesionรกly:** Nejlevnฤ›jลกรญ varianta pro dlouhรฝ kontext (1 milion tokenลฏ)! - -#### Kimi K2 (pauลกรกlnรญ poplatek 9 dolarลฏ mฤ›sรญฤnฤ›) - -1. Odebรญrat: [Moonshot AI](https://platform.moonshot.ai/) -2. Zรญskat API klรญฤ โ†’ Dashboard โ†’ Pล™idat API klรญฤ - -**Pouลพitรญ:** `kimi/kimi-latest` โ€” **Tip pro profesionรกly:** Fixnรญ cena 9 $/mฤ›sรญc za 10 milionลฏ tokenลฏ = efektivnรญ nรกklady 0,90 $/1 milion! - -### ๐Ÿ†“ Poskytovatelรฉ ZDARMA - -#### Qoder (8 modelลฏ ZDARMA) - -```bash -Dashboard โ†’ Connect Qoder โ†’ OAuth login โ†’ Unlimited usage - -Models: if/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1 -``` - -#### Qwen (3 modely ZDARMA) - -```bash -Dashboard โ†’ Connect Qwen โ†’ Device code auth โ†’ Unlimited usage - -Models: qw/qwen3-coder-plus, qw/qwen3-coder-flash -``` - -#### Kiro (Claude ZDARMA) - -```bash -Dashboard โ†’ Connect Kiro โ†’ AWS Builder ID or Google/GitHub โ†’ Unlimited - -Models: kr/claude-sonnet-4.5, kr/claude-haiku-4.5 -``` - ---- - -## ๐ŸŽจ Kombinace - -### Pล™รญklad 1: Maximalizace pล™edplatnรฉho โ†’ Levnรฉ zรกlohovรกnรญ - -``` -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 -``` - -### Pล™รญklad 2: Pouze zdarma (nulovรฉ nรกklady) - -``` -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! -``` - ---- - -## ๐Ÿ”ง Integrace s rozhranรญm pล™รญkazovรฉho ล™รกdku - -### IDE kurzoru - -``` -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 - -Upravit `~/.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 - -Upravit `~/.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" }] - } - } - } -} -``` - -**Nebo pouลพijte Dashboard:** CLI Tools โ†’ OpenClaw โ†’ Auto-config - -### Cline / Pokraฤovat / RooCode - -``` -Provider: OpenAI Compatible -Base URL: http://localhost:20128/v1 -API Key: [from dashboard] -Model: cc/claude-opus-4-6 -``` - ---- - -## ๐Ÿš€ Nasazenรญ - -### Globรกlnรญ instalace npm (doporuฤeno) - -```bash -npm install -g omniroute - -# Create config directory -mkdir -p ~/.omniroute - -# Create .env file (see .env.example) -cp .env.example ~/.omniroute/.env - -# Start server -omniroute -# Or with custom port: -omniroute --port 3000 -``` - -CLI automaticky naฤte `.env` z adresรกล™e `~/.omniroute/.env` nebo `./.env` . - -### Nasazenรญ VPS - -```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 -``` - -### Nasazenรญ PM2 (mรกlo pamฤ›ti) - -Pro servery s omezenou pamฤ›tรญ RAM pouลพijte moลพnost omezenรญ pamฤ›ti: - -```bash -# With 512MB limit (default) -pm2 start npm --name omniroute -- start - -# Or with custom memory limit -OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start - -# Or using ecosystem.config.js -pm2 start ecosystem.config.js -``` - -Vytvoล™te soubor `ecosystem.config.js` : - -```javascript -module.exports = { - apps: [ - { - name: "omniroute", - script: "npm", - args: "start", - env: { - NODE_ENV: "production", - OMNIROUTE_MEMORY_MB: "512", - JWT_SECRET: "your-secret", - INITIAL_PASSWORD: "your-password", - }, - node_args: "--max-old-space-size=512", - max_memory_restart: "300M", - }, - ], -}; -``` - -### Pล™รญstavnรญ dฤ›lnรญk - -```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 -``` - -Informace o reลพimu integrovanรฉm s hostitelem s binรกrnรญmi soubory CLI naleznete v ฤรกsti Docker v hlavnรญ dokumentaci. - -### Promฤ›nnรฉ prostล™edรญ - -| Promฤ›nnรก | Vรฝchozรญ | Popis | -| ------------------------- | ------------------------------------ | ------------------------------------------------------------------ | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | Tajnรฝ klรญฤ podpisu JWT ( **zmฤ›na v produkฤnรญm prostล™edรญ** ) | -| `INITIAL_PASSWORD` | `123456` | Prvnรญ pล™ihlaลกovacรญ heslo | -| `DATA_DIR` | `~/.omniroute` | Datovรฝ adresรกล™ (db, vyuลพitรญ, protokoly) | -| `PORT` | vรฝchozรญ nastavenรญ rรกmce | Servisnรญ port ( `20128` v pล™รญkladech) | -| `HOSTNAME` | vรฝchozรญ nastavenรญ rรกmce | Vรกzat hostitele (Docker mรก vรฝchozรญ hodnotu `0.0.0.0` ) | -| `NODE_ENV` | vรฝchozรญ nastavenรญ za bฤ›hu | Nastavenรญ `production` pro nasazenรญ | -| `BASE_URL` | `http://localhost:20128` | Internรญ zรกkladnรญ URL na stranฤ› serveru | -| `CLOUD_URL` | `https://omniroute.dev` | Zรกkladnรญ adresa URL koncovรฉho bodu synchronizace s cloudem | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | Tajnรฝ klรญฤ HMAC pro generovanรฉ klรญฤe API | -| `REQUIRE_API_KEY` | `false` | Vynutit klรญฤ rozhranรญ Bearer API na `/v1/*` | -| `ENABLE_REQUEST_LOGS` | `false` | Povoluje protokolovรกnรญ poลพadavkลฏ/odpovฤ›dรญ | -| `AUTH_COOKIE_SECURE` | `false` | Vynutit soubor cookie `Secure` ovฤ›ล™ovรกnรญ (za reverznรญ proxy HTTPS) | -| `OMNIROUTE_MEMORY_MB` | `512` | Limit haldy Node.js v MB | -| `PROMPT_CACHE_MAX_SIZE` | `50` | Maximรกlnรญ poฤet poloลพek mezipamฤ›ti vรฝzev | -| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Maximรกlnรญ poฤet poloลพek sรฉmantickรฉ mezipamฤ›ti | - -รšplnรฝ pล™ehled promฤ›nnรฝch prostล™edรญ naleznete v souboru [README](../README.md) . - ---- - -## ๐Ÿ“Š Dostupnรฉ modely - -
-Zobrazit vลกechny dostupnรฉ modely -
- -**Claude Code ( `cc/` )** โ€” Pro/Max: `cc/claude-opus-4-6` , `cc/claude-sonnet-4-5-20250929` , `cc/claude-haiku-4-5-20251001` - -**Codex ( `cx/` )** โ€” Plus/Pro: `cx/gpt-5.2-codex` , `cx/gpt-5.1-codex-max` - -**Gemini CLI ( `gc/` )** โ€” ZDARMA: `gc/gemini-3-flash-preview` , `gc/gemini-2.5-pro` - -**GitHub Copilot ( `gh/` )** : `gh/gpt-5` , `gh/claude-4.5-sonnet` - -**GLM ( `glm/` )** โ€” 0,6 USD/1 milion: `glm/glm-4.7` - -**MiniMax ( `minimax/` )** โ€” 0,2 USD/1 milion: `minimax/MiniMax-M2.1` - -**Qoder ( `if/` )** โ€” ZDARMA: `if/kimi-k2-thinking` , `if/qwen3-coder-plus` , `if/deepseek-r1` - -**Qwen ( `qw/` )** โ€” ZDARMA: `qw/qwen3-coder-plus` , `qw/qwen3-coder-flash` - -**Kiro ( `kr/` )** โ€” ZDARMA: `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` - -**Zmatek ( `pplx/` )** : `pplx/sonar-pro` , `pplx/sonar` - -**Spoleฤnฤ› AI ( `together/` )** : `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` - -**Umฤ›lรก inteligence pro ohลˆostroje ( `fireworks/` )** : `fireworks/accounts/fireworks/models/deepseek-v3p1` - -**Cerebras ( `cerebras/` )** : `cerebras/llama-3.3-70b` - -**Soudrลพnost ( `cohere/` )** : `cohere/command-r-plus-08-2024` - -**NVIDIA NIM ( `nvidia/` )** : `nvidia/nvidia/llama-3.3-70b-instruct` - ---- - -## ๐Ÿงฉ Pokroฤilรฉ funkce - -### Vlastnรญ modely - -Pล™idejte libovolnรฉ ID modelu k libovolnรฉmu poskytovateli bez ฤekรกnรญ na aktualizaci aplikace: - -```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" -``` - -Nebo pouลพijte Dashboard: **Poskytovatelรฉ โ†’ [Poskytovatel] โ†’ Vlastnรญ modely** . - -### Vyhrazenรฉ trasy poskytovatelลฏ - -Smฤ›rovรกnรญ poลพadavkลฏ pล™รญmo ke konkrรฉtnรญmu poskytovateli s validacรญ modelu: - -```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 -``` - -Pokud chybรญ prefix poskytovatele, automaticky se pล™idรก. Neshodnรฉ modely vrรกtรญ chybu `400` . - -### Konfigurace sรญลฅovรฉho proxy serveru - -```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"}}' -``` - -**Priorita:** Specifickรก pro klรญฤ โ†’ Specifickรก pro kombinaci โ†’ Specifickรก pro poskytovatele โ†’ Globรกlnรญ โ†’ Prostล™edรญ. - -### API katalogu modelลฏ - -```bash -curl http://localhost:20128/api/models/catalog -``` - -Vrรกtรญ modely seskupenรฉ podle poskytovatele s typy ( `chat` , `embedding` , `image` ). - -### Synchronizace s cloudem - -- Synchronizace poskytovatelลฏ, kombinacรญ a nastavenรญ napล™รญฤ zaล™รญzenรญmi -- Automatickรก synchronizace na pozadรญ s ฤasovรฝm limitem + rychlรก ochrana proti selhรกnรญ -- V produkฤnรญm prostล™edรญ preferovat `BASE_URL` / `CLOUD_URL` na stranฤ› serveru - -### LLM Gateway Intelligence (fรกze 9) - -- **Sรฉmantickรก mezipamฤ›ลฅ** โ€” Automaticky uklรกdรก do mezipamฤ›ti nestreamovanรฉ odpovฤ›di s teplotou 0 (obejde se pomocรญ `X-OmniRoute-No-Cache: true` ) -- **Request Idempotency** โ€” Deduplikuje poลพadavky do 5 sekund pomocรญ hlaviฤky `Idempotency-Key` nebo `X-Request-Id` -- **Sledovรกnรญ prลฏbฤ›hu** โ€” `event: progress` prostล™ednictvรญm zรกhlavรญ `X-OmniRoute-Progress: true` - ---- - -### Hล™iลกtฤ› pล™ekladatelลฏ - -Pล™รญstup pล™es **Dashboard โ†’ Translator** . Ladฤ›nรญ a vizualizace toho, jak OmniRoute pล™eklรกdรก poลพadavky API mezi poskytovateli. - -| Reลพim | รšฤel | -| -------------------- | ------------------------------------------------------------------------------------------- | -| **Dฤ›tskรฉ hล™iลกtฤ›** | Vyberte zdrojovรฝ/cรญlovรฝ formรกt, vloลพte poลพadavek a okamลพitฤ› si prohlรฉdnฤ›te pล™eloลพenรฝ vรฝstup | -| **Tester chatu** | Odesรญlejte zprรกvy ลพivรฉho chatu pล™es proxy a kontrolujte celรฝ cyklus poลพadavku/odpovฤ›di | -| **Zkuลกebnรญ stolice** | Spusลฅte dรกvkovรฉ testy napล™รญฤ rลฏznรฝmi kombinacemi formรกtลฏ pro ovฤ›ล™enรญ sprรกvnosti pล™ekladu | -| **ลฝivรฝ monitor** | Sledujte pล™eklady v reรกlnรฉm ฤase, jak poลพadavky prochรกzejรญ proxy serverem | - -**Pล™รญpady pouลพitรญ:** - -- Ladฤ›nรญ, proฤ selhรกvรก urฤitรก kombinace klienta/poskytovatele -- Ovฤ›ล™te, zda se tagy myลกlenรญ, volรกnรญ nรกstrojลฏ a systรฉmovรฉ vรฝzvy sprรกvnฤ› pล™eklรกdajรญ. -- Porovnejte rozdรญly ve formรกtech OpenAI, Claude, Gemini a Responses API - ---- - -### Strategie smฤ›rovรกnรญ - -Konfigurace pล™es **Dashboard โ†’ Nastavenรญ โ†’ Routing** . - -| Strategie | Popis | -| ---------------------------- | ------------------------------------------------------------------------------------------------- | -| **Nejprve vyplลˆte** | Pouลพรญvรก รบฤty podle priority โ€“ primรกrnรญ รบฤet zpracovรกvรก vลกechny poลพadavky, dokud nenรญ k dispozici. | -| **Round Robin** | Cykluje mezi vลกemi รบฤty s nastavitelnรฝm trvalรฝm limitem (vรฝchozรญ: 3 volรกnรญ na รบฤet) | -| **P2C (Sรญla dvou moลพnostรญ)** | Vybere 2 nรกhodnรฉ รบฤty a nasmฤ›ruje je k tomu zdravฤ›jลกรญmu โ€“ vyvaลพuje zรกtฤ›ลพ s povฤ›domรญm o zdravรญ | -| **Nรกhodnรฝ** | Nรกhodnฤ› vybere รบฤet pro kaลพdรฝ poลพadavek pomocรญ Fisher-Yatesova nรกhodnรฉho vรฝbฤ›ru. | -| **Nejmรฉnฤ› pouลพรญvanรฉ** | Smฤ›ruje k รบฤtu s nejstarลกรญm ฤasovรฝm razรญtkem `lastUsedAt` a rovnomฤ›rnฤ› rozdฤ›luje provoz. | -| **Optimalizovanรฉ nรกklady** | Smฤ›ruje k รบฤtu s nejniลพลกรญ prioritou a optimalizuje pro poskytovatele s nejniลพลกรญmi nรกklady. | - -#### Aliasy zรกstupnรฝch znakลฏ modelลฏ - -Vytvoล™te zรกstupnรฉ znaky pro pล™emapovรกnรญ nรกzvลฏ modelลฏ: - -``` -Pattern: claude-sonnet-* โ†’ Target: cc/claude-sonnet-4-5-20250929 -Pattern: gpt-* โ†’ Target: gh/gpt-5.1-codex -``` - -Zรกstupnรฉ znaky podporujรญ `*` (libovolnรฝ znak) a `?` (jeden znak). - -#### Zรกloลพnรญ ล™etฤ›zce - -Definujte globรกlnรญ zรกloลพnรญ ล™etฤ›zce, kterรฉ platรญ pro vลกechny poลพadavky: - -``` -Chain: production-fallback - 1. cc/claude-opus-4-6 - 2. gh/gpt-5.1-codex - 3. glm/glm-4.7 -``` - ---- - -### Odolnost a jistiฤe - -Konfigurace pล™es **Dashboard โ†’ Settings โ†’ Resilience** . - -OmniRoute implementuje odolnost na รบrovni poskytovatele se ฤtyล™mi komponentami: - -1. **Profily poskytovatelลฏ** โ€“ Konfigurace pro jednotlivรฉ poskytovatele pro: - - Prรกh selhรกnรญ (poฤet selhรกnรญ pล™ed otevล™enรญm) - - Doba zchlazenรญ - - Citlivost detekce limitu frekvence - - Exponenciรกlnรญ backoff parametry - -2. **Upravitelnรฉ limity rychlosti** โ€“ Vรฝchozรญ nastavenรญ na รบrovni systรฉmu konfigurovatelnรก na ล™รญdicรญm panelu: - - **Poลพadavky za minutu (RPM)** โ€” Maximรกlnรญ poฤet poลพadavkลฏ za minutu na รบฤet - - **Minimรกlnรญ doba mezi poลพadavky** โ€” Minimรกlnรญ mezera v milisekundรกch mezi poลพadavky - - **Max. poฤet soubฤ›ลพnรฝch poลพadavkลฏ** โ€” Maximรกlnรญ poฤet soubฤ›ลพnรฝch poลพadavkลฏ na รบฤet - - Kliknฤ›te na **Upravit** pro รบpravu a potรฉ **na Uloลพit** nebo **Zruลกit** . Hodnoty se uklรกdajรญ prostล™ednictvรญm rozhranรญ API pro odolnost. - -3. **Jistiฤ** โ€“ Sleduje poruchy u jednotlivรฝch poskytovatelลฏ a automaticky rozpojuje obvod, kdyลพ je dosaลพeno prahovรฉ hodnoty: - - **ZAVล˜ENO** (v poล™รกdku) โ€“ Poลพadavky probรญhajรญ normรกlnฤ›. - - **OTEVล˜ENO** โ€” Poskytovatel je doฤasnฤ› zablokovรกn po opakovanรฝch selhรกnรญch - - **HALF_OPEN** โ€” Testovรกnรญ, zda se poskytovatel zotavil - -4. **Zรกsady a uzamฤenรฉ identifikรกtory** โ€“ Zobrazuje stav jistiฤe a uzamฤenรฉ identifikรกtory s moลพnostรญ vynucenรฉho odemฤenรญ. - -5. **Automatickรก detekce limitu rychlosti** โ€“ Monitoruje zรกhlavรญ `429` a `Retry-After` , aby se proaktivnฤ› zabrรกnilo dosaลพenรญ limitลฏ rychlosti poskytovatele. - -**Tip pro profesionรกly:** Pomocรญ tlaฤรญtka **Obnovit vลกe** vymaลพete vลกechny jistiฤe a doby ochlazovรกnรญ, kdyลพ se poskytovatel zotavรญ z vรฝpadku. - ---- - -### Export / import databรกze - -Sprรกva zรกloh databรกze se provรกdรญ v **nabรญdce Ovlรกdacรญ panel โ†’ Nastavenรญ โ†’ Systรฉm a รบloลพiลกtฤ›** . - -| Akce | Popis | -| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -| **Exportovat databรกzi** | Stรกhne aktuรกlnรญ databรกzi SQLite jako soubor `.sqlite` | -| **Exportovat vลกe (.tar.gz)** | Stรกhne kompletnรญ zรกlohu vฤetnฤ›: databรกze, nastavenรญ, kombinacรญ, pล™ipojenรญ k poskytovatelลฏm (bez pล™ihlaลกovacรญch รบdajลฏ) a metadat klรญฤe API. | -| **Importovat databรกzi** | Nahrajte soubor `.sqlite` , kterรฝ nahradรญ aktuรกlnรญ databรกzi. Zรกloha pล™ed importem se vytvoล™รญ automaticky. | - -```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" -``` - -**Ovฤ›ล™enรญ importu:** Importovanรฝ soubor je ovฤ›ล™en z hlediska integrity (kontrola pragma SQLite), poลพadovanรฝch tabulek ( `provider_connections` , `provider_nodes` , `combos` , `api_keys` ) a velikosti (max. 100 MB). - -**Pล™รญpady pouลพitรญ:** - -- Migrace OmniRoute mezi poฤรญtaฤi -- Vytvoล™te externรญ zรกlohy pro zotavenรญ po havรกrii -- Sdรญlenรญ konfiguracรญ mezi ฤleny tรฝmu (exportovat vลกe โ†’ sdรญlet archiv) - ---- - -### Ovlรกdacรญ panel nastavenรญ - -Strรกnka nastavenรญ je pro snadnou navigaci uspoล™รกdรกna do 5 zรกloลพek: - -| Zรกloลพka | Obsah | -| --------------------- | ---------------------------------------------------------------------------------------------------------------- | -| **Zabezpeฤenรญ** | Nastavenรญ pล™ihlรกลกenรญ/hesla, ล™รญzenรญ pล™รญstupu k IP adrese, autorizace API pro `/models` a blokovรกnรญ poskytovatelลฏ | -| **Smฤ›rovรกnรญ** | Globรกlnรญ strategie smฤ›rovรกnรญ (6 moลพnostรญ), aliasy zรกstupnรฝch znakลฏ, zรกloลพnรญ ล™etฤ›zce, kombinovanรฉ vรฝchozรญ hodnoty | -| **Odolnost** | Profily poskytovatelลฏ, upravitelnรฉ limity sazeb, stav jistiฤลฏ, zรกsady a uzamฤenรฉ identifikรกtory | -| **Umฤ›lรก inteligence** | Konfigurace rozpoฤtu promyลกlenรฉho projektu, globรกlnรญ vklรกdรกnรญ promptu do systรฉmu, statistiky mezipamฤ›ti promptu | -| **Modernรญ** | Globรกlnรญ konfigurace proxy (HTTP/SOCKS5) | - ---- - -### Sprรกva nรกkladลฏ a rozpoฤtu - -Pล™รญstup pล™es **Dashboard โ†’ Nรกklady** . - -| Zรกloลพka | รšฤel | -| ------------ | ----------------------------------------------------------------------------------------------------------- | -| **Rozpoฤet** | Nastavte limity รบtrat pro kaลพdรฝ klรญฤ API s dennรญmi/tรฝdennรญmi/mฤ›sรญฤnรญmi rozpoฤty a sledovรกnรญm v reรกlnรฉm ฤase | -| **Ceny** | Zobrazenรญ a รบprava cenovรฝch poloลพek modelu โ€“ cena za 1000 vstupnรญch/vรฝstupnรญch tokenลฏ na poskytovatele | - -```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 -``` - -**Sledovรกnรญ nรกkladลฏ:** Kaลพdรฝ poลพadavek zaznamenรกvรก vyuลพitรญ tokenลฏ a vypoฤรญtรกvรก nรกklady pomocรญ cenรญkovรฉ tabulky. Rozdฤ›lenรญ si mลฏลพete prohlรฉdnout v **sekci Dashboard โ†’ Vyuลพitรญ** podle poskytovatele, modelu a klรญฤe API. - ---- - -### Pล™epis zvuku - -OmniRoute podporuje pล™epis zvuku prostล™ednictvรญm koncovรฉho bodu kompatibilnรญho s OpenAI: - -```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" -``` - -Dostupnรญ poskytovatelรฉ: **Deepgram** ( `deepgram/` ), **AssemblyAI** ( `assemblyai/` ). - -Podporovanรฉ zvukovรฉ formรกty: `mp3` , `wav` , `m4a` , `flac` , `ogg` , `webm` . - ---- - -### Strategie kombinovanรฉho vyvaลพovรกnรญ - -Nastavte vyvaลพovรกnรญ jednotlivรฝch kombinacรญ v **nabรญdce Dashboard โ†’ Kombinace โ†’ Vytvoล™it/Upravit โ†’ Strategie** . - -| Strategie | Popis | -| ------------------------------------- | ------------------------------------------------------------------------------------- | -| **Round-Robin** | Postupnฤ› prochรกzรญ modely | -| **Pล™ednost** | Vลพdy se pokusรญ o prvnรญ model; vracรญ se pouze v pล™รญpadฤ› chyby. | -| **Nรกhodnรฝ** | Pro kaลพdรฝ poลพadavek vybere nรกhodnรฝ model z komba | -| **Vรกลพenรฉ** | Trasy proporcionรกlnฤ› na zรกkladฤ› pล™iล™azenรฝch vah pro kaลพdรฝ model | -| **Nejmรฉnฤ› pouลพรญvanรฉ** | Smฤ›ruje k modelu s nejmenลกรญm poฤtem nedรกvnรฝch poลพadavkลฏ (pouลพรญvรก kombinovanรฉ metriky) | -| **Optimalizovanรฉ z hlediska nรกkladลฏ** | Trasy k nejlevnฤ›jลกรญmu dostupnรฉmu modelu (pouลพรญvรก cenรญk) | - -Globรกlnรญ vรฝchozรญ hodnoty kombinacรญ lze nastavit v **nabรญdce Dashboard โ†’ Settings โ†’ Routing โ†’ Combo Defaults** . - ---- - -### Dashboard zdravรญ - -Pล™รญstup pล™es **Dashboard โ†’ Stav** . Pล™ehled stavu systรฉmu v reรกlnรฉm ฤase se 6 kartami: - -| Karta | Co to ukazuje | -| ------------------------ | ------------------------------------------------------------------ | -| **Stav systรฉmu** | Doba provozuschopnosti, verze, vyuลพitรญ pamฤ›ti, datovรฝ adresรกล™ | -| **Zdravรญ poskytovatelลฏ** | Stav jistiฤe podle dodavatele (Zapnuto/Vypnuto/Napลฏl vypnuto) | -| **Limity sazeb** | Aktivnรญ limit rychlosti cooldownลฏ na รบฤet se zbรฝvajรญcรญm ฤasem | -| **Aktivnรญ vรฝluky** | Poskytovatelรฉ doฤasnฤ› blokovanรญ politikou uzamฤenรญ | -| **Mezipamฤ›ลฅ podpisลฏ** | Statistiky mezipamฤ›ti pro deduplikaci (aktivnรญ klรญฤe, mรญra zรกsahลฏ) | -| **Telemetrie latence** | Agregace latence p50/p95/p99 na poskytovatele | - -**Tip pro profesionรกly:** Strรกnka Zdravรญ se automaticky obnovuje kaลพdรฝch 10 sekund. Pomocรญ karty jistiฤe mลฏลพete zjistit, kteล™รญ poskytovatelรฉ majรญ problรฉmy. - ---- - -## ๐Ÿ–ฅ๏ธ Desktopovรก aplikace (Electron) - -OmniRoute je k dispozici jako nativnรญ desktopovรก aplikace pro Windows, macOS a Linux. - -### Instalace - -```bash -# From the electron directory: -cd electron -npm install - -# Development mode (connect to running Next.js dev server): -npm run dev - -# Production mode (uses standalone build): -npm start -``` - -### Instalatรฉล™i budov - -```bash -cd electron -npm run build # Current platform -npm run build:win # Windows (.exe NSIS) -npm run build:mac # macOS (.dmg universal) -npm run build:linux # Linux (.AppImage) -``` - -Vรฝstup โ†’ `electron/dist-electron/` - -### Klรญฤovรฉ vlastnosti - -| Funkce | Popis | -| ----------------------------- | -------------------------------------------------------------------- | -| **Pล™ipravenost serveru** | Pล™ed zobrazenรญm okna se dotazuje server (ลพรกdnรก prรกzdnรก obrazovka) | -| **Systรฉmovรฝ zรกsobnรญk** | Minimalizovat do zรกsobnรญku, zmฤ›nit port, ukonฤit menu v zรกsobnรญku | -| **Sprรกva pล™รญstavลฏ** | Zmฤ›na portu serveru z panelu รบloh (automatickรฉ restartovรกnรญ serveru) | -| **Zรกsady zabezpeฤenรญ obsahu** | Omezujรญcรญ CSP prostล™ednictvรญm zรกhlavรญ relace | -| **Jedna instance** | V danรฉm okamลพiku mลฏลพe bฤ›ลพet pouze jedna instance aplikace | -| **Offline reลพim** | Dodรกvanรฝ server Next.js funguje bez internetu | - -### Promฤ›nnรฉ prostล™edรญ - -| Promฤ›nnรก | Vรฝchozรญ | Popis | -| --------------------- | ------- | --------------------------------- | -| `OMNIROUTE_PORT` | `20128` | Port serveru | -| `OMNIROUTE_MEMORY_MB` | `512` | Limit haldy Node.js (64โ€“16384 MB) | - -๐Ÿ“– รšplnรก dokumentace: [`electron/README.md`](../electron/README.md) diff --git a/docs/i18n/cs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/cs/VM_DEPLOYMENT_GUIDE.md deleted file mode 100644 index c33bb94069..0000000000 --- a/docs/i18n/cs/VM_DEPLOYMENT_GUIDE.md +++ /dev/null @@ -1,401 +0,0 @@ -# Prลฏvodce nasazenรญm OmniRoute na VM s Cloudflare - -๐ŸŒ **Jazyky:** ๐Ÿ‡บ๐Ÿ‡ธ [English](VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](i18n/cs/VM_DEPLOYMENT_GUIDE.md) - -Kompletnรญ prลฏvodce instalacรญ a konfiguracรญ OmniRoute na virtuรกlnรญm stroji (VPS) se sprรกvou domรฉny prostล™ednictvรญm Cloudflare. - ---- - -## Pล™edpoklady - -| Poloลพka | Minimรกlnรญ | Doporuฤeno | -| ------------ | --------------------------- | ---------------- | -| **Procesor** | 1 virtuรกlnรญ procesor | 2 vCPU | -| **RAM** | 1 GB | 2 GB | -| **Disk** | 10GB SSD | 25GB SSD | -| **CPU** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS | -| **Domรฉna** | Zaregistrovรกna v Cloudflare | โ€” | -| **Docker** | Docker Engine 24+ | Docker 27+ | - -**Testovanรญ poskytovatelรฉ**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. - ---- - -## 1. Konfigurace virtuรกlnรญho poฤรญtaฤe - -### 1.1 Vytvoล™it ihned - -ลฝรกdnรฝ preferovanรฝ poskytovatel VPS: - -- Vyberte si Ubuntu 24.04 LTS -- Vyberte minimรกlnรญ plรกn (1 vCPU / 1 GB RAM) -- Nastavte silnรฉ heslo pro root nebo konfiguraci SSH klรญฤe -- Poznamenejte si **veล™ejnou IP** (napล™.: `203.0.113.10`) - -### 1.2 Pล™ipojenรญ pล™es SSH - -```bash -ssh root@203.0.113.10 -``` - -### 1.3 Aktualizace systรฉmu - -```bash -apt update && apt upgrade -y -``` - -### 1.4 Instalace Dockeru - -```bash -# Nainstalovat zรกvislosti -apt install -y ca-certificates curl gnupg - -# Pล™idat oficiรกlnรญ Docker repository -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 Instalace nginxu - -```bash -apt install -y nginx -``` - -### 1.6 Konfigurace firewallu (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 -``` - -> **Tip**: Pro maximรกlnรญ zabezpeฤenรญ omezte porty 80 a 443 pouze na IP Cloudflare. Viz sekce [Pokroฤilรฉ zabezpeฤenรญ](#pokrocilรฉ-zabezpeฤenรญ). - ---- - -## 2. Instalace OmniRoute - -### 2.1 Vytvoล™it konfiguraฤnรญ adresรกล™ - -```bash -mkdir -p /opt/omniroute -``` - -### 2.2 Vytvoล™it soubor s promฤ›nnรฝmi prostล™edรญ - -```bash -cat > /opt/omniroute/.env << 'EOF' -# === Bezpeฤnost === -JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY -INITIAL_PASSWORD=YourSecurePassword123! -API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY -STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY -STORAGE_ENCRYPTION_KEY_VERSION=v1 -MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT - -# === 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 - -# === Domรฉna (zmฤ›ลˆte na vaลกi domรฉnu) === -BASE_URL=https://llms.vasedomena.com -NEXT_PUBLIC_BASE_URL=https://llms.vasedomena.com - -# === Cloud Sync (opcional) === -# CLOUD_URL=https://cloud.omniroute.online -# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online -EOF -``` - -> โš ๏ธ **DลฎLEลฝITร‰**: Vygenerujte jedineฤnรฉ tajnรฉ klรญฤe! Pouลพijte `openssl rand -hex 32` pro kaลพdรฝ klรญฤ. - -### 2.3 Spuลกtฤ›nรญ kontejneru - -```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 -``` - -Vรฝvojovรฝ pล™รญklad: `[DB] SQLite database ready` a `listening on port 20128` . - ---- - -## 3. Konfigurace nginx (reverznรญ proxy) - -### 3.1 Vygenerovat SSL certifikรกt (Cloudflare Origin) - -Cloudflare nic neล™eลกรญ: - -1. Pouลพรญvรก **SSL/TLS โ†’ Origin Server** -2. Kliknฤ›te na **Vytvoล™it certifikรกt** -3. Ponechte vรฝchozรญ nastavenรญ (15 let, \*.vasedomena.com) -4. Zkopรญrujte nebo zkopรญrujte **certifikรกt pลฏvodu** a **soukromรฝ klรญฤ** - -```bash -mkdir -p /etc/nginx/ssl - -# Vloลพit certifikรกt -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 Konfigurace nginxu - -```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.vasedomena.com; # Zmฤ›ลˆte na vaลกi domรฉnu - - 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.vasedomena.com; - return 301 https://$server_name$request_uri; -} -NGINX -``` - -### 3.3 Ativar a testovรกnรญ - -```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. Konfigurace DNS v Cloudflare - -### 4.1 Dalลกรญ DNS registr - -V dashboardu Cloudflare โ†’ DNS: - -| Typ | Jmรฉno | Obsah | Proxy | -| --- | ------ | ----------------------------------------------- | -------- | -| A | `llms` | `203.0.113.10` (IP adresa virtuรกlnรญho poฤรญtaฤe) | โœ… Proxy | - -### 4.2 Konfigurace SSL - -Em **SSL/TLS โ†’ Pล™ehled** : - -- Reลพim: **Plnรฝ (Pล™รญsnรฝ)** - -V **SSL/TLS โ†’ Edge Certificates**: - -- Vลพdy pouลพรญvat HTTPS: โœ… Zapnuto -- Minimรกlnรญ verze TLS: TLS 1.2 -- Automatickรฉ pล™episovรกnรญ HTTPS: โœ… Zapnuto - -### 4.3 Testar - -```bash -curl -sI https://llms.vasedomena.com/health -# Deve retornar HTTP/2 200 -``` - ---- - -## 5. Operace a รบdrลพba - -### Aktualizovat na novou verzi - -```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 -``` - -### Verzovnรญ protokoly - -```bash -docker logs -f omniroute # ลฝivรฝ stream -docker logs omniroute --tail 50 # รšltimas 50 linhas -``` - -### Ruฤnรญ zรกlohovรกnรญ banky - -```bash -# Kopรญrovat data z volume do hostitele -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 -``` - -### Obnovenรญ zรกlohy - -```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. Pokroฤilรก bezpeฤnost - -### Omezte pล™รญstup k IP Cloudflare - -```bash -cat > /etc/nginx/cloudflare-ips.conf << 'CF' -# Cloudflare IPv4 ranges โ€” aktualizovat pravidelnฤ› -# 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 -``` - -Pล™idat do `nginx.conf` do bloku `http {}`: - -```nginx -include /etc/nginx/cloudflare-ips.conf; -``` - -### Nainstalujte fail2ban - -```bash -apt install -y fail2ban -systemctl enable fail2ban -systemctl start fail2ban - -# Verificar status -fail2ban-client status sshd -``` - -### Bloquear accesso direto na port do Docker - -```bash -# Zamezit pล™รญmรฉmu externรญmu pล™รญstupu k portu 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. Nasazenรญ cloudovรฉho pracovnรญka (volitelnรฉ) - -Vzdรกlenรฝ pล™รญstup pล™es Cloudflare Workers (zde exponovat diretament VM): - -```bash -# No repositรณrio local -cd omnirouteCloud -npm install -npx wrangler login -npx wrangler deploy -``` - -Dokumenty jsou kompletnรญ pro [omnirouteCloud/README.md](../omnirouteCloud/README.md) . - ---- - -## Pล™ehled portลฏ - -| Port | Sluลพba | Pล™รญstup | -| ----- | ----------- | ---------------------------------------- | -| 22 | SSH | Veล™ejnรฉ (s fail2ban) | -| 80 | nginx HTTP | Pล™esmฤ›rovรกnรญ โ†’ HTTPS | -| 443 | nginx HTTPS | Prostล™ednictvรญm proxy serveru Cloudflare | -| 20128 | OmniRoute | Nฤ›kdy na localhostu (pล™es nginx) | diff --git a/docs/i18n/cs/adr/0001-proxy-registry-limit-generalization.md b/docs/i18n/cs/adr/0001-proxy-registry-limit-generalization.md deleted file mode 100644 index cb1ba57871..0000000000 --- a/docs/i18n/cs/adr/0001-proxy-registry-limit-generalization.md +++ /dev/null @@ -1,45 +0,0 @@ -# ADR-0001: Zobecnฤ›nรญ registru proxy serverลฏ + kontroly vyuลพitรญ - -Datum: 17. 3. 2026 Stav: Pล™ijato - -## Kontext - -OmniRoute je uลพiteฤnรฝ: - -- Pล™iล™azenรญ proxy na zรกkladฤ› konfiguraฤnรญ mapy ( `global` , `providers` , `combos` , `keys` ). -- Vรฝbฤ›r s ohledem na kvรณty poskytovatele khusus tertentu (zejmรฉna `codex` ). - -Mezera utama: - -- Proxy belum menjadi asset opakovanฤ› pouลพitelnรฝ jang bisa di-manage sebagai entitas (metadata, kde se pouลพรญvajรญ, bezpeฤnรฉ smazรกnรญ). -- Zรกsady pouลพitรญ belum konsisten lintas provider. -- Chybovรก smlouva API belum seragam untuk manajemen endpoint manajemen. - -## Rozhodnutรญ - -1. Tambah **Proxy Registry** sebegai domรฉny baru di DB ( `proxy_registry` , `proxy_assignments` ). -2. Stรกlรก kompatibilita pล™iล™azenรญ lama (zรกloลพnรญ lama `proxyConfig` ). -3. Priority pakai runtime modulu Resolver: - - รบฤet -> poskytovatel -> globรกlnรญ (registr) - - zรกloลพnรญ ke legacy resolver jika registry belum ada pล™iล™azenรญ -4. Vรฝchozรญ registr vรฝstupnรญho seznamu Wajib redaction kredensial di. -5. Standarkan error JSON unuk endpoint manajemen proxy agar konsisten dan punya `requestId` . - -## Dลฏsledky - -Pozitivnรญ: - -- Opakovanฤ› pouลพitelnรฝ proxy server. -- Bezpeฤnรฉ odstranฤ›nรญ bisa ditegakkan (409 saat masih dipakai). -- Migrasi bertahap tanpa prolomenรญ runtime zmฤ›n. - -Negativnรญ: - -- Ada dual-source sementara (registr + starลกรญ konfigurace) sampai migrasi selesai. -- Ale pล™iล™azenรญ koncovรฝch bodลฏ tambahan a pemetaan rozsah a rozsah. - -## Nรกslednรก opatล™enรญ - -- Poskytovatel uลพivatelskรฉho rozhranรญ Migrasi/รบฤet umoลพลˆuje zadat nezpracovanรฝ registr selektoru proxy serveru. -- Telemetrie zdravรญ Tambah na proxy a upozornฤ›nรญ. -- Vลกeobecnรก kontrola pouลพรญvรกnรญ ke poskytovateli lain melalui interface policy yang sama. diff --git a/docs/i18n/cs/adr/0002-api-error-contract-management-endpoints.md b/docs/i18n/cs/adr/0002-api-error-contract-management-endpoints.md deleted file mode 100644 index f3be181aa3..0000000000 --- a/docs/i18n/cs/adr/0002-api-error-contract-management-endpoints.md +++ /dev/null @@ -1,31 +0,0 @@ -# ADR-0002: Chybovรก smlouva pro koncovรฉ body sprรกvy - -Datum: 17. 3. 2026 Stav: Pล™ijato - -## Rozhodnutรญ - -Koncovรฉ body sprรกvy (konfigurace proxy, registr proxy a pล™iล™azenรญ proxy) vracejรญ jednotnรฉ tฤ›lo chyby: - -```json -{ - "error": { - "message": "Human-readable summary", - "type": "invalid_request | not_found | conflict | server_error", - "details": {} - }, - "requestId": "uuid" -} -``` - -## Mapovรกnรญ stavu - -- 400: neplatnรฝ poลพadavek / selhรกnรญ ovฤ›ล™enรญ -- 404: zdroj nenalezen -- 409: konflikt zdrojลฏ (napล™รญklad proxy stรกle pล™iล™azen) -- 500: neoฤekรกvanรก chyba serveru - -## Poznรกmky - -- `requestId` je povinnรฝ pro korelaci protokolลฏ. -- `details` je volitelnรฉ a pouลพรญvรก se pouze pro bezpeฤnรฉ ovฤ›ล™enรญ detailลฏ. -- Citlivรฉ tajnรฉ informace (pล™ihlaลกovacรญ รบdaje proxy, tokeny) se nikdy nesmรญ objevit ve `message` ani v `details` . diff --git a/docs/i18n/cs/adr/0003-security-checklist-proxy-limits.md b/docs/i18n/cs/adr/0003-security-checklist-proxy-limits.md deleted file mode 100644 index e6ac963c3a..0000000000 --- a/docs/i18n/cs/adr/0003-security-checklist-proxy-limits.md +++ /dev/null @@ -1,15 +0,0 @@ -# ADR-0003: Kontrolnรญ seznam zabezpeฤenรญ pro registr proxy a kontroly pouลพรญvรกnรญ - -Datum: 17. 3. 2026 Stav: Pล™ijato - -## Kontrolnรญ seznam - -- Ovฤ›ล™te vลกechny datovรฉ ฤรกsti sprรกvy pomocรญ Zodu. -- Odmรญtnout aktualizace chybnฤ› formรกtovanรฉho pล™iล™azenรญ rozsahu se stavem 400. -- Odmรญtnout smazรกnรญ pouลพรญvanรฉ proxy se stavem 409, pokud to nenรญ vynuceno. -- Ve vรฝchozรญm nastavenรญ nikdy nezobrazovat uลพivatelskรฉ jmรฉno/heslo proxy v odpovฤ›dรญch seznamu. -- Nikdy nezaznamenรกvejte nezpracovanรฉ pล™ihlaลกovacรญ รบdaje ani hodnoty tokenลฏ. -- Udrลพujte chybovรฉ odpovฤ›di bez internรญch trasovรกnรญ zรกsobnรญku. -- Chraลˆte koncovรฉ body sprรกvy pomocรญ stรกvajรญcรญch zรกsad middlewaru pro ovฤ›ล™ovรกnรญ. -- Auditovat mutujรญcรญ operace: vytvoล™it/aktualizovat/smazat/pล™iล™adit/migraci. -- Zajistฤ›te, aby se resolver bฤ›hem pล™echodu vrรกtil k pลฏvodnรญ konfiguraci. diff --git a/docs/i18n/cs/docs/A2A-SERVER.md b/docs/i18n/cs/docs/A2A-SERVER.md new file mode 100644 index 0000000000..e8f673c33a --- /dev/null +++ b/docs/i18n/cs/docs/A2A-SERVER.md @@ -0,0 +1,200 @@ +# OmniRoute A2A Server Documentation (ฤŒeลกtina) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/A2A-SERVER.md) + +--- + +> Agent-to-Agent Protocol v0.3 โ€” OmniRoute as an intelligent routing agent + +## Agent Discovery + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements. + +--- + +## Authentication + +All `/a2a` requests require an API key via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server, authentication is bypassed. + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Sends a message to a skill and waits for the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a hello world in Python"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "uuid", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "..." }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}} + +: heartbeat 2026-03-03T17:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Available Skills + +| Skill | Description | +| :----------------- | :------------------------------------------------------------------------------------------------------------------------------ | +| `smart-routing` | Routes prompts through OmniRoute's intelligent pipeline. Returns response with routing explanation, cost, and resilience trace. | +| `quota-management` | Answers natural-language queries about provider quotas, suggests free combos, and provides quota rankings. | + +--- + +## Task Lifecycle + +``` +submitted โ†’ working โ†’ completed + โ†’ failed + โ†’ cancelled +``` + +- Tasks expire after 5 minutes (configurable) +- Terminal states: `completed`, `failed`, `cancelled` +- Event log tracks every state transition + +--- + +## Error Codes + +| Code | Meaning | +| :----- | :----------------------------- | +| -32700 | Parse error (invalid JSON) | +| -32600 | Invalid request / Unauthorized | +| -32601 | Method or skill not found | +| -32602 | Invalid params | +| -32603 | Internal error | + +--- + +## Integration Examples + +### Python (requests) + +```python +import requests + +resp = requests.post("http://localhost:20128/a2a", json={ + "jsonrpc": "2.0", "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Hello"}] + } +}, headers={"Authorization": "Bearer YOUR_KEY"}) + +result = resp.json()["result"] +print(result["artifacts"][0]["content"]) +print(result["metadata"]["routing_explanation"]) +``` + +### TypeScript (fetch) + +```typescript +const resp = await fetch("http://localhost:20128/a2a", { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: "Bearer YOUR_KEY", + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "1", + method: "message/send", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Hello" }], + }, + }), +}); +const { result } = await resp.json(); +console.log(result.metadata.routing_explanation); +``` diff --git a/docs/i18n/cs/docs/API_REFERENCE.md b/docs/i18n/cs/docs/API_REFERENCE.md new file mode 100644 index 0000000000..b02cec2c81 --- /dev/null +++ b/docs/i18n/cs/docs/API_REFERENCE.md @@ -0,0 +1,465 @@ +# API Reference (ฤŒeลกtina) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/API_REFERENCE.md) + +--- + +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 | +| `X-Session-Id` | Request | Sticky session key for external session affinity | +| `x_session_id` | Request | Underscore variant also accepted (direct HTTP) | +| `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 | +| `X-OmniRoute-Session-Id` | Response | Effective session ID used by OmniRoute | + +> Nginx note: if you rely on underscore headers (for example `x_session_id`), enable `underscores_in_headers 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/stats + +# Clear all caches +DELETE /api/cache/stats +``` + +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/PATCH | 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 + provider summary (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`) | +| `/api/cache/stats` | 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 | + +### Tunnels + +| Endpoint | Method | Description | +| -------------------------- | ------ | ----------------------------------------------------------------------- | +| `/api/tunnels/cloudflared` | GET | Read Cloudflare Quick Tunnel install/runtime status for the dashboard | +| `/api/tunnels/cloudflared` | POST | Enable or disable the Cloudflare Quick Tunnel (`action=enable/disable`) | + +### 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`. + +### ACP Agents + +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | + +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). + +### Resilience & Rate Limits + +| Endpoint | Method | Description | +| ----------------------- | --------- | ------------------------------- | +| `/api/resilience` | GET/PATCH | 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` diff --git a/docs/i18n/cs/docs/ARCHITECTURE.md b/docs/i18n/cs/docs/ARCHITECTURE.md new file mode 100644 index 0000000000..122e80eda2 --- /dev/null +++ b/docs/i18n/cs/docs/ARCHITECTURE.md @@ -0,0 +1,814 @@ +# OmniRoute Architecture (ฤŒeลกtina) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/ARCHITECTURE.md) + +--- + +_Last updated: 2026-03-28_ + +## 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 (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developerโ†’system, systemโ†’user) for cross-provider compatibility +- Structured output conversion (json_schema โ†’ Gemini responseSchema) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) +- Global system prompt injection +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout โ†’ budget โ†’ fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) + +Primary runtime model: + +- Next.js 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.) + +## Dashboard Surface (Current) + +Main pages under `src/app/(dashboard)/dashboard/`: + +- `/dashboard` โ€” quick start + provider overview +- `/dashboard/endpoint` โ€” endpoint proxy + MCP + A2A + API endpoint tabs +- `/dashboard/providers` โ€” provider connections and credentials +- `/dashboard/combos` โ€” combo strategies, templates, model routing rules +- `/dashboard/costs` โ€” cost aggregation and pricing visibility +- `/dashboard/analytics` โ€” usage analytics and evaluations +- `/dashboard/limits` โ€” quota/rate controls +- `/dashboard/cli-tools` โ€” CLI onboarding, runtime detection, config generation +- `/dashboard/agents` โ€” detected ACP agents + custom agent registration +- `/dashboard/media` โ€” image/video/music playground +- `/dashboard/search-tools` โ€” search provider testing and history +- `/dashboard/health` โ€” uptime, circuit breakers, rate limits +- `/dashboard/logs` โ€” request/proxy/audit/console logs +- `/dashboard/settings` โ€” system settings tabs (general, routing, combo defaults, etc.) +- `/dashboard/api-manager` โ€” API key lifecycle and model permissions + +## 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[(storage.sqlite)] + UDB[(usage tables + log artifacts)] + end + + subgraph Upstreams[Upstream Providers] + P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/Qoder/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/route.ts` (GET) +- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- OAuth: `src/app/api/oauth/*` +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` +- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI tooling helpers: `src/app/api/cli-tools/*` +- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) +- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) โ€” provider profiles, circuit breaker, rate limit state +- Resilience reset: `src/app/api/resilience/reset` (POST) โ€” reset breakers + cooldowns +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) +- Telemetry: `src/app/api/telemetry/summary` (GET) +- Budget: `src/app/api/usage/budget` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Policies: `src/app/api/policies` (GET/POST) + +## 2) SSE + 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` +- Response sanitization: `open-sse/handlers/responseSanitizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.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`, `qoder.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 (SQLite): + +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** + +Usage persistence: + +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present + +Domain State DB (SQLite): + +- `src/lib/db/domainState.ts` โ€” CRUD operations 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`, `src/shared/services/modelSyncScheduler.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Periodic task: `src/shared/services/modelSyncScheduler.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. Combo routing adds one extra guard: provider-scoped 400s such as upstream content-block and role-validation failures are treated as model-local failures so later combo targets can still run. + +## 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: + +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` + +## Deployment Topology + +```mermaid +flowchart LR + 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[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] + end + + subgraph External[External Services] + Providers[AI Providers] + SyncCloud[Cloud Sync Service] + end + + CLI --> Next + Browser --> Next + Next --> Core + Next --> MainDB + Core --> MainDB + Core --> UsageDB + Core --> Providers + Next --> SyncCloud +``` + +## Module Mapping (Decision-Critical) + +### Route and API Modules + +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle +- `src/app/api/models/alias`: alias management +- `src/app/api/combos*`: fallback combo management +- `src/app/api/pricing`: pricing overrides for cost calculation +- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers +- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) +- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) +- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) +- `src/app/api/sessions`: active session listing (GET) +- `src/app/api/rate-limits`: per-account rate limit status (GET) + +### Routing and Execution Core + +- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior + +### Translation Registry and Format Converters + +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` +- Format constants: `open-sse/translator/formats.ts` + +### Persistence + +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables + +## Provider Executor Coverage (Strategy Pattern) + +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. + +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, Qoder, 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 | +| Qoder | openai | OAuth (Basic) | โœ… | โœ… | โœ… | โš ๏ธ Per request | +| OpenRouter | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| GLM/Kimi/MiniMax | claude | API Key | โœ… | โœ… | โŒ | โŒ | +| DeepSeek | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Groq | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| xAI (Grok) | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Mistral | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Perplexity | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Together AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Fireworks AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Cerebras | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Cohere | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| NVIDIA NIM | openai | API Key | โœ… | โœ… | โŒ | โŒ | + +## Format Translation Coverage + +Detected source formats include: + +- `openai` +- `openai-responses` +- `claude` +- `gemini` + +Target formats include: + +- OpenAI chat/Responses +- Claude +- Gemini/Gemini-CLI/Antigravity envelope +- Kiro +- Cursor + +Translations use **OpenAI as the hub format** โ€” all conversions go through OpenAI as intermediate: + +``` +Source Format โ†’ OpenAI (hub) โ†’ Target Format +``` + +Translations are selected dynamically based on source payload shape and provider target format. + +Additional processing layers in the translation pipeline: + +- **Response sanitization** โ€” Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI targets; merges `system` โ†’ `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** โ€” Parses `...` blocks from content into `reasoning_content` field +- **Structured output** โ€” Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` + +## Supported API Endpoints + +| 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` | Provider Models | Provider model metadata backing custom and managed available models | + +## 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 `/logs//` 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 + +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON โ†’ SQLite migration compatibility path + +## Observability and Operational Signals + +Runtime visibility sources: + +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- four-stage detailed payload captures in SQLite (`request_detail_logs`) when `settings.detailed_logs_enabled=true` +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption + +Detailed request payload capture stores up to four JSON payload stages per routed call: + +- raw request received from the client +- translated request actually sent upstream +- provider response reconstructed as JSON; streamed responses are compacted to the final summary plus stream metadata +- final client response returned by OmniRoute; streamed responses are stored in the same compact summary form + +## Security-Sensitive Boundaries + +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics + +## Environment and Runtime Matrix + +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` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). + +## Operational Verification Checklist + +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: +- `GET /api/settings` +- `GET /api/v1/models` +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/cs/docs/AUTO-COMBO.md b/docs/i18n/cs/docs/AUTO-COMBO.md new file mode 100644 index 0000000000..87e38de265 --- /dev/null +++ b/docs/i18n/cs/docs/AUTO-COMBO.md @@ -0,0 +1,67 @@ +# OmniRoute Auto-Combo Engine (ฤŒeลกtina) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/AUTO-COMBO.md) + +--- + +> Self-managing model chains with adaptive scoring + +## How It Works + +The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**: + +| Factor | Weight | Description | +| :--------- | :----- | :---------------------------------------------- | +| Quota | 0.20 | Remaining capacity [0..1] | +| Health | 0.25 | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 | +| CostInv | 0.20 | Inverse cost (cheaper = higher score) | +| LatencyInv | 0.15 | Inverse p95 latency (faster = higher) | +| TaskFit | 0.10 | Model ร— task type fitness score | +| Stability | 0.10 | Low variance in latency/errors | + +## Mode Packs + +| Pack | Focus | Key Weight | +| :---------------------- | :----------- | :--------------- | +| ๐Ÿš€ **Ship Fast** | Speed | latencyInv: 0.35 | +| ๐Ÿ’ฐ **Cost Saver** | Economy | costInv: 0.40 | +| ๐ŸŽฏ **Quality First** | Best model | taskFit: 0.40 | +| ๐Ÿ“ก **Offline Friendly** | Availability | quota: 0.40 | + +## Self-Healing + +- **Temporary exclusion**: Score < 0.2 โ†’ excluded for 5 min (progressive backoff, max 30 min) +- **Circuit breaker awareness**: OPEN โ†’ auto-excluded; HALF_OPEN โ†’ probe requests +- **Incident mode**: >50% OPEN โ†’ disable exploration, maximize stability +- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout + +## Bandit Exploration + +5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode. + +## API + +```bash +# Create auto-combo +curl -X POST http://localhost:20128/api/combos/auto \ + -H "Content-Type: application/json" \ + -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}' + +# List auto-combos +curl http://localhost:20128/api/combos/auto +``` + +## Task Fitness + +30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` โ†’ high coding score). + +## Files + +| File | Purpose | +| :------------------------------------------- | :------------------------------------ | +| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization | +| `open-sse/services/autoCombo/taskFitness.ts` | Model ร— task fitness lookup | +| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap | +| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode | +| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles | +| `src/app/api/combos/auto/route.ts` | REST API | diff --git a/docs/i18n/cs/docs/CLI-TOOLS.md b/docs/i18n/cs/docs/CLI-TOOLS.md new file mode 100644 index 0000000000..4bc5c08051 --- /dev/null +++ b/docs/i18n/cs/docs/CLI-TOOLS.md @@ -0,0 +1,348 @@ +# CLI Tools Setup Guide โ€” OmniRoute (ฤŒeลกtina) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CLI-TOOLS.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CLI-TOOLS.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CLI-TOOLS.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CLI-TOOLS.md) + +--- + +This guide explains how to install and configure all supported AI coding CLI tools +to use **OmniRoute** as the unified backend, giving you centralized key management, +cost tracking, model switching, and request logging across every tool. + +--- + +## How It Works + +``` +Claude / Codex / OpenCode / Cline / KiloCode / Continue / Kiro / Cursor / Copilot + โ”‚ + โ–ผ (all point to OmniRoute) + http://YOUR_SERVER:20128/v1 + โ”‚ + โ–ผ (OmniRoute routes to the right provider) + Anthropic / OpenAI / Gemini / DeepSeek / Groq / Mistral / ... +``` + +**Benefits:** + +- One API key to manage all tools +- Cost tracking across all CLIs in the dashboard +- Model switching without reconfiguring every tool +- Works locally and on remote servers (VPS) + +--- + +## Supported Tools (Dashboard Source of Truth) + +The dashboard cards in `/dashboard/cli-tools` are generated from `src/shared/constants/cliTools.ts`. +Current list (v3.0.0-rc.16): + +| Tool | ID | Command | Setup Mode | Install Method | +| ------------------ | ------------- | ---------- | ---------- | -------------- | +| **Claude Code** | `claude` | `claude` | env | npm | +| **OpenAI Codex** | `codex` | `codex` | custom | npm | +| **Factory Droid** | `droid` | `droid` | custom | bundled/CLI | +| **OpenClaw** | `openclaw` | `openclaw` | custom | bundled/CLI | +| **Cursor** | `cursor` | app | guide | desktop app | +| **Cline** | `cline` | `cline` | custom | npm | +| **Kilo Code** | `kilo` | `kilocode` | custom | npm | +| **Continue** | `continue` | extension | guide | VS Code | +| **Antigravity** | `antigravity` | internal | mitm | OmniRoute | +| **GitHub Copilot** | `copilot` | extension | custom | VS Code | +| **OpenCode** | `opencode` | `opencode` | guide | npm | +| **Kiro AI** | `kiro` | app/cli | mitm | desktop/CLI | + +### CLI fingerprint sync (Agents + Settings) + +`/dashboard/agents` and `Settings > CLI Fingerprint` use `src/shared/constants/cliCompatProviders.ts`. +This keeps provider IDs aligned with CLI cards and legacy IDs. + +| CLI ID | Fingerprint Provider ID | +| ---------------------------------------------------------------------------------------------------- | ----------------------- | +| `kilo` | `kilocode` | +| `copilot` | `github` | +| `claude` / `codex` / `antigravity` / `kiro` / `cursor` / `cline` / `opencode` / `droid` / `openclaw` | same ID | + +Legacy IDs still accepted for compatibility: `copilot`, `kimi-coding`, `qwen`. + +--- + +## Step 1 โ€” Get an OmniRoute API Key + +1. Open the OmniRoute dashboard โ†’ **API Manager** (`/dashboard/api-manager`) +2. Click **Create API Key** +3. Give it a name (e.g. `cli-tools`) and select all permissions +4. Copy the key โ€” you'll need it for every CLI below + +> Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` + +--- + +## Step 2 โ€” Install CLI Tools + +All npm-based tools require Node.js 18+: + +```bash +# Claude Code (Anthropic) +npm install -g @anthropic-ai/claude-code + +# OpenAI Codex +npm install -g @openai/codex + +# OpenCode +npm install -g opencode-ai + +# Cline +npm install -g cline + +# KiloCode +npm install -g kilocode + +# Kiro CLI (Amazon โ€” requires curl + unzip) +apt-get install -y unzip # on Debian/Ubuntu +curl -fsSL https://cli.kiro.dev/install | bash +export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc +``` + +**Verify:** + +```bash +claude --version # 2.x.x +codex --version # 0.x.x +opencode --version # x.x.x +cline --version # 2.x.x +kilocode --version # x.x.x (or: kilo --version) +kiro-cli --version # 1.x.x +``` + +--- + +## Step 3 โ€” Set Global Environment Variables + +Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`: + +```bash +# OmniRoute Universal Endpoint +export OPENAI_BASE_URL="http://localhost:20128/v1" +export OPENAI_API_KEY="sk-your-omniroute-key" +export ANTHROPIC_BASE_URL="http://localhost:20128/v1" +export ANTHROPIC_API_KEY="sk-your-omniroute-key" +export GEMINI_BASE_URL="http://localhost:20128/v1" +export GEMINI_API_KEY="sk-your-omniroute-key" +``` + +> For a **remote server** replace `localhost:20128` with the server IP or domain, +> e.g. `http://192.168.0.15:20128`. + +--- + +## Step 4 โ€” Configure Each Tool + +### Claude Code + +```bash +# Via CLI: +claude config set --global api-base-url http://localhost:20128/v1 + +# Or create ~/.claude/settings.json: +mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF +{ + "apiBaseUrl": "http://localhost:20128/v1", + "apiKey": "sk-your-omniroute-key" +} +EOF +``` + +**Test:** `claude "say hello"` + +--- + +### OpenAI Codex + +```bash +mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF +model: auto +apiKey: sk-your-omniroute-key +apiBaseUrl: http://localhost:20128/v1 +EOF +``` + +**Test:** `codex "what is 2+2?"` + +--- + +### OpenCode + +```bash +mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF +[provider.openai] +base_url = "http://localhost:20128/v1" +api_key = "sk-your-omniroute-key" +EOF +``` + +**Test:** `opencode` + +--- + +### Cline (CLI or VS Code) + +**CLI mode:** + +```bash +mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF +{ + "apiProvider": "openai", + "openAiBaseUrl": "http://localhost:20128/v1", + "openAiApiKey": "sk-your-omniroute-key" +} +EOF +``` + +**VS Code mode:** +Cline extension settings โ†’ API Provider: `OpenAI Compatible` โ†’ Base URL: `http://localhost:20128/v1` + +Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ Cline โ†’ Apply Config**. + +--- + +### KiloCode (CLI or VS Code) + +**CLI mode:** + +```bash +kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key +``` + +**VS Code settings:** + +```json +{ + "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", + "kilo-code.apiKey": "sk-your-omniroute-key" +} +``` + +Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ KiloCode โ†’ Apply Config**. + +--- + +### Continue (VS Code Extension) + +Edit `~/.continue/config.yaml`: + +```yaml +models: + - name: OmniRoute + provider: openai + model: auto + apiBase: http://localhost:20128/v1 + apiKey: sk-your-omniroute-key + default: true +``` + +Restart VS Code after editing. + +--- + +### Kiro CLI (Amazon) + +```bash +# Login to your AWS/Kiro account: +kiro-cli login + +# The CLI uses its own auth โ€” OmniRoute is not needed as backend for Kiro CLI itself. +# Use kiro-cli alongside OmniRoute for other tools. +kiro-cli status +``` + +--- + +### Cursor (Desktop App) + +> **Note:** Cursor routes requests through its cloud. For OmniRoute integration, +> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL. + +Via GUI: **Settings โ†’ Models โ†’ OpenAI API Key** + +- Base URL: `https://your-domain.com/v1` +- API Key: your OmniRoute key + +--- + +## Dashboard Auto-Configuration + +The OmniRoute dashboard automates configuration for most tools: + +1. Go to `http://localhost:20128/dashboard/cli-tools` +2. Expand any tool card +3. Select your API key from the dropdown +4. Click **Apply Config** (if tool is detected as installed) +5. Or copy the generated config snippet manually + +--- + +## Built-in Agents: Droid & OpenClaw + +**Droid** and **OpenClaw** are AI agents built directly into OmniRoute โ€” no installation needed. +They run as internal routes and use OmniRoute's model routing automatically. + +- Access: `http://localhost:20128/dashboard/agents` +- Configure: same combos and providers as all other tools +- No API key or CLI install required + +--- + +## Available API Endpoints + +| Endpoint | Description | Use For | +| -------------------------- | ----------------------------- | --------------------------- | +| `/v1/chat/completions` | Standard chat (all providers) | All modern tools | +| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows | +| `/v1/completions` | Legacy text completions | Older tools using `prompt:` | +| `/v1/embeddings` | Text embeddings | RAG, search | +| `/v1/images/generations` | Image generation | DALL-E, Flux, etc. | +| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS | +| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI | + +--- + +## ล˜eลกenรญ problรฉmลฏ + +| Error | Cause | Fix | +| ------------------------- | ----------------------- | ------------------------------------------ | +| `Connection refused` | OmniRoute not running | `pm2 start omniroute` | +| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` | +| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` | +| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` | +| CLI shows "not installed" | Binary not in PATH | Check `which ` | +| `kiro-cli: not found` | Not in PATH | `export PATH="$HOME/.local/bin:$PATH"` | + +--- + +## Quick Setup Script (One Command) + +```bash +# Install all CLIs and configure for OmniRoute (replace with your key and server URL) +OMNIROUTE_URL="http://localhost:20128/v1" +OMNIROUTE_KEY="sk-your-omniroute-key" + +npm install -g @anthropic-ai/claude-code @openai/codex opencode-ai cline kilocode + +# Kiro CLI +apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash + +# Write configs +mkdir -p ~/.claude ~/.codex ~/.config/opencode ~/.continue + +cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" +cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" +cat >> ~/.bashrc << EOF +export OPENAI_BASE_URL="$OMNIROUTE_URL" +export OPENAI_API_KEY="$OMNIROUTE_KEY" +export ANTHROPIC_BASE_URL="$OMNIROUTE_URL" +export ANTHROPIC_API_KEY="$OMNIROUTE_KEY" +EOF + +source ~/.bashrc +echo "โœ… All CLIs installed and configured for OmniRoute" +``` diff --git a/docs/i18n/de/CODEBASE_DOCUMENTATION.md b/docs/i18n/cs/docs/CODEBASE_DOCUMENTATION.md similarity index 91% rename from docs/i18n/de/CODEBASE_DOCUMENTATION.md rename to docs/i18n/cs/docs/CODEBASE_DOCUMENTATION.md index e2d7950052..1be858fc65 100644 --- a/docs/i18n/de/CODEBASE_DOCUMENTATION.md +++ b/docs/i18n/cs/docs/CODEBASE_DOCUMENTATION.md @@ -1,11 +1,9 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CODEBASE_DOCUMENTATION.md) +# omniroute โ€” Codebase Documentation (ฤŒeลกtina) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CODEBASE_DOCUMENTATION.md) --- -# omniroute โ€” Codebase Documentation - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) - > A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. --- @@ -352,7 +350,7 @@ flowchart LR The **format translation engine** using a self-registering plugin system. -#### Architecture +#### Architektura ```mermaid graph TD diff --git a/docs/i18n/cs/docs/COVERAGE_PLAN.md b/docs/i18n/cs/docs/COVERAGE_PLAN.md new file mode 100644 index 0000000000..f1c783733d --- /dev/null +++ b/docs/i18n/cs/docs/COVERAGE_PLAN.md @@ -0,0 +1,170 @@ +# Test Coverage Plan (ฤŒeลกtina) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/COVERAGE_PLAN.md) + +--- + +Last updated: 2026-03-28 + +## Baseline + +There are multiple coverage numbers depending on how the report is computed. For planning, only one of them is useful. + +| Metric | Scope | Statements / Lines | Branches | Functions | Notes | +| -------------------- | ----------------------------------------------------- | -----------------: | -------: | --------: | --------------------------------------------------- | +| Legacy | Old `npm run test:coverage` | 79.42% | 75.15% | 67.94% | Inflated: counts test files and excludes `open-sse` | +| Diagnostic | Source-only, excluding tests and excluding `open-sse` | 68.16% | 63.55% | 64.06% | Useful only to isolate `src/**` | +| Recommended baseline | Source-only, excluding tests and including `open-sse` | 56.95% | 66.05% | 57.80% | This is the project-wide baseline to improve | + +The recommended baseline is the number to optimize against. + +## Rules + +- Coverage targets apply to source files, not to `tests/**`. +- `open-sse/**` is part of the product and must remain in scope. +- New code should not reduce coverage in touched areas. +- Prefer testing behavior and branch outcomes over implementation details. +- Prefer temp SQLite databases and small fixtures over broad mocks for `src/lib/db/**`. + +## Current command set + +- `npm run test:coverage` + - Main source coverage gate for the unit test suite + - Generates `text-summary`, `html`, `json-summary`, and `lcov` +- `npm run coverage:report` + - Detailed file-by-file report from the latest run +- `npm run test:coverage:legacy` + - Historical comparison only + +## Milestones + +| Phase | Target | Focus | +| ------- | ---------------------: | ------------------------------------------------- | +| Phase 1 | 60% statements / lines | Quick wins and low-risk utility coverage | +| Phase 2 | 65% statements / lines | DB and route foundations | +| Phase 3 | 70% statements / lines | Provider validation and usage analytics | +| Phase 4 | 75% statements / lines | `open-sse` translators and helpers | +| Phase 5 | 80% statements / lines | `open-sse` handlers and executor branches | +| Phase 6 | 85% statements / lines | Harder edge cases, branch debt, regression suites | +| Phase 7 | 90% statements / lines | Final sweep, gap closure, strict ratchet | + +Branches and functions should ratchet upward with each phase, but the primary hard target is statements / lines. + +## Priority hotspots + +These files or areas offer the best return for the next phases: + +1. `open-sse/handlers` + - `chatCore.ts` at 7.57% + - Overall directory at 29.07% +2. `open-sse/translator/request` + - Overall directory at 36.39% + - Many translators are still near single-digit coverage +3. `open-sse/translator/response` + - Overall directory at 8.07% +4. `open-sse/executors` + - Overall directory at 36.62% +5. `src/lib/db` + - `models.ts` at 20.66% + - `registeredKeys.ts` at 34.46% + - `modelComboMappings.ts` at 36.25% + - `settings.ts` at 46.40% + - `webhooks.ts` at 33.33% +6. `src/lib/usage` + - `usageHistory.ts` at 21.12% + - `usageStats.ts` at 9.56% + - `costCalculator.ts` at 30.00% +7. `src/lib/providers` + - `validation.ts` at 41.16% +8. Low-risk utility and API files for early gains + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/api/errorResponse.ts` + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +## Execution checklist + +### Phase 1: 56.95% -> 60% + +- [x] Fix coverage metric so it reflects source code instead of test files +- [x] Keep a legacy coverage script for comparison +- [x] Record the baseline and hotspots in-repo +- [ ] Add focused tests for low-risk utilities: + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/fetchTimeout.ts` + - `src/lib/api/errorResponse.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/display/names.ts` +- [ ] Add route tests for: + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +### Phase 2: 60% -> 65% + +- [ ] Add DB-backed tests for: + - `src/lib/db/modelComboMappings.ts` + - `src/lib/db/settings.ts` + - `src/lib/db/registeredKeys.ts` +- [ ] Cover branch behavior in: + - `src/lib/providers/validation.ts` + - `src/app/api/v1/embeddings/route.ts` + - `src/app/api/v1/moderations/route.ts` + +### Phase 3: 65% -> 70% + +- [ ] Add usage analytics tests for: + - `src/lib/usage/usageHistory.ts` + - `src/lib/usage/usageStats.ts` + - `src/lib/usage/costCalculator.ts` +- [ ] Expand route coverage for proxy management and settings branches + +### Phase 4: 70% -> 75% + +- [ ] Cover translator helpers and central translation paths: + - `open-sse/translator/index.ts` + - `open-sse/translator/helpers/*` + - `open-sse/translator/request/*` + - `open-sse/translator/response/*` + +### Phase 5: 75% -> 80% + +- [ ] Add handler-level tests for: + - `open-sse/handlers/chatCore.ts` + - `open-sse/handlers/responsesHandler.js` + - `open-sse/handlers/imageGeneration.js` + - `open-sse/handlers/embeddings.js` +- [ ] Add executor branch coverage for provider-specific auth, retries, and endpoint overrides + +### Phase 6: 80% -> 85% + +- [ ] Merge more edge-case suites into the main coverage path +- [ ] Increase function coverage for DB modules with weak constructor/helper coverage +- [ ] Close branch gaps in `settings.ts`, `registeredKeys.ts`, `validation.ts`, and translator helpers + +### Phase 7: 85% -> 90% + +- [ ] Treat the remaining low-coverage files as blockers +- [ ] Add regression tests for every uncovered production bug fixed during the push to 90% +- [ ] Raise the coverage gate in CI only after the local baseline is stable for at least two consecutive runs + +## Ratchet policy + +Update `npm run test:coverage` thresholds only after the project actually exceeds the next milestone with a comfortable buffer. + +Recommended ratchet sequence: + +1. 55/60/55 +2. 60/62/58 +3. 65/64/62 +4. 70/66/66 +5. 75/70/72 +6. 80/75/78 +7. 85/80/84 +8. 90/85/88 + +Order is `statements-lines / branches / functions`. + +## Known gap + +The current coverage command measures the main Node unit suite and includes source reached from it, including `open-sse`. It does not yet merge Vitest coverage into a single unified report. That merge is worth doing later, but it is not a blocker for starting the 60% -> 80% climb. diff --git a/docs/i18n/de/FEATURES.md b/docs/i18n/cs/docs/FEATURES.md similarity index 75% rename from docs/i18n/de/FEATURES.md rename to docs/i18n/cs/docs/FEATURES.md index c212d33261..7743ece44e 100644 --- a/docs/i18n/de/FEATURES.md +++ b/docs/i18n/cs/docs/FEATURES.md @@ -1,8 +1,6 @@ -# OmniRoute โ€” Dashboard Features Gallery (Deutsch) +# OmniRoute โ€” Dashboard Features Gallery (ฤŒeลกtina) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) - -> ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../docs/FEATURES.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/FEATURES.md) --- @@ -70,8 +68,8 @@ Comprehensive settings panel with tabs: - **Appearance** โ€” Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls - **Security** โ€” API endpoint protection, custom provider blocking, IP filtering, session info - **Routing** โ€” Model aliases, background task degradation -- **Resilience** โ€” Rate limit persistence, circuit breaker tuning -- **Advanced** โ€” Configuration overrides +- **Resilience** โ€” Rate limit persistence, circuit breaker tuning, auto-disable banned accounts, provider expiration monitoring +- **Advanced** โ€” Configuration overrides, configuration audit trail, fallback degradation mode ![Settings Dashboard](screenshots/06-settings.png) @@ -112,7 +110,7 @@ Real-time request logging with filtering by provider, model, account, and API ke ## ๐ŸŒ API Endpoint -Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. +Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloudflare Quick Tunnel integration and cloud proxy support for remote access. ![Endpoint Dashboard](screenshots/09-endpoint.png) diff --git a/docs/i18n/cs/docs/MCP-SERVER.md b/docs/i18n/cs/docs/MCP-SERVER.md new file mode 100644 index 0000000000..ac766bad88 --- /dev/null +++ b/docs/i18n/cs/docs/MCP-SERVER.md @@ -0,0 +1,87 @@ +# OmniRoute MCP Server Documentation (ฤŒeลกtina) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/MCP-SERVER.md) + +--- + +> Model Context Protocol server with 16 intelligent tools + +## Instalace + +OmniRoute MCP is built-in. Start it with: + +```bash +omniroute --mcp +``` + +Or via the open-sse transport: + +```bash +# HTTP streamable transport (port 20130) +omniroute --dev # MCP auto-starts on /mcp endpoint +``` + +## IDE Configuration + +See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup. + +--- + +## Essential Tools (8) + +| Tool | Description | +| :------------------------------ | :--------------------------------------- | +| `omniroute_get_health` | Gateway health, circuit breakers, uptime | +| `omniroute_list_combos` | All configured combos with models | +| `omniroute_get_combo_metrics` | Performance metrics for a specific combo | +| `omniroute_switch_combo` | Switch active combo by ID/name | +| `omniroute_check_quota` | Quota status per provider or all | +| `omniroute_route_request` | Send a chat completion through OmniRoute | +| `omniroute_cost_report` | Cost analytics for a time period | +| `omniroute_list_models_catalog` | Full model catalog with capabilities | + +## Advanced Tools (8) + +| Tool | Description | +| :--------------------------------- | :---------------------------------------------------------- | +| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | +| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | +| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | +| `omniroute_test_combo` | Live-test all models in a combo via a real upstream request | +| `omniroute_get_provider_metrics` | Detailed metrics for one provider | +| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | +| `omniroute_explain_route` | Explain a past routing decision | +| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | + +## Authentication + +MCP tools are authenticated via API key scopes. Each tool requires specific scopes: + +| Scope | Tools | +| :------------- | :----------------------------------------------- | +| `read:health` | get_health, get_provider_metrics | +| `read:combos` | list_combos, get_combo_metrics | +| `write:combos` | switch_combo | +| `read:quota` | check_quota | +| `write:route` | route_request, simulate_route, test_combo | +| `read:usage` | cost_report, get_session_snapshot, explain_route | +| `write:config` | set_budget_guard, set_resilience_profile | +| `read:models` | list_models_catalog, best_combo_for_task | + +## Audit Logging + +Every tool call is logged to `mcp_tool_audit` with: + +- Tool name, arguments, result +- Duration (ms), success/failure +- API key hash, timestamp + +## Files + +| File | Purpose | +| :------------------------------------------- | :------------------------------------------ | +| `open-sse/mcp-server/server.ts` | MCP server creation + 16 tool registrations | +| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport | +| `open-sse/mcp-server/auth.ts` | API key + scope validation | +| `open-sse/mcp-server/audit.ts` | Tool call audit logging | +| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers | diff --git a/docs/i18n/cs/docs/RELEASE_CHECKLIST.md b/docs/i18n/cs/docs/RELEASE_CHECKLIST.md new file mode 100644 index 0000000000..59b4301828 --- /dev/null +++ b/docs/i18n/cs/docs/RELEASE_CHECKLIST.md @@ -0,0 +1,37 @@ +# Release Checklist (ฤŒeลกtina) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/RELEASE_CHECKLIST.md) + +--- + +Use this checklist before tagging or publishing a new OmniRoute release. + +## Version and Changelog + +1. Bump `package.json` version (`x.y.z`) in the release branch. +2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: + - `## [x.y.z] โ€” YYYY-MM-DD` +3. Keep `## [Unreleased]` as the first changelog section for upcoming work. +4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. + +## API Docs + +1. Update `docs/openapi.yaml`: + - `info.version` must equal `package.json` version. +2. Validate endpoint examples if API contracts changed. + +## Runtime Docs + +1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. +2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. +3. Update localized docs if source docs changed significantly. + +## Automated Check + +Run the sync guard locally before opening PR: + +```bash +npm run check:docs-sync +``` + +CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/de/TROUBLESHOOTING.md b/docs/i18n/cs/docs/TROUBLESHOOTING.md similarity index 77% rename from docs/i18n/de/TROUBLESHOOTING.md rename to docs/i18n/cs/docs/TROUBLESHOOTING.md index 63c148000a..3194e66812 100644 --- a/docs/i18n/de/TROUBLESHOOTING.md +++ b/docs/i18n/cs/docs/TROUBLESHOOTING.md @@ -1,11 +1,9 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/TROUBLESHOOTING.md) +# Troubleshooting (ฤŒeลกtina) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/TROUBLESHOOTING.md) --- -# Troubleshooting - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/TROUBLESHOOTING.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/TROUBLESHOOTING.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/TROUBLESHOOTING.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/TROUBLESHOOTING.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/TROUBLESHOOTING.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/TROUBLESHOOTING.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/TROUBLESHOOTING.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/TROUBLESHOOTING.md) - Common problems and solutions for OmniRoute. --- diff --git a/docs/i18n/cs/docs/USER_GUIDE.md b/docs/i18n/cs/docs/USER_GUIDE.md new file mode 100644 index 0000000000..d972e842de --- /dev/null +++ b/docs/i18n/cs/docs/USER_GUIDE.md @@ -0,0 +1,944 @@ +# User Guide (ฤŒeลกtina) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/USER_GUIDE.md) + +--- + +Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute. + +--- + +## Table of Contents + +- [Pricing at a Glance](#-pricing-at-a-glance) +- [Use Cases](#-use-cases) +- [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** | Qoder | $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) + Qoder (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 + +#### Qoder (8 FREE models) + +```bash +Dashboard โ†’ Connect Qoder โ†’ 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 +``` + +--- + +## Nasazenรญ + +### Global npm install (Recommended) + +```bash +npm install -g omniroute + +# Create config directory +mkdir -p ~/.omniroute + +# Create .env file (see .env.example) +cp .env.example ~/.omniroute/.env + +# Start server +omniroute +# Or with custom port: +omniroute --port 3000 +``` + +The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`. + +### VPS Deployment + +```bash +git clone https://github.com/diegosouzapw/OmniRoute.git +cd OmniRoute && npm install && npm run build + +export JWT_SECRET="your-secure-secret-change-this" +export INITIAL_PASSWORD="your-password" +export DATA_DIR="/var/lib/omniroute" +export PORT="20128" +export HOSTNAME="0.0.0.0" +export NODE_ENV="production" +export NEXT_PUBLIC_BASE_URL="http://localhost:20128" +export API_KEY_SECRET="endpoint-proxy-api-key-secret" + +npm run start +# Or: pm2 start npm --name omniroute -- start +``` + +### PM2 Deployment (Low Memory) + +For servers with limited RAM, use the memory limit option: + +```bash +# With 512MB limit (default) +pm2 start npm --name omniroute -- start + +# Or with custom memory limit +OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start + +# Or using ecosystem.config.js +pm2 start ecosystem.config.js +``` + +Create `ecosystem.config.js`: + +```javascript +module.exports = { + apps: [ + { + name: "omniroute", + script: "npm", + args: "start", + env: { + NODE_ENV: "production", + OMNIROUTE_MEMORY_MB: "512", + JWT_SECRET: "your-secret", + INITIAL_PASSWORD: "your-password", + }, + node_args: "--max-old-space-size=512", + max_memory_restart: "300M", + }, + ], +}; +``` + +### Docker + +```bash +# Build image (default = runner-cli with codex/claude/droid preinstalled) +docker build -t omniroute:cli . + +# Portable mode (recommended) +docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli +``` + +For host-integrated mode with CLI binaries, see the Docker section in the main docs. + +### Void Linux (xbps-src) + +Void Linux users can package and install OmniRoute natively using the `xbps-src` cross-compilation framework. This automates the Node.js standalone build along with the required `better-sqlite3` native bindings. + +
+View xbps-src template + +```bash +# Template file for 'omniroute' +pkgname=omniroute +version=3.2.4 +revision=1 +hostmakedepends="nodejs python3 make" +depends="openssl" +short_desc="Universal AI gateway with smart routing for multiple LLM providers" +maintainer="zenobit " +license="MIT" +homepage="https://github.com/diegosouzapw/OmniRoute" +distfiles="https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz" +checksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b +system_accounts="_omniroute" +omniroute_homedir="/var/lib/omniroute" +export NODE_ENV=production +export npm_config_engine_strict=false +export npm_config_loglevel=error +export npm_config_fund=false +export npm_config_audit=false + +do_build() { + # Determine target CPU arch for node-gyp + local _gyp_arch + case "$XBPS_TARGET_MACHINE" in + aarch64*) _gyp_arch=arm64 ;; + armv7*|armv6*) _gyp_arch=arm ;; + i686*) _gyp_arch=ia32 ;; + *) _gyp_arch=x64 ;; + esac + + # 1) Install all deps โ€“ skip scripts + NODE_ENV=development npm ci --ignore-scripts + + # 2) Build the Next.js standalone bundle + npm run build + + # 3) Copy static assets into standalone + cp -r .next/static .next/standalone/.next/static + [ -d public ] && cp -r public .next/standalone/public || true + + # 4) Compile better-sqlite3 native binding + local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js + (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch") + + # 5) Place the compiled binding into the standalone bundle + local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release + mkdir -p "$_bs3_release" + cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/" + + # 6) Remove arch-specific sharp bundles + rm -rf .next/standalone/node_modules/@img + + # 7) Copy pino runtime deps omitted by Next.js static analysis: + for _mod in pino-abstract-transport split2 process-warning; do + cp -r "node_modules/$_mod" .next/standalone/node_modules/ + done +} + +do_check() { + npm run test:unit +} + +do_install() { + vmkdir usr/lib/omniroute/.next + vcopy .next/standalone/. usr/lib/omniroute/.next/standalone + + # Prevent removal of empty Next.js app router dirs by the post-install hook + for _d in \ + .next/standalone/.next/server/app/dashboard \ + .next/standalone/.next/server/app/dashboard/settings \ + .next/standalone/.next/server/app/dashboard/providers; do + touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep" + done + + cat > "${WRKDIR}/omniroute" <<'EOF' +#!/bin/sh +export PORT="${PORT:-20128}" +export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}" +export LOG_TO_FILE="${LOG_TO_FILE:-false}" +mkdir -p "${DATA_DIR}" +exec node /usr/lib/omniroute/.next/standalone/server.js "$@" +EOF + vbin "${WRKDIR}/omniroute" +} + +post_install() { + vlicense LICENSE +} +``` + +
+ +### 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/*` | +| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand | +| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | + +For the full environment variable reference, see the [README](../README.md). + +--- + +## ๐Ÿ“Š Available Models + +
+View all available models + +**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` + +**Qoder (`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` + +
+ +--- + +## ๐Ÿงฉ 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**. + +Notes: + +- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers. +- The **Custom Models** section is intended for providers that do not expose managed available-model imports. + +### 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 + +### Cloudflare Quick Tunnel + +- Available in **Dashboard โ†’ Endpoints** for Docker and other self-hosted deployments +- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint +- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary +- Tunnel URLs are ephemeral and change every time you stop/start the tunnel +- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download + +### 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 | + +#### External Sticky Session Header + +For external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send: + +```http +X-Session-Id: your-session-key +``` + +OmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`. + +If you use Nginx and send underscore-form headers, enable: + +```nginx +underscores_in_headers on; +``` + +#### 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 unless `DISABLE_SQLITE_AUTO_BACKUP=true` | + +```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 6 tabs for easy navigation: + +| Tab | Contents | +| -------------- | ---------------------------------------------------------------------------------------------- | +| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility | +| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | +| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | +| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | +| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats | +| **Advanced** | Global proxy configuration (HTTP/SOCKS5) | + +--- + +### Costs & Budget Management + +Access via **Dashboard โ†’ Costs**. + +| 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. + +--- + +## ๐Ÿ–ฅ๏ธ Desktop Application (Electron) + +OmniRoute is available as a native desktop application for Windows, macOS, and Linux. + +### Instalace + +```bash +# From the electron directory: +cd electron +npm install + +# Development mode (connect to running Next.js dev server): +npm run dev + +# Production mode (uses standalone build): +npm start +``` + +### Building Installers + +```bash +cd electron +npm run build # Current platform +npm run build:win # Windows (.exe NSIS) +npm run build:mac # macOS (.dmg universal) +npm run build:linux # Linux (.AppImage) +``` + +Output โ†’ `electron/dist-electron/` + +### Key Features + +| Feature | Description | +| --------------------------- | ---------------------------------------------------- | +| **Server Readiness** | Polls server before showing window (no blank screen) | +| **System Tray** | Minimize to tray, change port, quit from tray menu | +| **Port Management** | Change server port from tray (auto-restarts server) | +| **Content Security Policy** | Restrictive CSP via session headers | +| **Single Instance** | Only one app instance can run at a time | +| **Offline Mode** | Bundled Next.js server works without internet | + +### Environment Variables + +| Variable | Default | Description | +| --------------------- | ------- | -------------------------------- | +| `OMNIROUTE_PORT` | `20128` | Server port | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64โ€“16384 MB) | + +๐Ÿ“– Full documentation: [`electron/README.md`](../electron/README.md) diff --git a/docs/i18n/cs/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/cs/docs/VM_DEPLOYMENT_GUIDE.md new file mode 100644 index 0000000000..ee8241396a --- /dev/null +++ b/docs/i18n/cs/docs/VM_DEPLOYMENT_GUIDE.md @@ -0,0 +1,403 @@ +# OmniRoute โ€” Deployment Guide on VM with Cloudflare (ฤŒeลกtina) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/VM_DEPLOYMENT_GUIDE.md) + +--- + +Complete guide to install and configure OmniRoute on a VM (VPS) with domain managed via Cloudflare. + +--- + +## Prerequisites + +| Item | Minimum | Recommended | +| ---------- | ------------------------ | ---------------- | +| **CPU** | 1 vCPU | 2 vCPU | +| **RAM** | 1 GB | 2 GB | +| **Disk** | 10 GB SSD | 25 GB SSD | +| **OS** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS | +| **Domain** | Registered on Cloudflare | โ€” | +| **Docker** | Docker Engine 24+ | Docker 27+ | + +**Tested providers**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. + +--- + +## 1. Configure the VM + +### 1.1 Create the instance + +On your preferred VPS provider: + +- Choose Ubuntu 24.04 LTS +- Select the minimum plan (1 vCPU / 1 GB RAM) +- Set a strong root password or configure SSH key +- Note the **public IP** (e.g., `203.0.113.10`) + +### 1.2 Connect via SSH + +```bash +ssh root@203.0.113.10 +``` + +### 1.3 Update the system + +```bash +apt update && apt upgrade -y +``` + +### 1.4 Install Docker + +```bash +# Install dependencies +apt install -y ca-certificates curl gnupg + +# Add official Docker repository +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 Install nginx + +```bash +apt install -y nginx +``` + +### 1.6 Configure 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 +``` + +> **Tip**: For maximum security, restrict ports 80 and 443 to Cloudflare IPs only. See the [Advanced Security](#advanced-security) section. + +--- + +## 2. Install OmniRoute + +### 2.1 Create configuration directory + +```bash +mkdir -p /opt/omniroute +``` + +### 2.2 Create environment variables file + +```bash +cat > /opt/omniroute/.env << โ€˜EOFโ€™ +# === Security === +JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY +INITIAL_PASSWORD=YourSecurePassword123! +API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY +STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY +STORAGE_ENCRYPTION_KEY_VERSION=v1 +MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT + +# === 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 (change to your domain) === +BASE_URL=https://llms.seudominio.com +NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com + +# === Cloud Sync (optional) === +# CLOUD_URL=https://cloud.omniroute.online +# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online +EOF +``` + +> โš ๏ธ **IMPORTANT**: Generate unique secret keys! Use `openssl rand -hex 32` for each key. + +### 2.3 Start the 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 Verify that it is running + +```bash +docker ps | grep omniroute +docker logs omniroute --tail 20 +``` + +It should display: `[DB] SQLite database ready` and `listening on port 20128`. + +--- + +## 3. Configure nginx (Reverse Proxy) + +### 3.1 Generate SSL certificate (Cloudflare Origin) + +In the Cloudflare dashboard: + +1. Go to **SSL/TLS โ†’ Origin Server** +2. Click **Create Certificate** +3. Keep the defaults (15 years, \*.yourdomain.com) +4. Copy the **Origin Certificate** and the **Private Key** + +```bash +mkdir -p /etc/nginx/ssl + +# Paste the certificate +nano /etc/nginx/ssl/origin.crt + +# Paste the private key +nano /etc/nginx/ssl/origin.key + +chmod 600 /etc/nginx/ssl/origin.key +``` + +### 3.2 Nginx Configuration + +```bash +cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ +# Default server โ€” blocks direct access via 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.yourdomain.com; # Change to your domain + + 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.yourdomain.com; + return 301 https://$server_name$request_uri; +} +NGINX +``` + +### 3.3 Enable and Test + +```bash +# Remove default configuration +rm -f /etc/nginx/sites-enabled/default + +# Enable OmniRoute +ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute + +# Test and reload +nginx -t && systemctl reload nginx +``` + +--- + +## 4. Configure Cloudflare DNS + +### 4.1 Add DNS record + +In the Cloudflare dashboard โ†’ DNS: + +| Type | Name | Content | Proxy | +| ---- | ------ | ---------------------- | ---------- | +| A | `llms` | `203.0.113.10` (VM IP) | โœ… Proxied | + +### 4.2 Configure SSL + +Under **SSL/TLS โ†’ Overview**: + +- Mode: **Full (Strict)** + +Under **SSL/TLS โ†’ Edge Certificates**: + +- Always Use HTTPS: โœ… On +- Minimum TLS Version: TLS 1.2 +- Automatic HTTPS Rewrites: โœ… On + +### 4.3 Testing + +```bash +curl -sI https://llms.seudominio.com/health +# Should return HTTP/2 200 +``` + +--- + +## 5. Operations and Maintenance + +### Upgrade to a new version + +```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 +``` + +### View logs + +```bash +docker logs -f omniroute # Real-time stream +docker logs omniroute --tail 50 # Last 50 lines +``` + +### Manual database backup + +```bash +# Copy data from the volume to the host +docker cp omniroute:/app/data ./backup-$(date +%F) + +# Or compress the entire volume +docker run --rm -v omniroute-data:/data -v $(pwd):/backup \ + alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data +``` + +### Restore from 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. Advanced Security + +### Restrict nginx to Cloudflare IPs + +```bash +cat > /etc/nginx/cloudflare-ips.conf << โ€˜CFโ€™ +# Cloudflare IPv4 ranges โ€” update periodically +# 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 +``` + +Add the following to `nginx.conf` inside the `http {}` block: + +```nginx +include /etc/nginx/cloudflare-ips.conf; +``` + +### Install fail2ban + +```bash +apt install -y fail2ban +systemctl enable fail2ban +systemctl start fail2ban + +# Check status +fail2ban-client status sshd +``` + +### Block direct access to the Docker port + +```bash +# Prevent direct external access to port 20128 +iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP +iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT + +# Persist the rules +apt install -y iptables-persistent +netfilter-persistent save +``` + +--- + +## 7. Deploy to Cloudflare Workers (Optional) + +For remote access via Cloudflare Workers (without exposing the VM directly): + +```bash +# In the local repository +cd omnirouteCloud +npm install +npx wrangler login +npx wrangler deploy +``` + +See the full documentation at [omnirouteCloud/README.md](../omnirouteCloud/README.md). + +--- + +## Port Summary + +| Port | Service | Access | +| ----- | ----------- | -------------------------- | +| 22 | SSH | Public (with fail2ban) | +| 80 | nginx HTTP | Redirect โ†’ HTTPS | +| 443 | nginx HTTPS | Via Cloudflare Proxy | +| 20128 | OmniRoute | Localhost only (via nginx) | diff --git a/docs/i18n/cs/electron/README.md b/docs/i18n/cs/electron/README.md deleted file mode 100644 index 28d3903ad3..0000000000 --- a/docs/i18n/cs/electron/README.md +++ /dev/null @@ -1,254 +0,0 @@ -# Aplikace OmniRoute Electron pro stolnรญ poฤรญtaฤe - -Tento adresรกล™ obsahuje obalovou aplikaci Electron pro desktopovou aplikaci OmniRoute. - -## Architektura (v1.6.4) - -``` -electron/ -โ”œโ”€โ”€ main.js # Main process โ€” window, tray, server lifecycle, CSP, IPC -โ”œโ”€โ”€ preload.js # Preload script โ€” secure IPC bridge with disposer pattern -โ”œโ”€โ”€ package.json # Electron-specific dependencies & electron-builder config -โ”œโ”€โ”€ types.d.ts # TypeScript definitions (AppInfo, ServerStatus, ElectronAPI) -โ””โ”€โ”€ assets/ # Application icons and resources - -src/shared/hooks/ -โ””โ”€โ”€ useElectron.ts # React hooks โ€” useSyncExternalStore, zero re-renders -``` - -## Klรญฤovรก rozhodnutรญ o designu - -Rozhodnutรญ | Odลฏvodnฤ›nรญ ---- | --- -dotazovรกnรญ `waitForServer()` | Zabraลˆuje zobrazenรญ prรกzdnรฉ obrazovky pล™i studenรฉm startu โ€” pล™ed naฤtenรญm se ozve `http://localhost:PORT` -`stdio: 'pipe'` | Zachycuje stdout/stderr serveru pro logovรกnรญ + detekci pล™ipravenosti ( `inherit` ) -Vzor drtiฤe odpadu | `onServerStatus()` vracรญ `() => void` pro pล™esnรฉ vyฤiลกtฤ›nรญ listeneru (ne `removeAllListeners` ) -`useSyncExternalStore` | Nulovรฉ renderovรกnรญ pro `useIsElectron()` โ€” ลพรกdnรฝ cyklus `useState` + `useEffect` -CSP prostล™ednictvรญm zรกhlavรญ relace | `Content-Security-Policy` omezuje `script-src` , `connect-src` atd. dle osvฤ›dฤenรฝch postupลฏ Electron. -Podmรญnฤ›nรฝ titulek pro platformu | `titleBarStyle: 'hiddenInset'` pouze v systรฉmu macOS; `default` ve Windows/Linuxu - -## Rozvoj - -### Pล™edpoklady - -1. Nejprve sestavte aplikaci Next.js: - -```bash -npm run build -``` - -1. Instalace zรกvislostรญ Electronu: - -```bash -cd electron -npm install -``` - -### Spuลกtฤ›no ve vรฝvoji - -1. Spusลฅte vรฝvojovรฝ server Next.js: - -```bash -npm run dev -``` - -1. V jinรฉm terminรกlu spusลฅte Electron: - -```bash -cd electron -npm run dev -``` - -### Spuลกtฤ›nรญ v produkฤnรญm reลพimu - -1. Sestavenรญ Next.js v samostatnรฉm reลพimu: - -```bash -npm run build -``` - -1. Spuลกtฤ›nรญ elektronu: - -```bash -cd electron -npm start -``` - -## Budova - -### Sestavenรญ pro aktuรกlnรญ platformu - -```bash -cd electron -npm run build -``` - -### Vytvoล™te pro specifickรฉ platformy - -```bash -# Windows -npm run build:win - -# macOS (x64 + arm64) -npm run build:mac - -# Linux -npm run build:linux -``` - -## Vรฝstup - -Vytvoล™enรฉ aplikace jsou umรญstฤ›ny v `dist-electron/` : - -- Windows: `.exe` instalaฤnรญ program (NSIS) + pล™enosnรฝ `.exe` -- macOS: instalaฤnรญ soubor `.dmg` (Intel + Apple Silicon) -- Linux: `.AppImage` - -## Instalace - -### macOS - -1. Stรกhnฤ›te si nejnovฤ›jลกรญ soubor `.dmg` ze strรกnky [Verze](https://github.com/diegosouzapw/OmniRoute/releases) . -2. Otevล™ete soubor `.dmg` . -3. Pล™etรกhnฤ›te `OmniRoute.app` do sloลพky Aplikace. -4. Spustit z Aplikacรญ. - -> โš ๏ธ **Poznรกmka:** Aplikace zatรญm nenรญ podepsรกna certifikรกtem Apple Developer. Pokud macOS aplikaci blokuje, spusลฅte: -> -> ```bash -> xattr -cr /Applications/OmniRoute.app -> ``` -> -> Nebo kliknฤ›te pravรฝm tlaฤรญtkem myลกi na aplikaci โ†’ Otevล™รญt โ†’ Otevล™รญt (pro obejitรญ Gatekeeperu pล™i prvnรญm spuลกtฤ›nรญ). - -### Windows - -**Instalaฤnรญ program (doporuฤeno):** - -1. Stรกhnฤ›te si `OmniRoute.Setup.*.exe` z [Releases](https://github.com/diegosouzapw/OmniRoute/releases) . -2. Spusลฅte instalaฤnรญ program. -3. Spuลกtฤ›nรญ z nabรญdky Start nebo zรกstupce na ploลกe. - -**Pล™enosnรฉ (bez instalace):** - -1. Stรกhnฤ›te si soubor `OmniRoute.exe` ze [sekce Vydรกnรญ](https://github.com/diegosouzapw/OmniRoute/releases) . -2. Spouลกtฤ›t pล™รญmo z libovolnรฉ sloลพky. - -### Linux - -1. Stรกhnฤ›te si soubor `.AppImage` ze [sekce Releases](https://github.com/diegosouzapw/OmniRoute/releases) . -2. Udฤ›lejte z nฤ›j spustitelnรฝ soubor: - ```bash - chmod +x OmniRoute-*.AppImage - ``` -3. Bฤ›h: - ```bash - ./OmniRoute-*.AppImage - ``` - -## Funkce - -- **Pล™ipravenost serveru** โ€“ Pล™ed zobrazenรญm okna ฤekรก na kontrolu stavu -- **Systรฉmovรฝ zรกsobnรญk** โ€” Minimalizace do systรฉmovรฉho zรกsobnรญku s rychlรฝmi akcemi (otevล™รญt, zmฤ›nit port, ukonฤit) -- **Sprรกva portลฏ** โ€” Zmฤ›na portu z nabรญdky v systรฉmovรฉ liลกtฤ› (server se automaticky restartuje) -- **Ovlรกdacรญ prvky oken** โ€” Vlastnรญ minimalizace, maximalizace, zavล™enรญ pล™es IPC -- **Zรกsady zabezpeฤenรญ obsahu** โ€“ Omezujรญcรญ CSP prostล™ednictvรญm zรกhlavรญ relacรญ -- **Offline podpora** โ€” Samostatnรฝ server Next.js v balรญฤku -- **Jedna instance** โ€“ V danรฉm okamลพiku mลฏลพe bฤ›ลพet pouze jedna instance aplikace. - -## Konfigurace - -### Promฤ›nnรฉ prostล™edรญ - -Promฤ›nnรก | Vรฝchozรญ | Popis ---- | --- | --- -`OMNIROUTE_PORT` | `20128` | Port serveru -`OMNIROUTE_MEMORY_MB` | `512` | Limit haldy Node.js (64โ€“16384 MB) -`NODE_ENV` | `production` | Nastavit na `development` pro vรฝvojรกล™skรฝ reลพim - -### Vlastnรญ ikona - -Umรญstฤ›te ikony do `assets/` : - -- `icon.ico` โ€” ikona Windows (256ร—256) -- `icon.icns` โ€” balรญฤek ikon pro macOS -- `icon.png` โ€” Linux/obecnรฉ pouลพitรญ (512ร—512) -- `tray-icon.png` โ€” Ikona na systรฉmovรฉ liลกtฤ› (16ร—16 nebo 32ร—32) - -## Kanรกly IPC - -### Vyvolรกnรญ (Renderer โ†’ Hlavnรญ, asynchronnรญ) - -Kanรกl | Vrรกcenรญ zboลพรญ | Popis ---- | --- | --- -`get-app-info` | `AppInfo` | Nรกzev aplikace, verze, platforma, isDev, port -`open-external` | `void` | Otevล™รญt URL ve vรฝchozรญm prohlรญลพeฤi (pouze http/https) -`get-data-dir` | `string` | Zรญskat cestu k adresรกล™i userData -`restart-server` | `{ success }` | Zastavenรญ + restart serveru (ฤasovรฝ limit 5 s + SIGKILL) - -### Odeslat (Renderer โ†’ Hlavnรญ, spustit a zapomenout) - -Kanรกl | Popis ---- | --- -`window-minimize` | Minimalizovat okno -`window-maximize` | Pล™epnout maximalizaci/obnovenรญ -`window-close` | Zavล™รญt okno (minimalizovat do zรกsobnรญku) - -### Pล™รญjem (Hlavnรญ โ†’ Renderer, udรกlosti) - -Kanรกl | Uลพiteฤnรฉ zatรญลพenรญ | Vydรกno, kdyลพ ---- | --- | --- -`server-status` | `ServerStatus` | Server se spouลกtรญ, zastavuje, dochรกzรญ k chybรกm nebo se restartuje -`port-changed` | `number` | Zmฤ›na portu pล™es menu zรกsobnรญku - -> **Poznรกmka** : Posluchaฤe vracejรญ funkce pro pล™esnรฉ ฤiลกtฤ›nรญ. Viz hooky `useServerStatus` a `usePortChanged` . - -## Zabezpeฤenรญ - -Funkce | Implementace ---- | --- -Izolace kontextu | `contextIsolation: true` โ€” renderer nemลฏลพe pล™istupovat k Node.js -Integrace uzlลฏ | `nodeIntegration: false` โ€” v rendereru nenรญ `require()` -Bรญlรฝ seznam IPC | Nรกzvy kanรกlลฏ ovฤ›ล™enรฉ pล™i pล™edbฤ›ลพnรฉm naฤรญtรกnรญ pomocรญ `safeInvoke` / `safeSend` / `safeOn` -Ovฤ›ล™enรญ URL adresy | `shell.openExternal()` povoluje pouze protokoly `http:` / `https:` -CSP | Zรกhlavรญ `Content-Security-Policy` nastavenรฉ pomocรญ `session.webRequest.onHeadersReceived` -Zabezpeฤenรญ webu | `webSecurity: true` โ€“ vynucena politika stejnรฉho pลฏvodu - -## React Hooky - -Hรกฤek | Vrรกcenรญ zboลพรญ | Popis ---- | --- | --- -`useIsElectron()` | `boolean` | Detekce nulovรฉho renderovรกnรญ pomocรญ `useSyncExternalStore` -`useElectronAppInfo()` | `{ appInfo, loading, error }` | Informace o aplikaci z hlavnรญho procesu -`useDataDir()` | `{ dataDir, loading, error }` | Adresรกล™ uลพivatelskรฝch dat -`useWindowControls()` | `{ minimize, maximize, close }` | Akce ovlรกdรกnรญ oken -`useOpenExternal()` | `{ openExternal }` | Otevล™รญt URL adresy v prohlรญลพeฤi -`useServerControls()` | `{ restart, restarting }` | ล˜รญzenรญ restartu serveru -`useServerStatus(cb)` | Drtiฤ odpadu | Poslouchejte udรกlosti stavu serveru -`usePortChanged(cb)` | Drtiฤ odpadu | Poslouchejte udรกlosti zmฤ›ny portu - -## Odstraลˆovรกnรญ problรฉmลฏ - -### Aplikace se nespustรญ - -1. Zkontrolujte, zda je port 20128 dostupnรฝ: `lsof -i :20128` -2. Zkontrolujte protokoly konzole pro prefix `[Electron]` -3. Ovฤ›ล™te, zda vรฝstup sestavenรญ existuje v souboru `.next/standalone` - -### Bรญlรก obrazovka - -1. Ovฤ›ล™enรญ existence buildu Next.js โ€“ ฤekรกnรญ na pล™ipravenost serveru maximรกlnฤ› 30 sekund -2. Zkontrolujte vรฝstup protokolลฏ `[Server]` a `[Server:err]` -3. Hledรกnรญ poruลกenรญ CSP v konzoli pro vรฝvojรกล™e - -### Selhรกnรญ sestavenรญ - -Ujistฤ›te se, ลพe mรกte nainstalovanรฉ nรกstroje pro sestavenรญ: - -- Windows: Nรกstroje pro sestavenรญ ve Visual Studiu -- macOS: Nรกstroje pล™รญkazovรฉho ล™รกdku Xcode -- Linux: `build-essential` , `libsecret-1-dev` - -## Licence - -MIT diff --git a/docs/i18n/cs/i18n/README.md b/docs/i18n/cs/i18n/README.md deleted file mode 100644 index 5de17b4a03..0000000000 --- a/docs/i18n/cs/i18n/README.md +++ /dev/null @@ -1,26 +0,0 @@ -# Vรญcejazyฤnรก dokumentace - -Tento adresรกล™ obsahuje strojovฤ› asistovanรฉ pล™eklady zaloลพenรฉ na anglickรฉ dokumentaci. - -- **API_REFERENCE.md** : ๐Ÿ‡บ๐Ÿ‡ธ [ฤŒesky](../API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brazรญlie)](./pt-BR/API_REFERENCE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](./es/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](./fr/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](./it/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](./ru/API_REFERENCE.md) | ๐Ÿ‡จ๐Ÿ‡ณ[ไธญๆ–‡ (็ฎ€ไฝ“)](./zh-CN/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](./de/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](./in/API_REFERENCE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](./th/API_REFERENCE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](./uk-UA/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](./ar/API_REFERENCE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต[ๆ—ฅๆœฌ่ชž](./ja/API_REFERENCE.md)| ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](./vi/API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](./bg/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dรกnsko](./da/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](./fi/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](./he/API_REFERENCE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [maฤarลกtina](./hu/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonรฉsie](./id/API_REFERENCE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](./ko/API_REFERENCE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](./ms/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nizozemsko](./nl/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](./no/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugalsko)](./pt/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](./ro/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](./pl/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](./sk/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](./sv/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipรญnec](./phi/API_REFERENCE.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](./cs/API_REFERENCE.md) - -- **ARCHITECTURE.md** : ๐Ÿ‡บ๐Ÿ‡ธ [anglicky](../ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brazรญlie)](./pt-BR/ARCHITECTURE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](./es/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](./fr/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](./it/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](./ru/ARCHITECTURE.md) | ๐Ÿ‡จ๐Ÿ‡ณ[ไธญๆ–‡ (็ฎ€ไฝ“)](./zh-CN/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](./de/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](./in/ARCHITECTURE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](./th/ARCHITECTURE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](./uk-UA/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](./ar/ARCHITECTURE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต[ๆ—ฅๆœฌ่ชž](./ja/ARCHITECTURE.md)| ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](./vi/ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](./bg/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dรกnsko](./da/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](./fi/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](./he/ARCHITECTURE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [maฤarลกtina](./hu/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonรฉsie](./id/ARCHITECTURE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](./ko/ARCHITECTURE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](./ms/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nizozemsko](./nl/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](./no/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugalsko)](./pt/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](./ro/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](./pl/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](./sk/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](./sv/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipรญnec](./phi/ARCHITECTURE.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](./cs/ARCHITECTURE.md) - -- **CODEBASE_DOCUMENTATION.md** : ๐Ÿ‡บ๐Ÿ‡ธ [anglicky](../CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brazรญlie)](./pt-BR/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](./es/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](./fr/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](./it/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](./ru/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡จ๐Ÿ‡ณ[ไธญๆ–‡ (็ฎ€ไฝ“)](./zh-CN/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](./de/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](./in/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](./th/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](./uk-UA/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](./ar/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฏ๐Ÿ‡ต[ๆ—ฅๆœฌ่ชž](./ja/CODEBASE_DOCUMENTATION.md)| ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](./vi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](./bg/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dรกnsko](./da/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](./fi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](./he/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ญ๐Ÿ‡บ [maฤarลกtina](./hu/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonรฉsie](./id/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](./ko/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](./ms/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nizozemsko](./nl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](./no/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugalsko)](./pt/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](./ro/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](./pl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](./sk/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](./sv/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipรญnec](./phi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](./cs/CODEBASE_DOCUMENTATION.md) - -- **FEATURES.md** : ๐Ÿ‡บ๐Ÿ‡ธ [anglicky](../FEATURES.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brazรญlie)](./pt-BR/FEATURES.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](./es/FEATURES.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](./fr/FEATURES.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](./it/FEATURES.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](./ru/FEATURES.md) | ๐Ÿ‡จ๐Ÿ‡ณ[ไธญๆ–‡ (็ฎ€ไฝ“)](./zh-CN/FEATURES.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](./de/FEATURES.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](./in/FEATURES.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](./th/FEATURES.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](./uk-UA/FEATURES.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](./ar/FEATURES.md) | ๐Ÿ‡ฏ๐Ÿ‡ต[ๆ—ฅๆœฌ่ชž](./ja/FEATURES.md)| ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](./vi/FEATURES.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](./bg/FEATURES.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dรกnsko](./da/FEATURES.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](./fi/FEATURES.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](./he/FEATURES.md) | ๐Ÿ‡ญ๐Ÿ‡บ [maฤarลกtina](./hu/FEATURES.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonรฉsie](./id/FEATURES.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](./ko/FEATURES.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](./ms/FEATURES.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nizozemsko](./nl/FEATURES.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](./no/FEATURES.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugalsko)](./pt/FEATURES.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](./ro/FEATURES.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](./pl/FEATURES.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](./sk/FEATURES.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](./sv/FEATURES.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipรญnec](./phi/FEATURES.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](./cs/FEATURES.md) - -- **TOUBLESHOOTING.md** : ๐Ÿ‡บ๐Ÿ‡ธ [anglicky](../TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brazรญlie)](./pt-BR/TROUBLESHOOTING.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](./es/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](./fr/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](./it/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](./ru/TROUBLESHOOTING.md) | ๐Ÿ‡จ๐Ÿ‡ณ[ไธญๆ–‡ (็ฎ€ไฝ“)](./zh-CN/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](./de/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](./in/TROUBLESHOOTING.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](./th/TROUBLESHOOTING.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](./uk-UA/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](./ar/TROUBLESHOOTING.md) | ๐Ÿ‡ฏ๐Ÿ‡ต[ๆ—ฅๆœฌ่ชž](./ja/TROUBLESHOOTING.md)| ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](./vi/TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](./bg/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dรกnsko](./da/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](./fi/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](./he/TROUBLESHOOTING.md) | ๐Ÿ‡ญ๐Ÿ‡บ [maฤarลกtina](./hu/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonรฉsie](./id/TROUBLESHOOTING.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](./ko/TROUBLESHOOTING.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](./ms/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nizozemsko](./nl/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](./no/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugalsko)](./pt/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](./ro/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](./pl/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](./sk/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](./sv/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipรญnec](./phi/TROUBLESHOOTING.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](./cs/TROUBLESHOOTING.md) - -- **USER_GUIDE.md** : ๐Ÿ‡บ๐Ÿ‡ธ [anglicky](../USER_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brazรญlie)](./pt-BR/USER_GUIDE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](./es/USER_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](./fr/USER_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](./it/USER_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](./ru/USER_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ณ[ไธญๆ–‡ (็ฎ€ไฝ“)](./zh-CN/USER_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](./de/USER_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](./in/USER_GUIDE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](./th/USER_GUIDE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](./uk-UA/USER_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](./ar/USER_GUIDE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต[ๆ—ฅๆœฌ่ชž](./ja/USER_GUIDE.md)| ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](./vi/USER_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](./bg/USER_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dรกnsko](./da/USER_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](./fi/USER_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](./he/USER_GUIDE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [maฤarลกtina](./hu/USER_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonรฉsie](./id/USER_GUIDE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](./ko/USER_GUIDE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](./ms/USER_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nizozemsko](./nl/USER_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](./no/USER_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugalsko)](./pt/USER_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](./ro/USER_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](./pl/USER_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](./sk/USER_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](./sv/USER_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipรญnec](./phi/USER_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](./cs/USER_GUIDE.md) - -## Nedรกvnรก poznรกmka: Zรกsady limitลฏ pro รบฤty Codex - -Dokumentace nynรญ zahrnuje chovรกnรญ zรกsad kvรณt na รบrovni รบฤtu Codex: - -- Pล™epรญnรกnรญ pro jednotlivรฉ รบฤty: `5h` a `Weekly` (ZAP/VYP). -- Zรกsady prahovรฝch hodnot: povolenรฉ okno dosahujรญcรญ >=90 % oznaฤuje รบฤet jako nezpลฏsobilรฝ k vรฝbฤ›ru. -- Automatickรก rotace: provoz se pล™esune na dalลกรญ zpลฏsobilรฝ รบฤet Codex. -- Automatickรฉ opฤ›tovnรฉ pouลพitรญ: รบฤet se opฤ›t stane zpลฏsobilรฝm po รบspฤ›ลกnรฉm `resetAt` poskytovatele. - -Vygenerovรกno 26. รบnora 2026. diff --git a/docs/i18n/cs/open-sse/mcp-server/README.md b/docs/i18n/cs/open-sse/mcp-server/README.md deleted file mode 100644 index cbf1561f19..0000000000 --- a/docs/i18n/cs/open-sse/mcp-server/README.md +++ /dev/null @@ -1,587 +0,0 @@ -# Server OmniRoute MCP - -> **Server protokolu modelovรฉho kontextu** , kterรฝ zpล™รญstupลˆuje inteligenci brรกny OmniRoute jako **16 nรกstrojลฏ** pro agenty umฤ›lรฉ inteligence. - -Server MCP umoลพลˆuje libovolnรฉmu agentovi umฤ›lรฉ inteligence (Claude Desktop, Cursor, VS Code Copilot, vlastnรญm agentลฏm) programovฤ› **monitorovat, ล™รญdit a optimalizovat** brรกnu umฤ›lรฉ inteligence OmniRoute. - ---- - -## Architektura - -``` -โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” -โ”‚ AI Agent / IDE โ”‚ -โ”‚ (Claude Desktop, Cursor, VS Code, Custom) โ”‚ -โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ - โ”‚ MCP Protocol (stdio or HTTP) - โ–ผ -โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” -โ”‚ OmniRoute MCP Server โ”‚ -โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ -โ”‚ โ”‚ Scope โ”‚ โ”‚ 16 MCP Tools โ”‚ โ”‚ Audit Logger โ”‚ โ”‚ -โ”‚ โ”‚ Enforcement โ”‚โ”€โ”€โ”‚ (Phase 1 + 2) โ”‚โ”€โ”€โ”‚ (SHA-256/SQLite) โ”‚ โ”‚ -โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ -โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ - โ”‚ HTTP (internal) - โ–ผ -โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” -โ”‚ OmniRoute Gateway (port 20128) โ”‚ -โ”‚ /v1/chat/completions /api/combos /api/usage ... โ”‚ -โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ -``` - ---- - -## Rychlรฝ start - -### 1. Promฤ›nnรฉ prostล™edรญ - -```bash -# Required: OmniRoute base URL -export OMNIROUTE_BASE_URL="http://localhost:20128" - -# Optional: API key for authenticated access -export OMNIROUTE_API_KEY="your-api-key" - -# Optional: Scope enforcement (default: disabled) -export OMNIROUTE_MCP_ENFORCE_SCOPES="true" -export OMNIROUTE_MCP_SCOPES="read:health,read:combos,read:quota,read:usage,read:models,execute:completions,write:combos,write:budget,write:resilience" -``` - -### 2. Transport stdio (integrace IDE) - -Pล™idejte do konfigurace klienta MCP: - -**Claude Desktop** ( `claude_desktop_config.json` ): - -```json -{ - "mcpServers": { - "omniroute": { - "command": "node", - "args": ["path/to/9router/open-sse/mcp-server/server.ts"], - "env": { - "OMNIROUTE_BASE_URL": "http://localhost:20128", - "OMNIROUTE_API_KEY": "your-key" - } - } - } -} -``` - -**Cursor** ( `.cursor/mcp.json` ): - -```json -{ - "mcpServers": { - "omniroute": { - "command": "npx", - "args": ["tsx", "open-sse/mcp-server/server.ts"], - "env": { - "OMNIROUTE_BASE_URL": "http://localhost:20128" - } - } - } -} -``` - -**VS Code** ( `.vscode/settings.json` ): - -```json -{ - "mcp": { - "servers": { - "omniroute": { - "command": "npx", - "args": ["tsx", "open-sse/mcp-server/server.ts"], - "env": { - "OMNIROUTE_BASE_URL": "http://localhost:20128" - } - } - } - } -} -``` - -### 3. Spuลกtฤ›nรญ pล™es CLI - -```bash -# Direct start (stdio) -npx tsx open-sse/mcp-server/server.ts - -# Or via OmniRoute CLI -omniroute --mcp -``` - ---- - -## Referenฤnรญ informace o nรกstrojรญch - -### Fรกze 1: Zรกkladnรญ nรกstroje (8) - -# | Nรกstroj | Rozsahy | Popis ---- | --- | --- | --- -1 | `omniroute_get_health` | `read:health` | Stav brรกny, dostupnost, pamฤ›ลฅ, jistiฤe, limity rychlosti, statistiky mezipamฤ›ti -2 | `omniroute_list_combos` | `read:combos` | Vypsat vลกechny kombinace (modelovรฉ ล™etฤ›zce) se strategiemi a volitelnรฝmi metrikami -3 | `omniroute_get_combo_metrics` | `read:combos` | Metriky vรฝkonu pro konkrรฉtnรญ kombinaci -4 | `omniroute_switch_combo` | `write:combos` | Aktivace nebo deaktivace komba pro smฤ›rovรกnรญ -5 | `omniroute_check_quota` | `read:quota` | Zbรฝvajรญcรญ kvรณta API na poskytovatele se stavem tokenu -6 | `omniroute_route_request` | `execute:completions` | Odeslat dokonฤenรญ chatu pomocรญ inteligentnรญho smฤ›rovรกnรญ -7 | `omniroute_cost_report` | `read:usage` | Zprรกva o nรกkladech podle obdobรญ (relace/den/tรฝden/mฤ›sรญc) s rozpisem podle poskytovatele -8 | `omniroute_list_models_catalog` | `read:models` | Seznam vลกech dostupnรฝch modelลฏ od rลฏznรฝch poskytovatelลฏ s funkcemi a cenami - -### Fรกze 2: Pokroฤilรฉ nรกstroje (8) - -# | Nรกstroj | Rozsahy | Popis ---- | --- | --- | --- -9 | `omniroute_simulate_route` | `read:health` , `read:combos` | Simulace trasy na dryru zobrazujรญcรญ zรกloลพnรญ strom a odhadovanรฉ nรกklady -10 | `omniroute_set_budget_guard` | `write:budget` | Nastavit rozpoฤet relace s akcรญ pล™i pล™ekroฤenรญ: `degrade` , `block` nebo `alert` -11 | `omniroute_set_resilience_profile` | `write:resilience` | Pouลพijte profil odolnosti: `aggressive` , `balanced` nebo `conservative` -12 | `omniroute_test_combo` | `execute:completions` , `read:combos` | Otestujte kaลพdรฉho poskytovatele v kombinaci se skuteฤnรฝm vรฝzvou a nahlaste latenci/nรกklady -13 | `omniroute_get_provider_metrics` | `read:health` | Metriky pro jednotlivรฉ poskytovatele s percentily latence (p50/p95/p99), jistiฤ -14 | `omniroute_best_combo_for_task` | `read:combos` , `read:health` | Doporuฤenรญ kombinacรญ podle typu รบkolu s vyuลพitรญm umฤ›lรฉ inteligence s omezenรญmi rozpoฤtu/latence -15 | `omniroute_explain_route` | `read:health` , `read:usage` | Vysvฤ›tlete, proฤ byl poลพadavek smฤ›rovรกn k poskytovateli (faktory hodnocenรญ, zรกloลพnรญ metody) -16 | `omniroute_get_session_snapshot` | `read:usage` | Snรญmek celรฉho relace: nรกklady, tokeny, top modely, chyby, stav rozpoฤtu - ---- - -## Pล™รญklady klientลฏ - -### Python โ€” Kompletnรญ pracovnรญ postup agenta - -```python -""" -OmniRoute MCP Client โ€” Python example using the mcp SDK. -Install: pip install mcp -""" -import asyncio -from mcp import ClientSession, StdioServerParameters -from mcp.client.stdio import stdio_client - -async def main(): - server = StdioServerParameters( - command="npx", - args=["tsx", "open-sse/mcp-server/server.ts"], - env={ - "OMNIROUTE_BASE_URL": "http://localhost:20128", - "OMNIROUTE_API_KEY": "your-key", - }, - ) - - async with stdio_client(server) as (read, write): - async with ClientSession(read, write) as session: - await session.initialize() - - # 1. Check gateway health - health = await session.call_tool("omniroute_get_health", {}) - print("Health:", health.content[0].text) - - # 2. List available combos with metrics - combos = await session.call_tool("omniroute_list_combos", { - "includeMetrics": True - }) - print("Combos:", combos.content[0].text) - - # 3. Find the best combo for a coding task - best = await session.call_tool("omniroute_best_combo_for_task", { - "taskType": "coding", - "budgetConstraint": 0.50, - "latencyConstraint": 5000, - }) - print("Best combo:", best.content[0].text) - - # 4. Set a session budget guard - budget = await session.call_tool("omniroute_set_budget_guard", { - "maxCost": 1.00, - "action": "degrade", - "degradeToTier": "cheap", - }) - print("Budget guard:", budget.content[0].text) - - # 5. Route a request through intelligent pipeline - response = await session.call_tool("omniroute_route_request", { - "model": "claude-sonnet-4", - "messages": [ - {"role": "user", "content": "Write a Python hello world"} - ], - "role": "coding", - }) - print("Response:", response.content[0].text) - - # 6. Get the session snapshot - snapshot = await session.call_tool("omniroute_get_session_snapshot", {}) - print("Session:", snapshot.content[0].text) - -asyncio.run(main()) -``` - -### TypeScript โ€” Programovรฝ agent - -```typescript -import { Client } from "@modelcontextprotocol/sdk/client/index.js"; -import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js"; - -async function main() { - const transport = new StdioClientTransport({ - command: "npx", - args: ["tsx", "open-sse/mcp-server/server.ts"], - env: { - OMNIROUTE_BASE_URL: "http://localhost:20128", - OMNIROUTE_API_KEY: "your-key", - }, - }); - - const client = new Client({ name: "my-agent", version: "1.0.0" }); - await client.connect(transport); - - // Check quota before deciding which model to use - const quota = await client.callTool({ - name: "omniroute_check_quota", - arguments: { provider: "claude" }, - }); - console.log("Claude quota:", quota.content); - - // Simulate the route before actually calling - const simulation = await client.callTool({ - name: "omniroute_simulate_route", - arguments: { - model: "claude-sonnet-4", - promptTokenEstimate: 2000, - }, - }); - console.log("Route simulation:", simulation.content); - - // Send the actual request - const result = await client.callTool({ - name: "omniroute_route_request", - arguments: { - model: "claude-sonnet-4", - messages: [{ role: "user", content: "Explain async/await" }], - }, - }); - console.log("Result:", result.content); - - // Cost report - const costs = await client.callTool({ - name: "omniroute_cost_report", - arguments: { period: "session" }, - }); - console.log("Costs:", costs.content); - - await client.close(); -} - -main(); -``` - -### Go โ€” HTTP klient - -```go -package main - -import ( - "bytes" - "encoding/json" - "fmt" - "io" - "net/http" -) - -// Simplified direct-API approach (bypass MCP, hit OmniRoute APIs directly) -// Useful if you don't need MCP protocol framing. - -func callTool(baseURL, tool string, args map[string]any) (string, error) { - // MCP tools map to OmniRoute APIs: - endpoints := map[string]string{ - "health": "/api/monitoring/health", - "combos": "/api/combos", - "quota": "/api/usage/quota", - "models": "/v1/models", - } - - url := baseURL + endpoints[tool] - resp, err := http.Get(url) - if err != nil { - return "", err - } - defer resp.Body.Close() - body, _ := io.ReadAll(resp.Body) - return string(body), nil -} - -func routeRequest(baseURL, model, prompt string) (string, error) { - payload := map[string]any{ - "model": model, - "messages": []map[string]string{ - {"role": "user", "content": prompt}, - }, - "stream": false, - } - data, _ := json.Marshal(payload) - - resp, err := http.Post( - baseURL+"/v1/chat/completions", - "application/json", - bytes.NewReader(data), - ) - if err != nil { - return "", err - } - defer resp.Body.Close() - body, _ := io.ReadAll(resp.Body) - return string(body), nil -} - -func main() { - base := "http://localhost:20128" - - health, _ := callTool(base, "health", nil) - fmt.Println("Health:", health) - - result, _ := routeRequest(base, "auto", "Hello from Go!") - fmt.Println("Result:", result) -} -``` - ---- - -## Pล™รญpady pouลพitรญ - -### ๐Ÿ”„ Pล™รญpad pouลพitรญ 1: Agent pro automatickรฉ ozdravovรกnรญ - -Agent, kterรฝ monitoruje stav OmniRoute a automaticky pล™epรญnรก kombinace, kdyลพ se stav poskytovatelลฏ zhorลกรญ. - -```python -async def auto_healing_loop(session): - """Monitor health and react to provider issues.""" - while True: - # Check health - health = await session.call_tool("omniroute_get_health", {}) - data = json.loads(health.content[0].text) - - # Find providers with open circuit breakers - broken = [ - cb for cb in data["circuitBreakers"] - if cb["state"] == "OPEN" - ] - - if broken: - # Switch to a different resilience profile - await session.call_tool("omniroute_set_resilience_profile", { - "profile": "conservative" - }) - - # Find best alternative combo - best = await session.call_tool("omniroute_best_combo_for_task", { - "taskType": "coding" - }) - best_data = json.loads(best.content[0].text) - combo_id = best_data["recommendedCombo"]["id"] - - # Activate it - await session.call_tool("omniroute_switch_combo", { - "comboId": combo_id, "active": True - }) - print(f"โš ๏ธ Auto-healed: switched to {combo_id}") - - await asyncio.sleep(30) # Check every 30 seconds -``` - -### ๐Ÿ’ฐ Pล™รญpad uลพitรญ 2: Programovacรญ agent s ohledem na rozpoฤet - -Agent, kterรฝ sleduje nรกklady v reรกlnรฉm ฤase a pล™i blรญลพรญcรญm se vyฤerpรกnรญ rozpoฤtu pล™echรกzรญ na levnฤ›jลกรญ modely. - -```python -async def budget_aware_coding(session, task: str, max_budget: float): - """Complete a coding task within a budget.""" - # Set budget guard - await session.call_tool("omniroute_set_budget_guard", { - "maxCost": max_budget, - "action": "degrade", - "degradeToTier": "cheap", - }) - - # Simulate first to estimate cost - sim = await session.call_tool("omniroute_simulate_route", { - "model": "claude-sonnet-4", - "promptTokenEstimate": len(task.split()) * 2, - }) - sim_data = json.loads(sim.content[0].text) - estimated_cost = sim_data["fallbackTree"]["bestCaseCost"] - print(f"Estimated cost: ${estimated_cost:.4f}") - - # Send request - result = await session.call_tool("omniroute_route_request", { - "model": "claude-sonnet-4", - "messages": [{"role": "user", "content": task}], - "role": "coding", - }) - - # Check remaining budget - snapshot = await session.call_tool("omniroute_get_session_snapshot", {}) - snap_data = json.loads(snapshot.content[0].text) - print(f"Session cost: ${snap_data['costTotal']:.4f}") - if snap_data.get("budgetGuard"): - print(f"Budget remaining: ${snap_data['budgetGuard']['remaining']:.4f}") - - return json.loads(result.content[0].text)["response"]["content"] -``` - -### ๐Ÿงช Pล™รญpad pouลพitรญ 3: Kombinovanรฝ benchmarkingovรฝ agent - -Agent, kterรฝ pravidelnฤ› porovnรกvรก vลกechna komba a hlรกsรญ nejrychlejลกรญ/nejlevnฤ›jลกรญ. - -```python -async def benchmark_combos(session): - """Benchmark all enabled combos and rank them.""" - combos = await session.call_tool("omniroute_list_combos", { - "includeMetrics": True, - }) - combo_list = json.loads(combos.content[0].text)["combos"] - - results = [] - for combo in combo_list: - if not combo["enabled"]: - continue - - test = await session.call_tool("omniroute_test_combo", { - "comboId": combo["id"], - "testPrompt": "Return the number 42.", - }) - test_data = json.loads(test.content[0].text) - results.append({ - "combo": combo["name"], - "fastest": test_data["summary"]["fastestProvider"], - "cheapest": test_data["summary"]["cheapestProvider"], - "success_rate": f'{test_data["summary"]["successful"]}/{test_data["summary"]["totalProviders"]}', - }) - - print("๐Ÿ“Š Combo Benchmark Results:") - for r in results: - print(f" {r['combo']}: fastest={r['fastest']}, cheapest={r['cheapest']}, success={r['success_rate']}") -``` - -### ๐Ÿ” Pล™รญpad pouลพitรญ 4: Agent pro ladฤ›nรญ po smrti - -Agent, kterรฝ vysvฤ›tluje, proฤ byl poลพadavek smฤ›rovรกn ke konkrรฉtnรญmu poskytovateli. - -```typescript -async function debugRouting(client: Client, requestId: string) { - // Explain the routing decision - const explanation = await client.callTool({ - name: "omniroute_explain_route", - arguments: { requestId }, - }); - const data = JSON.parse(explanation.content[0].text); - - console.log(`Request ${requestId}:`); - console.log(` Provider: ${data.decision.providerSelected}`); - console.log(` Model: ${data.decision.modelUsed}`); - console.log(` Score: ${data.decision.score}`); - console.log(` Factors:`); - for (const factor of data.decision.factors) { - console.log(` ${factor.name}: ${factor.value} (weight: ${factor.weight})`); - } - if (data.decision.fallbacksTriggered.length > 0) { - console.log(` Fallbacks triggered:`); - for (const fb of data.decision.fallbacksTriggered) { - console.log(` ${fb.provider}: ${fb.reason}`); - } - } -} -``` - -### ๐Ÿ“‹ Pล™รญpad pouลพitรญ 5: Agent pro vyhledรกvรกnรญ modelลฏ - -Agent, kterรฝ vyhledรกvรก nejlevnฤ›jลกรญ modely pro danou funkci. - -```python -async def find_cheapest_models(session, capability="chat"): - """Find the cheapest available models for a capability.""" - catalog = await session.call_tool("omniroute_list_models_catalog", { - "capability": capability, - }) - models = json.loads(catalog.content[0].text)["models"] - - # Filter available models with pricing - priced = [ - m for m in models - if m["status"] == "available" and m.get("pricing") - ] - priced.sort(key=lambda m: m["pricing"]["inputPerMillion"] or float("inf")) - - print(f"๐Ÿ’ก Cheapest {capability} models:") - for m in priced[:5]: - input_cost = m["pricing"]["inputPerMillion"] or 0 - output_cost = m["pricing"]["outputPerMillion"] or 0 - print(f" {m['id']} ({m['provider']}): ${input_cost}/M in, ${output_cost}/M out") -``` - ---- - -## Zabezpeฤenรญ a vynucovรกnรญ rozsahu - -Server MCP podporuje **detailnรญ vynucovรกnรญ rozsahu** pro prostล™edรญ s vรญce klienty: - -Rozsah | Nรกstroje ---- | --- -`read:health` | `get_health` , `simulate_route` , `get_provider_metrics` , `best_combo_for_task` , `explain_route` -`read:combos` | `list_combos` , `get_combo_metrics` , `simulate_route` , `best_combo_for_task` , `test_combo` -`read:quota` | `check_quota` -`read:usage` | `cost_report` , `explain_route` , `get_session_snapshot` -`read:models` | `list_models_catalog` -`write:combos` | `switch_combo` -`write:budget` | `set_budget_guard` -`write:resilience` | `set_resilience_profile` -`execute:completions` | `route_request` , `test_combo` - -**Rozsahy zรกstupnรฝch znakลฏ:** Pouลพijte `read:*` pro udฤ›lenรญ vลกech rozsahลฏ pro ฤtenรญ nebo `*` pro plnรฝ pล™รญstup. - ---- - -## Protokolovรกnรญ auditu - -Kaลพdรฉ volรกnรญ nรกstroje je zaznamenรกno do tabulky SQLite `mcp_tool_audit` : - -- **Vstup:** SHA-256 hash (nikdy neuklรกdรก nezpracovanรฉ vรฝzvy) -- **Vรฝstup:** Zkrรกceno na 200 znakลฏ -- **Metadata:** Nรกzev nรกstroje, doba trvรกnรญ, รบspฤ›ch/chyba, ID klรญฤe API - -Pล™รญstup k auditnรญm datลฏm prostล™ednictvรญm: - -```typescript -import { getRecentAuditEntries, getAuditStats } from "./audit"; - -const entries = await getRecentAuditEntries(50); -const stats = await getAuditStats(); -// stats: { totalCalls, successRate, avgDurationMs, topTools } -``` - ---- - -## Struktura souboru - -``` -mcp-server/ -โ”œโ”€โ”€ server.ts # MCP server setup, essential tool handlers, entry point -โ”œโ”€โ”€ index.ts # Barrel export -โ”œโ”€โ”€ audit.ts # SQLite audit logger (SHA-256 input hashing) -โ”œโ”€โ”€ scopeEnforcement.ts # Fine-grained scope enforcement -โ”œโ”€โ”€ schemas/ -โ”‚ โ”œโ”€โ”€ tools.ts # Zod schemas for all 16 tools (input/output/scopes) -โ”‚ โ”œโ”€โ”€ a2a.ts # A2A protocol types (Agent Card, Task, JSON-RPC) -โ”‚ โ”œโ”€โ”€ audit.ts # Audit & routing decision types + hash helpers -โ”‚ โ””โ”€โ”€ index.ts # Schema barrel export -โ”œโ”€โ”€ tools/ -โ”‚ โ””โ”€โ”€ advancedTools.ts # Phase 2 tool handlers (8 advanced tools) -โ””โ”€โ”€ __tests__/ - โ”œโ”€โ”€ essentialTools.test.ts - โ”œโ”€โ”€ advancedTools.test.ts - โ””โ”€โ”€ a2aLifecycle.test.ts -``` - ---- - -## Licence - -Souฤรกst [OmniRoute](https://github.com/diegosouzapw/OmniRoute) โ€” licence MIT. diff --git a/docs/i18n/cs/src/lib/a2a/README.md b/docs/i18n/cs/src/lib/a2a/README.md new file mode 100644 index 0000000000..a221082084 --- /dev/null +++ b/docs/i18n/cs/src/lib/a2a/README.md @@ -0,0 +1,752 @@ +# OmniRoute A2A Server (ฤŒeลกtina) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../../../src/lib/a2a/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../../../es/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../../../fr/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../../../de/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../../../it/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../../../ru/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../../../zh-CN/src/lib/a2a/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../../../ja/src/lib/a2a/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../../../ko/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../../../ar/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../../../in/src/lib/a2a/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../../../th/src/lib/a2a/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../../../vi/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../../../id/src/lib/a2a/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../../../ms/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../../../nl/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../../../pl/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../../../sv/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../../../no/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../../../da/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../../../fi/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../../../pt/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../../../ro/src/lib/a2a/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../../../hu/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../../../bg/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../../../sk/src/lib/a2a/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../../../uk-UA/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../../../he/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../../../phi/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../../../pt-BR/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../../../cs/src/lib/a2a/README.md) + +--- + +> **Agent-to-Agent Protocol v0.3** โ€” Enables any AI agent to use OmniRoute as an intelligent routing agent via JSON-RPC 2.0. + +The A2A Server exposes OmniRoute as a **first-class agent** that other agents can discover, delegate tasks to, and collaborate with using the [A2A Protocol](https://google.github.io/A2A/). + +--- + +## Architektura + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Orchestrator Agent โ”‚ +โ”‚ (LangChain, CrewAI, AutoGen, Custom Agent) โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ 1. GET /.well-known/agent.json (discover) + โ”‚ 2. POST /a2a (JSON-RPC 2.0) + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ OmniRoute A2A Server โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Task Manager โ”‚ โ”‚ Skill Engine โ”‚ โ”‚ SSE Streaming โ”‚ โ”‚ +โ”‚ โ”‚ (lifecycle) โ”‚โ”€โ”€โ”‚ (registry) โ”‚โ”€โ”€โ”‚ (real-time) โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ +โ”‚ Skills: โ”‚ โ”‚ +โ”‚ โ”œโ”€ smart-routing โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ””โ”€ quota-management โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ Routing Decision Logger โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ OmniRoute Gateway (internal) + /v1/chat/completions, /api/combos, /api/usage/quota +``` + +--- + +## Rychlรฝ start + +### Agent Discovery + +Every A2A-compatible agent exposes an **Agent Card** at `/.well-known/agent.json`: + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +**Response:** + +```json +{ + "name": "OmniRoute", + "description": "Intelligent AI gateway with auto-routing across 50+ providers", + "url": "http://localhost:20128/a2a", + "version": "1.8.1", + "capabilities": { + "streaming": true, + "pushNotifications": false + }, + "skills": [ + { + "id": "smart-routing", + "name": "Smart Routing", + "description": "Routes prompts through OmniRoute intelligent pipeline", + "tags": ["routing", "llm", "multi-provider", "cost-optimization"], + "examples": [ + "Write a hello world in Python", + "Explain quantum computing using the cheapest provider" + ] + }, + { + "id": "quota-management", + "name": "Quota Management", + "description": "Natural-language queries about provider quotas", + "tags": ["quota", "analytics", "cost"], + "examples": [ + "Which provider has the most quota remaining?", + "Suggest a free combo for coding" + ] + } + ], + "authentication": { + "schemes": ["bearer"], + "apiKeyHeader": "Authorization" + } +} +``` + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Send a message to a skill and receive the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python hello world"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "a1b2c3d4-...", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "print('Hello, World!')" }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.0030)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "2026-03-04T..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"Quantum computing..."}}} + +: heartbeat 2026-03-04T21:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Running Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Skills Reference + +### `smart-routing` + +Routes prompts through OmniRoute's intelligent pipeline with full observability. + +**Parameters (in `metadata`):** + +| Parameter | Type | Default | Description | +| --------- | -------- | ------------ | ---------------------------------------------------------------------------------------- | +| `model` | `string` | `"auto"` | Target model (e.g., `claude-sonnet-4`, `gpt-4o`, `auto`) | +| `combo` | `string` | active combo | Specific combo to route through | +| `budget` | `number` | none | Maximum cost in USD for this request | +| `role` | `string` | none | Task role hint: `coding`, `review`, `planning`, `analysis`, `debugging`, `documentation` | + +**Returns:** + +| Field | Description | +| ------------------------------ | --------------------------------------------------------- | +| `artifacts[].content` | The LLM response text | +| `metadata.routing_explanation` | Human-readable explanation of routing decision | +| `metadata.cost_envelope` | Estimated vs actual cost with currency | +| `metadata.resilience_trace` | Array of events (primary_selected, fallback_needed, etc.) | +| `metadata.policy_verdict` | Whether the request was allowed and why | + +### `quota-management` + +Answers natural-language queries about provider quotas. + +**Query types (inferred from message content):** + +| Query Pattern | Response Type | +| ---------------------------------------------- | -------------------------------------------------------- | +| Contains `"ranking"`, `"most quota"`, `"best"` | Providers ranked by remaining quota | +| Contains `"free"`, `"suggest"` | Lists free combos or suggests free-tier providers | +| Default | Full quota summary with warnings for low-quota providers | + +--- + +## Task Lifecycle + +``` +submitted โ”€โ”€โ†’ working โ”€โ”€โ†’ completed + โ”€โ”€โ†’ failed + โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ†’ cancelled +``` + +| State | Description | +| ----------- | ----------------------------------------------------- | +| `submitted` | Task created, queued for execution | +| `working` | Skill handler is executing | +| `completed` | Execution succeeded, artifacts available | +| `failed` | Execution failed or task expired (TTL: 5 min default) | +| `cancelled` | Cancelled by client via `tasks/cancel` | + +- Terminal states: `completed`, `failed`, `cancelled` (no further transitions) +- Expired tasks in `submitted` or `working` are auto-marked as `failed` +- Tasks are garbage-collected after 2ร— TTL + +--- + +## Client Examples + +### Python โ€” Orchestrator Agent + +```python +""" +A2A Client โ€” Python example. +Discovers OmniRoute agent, sends a task, and processes the result. +""" +import requests +import json + +BASE_URL = "http://localhost:20128" +API_KEY = "your-api-key" +HEADERS = { + "Content-Type": "application/json", + "Authorization": f"Bearer {API_KEY}", +} + +# 1. Discover agent capabilities +agent_card = requests.get(f"{BASE_URL}/.well-known/agent.json").json() +print(f"Agent: {agent_card['name']} v{agent_card['version']}") +print(f"Skills: {[s['id'] for s in agent_card['skills']]}") + +# 2. Send a smart-routing task +response = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python quicksort implementation"}], + "metadata": { + "model": "auto", + "combo": "fast-coding", + "budget": 0.10, + } + } +}) +result = response.json()["result"] +print(f"\n๐Ÿ“ Response: {result['artifacts'][0]['content'][:200]}...") +print(f"๐Ÿ”€ Routing: {result['metadata']['routing_explanation']}") +print(f"๐Ÿ’ฐ Cost: ${result['metadata']['cost_envelope']['actual']}") +print(f"๐Ÿ›ก๏ธ Policy: {result['metadata']['policy_verdict']['reason']}") + +# 3. Query quota status +quota_resp = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-2", + "method": "message/send", + "params": { + "skill": "quota-management", + "messages": [{"role": "user", "content": "Which provider has the most quota remaining?"}], + } +}) +quota_result = quota_resp.json()["result"] +print(f"\n๐Ÿ“Š Quota: {quota_result['artifacts'][0]['content']}") +``` + +### TypeScript โ€” Multi-Agent Orchestrator + +```typescript +/** + * A2A Client โ€” TypeScript example. + * Shows agent discovery, task delegation, and streaming. + */ + +const BASE_URL = "http://localhost:20128"; +const API_KEY = "your-api-key"; + +interface JsonRpcResponse { + jsonrpc: "2.0"; + id: string | number; + result?: T; + error?: { code: number; message: string }; +} + +async function a2aCall(method: string, params: Record): Promise { + const resp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: `${method}-${Date.now()}`, + method, + params, + }), + }); + const json: JsonRpcResponse = await resp.json(); + if (json.error) throw new Error(`[${json.error.code}] ${json.error.message}`); + return json.result!; +} + +// โ”€โ”€ Agent Discovery โ”€โ”€ +const agentCard = await fetch(`${BASE_URL}/.well-known/agent.json`).then((r) => r.json()); +console.log(`Connected to: ${agentCard.name} (${agentCard.skills.length} skills)`); + +// โ”€โ”€ Smart Routing: Send a coding task โ”€โ”€ +const routingResult = await a2aCall("message/send", { + skill: "smart-routing", + messages: [{ role: "user", content: "Implement a Redis cache wrapper in TypeScript" }], + metadata: { model: "claude-sonnet-4", role: "coding" }, +}); +console.log("Response:", routingResult.artifacts[0].content); +console.log("Provider:", routingResult.metadata.routing_explanation); + +// โ”€โ”€ Quota Management: Find free alternatives โ”€โ”€ +const quotaResult = await a2aCall("message/send", { + skill: "quota-management", + messages: [{ role: "user", content: "Suggest free combos for documentation" }], +}); +console.log("Free combos:", quotaResult.artifacts[0].content); + +// โ”€โ”€ Streaming: Real-time response โ”€โ”€ +const streamResp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "stream-1", + method: "message/stream", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Explain microservices architecture" }], + }, + }), +}); + +const reader = streamResp.body!.getReader(); +const decoder = new TextDecoder(); +while (true) { + const { done, value } = await reader.read(); + if (done) break; + const chunk = decoder.decode(value); + for (const line of chunk.split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + if (event.params.chunk) { + process.stdout.write(event.params.chunk.content); + } + if (event.params.task.state === "completed") { + console.log("\nโœ… Stream completed"); + } + } + } +} +``` + +### Python โ€” LangChain A2A Integration + +```python +""" +LangChain integration โ€” Use OmniRoute A2A as a custom LLM. +""" +from langchain.llms.base import BaseLLM +from langchain.schema import LLMResult, Generation +import requests +from typing import List, Optional + +class OmniRouteA2A(BaseLLM): + base_url: str = "http://localhost:20128" + api_key: str = "" + model: str = "auto" + combo: Optional[str] = None + + @property + def _llm_type(self) -> str: + return "omniroute-a2a" + + def _call(self, prompt: str, stop: Optional[List[str]] = None, **kwargs) -> str: + response = requests.post( + f"{self.base_url}/a2a", + headers={ + "Content-Type": "application/json", + "Authorization": f"Bearer {self.api_key}", + }, + json={ + "jsonrpc": "2.0", + "id": "langchain-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": prompt}], + "metadata": { + "model": self.model, + **({"combo": self.combo} if self.combo else {}), + }, + }, + }, + ) + result = response.json()["result"] + return result["artifacts"][0]["content"] + + def _generate(self, prompts: List[str], stop=None, **kwargs) -> LLMResult: + return LLMResult( + generations=[[Generation(text=self._call(p, stop))] for p in prompts] + ) + +# Usage +llm = OmniRouteA2A( + base_url="http://localhost:20128", + api_key="your-key", + model="auto", + combo="fast-coding", +) +result = llm("Write a Python function to merge two sorted lists") +print(result) +``` + +### Go โ€” A2A Client + +```go +package main + +import ( + "bytes" + "encoding/json" + "fmt" + "io" + "net/http" +) + +const baseURL = "http://localhost:20128" +const apiKey = "your-api-key" + +type JsonRpcRequest struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Method string `json:"method"` + Params interface{} `json:"params"` +} + +type JsonRpcResponse struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Result interface{} `json:"result"` + Error *struct { + Code int `json:"code"` + Message string `json:"message"` + } `json:"error"` +} + +func a2aCall(method string, params interface{}) (*JsonRpcResponse, error) { + body, _ := json.Marshal(JsonRpcRequest{ + Jsonrpc: "2.0", + ID: "go-1", + Method: method, + Params: params, + }) + + req, _ := http.NewRequest("POST", baseURL+"/a2a", bytes.NewReader(body)) + req.Header.Set("Content-Type", "application/json") + req.Header.Set("Authorization", "Bearer "+apiKey) + + resp, err := http.DefaultClient.Do(req) + if err != nil { + return nil, err + } + defer resp.Body.Close() + data, _ := io.ReadAll(resp.Body) + + var result JsonRpcResponse + json.Unmarshal(data, &result) + return &result, nil +} + +func main() { + // Discover agent + resp, _ := http.Get(baseURL + "/.well-known/agent.json") + defer resp.Body.Close() + body, _ := io.ReadAll(resp.Body) + fmt.Println("Agent Card:", string(body)) + + // Send smart-routing task + result, _ := a2aCall("message/send", map[string]interface{}{ + "skill": "smart-routing", + "messages": []map[string]string{{"role": "user", "content": "Hello from Go!"}}, + "metadata": map[string]interface{}{"model": "auto"}, + }) + out, _ := json.MarshalIndent(result.Result, "", " ") + fmt.Println("Result:", string(out)) +} +``` + +--- + +## Use Cases + +### ๐Ÿค– Use Case 1: Multi-Agent Coding Pipeline + +An orchestrator agent delegates code generation to OmniRoute, then passes the output to a review agent. + +```python +def coding_pipeline(task: str): + # Step 1: Generate code via OmniRoute A2A + code_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Write production-quality code: {task}"} + ], metadata={"model": "auto", "role": "coding"}) + code = code_result["artifacts"][0]["content"] + + # Step 2: Review the code via OmniRoute A2A (different model) + review_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Review this code for bugs and improvements:\n\n{code}"} + ], metadata={"model": "auto", "role": "review"}) + review = review_result["artifacts"][0]["content"] + + # Step 3: Check costs + print(f"Code cost: ${code_result['metadata']['cost_envelope']['actual']}") + print(f"Review cost: ${review_result['metadata']['cost_envelope']['actual']}") + + return {"code": code, "review": review} +``` + +### ๐Ÿ’ก Use Case 2: Quota-Aware Agent Swarm + +Multiple agents share quota through OmniRoute, using the quota skill to coordinate. + +```python +async def quota_aware_agent(agent_name: str, task: str): + # Check quota before starting + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Which provider has the most quota remaining?"} + ]) + print(f"[{agent_name}] {quota['artifacts'][0]['content']}") + + # Send request with budget constraint + result = a2a_send("smart-routing", [ + {"role": "user", "content": task} + ], metadata={"budget": 0.05}) + + policy = result["metadata"]["policy_verdict"] + if not policy["allowed"]: + print(f"[{agent_name}] โš ๏ธ Budget exceeded: {policy['reason']}") + # Fall back to free combo + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Suggest free combos"} + ]) + print(f"[{agent_name}] Free alternatives: {quota['artifacts'][0]['content']}") + + return result +``` + +### ๐Ÿ“Š Use Case 3: Real-Time Streaming Dashboard + +A monitoring agent streams responses and displays progress in real-time. + +```typescript +async function streamingDashboard(prompt: string) { + const response = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { "Content-Type": "application/json", Authorization: `Bearer ${API_KEY}` }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "dash-1", + method: "message/stream", + params: { skill: "smart-routing", messages: [{ role: "user", content: prompt }] }, + }), + }); + + let totalChunks = 0; + const reader = response.body!.getReader(); + const decoder = new TextDecoder(); + + while (true) { + const { done, value } = await reader.read(); + if (done) break; + + for (const line of decoder.decode(value).split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + const state = event.params.task.state; + + if (state === "working" && event.params.chunk) { + totalChunks++; + process.stdout.write( + `\r[Chunk ${totalChunks}] ${event.params.chunk.content.slice(0, 50)}...` + ); + } + if (state === "completed") { + const meta = event.params.metadata; + console.log( + `\nโœ… Done | Cost: $${meta?.cost_envelope?.actual || 0} | Route: ${meta?.routing_explanation || "N/A"}` + ); + } + if (state === "failed") { + console.error(`\nโŒ Failed: ${event.params.metadata?.error}`); + } + } + } + } +} +``` + +### ๐Ÿ” Use Case 4: Task Polling Pattern + +For long-running tasks, poll the task status instead of waiting synchronously. + +```python +import time + +def poll_task(task_id: str, timeout: int = 60): + """Poll task status until completion or timeout.""" + start = time.time() + while time.time() - start < timeout: + result = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "poll-1", + "method": "tasks/get", + "params": {"taskId": task_id}, + }).json() + + task = result["result"]["task"] + state = task["state"] + print(f" Task {task_id[:8]}... state={state}") + + if state in ("completed", "failed", "cancelled"): + return task + time.sleep(2) + + # Timeout โ€” cancel the task + requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "cancel-1", + "method": "tasks/cancel", + "params": {"taskId": task_id}, + }) + raise TimeoutError(f"Task {task_id} timed out after {timeout}s") +``` + +--- + +## Error Codes + +| Code | Constant | Meaning | +| ------ | ------------------------ | ---------------------------------------- | +| -32700 | โ€” | Parse error (invalid JSON) | +| -32600 | `INVALID_REQUEST` | Invalid JSON-RPC request or unauthorized | +| -32601 | `METHOD_NOT_FOUND` | Unknown method or skill | +| -32602 | `INVALID_PARAMS` | Missing or invalid parameters | +| -32603 | `INTERNAL_ERROR` | Skill execution failed | +| -32001 | `TASK_NOT_FOUND` | Task ID not found | +| -32002 | `TASK_ALREADY_COMPLETED` | Cannot modify a completed task | +| -32003 | `UNAUTHORIZED` | Invalid or missing API key | +| -32004 | `BUDGET_EXCEEDED` | Request exceeds configured budget | +| -32005 | `PROVIDER_UNAVAILABLE` | No available providers | + +--- + +## Authentication + +All `/a2a` requests require a Bearer token via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server (`OMNIROUTE_API_KEY` is empty), authentication is bypassed. + +--- + +## File Structure + +``` +src/lib/a2a/ +โ”œโ”€โ”€ taskManager.ts # Task lifecycle (create/update/cancel/list), TTL, cleanup +โ”œโ”€โ”€ taskExecution.ts # Generic task executor with state management +โ”œโ”€โ”€ streaming.ts # SSE stream formatting, heartbeat, chunk/completion events +โ”œโ”€โ”€ routingLogger.ts # Routing decision logger (stats, history, retention) +โ””โ”€โ”€ skills/ + โ”œโ”€โ”€ smartRouting.ts # Smart routing skill (routes via /v1/chat/completions) + โ””โ”€โ”€ quotaManagement.ts # Quota management skill (natural-language quota queries) + +src/app/a2a/ +โ””โ”€โ”€ route.ts # Next.js API route handler (JSON-RPC 2.0 dispatch) + +open-sse/mcp-server/ +โ””โ”€โ”€ schemas/a2a.ts # Zod schemas (AgentCard, Task, JSON-RPC, SSE events) +``` + +--- + +## Comparison: MCP vs A2A + +| Feature | MCP Server | A2A Server | +| ----------------- | ---------------------------- | ------------------------------------------------- | +| **Protocol** | Model Context Protocol | Agent-to-Agent Protocol v0.3 | +| **Transport** | stdio / HTTP | HTTP (JSON-RPC 2.0) | +| **Discovery** | Tool listing via MCP | `/.well-known/agent.json` | +| **Granularity** | 16 individual tools | 2 high-level skills | +| **Best for** | IDE agents (Cursor, VS Code) | Multi-agent systems (LangChain, CrewAI) | +| **Streaming** | Not supported | SSE via `message/stream` | +| **Task tracking** | No | Full lifecycle (submitted โ†’ completed) | +| **Observability** | Audit log per tool call | Cost envelope + resilience trace + policy verdict | + +--- + +## Licence + +Part of [OmniRoute](https://github.com/diegosouzapw/OmniRoute) โ€” MIT License. diff --git a/docs/i18n/da/CHANGELOG.md b/docs/i18n/da/CHANGELOG.md index ea9a2c049c..bc247ceb7d 100644 --- a/docs/i18n/da/CHANGELOG.md +++ b/docs/i18n/da/CHANGELOG.md @@ -1,12 +1,92 @@ # Changelog (Dansk) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CHANGELOG.md) --- - ## [Unreleased] +### ๐Ÿ› ๏ธ Maintenance + +- **AGENTS.md rewrite:** Condensed from 297โ†’153 lines. Added build/lint/test commands (including single-test execution), code style guidelines (Prettier, TypeScript, ESLint, naming, imports, error handling, security), and trimmed verbose architecture tables for AI agent consumption. + +## [3.4.2] - 2026-04-01 + +### ๐Ÿ› Bug Fixes + +- **CI Stabilization:** Fixed failing analytics/settings Playwright selectors and request assertions so GitHub Actions E2E runs pass reliably across localized UIs and switch-based controls. +- **Deterministic Tests:** Removed date-sensitive quota fixtures from Copilot usage tests and aligned idempotency/model catalog tests with the merged runtime behavior. +- **MCP Type Hardening:** Removed zero-budget explicit `any` regressions from the MCP server tool registration path, restoring the `check:any-budget:t11` workflow gate. + +### ๐Ÿ› ๏ธ Maintenance + +- **Release Branch Integration:** Consolidated the active feature branches into `release/v3.4.2` on top of current `main` and validated the branch with lint, unit, coverage, build, and CI-mode E2E runs. + +## [3.4.1] - 2026-03-31 + +> [!WARNING] +> **BREAKING CHANGE: request logging, retention, and logging environment variables have been redesigned.** +> On the first startup after upgrading, OmniRoute archives legacy request logs from `DATA_DIR/logs/`, legacy `DATA_DIR/call_logs/`, and `DATA_DIR/log.txt` into `DATA_DIR/log_archives/*.zip`, then removes the deprecated layout and switches to the new unified artifact format under `DATA_DIR/call_logs/`. + +### โœจ New Features + +- **.ENV Migration Utility:** Included `scripts/migrate-env.mjs` to seamlessly migrate `= 18 < 24 (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` | `20128` | Server port | +| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | Base URL for frontend | +| `JWT_SECRET` | (generate above) | JWT signing secret | +| `INITIAL_PASSWORD` | `CHANGEME` | First login password | +| `APP_LOG_LEVEL` | `info` | Log verbosity level | + +### Dashboard Settings + +The dashboard provides UI toggles for features that can also be configured via environment variables: + +| Setting Location | Toggle | Description | +| ------------------- | ------------------ | ------------------------------ | +| Settings โ†’ Advanced | Debug Mode | Enable debug request logs (UI) | +| Settings โ†’ General | Sidebar Visibility | Show/hide sidebar sections | + +These settings are stored in the database and persist across restarts, overriding env var defaults when set. + +### 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:20128/dashboard` +- **API**: `http://localhost:20128/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`, `mcp`, `a2a`, `memory`, `skills`. + +--- + +## Running Tests + +```bash +# All tests (unit + vitest + ecosystem + e2e) +npm run test:all + +# Single test file (Node.js native test runner โ€” most tests use this) +node --import tsx/esm --test tests/unit/your-file.test.mjs + +# Vitest (MCP server, autoCombo, cache) +npm run test:vitest + +# E2E tests (requires Playwright) +npm run test:e2e + +# Protocol clients E2E (MCP transports, A2A) +npm run test:protocols:e2e + +# Ecosystem compatibility tests +npm run test:ecosystem + +# Coverage (55% min statements/lines/functions; 60% branches) +npm run test:coverage +npm run coverage:report + +# Lint + format check +npm run lint +npm run check +``` + +Coverage notes: + +- `npm run test:coverage` measures source coverage for the main unit test suite, excludes `tests/**`, and includes `open-sse/**` +- `npm run coverage:report` prints the detailed file-by-file report from the latest coverage run +- `npm run test:coverage:legacy` preserves the older metric for historical comparison +- See `docs/COVERAGE_PLAN.md` for the phased coverage improvement roadmap + +Current test status: **122 unit test files** covering: + +- Provider translators and format conversion +- Rate limiting, circuit breaker, and resilience +- Semantic cache, idempotency, progress tracking +- Database operations and schema (21 DB modules) +- OAuth flows and authentication +- API endpoint validation (Zod v4) +- MCP server tools and scope enforcement +- Memory and Skills systems + +--- + +## Code Style + +- **ESLint** โ€” Run `npm run lint` before committing +- **Prettier** โ€” Auto-formatted via `lint-staged` on commit (2 spaces, semicolons, double quotes, 100 char width, es5 trailing commas) +- **TypeScript** โ€” All `src/` code uses `.ts`/`.tsx`; `open-sse/` uses `.ts`/`.js`; document with TSDoc (`@param`, `@returns`, `@throws`) +- **No `eval()`** โ€” ESLint enforces `no-eval`, `no-implied-eval`, `no-new-func` +- **Zod validation** โ€” Use Zod v4 schemas for all API input validation +- **Naming**: Files = camelCase/kebab-case, components = PascalCase, constants = UPPER_SNAKE + +--- + +## Project Structure + +``` +src/ # TypeScript (.ts / .tsx) +โ”œโ”€โ”€ app/ # Next.js 16 App Router +โ”‚ โ”œโ”€โ”€ (dashboard)/ # Dashboard pages (23 sections) +โ”‚ โ”œโ”€โ”€ api/ # API routes (51 directories) +โ”‚ โ””โ”€โ”€ login/ # Auth pages (.tsx) +โ”œโ”€โ”€ domain/ # Policy engine (policyEngine, comboResolver, costRules, etc.) +โ”œโ”€โ”€ lib/ # Core business logic (.ts) +โ”‚ โ”œโ”€โ”€ a2a/ # Agent-to-Agent v0.3 protocol server +โ”‚ โ”œโ”€โ”€ acp/ # Agent Communication Protocol registry +โ”‚ โ”œโ”€โ”€ compliance/ # Compliance policy engine +โ”‚ โ”œโ”€โ”€ db/ # SQLite database layer (21 modules + 16 migrations) +โ”‚ โ”œโ”€โ”€ memory/ # Persistent conversational memory +โ”‚ โ”œโ”€โ”€ oauth/ # OAuth providers, services, and utilities +โ”‚ โ”œโ”€โ”€ skills/ # Extensible skill framework +โ”‚ โ”œโ”€โ”€ usage/ # Usage tracking and cost calculation +โ”‚ โ””โ”€โ”€ localDb.ts # Re-export layer only โ€” never add logic here +โ”œโ”€โ”€ middleware/ # Request middleware (promptInjectionGuard) +โ”œโ”€โ”€ mitm/ # MITM proxy (cert, DNS, target routing) +โ”œโ”€โ”€ shared/ +โ”‚ โ”œโ”€โ”€ components/ # React components (.tsx) +โ”‚ โ”œโ”€โ”€ constants/ # Provider definitions (60+), MCP scopes, routing strategies +โ”‚ โ”œโ”€โ”€ utils/ # Circuit breaker, sanitizer, auth helpers +โ”‚ โ””โ”€โ”€ validation/ # Zod v4 schemas +โ””โ”€โ”€ sse/ # SSE proxy pipeline + +open-sse/ # @omniroute/open-sse workspace +โ”œโ”€โ”€ executors/ # 14 provider-specific request executors +โ”œโ”€โ”€ handlers/ # 11 request handlers (chat, responses, embeddings, images, etc.) +โ”œโ”€โ”€ mcp-server/ # MCP server (25 tools, 3 transports, 10 scopes) +โ”œโ”€โ”€ services/ # 36+ services (combo, autoCombo, rateLimitManager, etc.) +โ”œโ”€โ”€ translator/ # Format translators (OpenAI โ†” Claude โ†” Gemini โ†” Responses โ†” Ollama) +โ”œโ”€โ”€ transformer/ # Responses API transformer +โ””โ”€โ”€ utils/ # 22 utility modules (stream, TLS, proxy, logging) + +electron/ # Electron desktop app (cross-platform) + +tests/ +โ”œโ”€โ”€ unit/ # Node.js test runner (122 test files) +โ”œโ”€โ”€ integration/ # Integration tests +โ”œโ”€โ”€ e2e/ # Playwright tests +โ”œโ”€โ”€ security/ # Security tests +โ”œโ”€โ”€ translator/ # Translator-specific tests +โ””โ”€โ”€ load/ # Load tests + +docs/ # Documentation +โ”œโ”€โ”€ ARCHITECTURE.md # System architecture +โ”œโ”€โ”€ API_REFERENCE.md # All endpoints +โ”œโ”€โ”€ USER_GUIDE.md # Provider setup, CLI integration +โ”œโ”€โ”€ TROUBLESHOOTING.md # Common issues +โ”œโ”€โ”€ MCP-SERVER.md # MCP server (25 tools) +โ”œโ”€โ”€ A2A-SERVER.md # A2A agent protocol +โ”œโ”€โ”€ AUTO-COMBO.md # Auto-combo engine +โ”œโ”€โ”€ CLI-TOOLS.md # CLI tools integration +โ”œโ”€โ”€ COVERAGE_PLAN.md # Test coverage improvement plan +โ”œโ”€โ”€ openapi.yaml # OpenAPI specification +โ””โ”€โ”€ adr/ # Architecture Decision Records +``` + +--- + +## Adding a New Provider + +### Step 1: Register Provider Constants + +Add to `src/shared/constants/providers.ts` โ€” Zod-validated at module load. + +### Step 2: Add Executor (if custom logic needed) + +Create executor in `open-sse/executors/your-provider.ts` extending the base executor. + +### Step 3: Add Translator (if non-OpenAI format) + +Create request/response translators in `open-sse/translator/`. + +### Step 4: Add OAuth Config (if OAuth-based) + +Add OAuth credentials in `src/lib/oauth/constants/oauth.ts` and service in `src/lib/oauth/services/`. + +### Step 5: Register Models + +Add model definitions in `open-sse/config/providerRegistry.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 +- [ ] All inputs validated with Zod schemas +- [ ] CHANGELOG updated (if user-facing change) +- [ ] Documentation updated (if applicable) + +--- + +## Releasing + +Releases are managed via the `/generate-release` workflow. When a new GitHub Release is created, the package is **automatically published to npm** via GitHub Actions. + +--- + +## Getting Help + +- **Architecture**: See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) +- **API Reference**: See [`docs/API_REFERENCE.md`](docs/API_REFERENCE.md) +- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **ADRs**: See `docs/adr/` for architectural decision records diff --git a/docs/i18n/da/FEATURES.md b/docs/i18n/da/FEATURES.md deleted file mode 100644 index 8714147c1e..0000000000 --- a/docs/i18n/da/FEATURES.md +++ /dev/null @@ -1,147 +0,0 @@ -# OmniRoute โ€” Dashboard Features Gallery (Dansk) - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) - -> ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../docs/FEATURES.md) - ---- - -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 (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. - -![Providers Dashboard](screenshots/01-providers.png) - ---- - -## ๐ŸŽจ Combos - -Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. - -![Combos Dashboard](screenshots/02-combos.png) - ---- - -## ๐Ÿ“Š Analytics - -Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. - -![Analytics Dashboard](screenshots/03-analytics.png) - ---- - -## ๐Ÿฅ System Health - -Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. - -![Health Dashboard](screenshots/04-health.png) - ---- - -## ๐Ÿ”ง Translator Playground - -Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). - -![Translator Playground](screenshots/05-translator.png) - ---- - -## ๐ŸŽฎ Model Playground _(v2.0.9+)_ - -Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. - ---- - -## ๐ŸŽจ Themes _(v2.0.5+)_ - -Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. - ---- - -## โš™๏ธ Settings - -Comprehensive settings panel with tabs: - -- **General** โ€” System storage, backup management (export/import database) -- **Appearance** โ€” Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls -- **Security** โ€” API endpoint protection, custom provider blocking, IP filtering, session info -- **Routing** โ€” Model aliases, background task degradation -- **Resilience** โ€” Rate limit persistence, circuit breaker tuning -- **Advanced** โ€” Configuration overrides - -![Settings Dashboard](screenshots/06-settings.png) - ---- - -## ๐Ÿ”ง CLI Tools - -One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. - -![CLI Tools Dashboard](screenshots/07-cli-tools.png) - ---- - -## ๐Ÿค– CLI Agents _(v2.0.11+)_ - -Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: - -- **Installation status** โ€” Installed / Not Found with version detection -- **Protocol badges** โ€” stdio, HTTP, etc. -- **Custom agents** โ€” Register any CLI tool via form (name, binary, version command, spawn args) -- **CLI Fingerprint Matching** โ€” Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP - ---- - -## ๐Ÿ–ผ๏ธ Media _(v2.0.3+)_ - -Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. - ---- - -## ๐Ÿ“ Request Logs - -Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. - -![Usage Logs](screenshots/08-usage.png) - ---- - -## ๐ŸŒ API Endpoint - -Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. - -![Endpoint Dashboard](screenshots/09-endpoint.png) - ---- - -## ๐Ÿ”‘ API Key Management - -Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. - ---- - -## ๐Ÿ“‹ Audit Log - -Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. - ---- - -## ๐Ÿ–ฅ๏ธ Desktop Application - -Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. - -Key features: - -- Server readiness polling (no blank screen on cold start) -- System tray with port management -- Content Security Policy -- Single-instance lock -- Auto-update on restart -- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) -- Hardened Electron build packaging โ€” symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+) - -๐Ÿ“– See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/da/README.md b/docs/i18n/da/README.md index fca2d9b91f..84c2dba91a 100644 --- a/docs/i18n/da/README.md +++ b/docs/i18n/da/README.md @@ -1,12 +1,12 @@ # ๐Ÿš€ OmniRoute โ€” The Free AI Gateway (Dansk) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/README.md) --- ### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback. -_Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._ +_Your universal API proxy โ€” one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._ **Chat Completions โ€ข Embeddings โ€ข Image Generation โ€ข Video โ€ข Music โ€ข Audio โ€ข Reranking โ€ข **Web Search** โ€ข MCP Server โ€ข A2A Protocol โ€ข 100% TypeScript** @@ -46,15 +46,17 @@ _Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now wi > - `APP_LOG_FILE_PATH` > - `APP_LOG_MAX_FILE_SIZE` > - `APP_LOG_RETENTION_DAYS` +> - `APP_LOG_MAX_FILES` > - `APP_LOG_LEVEL` > - `APP_LOG_FORMAT` > - `CALL_LOG_RETENTION_DAYS` +> - `CALL_LOG_MAX_ENTRIES` > > For release details and upgrade notes, see the [CHANGELOG](CHANGELOG.md). --- -## ๐Ÿ†• What's New in v3.0.0 +## ๐Ÿ†• What's New > **Upgrading from v2.9.5?** โ€” See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes. @@ -274,7 +276,7 @@ Developers pay $20โ€“200/month for Claude Pro, Codex Pro, or GitHub Copilot. Eve - **Smart 4-Tier Fallback** โ€” If subscription quota runs out, automatically redirects to API Key โ†’ Cheap โ†’ Free with zero manual intervention - **Real-Time Quota Tracking** โ€” Shows token consumption in real-time with reset countdown (5h, daily, weekly) - **Multi-Account Support** โ€” Multiple accounts per provider with auto round-robin โ€” when one runs out, switches to the next -- **Custom Combos** โ€” Customizable fallback chains with 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Custom Combos** โ€” Customizable fallback chains with 9 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random) - **Codex Business Quotas** โ€” Business/Team workspace quota monitoring directly in the dashboard
@@ -286,7 +288,7 @@ OpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If **How OmniRoute solves it:** -- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 67+ providers +- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 60+ providers - **Format Translation** โ€” Automatic and transparent: OpenAI โ†” Claude โ†” Gemini โ†” Responses API - **Response Sanitization** โ€” Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+ - **Role Normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI providers; `system` โ†’ `user` for GLM/ERNIE @@ -372,7 +374,7 @@ Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code.. - **CLI Tools Dashboard** โ€” Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline - **GitHub Copilot Config Generator** โ€” Generates `chatLanguageModels.json` for VS Code with bulk model selection - **Onboarding Wizard** โ€” Guided 4-step setup for first-time users -- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 67+ providers +- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 60+ providers
@@ -419,7 +421,7 @@ When a call fails, the dev doesn't know if it was a rate limit, expired token, w - **SQLite Proxy Logs** โ€” Persistent logs that survive server restarts - **Translator Playground** โ€” 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time) - **Request Telemetry** โ€” p50/p95/p99 latency + X-Request-Id tracing -- **File-Based Logging with Rotation** โ€” Console interceptor captures everything to JSON log with size-based rotation +- **File-Based Logging with Rotation** โ€” App logs rotate by size, retention days, and archive count; call log artifacts rotate by retention days and file count - **System Info Report** โ€” `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage. @@ -514,7 +516,7 @@ Developers who want all responses in a specific language, with a specific tone, - **System Prompt Injection** โ€” Global prompt applied to all requests - **Thinking Budget Validation** โ€” Reasoning token allocation control per request (passthrough, auto, custom, adaptive) -- **6 Routing Strategies** โ€” Global strategies that determine how requests are distributed +- **9 Routing Strategies** โ€” Global strategies that determine how requests are distributed - **Wildcard Router** โ€” `provider/*` patterns route dynamically to any provider - **Combo Enable/Disable Toggle** โ€” Toggle combos directly from the dashboard - **Provider Toggle** โ€” Enable/disable all connections for a provider with one click @@ -581,7 +583,7 @@ Different clients should have least-privilege access to tool categories. **How OmniRoute solves it:** -- 9 granular MCP scopes for controlled tool access +- 10 granular MCP scopes for controlled tool access - Scope enforcement and visibility in MCP management UI - Safe default posture for operational tooling @@ -1325,19 +1327,19 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. ### ๐Ÿค– Agent & Protocol Operations (v2.0) -| Feature | What It Does | -| ------------------------------------- | -------------------------------------------------------------------------------------------------- | -| ๐Ÿ”ง **MCP Server (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) | -| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | -| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | -| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | -| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | -| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | -| ๐Ÿ” **MCP Scope Enforcement** | 9 granular scope permissions for controlled tool access | -| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | -| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | -| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | -| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | +| Feature | What It Does | +| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| ๐Ÿ”ง **MCP Server (25 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools | +| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | +| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | +| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | +| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | +| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | +| ๐Ÿ” **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access | +| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | +| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | +| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | +| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | ### ๐Ÿง  Routing & Intelligence @@ -1348,7 +1350,7 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. | ๐Ÿ”„ **Format Translation** | OpenAI โ†” Claude โ†” Gemini โ†” Responses with schema-safe conversions | | ๐Ÿ‘ฅ **Multi-Account Support** | Multiple accounts per provider with intelligent selection | | ๐Ÿ”„ **Auto Token Refresh** | OAuth tokens refresh automatically with retry | -| ๐ŸŽจ **Custom Combos** | 6 balancing strategies + fallback chain control | +| ๐ŸŽจ **Custom Combos** | 9 balancing strategies + fallback chain control | | ๐ŸŒ **Wildcard Router** | `provider/*` dynamic routing | | ๐Ÿง  **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits | | ๐Ÿ”€ **Model Aliases** | Built-in + custom model aliasing and migration safety | @@ -1949,6 +1951,7 @@ opencode - Request artifacts are written to `DATA_DIR/call_logs/` as one JSON file per request - Enable pipeline capture from Dashboard โ†’ Logs โ†’ Request Logs if you need detailed per-stage payloads - Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log` +- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed **Connection test shows "Invalid" for OpenAI-compatible providers** diff --git a/docs/i18n/da/RELEASE_CHECKLIST.md b/docs/i18n/da/RELEASE_CHECKLIST.md deleted file mode 100644 index 903e812c3f..0000000000 --- a/docs/i18n/da/RELEASE_CHECKLIST.md +++ /dev/null @@ -1,37 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/RELEASE_CHECKLIST.md) - ---- - -# Release Checklist - -Use this checklist before tagging or publishing a new OmniRoute release. - -## Version and Changelog - -1. Bump `package.json` version (`x.y.z`) in the release branch. -2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: - - `## [x.y.z] โ€” YYYY-MM-DD` -3. Keep `## [Unreleased]` as the first changelog section for upcoming work. -4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. - -## API Docs - -1. Update `docs/openapi.yaml`: - - `info.version` must equal `package.json` version. -2. Validate endpoint examples if API contracts changed. - -## Runtime Docs - -1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. -2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. -3. Update localized docs if source docs changed significantly. - -## Automated Check - -Run the sync guard locally before opening PR: - -```bash -npm run check:docs-sync -``` - -CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/da/SECURITY.md b/docs/i18n/da/SECURITY.md new file mode 100644 index 0000000000..e1e7c83cea --- /dev/null +++ b/docs/i18n/da/SECURITY.md @@ -0,0 +1,179 @@ +# Security Policy (Dansk) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../SECURITY.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/SECURITY.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/SECURITY.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/SECURITY.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/SECURITY.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/SECURITY.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/SECURITY.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/SECURITY.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/SECURITY.md) + +--- + +## 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 | +| ------- | -------------- | +| 3.4.x | โœ… Active | +| 3.0.x | โœ… Security | +| < 3.0.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 | +| **MCP Scopes** | 10 granular scopes for MCP tool access control | + +### ๐Ÿ›ก๏ธ 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:::` +- 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** | Allowlist/blocklist IP ranges in dashboard | +| **Rate Limiting** | Per-provider rate limits with automatic backoff | +| **Anti-Thundering Herd** | Mutex + per-connection locking prevents cascading 502s | +| **TLS Fingerprint** | Browser-like TLS fingerprint spoofing to reduce bot detection | +| **CLI Fingerprint** | Per-provider header/body ordering to match native CLI signatures | + +### ๐Ÿ”Œ Resilience & Availability + +| 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 `CALL_LOG_RETENTION_DAYS` | +| **No-Log Opt-out** | Per API key `noLog` flag disables request logging | +| **Audit Log** | Administrative actions tracked in `audit_log` table | +| **MCP Audit** | SQLite-backed audit logging for all MCP tool calls | +| **Zod Validation** | All API inputs validated with Zod v4 schemas at module load | + +--- + +## 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 +- Provider constants validated at module load via Zod (`src/shared/validation/providerSchema.ts`) diff --git a/docs/i18n/de/A2A-SERVER.md b/docs/i18n/da/docs/A2A-SERVER.md similarity index 77% rename from docs/i18n/de/A2A-SERVER.md rename to docs/i18n/da/docs/A2A-SERVER.md index 01531ff482..f850c3fc0b 100644 --- a/docs/i18n/de/A2A-SERVER.md +++ b/docs/i18n/da/docs/A2A-SERVER.md @@ -1,9 +1,9 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/A2A-SERVER.md) +# OmniRoute A2A Server Documentation (Dansk) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/A2A-SERVER.md) --- -# OmniRoute A2A Server Documentation - > Agent-to-Agent Protocol v0.3 โ€” OmniRoute as an intelligent routing agent ## Agent Discovery diff --git a/docs/i18n/ar/API_REFERENCE.md b/docs/i18n/da/docs/API_REFERENCE.md similarity index 74% rename from docs/i18n/ar/API_REFERENCE.md rename to docs/i18n/da/docs/API_REFERENCE.md index b878605221..69377fc6b7 100644 --- a/docs/i18n/ar/API_REFERENCE.md +++ b/docs/i18n/da/docs/API_REFERENCE.md @@ -1,11 +1,9 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/API_REFERENCE.md) +# API Reference (Dansk) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/API_REFERENCE.md) --- -# API Reference - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/API_REFERENCE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/API_REFERENCE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/API_REFERENCE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/API_REFERENCE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/API_REFERENCE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/API_REFERENCE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/API_REFERENCE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/API_REFERENCE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/API_REFERENCE.md) - Complete reference for all OmniRoute API endpoints. --- @@ -42,15 +40,20 @@ Content-Type: application/json ### 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 | +| Header | Direction | Description | +| ------------------------ | --------- | ------------------------------------------------ | +| `X-OmniRoute-No-Cache` | Request | Set to `true` to bypass cache | +| `X-OmniRoute-Progress` | Request | Set to `true` for progress events | +| `X-Session-Id` | Request | Sticky session key for external session affinity | +| `x_session_id` | Request | Underscore variant also accepted (direct HTTP) | +| `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 | +| `X-OmniRoute-Session-Id` | Response | Effective session ID used by OmniRoute | + +> Nginx note: if you rely on underscore headers (for example `x_session_id`), enable `underscores_in_headers on;`. --- @@ -141,10 +144,10 @@ The provider prefix is auto-added if missing. Mismatched models return `400`. ```bash # Get cache stats -GET /api/cache +GET /api/cache/stats # Clear all caches -DELETE /api/cache +DELETE /api/cache/stats ``` Response example: @@ -215,23 +218,23 @@ Response example: ### 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 | +| Endpoint | Method | Description | +| ------------------------------- | ------------- | ---------------------- | +| `/api/settings` | GET/PUT/PATCH | 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 | +| Endpoint | Method | Description | +| ------------------------ | ---------- | ---------------------------------------------------------------------------------------------------- | +| `/api/sessions` | GET | Active session tracking | +| `/api/rate-limits` | GET | Per-account rate limits | +| `/api/monitoring/health` | GET | Health check + provider summary (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`) | +| `/api/cache/stats` | GET/DELETE | Cache stats / clear | ### Backup & Export/Import @@ -252,6 +255,13 @@ Response example: | `/api/sync/initialize` | POST | Initialize sync | | `/api/cloud/*` | Various | Cloud management | +### Tunnels + +| Endpoint | Method | Description | +| -------------------------- | ------ | ----------------------------------------------------------------------- | +| `/api/tunnels/cloudflared` | GET | Read Cloudflare Quick Tunnel install/runtime status for the dashboard | +| `/api/tunnels/cloudflared` | POST | Enable or disable the Cloudflare Quick Tunnel (`action=enable/disable`) | + ### CLI Tools | Endpoint | Method | Description | @@ -276,12 +286,12 @@ GET response includes `agents[]` (id, name, binary, version, installed, protocol ### 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 | +| Endpoint | Method | Description | +| ----------------------- | --------- | ------------------------------- | +| `/api/resilience` | GET/PATCH | 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 diff --git a/docs/i18n/ar/ARCHITECTURE.md b/docs/i18n/da/docs/ARCHITECTURE.md similarity index 89% rename from docs/i18n/ar/ARCHITECTURE.md rename to docs/i18n/da/docs/ARCHITECTURE.md index 4ea06a29f2..9812e24ae0 100644 --- a/docs/i18n/ar/ARCHITECTURE.md +++ b/docs/i18n/da/docs/ARCHITECTURE.md @@ -1,12 +1,10 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/ARCHITECTURE.md) +# OmniRoute Architecture (Dansk) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/ARCHITECTURE.md) --- -# OmniRoute Architecture - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/ARCHITECTURE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/ARCHITECTURE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/ARCHITECTURE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/ARCHITECTURE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/ARCHITECTURE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/ARCHITECTURE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/ARCHITECTURE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/ARCHITECTURE.md) - -_Last updated: 2026-03-04_ +_Last updated: 2026-03-28_ ## Executive Summary @@ -69,6 +67,26 @@ Primary runtime model: - Provider SLA/control plane outside local process - External CLI binaries themselves (Claude CLI, Codex CLI, etc.) +## Dashboard Surface (Current) + +Main pages under `src/app/(dashboard)/dashboard/`: + +- `/dashboard` โ€” quick start + provider overview +- `/dashboard/endpoint` โ€” endpoint proxy + MCP + A2A + API endpoint tabs +- `/dashboard/providers` โ€” provider connections and credentials +- `/dashboard/combos` โ€” combo strategies, templates, model routing rules +- `/dashboard/costs` โ€” cost aggregation and pricing visibility +- `/dashboard/analytics` โ€” usage analytics and evaluations +- `/dashboard/limits` โ€” quota/rate controls +- `/dashboard/cli-tools` โ€” CLI onboarding, runtime detection, config generation +- `/dashboard/agents` โ€” detected ACP agents + custom agent registration +- `/dashboard/media` โ€” image/video/music playground +- `/dashboard/search-tools` โ€” search provider testing and history +- `/dashboard/health` โ€” uptime, circuit breakers, rate limits +- `/dashboard/logs` โ€” request/proxy/audit/console logs +- `/dashboard/settings` โ€” system settings tabs (general, routing, combo defaults, etc.) +- `/dashboard/api-manager` โ€” API key lifecycle and model permissions + ## High-Level System Context ```mermaid @@ -258,8 +276,9 @@ Domain State DB (SQLite): ## 5) Cloud Sync -- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` +- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts`, `src/shared/services/modelSyncScheduler.ts` - Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Periodic task: `src/shared/services/modelSyncScheduler.ts` - Control route: `src/app/api/sync/cloud/route.ts` ## Request Lifecycle (`/v1/chat/completions`) @@ -339,7 +358,7 @@ flowchart TD Q -- No --> R[Return all unavailable] ``` -Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics. +Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics. Combo routing adds one extra guard: provider-scoped 400s such as upstream content-block and role-validation failures are treated as model-local failures so later combo targets can still run. ## OAuth Onboarding and Token Refresh Lifecycle @@ -669,25 +688,25 @@ Additional processing layers in the translation pipeline: ## 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 | +| 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` | Provider Models | Provider model metadata backing custom and managed available models | ## Bypass Handler @@ -739,10 +758,18 @@ Runtime visibility sources: - console logs from `src/sse/utils/logger.ts` - per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- four-stage detailed payload captures in SQLite (`request_detail_logs`) when `settings.detailed_logs_enabled=true` - textual request status log in `log.txt` (optional/compat) - optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` - dashboard usage endpoints (`/api/usage/*`) for UI consumption +Detailed request payload capture stores up to four JSON payload stages per routed call: + +- raw request received from the client +- translated request actually sent upstream +- provider response reconstructed as JSON; streamed responses are compacted to the final summary plus stream metadata +- final client response returned by OmniRoute; streamed responses are stored in the same compact summary form + ## Security-Sensitive Boundaries - JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing diff --git a/docs/i18n/bg/AUTO-COMBO.md b/docs/i18n/da/docs/AUTO-COMBO.md similarity index 65% rename from docs/i18n/bg/AUTO-COMBO.md rename to docs/i18n/da/docs/AUTO-COMBO.md index 2166e41dff..257c960f41 100644 --- a/docs/i18n/bg/AUTO-COMBO.md +++ b/docs/i18n/da/docs/AUTO-COMBO.md @@ -1,9 +1,9 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/AUTO-COMBO.md) +# OmniRoute Auto-Combo Engine (Dansk) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/AUTO-COMBO.md) --- -# OmniRoute Auto-Combo Engine - > Self-managing model chains with adaptive scoring ## How It Works diff --git a/docs/i18n/de/CLI-TOOLS.md b/docs/i18n/da/docs/CLI-TOOLS.md similarity index 66% rename from docs/i18n/de/CLI-TOOLS.md rename to docs/i18n/da/docs/CLI-TOOLS.md index 523fd2254d..b9946a5c32 100644 --- a/docs/i18n/de/CLI-TOOLS.md +++ b/docs/i18n/da/docs/CLI-TOOLS.md @@ -1,8 +1,8 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CLI-TOOLS.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CLI-TOOLS.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CLI-TOOLS.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CLI-TOOLS.md) +# CLI Tools Setup Guide โ€” OmniRoute (Dansk) -# CLI-Tools Einrichtungsanleitung โ€” OmniRoute +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CLI-TOOLS.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CLI-TOOLS.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CLI-TOOLS.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CLI-TOOLS.md) -Diese Anleitung erklรคrt, wie alle unterstรผtzten AI-CLI-Tools installiert und konfiguriert werden, um **OmniRoute** als einheitlichen Backend zu verwenden. +--- This guide explains how to install and configure all supported AI coding CLI tools to use **OmniRoute** as the unified backend, giving you centralized key management, @@ -13,7 +13,7 @@ cost tracking, model switching, and request logging across every tool. ## How It Works ``` -Claude / Codex / Gemini CLI / OpenCode / Cline / KiloCode / Continue / Kiro CLI +Claude / Codex / OpenCode / Cline / KiloCode / Continue / Kiro / Cursor / Copilot โ”‚ โ–ผ (all point to OmniRoute) http://YOUR_SERVER:20128/v1 @@ -31,21 +31,38 @@ Claude / Codex / Gemini CLI / OpenCode / Cline / KiloCode / Continue / Kiro CLI --- -## Supported Tools +## Supported Tools (Dashboard Source of Truth) -| Tool | Command | Type | Install Method | -| ---------------- | ------------------- | ----------------- | -------------- | -| **Claude Code** | `claude` | CLI | npm | -| **OpenAI Codex** | `codex` | CLI | npm | -| **Gemini CLI** | `gemini` | CLI | npm | -| **OpenCode** | `opencode` | CLI | npm | -| **Cline** | `cline` | CLI + VS Code ext | npm | -| **KiloCode** | `kilocode` / `kilo` | CLI + VS Code ext | npm | -| **Continue** | guide-based | VS Code ext | VS Code | -| **Kiro CLI** | `kiro-cli` | CLI | curl installer | -| **Cursor** | `cursor` | Desktop app | Download | -| **Droid** | web-based | Built-in agent | OmniRoute | -| **OpenClaw** | web-based | Built-in agent | OmniRoute | +The dashboard cards in `/dashboard/cli-tools` are generated from `src/shared/constants/cliTools.ts`. +Current list (v3.0.0-rc.16): + +| Tool | ID | Command | Setup Mode | Install Method | +| ------------------ | ------------- | ---------- | ---------- | -------------- | +| **Claude Code** | `claude` | `claude` | env | npm | +| **OpenAI Codex** | `codex` | `codex` | custom | npm | +| **Factory Droid** | `droid` | `droid` | custom | bundled/CLI | +| **OpenClaw** | `openclaw` | `openclaw` | custom | bundled/CLI | +| **Cursor** | `cursor` | app | guide | desktop app | +| **Cline** | `cline` | `cline` | custom | npm | +| **Kilo Code** | `kilo` | `kilocode` | custom | npm | +| **Continue** | `continue` | extension | guide | VS Code | +| **Antigravity** | `antigravity` | internal | mitm | OmniRoute | +| **GitHub Copilot** | `copilot` | extension | custom | VS Code | +| **OpenCode** | `opencode` | `opencode` | guide | npm | +| **Kiro AI** | `kiro` | app/cli | mitm | desktop/CLI | + +### CLI fingerprint sync (Agents + Settings) + +`/dashboard/agents` and `Settings > CLI Fingerprint` use `src/shared/constants/cliCompatProviders.ts`. +This keeps provider IDs aligned with CLI cards and legacy IDs. + +| CLI ID | Fingerprint Provider ID | +| ---------------------------------------------------------------------------------------------------- | ----------------------- | +| `kilo` | `kilocode` | +| `copilot` | `github` | +| `claude` / `codex` / `antigravity` / `kiro` / `cursor` / `cline` / `opencode` / `droid` / `openclaw` | same ID | + +Legacy IDs still accepted for compatibility: `copilot`, `kimi-coding`, `qwen`. --- @@ -71,9 +88,6 @@ npm install -g @anthropic-ai/claude-code # OpenAI Codex npm install -g @openai/codex -# Gemini CLI (Google) -npm install -g @google/gemini-cli - # OpenCode npm install -g opencode-ai @@ -81,7 +95,7 @@ npm install -g opencode-ai npm install -g cline # KiloCode -npm install -g kilecode +npm install -g kilocode # Kiro CLI (Amazon โ€” requires curl + unzip) apt-get install -y unzip # on Debian/Ubuntu @@ -94,7 +108,6 @@ export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc ```bash claude --version # 2.x.x codex --version # 0.x.x -gemini --version # 0.x.x opencode --version # x.x.x cline --version # 2.x.x kilocode --version # x.x.x (or: kilo --version) @@ -157,21 +170,6 @@ EOF --- -### Gemini CLI - -```bash -mkdir -p ~/.gemini && cat > ~/.gemini/settings.json << EOF -{ - "apiKey": "sk-your-omniroute-key", - "baseUrl": "http://localhost:20128/v1" -} -EOF -``` - -**Test:** `gemini "hello"` - ---- - ### OpenCode ```bash @@ -308,7 +306,7 @@ They run as internal routes and use OmniRoute's model routing automatically. --- -## Troubleshooting +## Fejlfinding | Error | Cause | Fix | | ------------------------- | ----------------------- | ------------------------------------------ | @@ -328,17 +326,16 @@ They run as internal routes and use OmniRoute's model routing automatically. OMNIROUTE_URL="http://localhost:20128/v1" OMNIROUTE_KEY="sk-your-omniroute-key" -npm install -g @anthropic-ai/claude-code @openai/codex @google/gemini-cli opencode-ai cline kilecode +npm install -g @anthropic-ai/claude-code @openai/codex opencode-ai cline kilocode # Kiro CLI apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash # Write configs -mkdir -p ~/.claude ~/.codex ~/.gemini ~/.config/opencode ~/.continue +mkdir -p ~/.claude ~/.codex ~/.config/opencode ~/.continue cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" -cat > ~/.gemini/settings.json <<< "{\"apiKey\":\"$OMNIROUTE_KEY\",\"baseUrl\":\"$OMNIROUTE_URL\"}" cat >> ~/.bashrc << EOF export OPENAI_BASE_URL="$OMNIROUTE_URL" export OPENAI_API_KEY="$OMNIROUTE_KEY" diff --git a/docs/i18n/da/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/da/docs/CODEBASE_DOCUMENTATION.md new file mode 100644 index 0000000000..e513c901c1 --- /dev/null +++ b/docs/i18n/da/docs/CODEBASE_DOCUMENTATION.md @@ -0,0 +1,591 @@ +# omniroute โ€” Codebase Documentation (Dansk) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CODEBASE_DOCUMENTATION.md) + +--- + +> 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
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, Qoder, 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. + +#### Arkitektur + +```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 | +| Qoder | 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"] +``` diff --git a/docs/i18n/da/docs/COVERAGE_PLAN.md b/docs/i18n/da/docs/COVERAGE_PLAN.md new file mode 100644 index 0000000000..ecb6f0226f --- /dev/null +++ b/docs/i18n/da/docs/COVERAGE_PLAN.md @@ -0,0 +1,170 @@ +# Test Coverage Plan (Dansk) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/COVERAGE_PLAN.md) + +--- + +Last updated: 2026-03-28 + +## Baseline + +There are multiple coverage numbers depending on how the report is computed. For planning, only one of them is useful. + +| Metric | Scope | Statements / Lines | Branches | Functions | Notes | +| -------------------- | ----------------------------------------------------- | -----------------: | -------: | --------: | --------------------------------------------------- | +| Legacy | Old `npm run test:coverage` | 79.42% | 75.15% | 67.94% | Inflated: counts test files and excludes `open-sse` | +| Diagnostic | Source-only, excluding tests and excluding `open-sse` | 68.16% | 63.55% | 64.06% | Useful only to isolate `src/**` | +| Recommended baseline | Source-only, excluding tests and including `open-sse` | 56.95% | 66.05% | 57.80% | This is the project-wide baseline to improve | + +The recommended baseline is the number to optimize against. + +## Rules + +- Coverage targets apply to source files, not to `tests/**`. +- `open-sse/**` is part of the product and must remain in scope. +- New code should not reduce coverage in touched areas. +- Prefer testing behavior and branch outcomes over implementation details. +- Prefer temp SQLite databases and small fixtures over broad mocks for `src/lib/db/**`. + +## Current command set + +- `npm run test:coverage` + - Main source coverage gate for the unit test suite + - Generates `text-summary`, `html`, `json-summary`, and `lcov` +- `npm run coverage:report` + - Detailed file-by-file report from the latest run +- `npm run test:coverage:legacy` + - Historical comparison only + +## Milestones + +| Phase | Target | Focus | +| ------- | ---------------------: | ------------------------------------------------- | +| Phase 1 | 60% statements / lines | Quick wins and low-risk utility coverage | +| Phase 2 | 65% statements / lines | DB and route foundations | +| Phase 3 | 70% statements / lines | Provider validation and usage analytics | +| Phase 4 | 75% statements / lines | `open-sse` translators and helpers | +| Phase 5 | 80% statements / lines | `open-sse` handlers and executor branches | +| Phase 6 | 85% statements / lines | Harder edge cases, branch debt, regression suites | +| Phase 7 | 90% statements / lines | Final sweep, gap closure, strict ratchet | + +Branches and functions should ratchet upward with each phase, but the primary hard target is statements / lines. + +## Priority hotspots + +These files or areas offer the best return for the next phases: + +1. `open-sse/handlers` + - `chatCore.ts` at 7.57% + - Overall directory at 29.07% +2. `open-sse/translator/request` + - Overall directory at 36.39% + - Many translators are still near single-digit coverage +3. `open-sse/translator/response` + - Overall directory at 8.07% +4. `open-sse/executors` + - Overall directory at 36.62% +5. `src/lib/db` + - `models.ts` at 20.66% + - `registeredKeys.ts` at 34.46% + - `modelComboMappings.ts` at 36.25% + - `settings.ts` at 46.40% + - `webhooks.ts` at 33.33% +6. `src/lib/usage` + - `usageHistory.ts` at 21.12% + - `usageStats.ts` at 9.56% + - `costCalculator.ts` at 30.00% +7. `src/lib/providers` + - `validation.ts` at 41.16% +8. Low-risk utility and API files for early gains + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/api/errorResponse.ts` + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +## Execution checklist + +### Phase 1: 56.95% -> 60% + +- [x] Fix coverage metric so it reflects source code instead of test files +- [x] Keep a legacy coverage script for comparison +- [x] Record the baseline and hotspots in-repo +- [ ] Add focused tests for low-risk utilities: + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/fetchTimeout.ts` + - `src/lib/api/errorResponse.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/display/names.ts` +- [ ] Add route tests for: + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +### Phase 2: 60% -> 65% + +- [ ] Add DB-backed tests for: + - `src/lib/db/modelComboMappings.ts` + - `src/lib/db/settings.ts` + - `src/lib/db/registeredKeys.ts` +- [ ] Cover branch behavior in: + - `src/lib/providers/validation.ts` + - `src/app/api/v1/embeddings/route.ts` + - `src/app/api/v1/moderations/route.ts` + +### Phase 3: 65% -> 70% + +- [ ] Add usage analytics tests for: + - `src/lib/usage/usageHistory.ts` + - `src/lib/usage/usageStats.ts` + - `src/lib/usage/costCalculator.ts` +- [ ] Expand route coverage for proxy management and settings branches + +### Phase 4: 70% -> 75% + +- [ ] Cover translator helpers and central translation paths: + - `open-sse/translator/index.ts` + - `open-sse/translator/helpers/*` + - `open-sse/translator/request/*` + - `open-sse/translator/response/*` + +### Phase 5: 75% -> 80% + +- [ ] Add handler-level tests for: + - `open-sse/handlers/chatCore.ts` + - `open-sse/handlers/responsesHandler.js` + - `open-sse/handlers/imageGeneration.js` + - `open-sse/handlers/embeddings.js` +- [ ] Add executor branch coverage for provider-specific auth, retries, and endpoint overrides + +### Phase 6: 80% -> 85% + +- [ ] Merge more edge-case suites into the main coverage path +- [ ] Increase function coverage for DB modules with weak constructor/helper coverage +- [ ] Close branch gaps in `settings.ts`, `registeredKeys.ts`, `validation.ts`, and translator helpers + +### Phase 7: 85% -> 90% + +- [ ] Treat the remaining low-coverage files as blockers +- [ ] Add regression tests for every uncovered production bug fixed during the push to 90% +- [ ] Raise the coverage gate in CI only after the local baseline is stable for at least two consecutive runs + +## Ratchet policy + +Update `npm run test:coverage` thresholds only after the project actually exceeds the next milestone with a comfortable buffer. + +Recommended ratchet sequence: + +1. 55/60/55 +2. 60/62/58 +3. 65/64/62 +4. 70/66/66 +5. 75/70/72 +6. 80/75/78 +7. 85/80/84 +8. 90/85/88 + +Order is `statements-lines / branches / functions`. + +## Known gap + +The current coverage command measures the main Node unit suite and includes source reached from it, including `open-sse`. It does not yet merge Vitest coverage into a single unified report. That merge is worth doing later, but it is not a blocker for starting the 60% -> 80% climb. diff --git a/docs/i18n/da/docs/FEATURES.md b/docs/i18n/da/docs/FEATURES.md index 9b2ad6f8c9..05da2ca10f 100644 --- a/docs/i18n/da/docs/FEATURES.md +++ b/docs/i18n/da/docs/FEATURES.md @@ -1,6 +1,6 @@ # OmniRoute โ€” Dashboard Features Gallery (Dansk) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/FEATURES.md) --- @@ -10,7 +10,7 @@ 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). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. ![Providers Dashboard](screenshots/01-providers.png) diff --git a/docs/i18n/da/MCP-SERVER.md b/docs/i18n/da/docs/MCP-SERVER.md similarity index 65% rename from docs/i18n/da/MCP-SERVER.md rename to docs/i18n/da/docs/MCP-SERVER.md index 829acd30b1..5cad3f2a62 100644 --- a/docs/i18n/da/MCP-SERVER.md +++ b/docs/i18n/da/docs/MCP-SERVER.md @@ -1,12 +1,12 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/MCP-SERVER.md) +# OmniRoute MCP Server Documentation (Dansk) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/MCP-SERVER.md) --- -# OmniRoute MCP Server Documentation - > Model Context Protocol server with 16 intelligent tools -## Installation +## Installer OmniRoute MCP is built-in. Start it with: @@ -42,16 +42,16 @@ See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, ## Advanced Tools (8) -| Tool | Description | -| :--------------------------------- | :---------------------------------------------- | -| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | -| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | -| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | -| `omniroute_test_combo` | Live-test all models in a combo | -| `omniroute_get_provider_metrics` | Detailed metrics for one provider | -| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | -| `omniroute_explain_route` | Explain a past routing decision | -| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | +| Tool | Description | +| :--------------------------------- | :---------------------------------------------------------- | +| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | +| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | +| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | +| `omniroute_test_combo` | Live-test all models in a combo via a real upstream request | +| `omniroute_get_provider_metrics` | Detailed metrics for one provider | +| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | +| `omniroute_explain_route` | Explain a past routing decision | +| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | ## Authentication diff --git a/docs/i18n/da/docs/RELEASE_CHECKLIST.md b/docs/i18n/da/docs/RELEASE_CHECKLIST.md new file mode 100644 index 0000000000..e47fc40eab --- /dev/null +++ b/docs/i18n/da/docs/RELEASE_CHECKLIST.md @@ -0,0 +1,37 @@ +# Release Checklist (Dansk) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/RELEASE_CHECKLIST.md) + +--- + +Use this checklist before tagging or publishing a new OmniRoute release. + +## Version and Changelog + +1. Bump `package.json` version (`x.y.z`) in the release branch. +2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: + - `## [x.y.z] โ€” YYYY-MM-DD` +3. Keep `## [Unreleased]` as the first changelog section for upcoming work. +4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. + +## API Docs + +1. Update `docs/openapi.yaml`: + - `info.version` must equal `package.json` version. +2. Validate endpoint examples if API contracts changed. + +## Runtime Docs + +1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. +2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. +3. Update localized docs if source docs changed significantly. + +## Automated Check + +Run the sync guard locally before opening PR: + +```bash +npm run check:docs-sync +``` + +CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/ar/TROUBLESHOOTING.md b/docs/i18n/da/docs/TROUBLESHOOTING.md similarity index 77% rename from docs/i18n/ar/TROUBLESHOOTING.md rename to docs/i18n/da/docs/TROUBLESHOOTING.md index 63c148000a..d71db5edef 100644 --- a/docs/i18n/ar/TROUBLESHOOTING.md +++ b/docs/i18n/da/docs/TROUBLESHOOTING.md @@ -1,11 +1,9 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/TROUBLESHOOTING.md) +# Troubleshooting (Dansk) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/TROUBLESHOOTING.md) --- -# Troubleshooting - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/TROUBLESHOOTING.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/TROUBLESHOOTING.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/TROUBLESHOOTING.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/TROUBLESHOOTING.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/TROUBLESHOOTING.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/TROUBLESHOOTING.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/TROUBLESHOOTING.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/TROUBLESHOOTING.md) - Common problems and solutions for OmniRoute. --- diff --git a/docs/i18n/da/USER_GUIDE.md b/docs/i18n/da/docs/USER_GUIDE.md similarity index 82% rename from docs/i18n/da/USER_GUIDE.md rename to docs/i18n/da/docs/USER_GUIDE.md index 7af0a60c9f..99a99aefb2 100644 --- a/docs/i18n/da/USER_GUIDE.md +++ b/docs/i18n/da/docs/USER_GUIDE.md @@ -1,8 +1,6 @@ # User Guide (Dansk) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/USER_GUIDE.md) - -> ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/USER_GUIDE.md) --- @@ -320,7 +318,7 @@ Model: cc/claude-opus-4-6 --- -## ๐Ÿš€ Deployment +## Udrulning ### Global npm install (Recommended) @@ -511,23 +509,26 @@ post_install() { ### Environment Variables -| Variable | Default | Description | -| ------------------------- | ------------------------------------ | ------------------------------------------------------- | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | -| `INITIAL_PASSWORD` | `123456` | First login password | -| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | -| `PORT` | framework default | Service port (`20128` in examples) | -| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | -| `NODE_ENV` | runtime default | Set `production` for deploy | -| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | -| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | -| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | -| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | -| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | -| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | -| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | -| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | +| 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/*` | +| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand | +| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | For the full environment variable reference, see the [README](../README.md). @@ -598,6 +599,11 @@ curl -X POST http://localhost:20128/api/provider-models \ Or use Dashboard: **Providers โ†’ [Provider] โ†’ Custom Models**. +Notes: + +- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers. +- The **Custom Models** section is intended for providers that do not expose managed available-model imports. + ### Dedicated Provider Routes Route requests directly to a specific provider with model validation: @@ -642,6 +648,14 @@ Returns models grouped by provider with types (`chat`, `embedding`, `image`). - Automatic background sync with timeout + fail-fast - Prefer server-side `BASE_URL`/`CLOUD_URL` in production +### Cloudflare Quick Tunnel + +- Available in **Dashboard โ†’ Endpoints** for Docker and other self-hosted deployments +- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint +- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary +- Tunnel URLs are ephemeral and change every time you stop/start the tunnel +- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download + ### LLM Gateway Intelligence (Phase 9) - **Semantic Cache** โ€” Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) @@ -757,11 +771,11 @@ OmniRoute implements provider-level resilience with four components: 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 | +| 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 unless `DISABLE_SQLITE_AUTO_BACKUP=true` | ```bash # API: Export database @@ -787,10 +801,11 @@ curl -X POST http://localhost:20128/api/db-backups/import \ ### Settings Dashboard -The settings page is organized into 5 tabs for easy navigation: +The settings page is organized into 6 tabs for easy navigation: | Tab | Contents | | -------------- | ---------------------------------------------------------------------------------------------- | +| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility | | **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | | **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | | **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | diff --git a/docs/i18n/da/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/da/docs/VM_DEPLOYMENT_GUIDE.md new file mode 100644 index 0000000000..28a7130f63 --- /dev/null +++ b/docs/i18n/da/docs/VM_DEPLOYMENT_GUIDE.md @@ -0,0 +1,403 @@ +# OmniRoute โ€” Deployment Guide on VM with Cloudflare (Dansk) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/VM_DEPLOYMENT_GUIDE.md) + +--- + +Complete guide to install and configure OmniRoute on a VM (VPS) with domain managed via Cloudflare. + +--- + +## Prerequisites + +| Item | Minimum | Recommended | +| ---------- | ------------------------ | ---------------- | +| **CPU** | 1 vCPU | 2 vCPU | +| **RAM** | 1 GB | 2 GB | +| **Disk** | 10 GB SSD | 25 GB SSD | +| **OS** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS | +| **Domain** | Registered on Cloudflare | โ€” | +| **Docker** | Docker Engine 24+ | Docker 27+ | + +**Tested providers**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. + +--- + +## 1. Configure the VM + +### 1.1 Create the instance + +On your preferred VPS provider: + +- Choose Ubuntu 24.04 LTS +- Select the minimum plan (1 vCPU / 1 GB RAM) +- Set a strong root password or configure SSH key +- Note the **public IP** (e.g., `203.0.113.10`) + +### 1.2 Connect via SSH + +```bash +ssh root@203.0.113.10 +``` + +### 1.3 Update the system + +```bash +apt update && apt upgrade -y +``` + +### 1.4 Install Docker + +```bash +# Install dependencies +apt install -y ca-certificates curl gnupg + +# Add official Docker repository +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 Install nginx + +```bash +apt install -y nginx +``` + +### 1.6 Configure 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 +``` + +> **Tip**: For maximum security, restrict ports 80 and 443 to Cloudflare IPs only. See the [Advanced Security](#advanced-security) section. + +--- + +## 2. Install OmniRoute + +### 2.1 Create configuration directory + +```bash +mkdir -p /opt/omniroute +``` + +### 2.2 Create environment variables file + +```bash +cat > /opt/omniroute/.env << โ€˜EOFโ€™ +# === Security === +JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY +INITIAL_PASSWORD=YourSecurePassword123! +API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY +STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY +STORAGE_ENCRYPTION_KEY_VERSION=v1 +MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT + +# === 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 (change to your domain) === +BASE_URL=https://llms.seudominio.com +NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com + +# === Cloud Sync (optional) === +# CLOUD_URL=https://cloud.omniroute.online +# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online +EOF +``` + +> โš ๏ธ **IMPORTANT**: Generate unique secret keys! Use `openssl rand -hex 32` for each key. + +### 2.3 Start the 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 Verify that it is running + +```bash +docker ps | grep omniroute +docker logs omniroute --tail 20 +``` + +It should display: `[DB] SQLite database ready` and `listening on port 20128`. + +--- + +## 3. Configure nginx (Reverse Proxy) + +### 3.1 Generate SSL certificate (Cloudflare Origin) + +In the Cloudflare dashboard: + +1. Go to **SSL/TLS โ†’ Origin Server** +2. Click **Create Certificate** +3. Keep the defaults (15 years, \*.yourdomain.com) +4. Copy the **Origin Certificate** and the **Private Key** + +```bash +mkdir -p /etc/nginx/ssl + +# Paste the certificate +nano /etc/nginx/ssl/origin.crt + +# Paste the private key +nano /etc/nginx/ssl/origin.key + +chmod 600 /etc/nginx/ssl/origin.key +``` + +### 3.2 Nginx Configuration + +```bash +cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ +# Default server โ€” blocks direct access via 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.yourdomain.com; # Change to your domain + + 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.yourdomain.com; + return 301 https://$server_name$request_uri; +} +NGINX +``` + +### 3.3 Enable and Test + +```bash +# Remove default configuration +rm -f /etc/nginx/sites-enabled/default + +# Enable OmniRoute +ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute + +# Test and reload +nginx -t && systemctl reload nginx +``` + +--- + +## 4. Configure Cloudflare DNS + +### 4.1 Add DNS record + +In the Cloudflare dashboard โ†’ DNS: + +| Type | Name | Content | Proxy | +| ---- | ------ | ---------------------- | ---------- | +| A | `llms` | `203.0.113.10` (VM IP) | โœ… Proxied | + +### 4.2 Configure SSL + +Under **SSL/TLS โ†’ Overview**: + +- Mode: **Full (Strict)** + +Under **SSL/TLS โ†’ Edge Certificates**: + +- Always Use HTTPS: โœ… On +- Minimum TLS Version: TLS 1.2 +- Automatic HTTPS Rewrites: โœ… On + +### 4.3 Testing + +```bash +curl -sI https://llms.seudominio.com/health +# Should return HTTP/2 200 +``` + +--- + +## 5. Operations and Maintenance + +### Upgrade to a new version + +```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 +``` + +### View logs + +```bash +docker logs -f omniroute # Real-time stream +docker logs omniroute --tail 50 # Last 50 lines +``` + +### Manual database backup + +```bash +# Copy data from the volume to the host +docker cp omniroute:/app/data ./backup-$(date +%F) + +# Or compress the entire volume +docker run --rm -v omniroute-data:/data -v $(pwd):/backup \ + alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data +``` + +### Restore from 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. Advanced Security + +### Restrict nginx to Cloudflare IPs + +```bash +cat > /etc/nginx/cloudflare-ips.conf << โ€˜CFโ€™ +# Cloudflare IPv4 ranges โ€” update periodically +# 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 +``` + +Add the following to `nginx.conf` inside the `http {}` block: + +```nginx +include /etc/nginx/cloudflare-ips.conf; +``` + +### Install fail2ban + +```bash +apt install -y fail2ban +systemctl enable fail2ban +systemctl start fail2ban + +# Check status +fail2ban-client status sshd +``` + +### Block direct access to the Docker port + +```bash +# Prevent direct external access to port 20128 +iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP +iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT + +# Persist the rules +apt install -y iptables-persistent +netfilter-persistent save +``` + +--- + +## 7. Deploy to Cloudflare Workers (Optional) + +For remote access via Cloudflare Workers (without exposing the VM directly): + +```bash +# In the local repository +cd omnirouteCloud +npm install +npx wrangler login +npx wrangler deploy +``` + +See the full documentation at [omnirouteCloud/README.md](../omnirouteCloud/README.md). + +--- + +## Port Summary + +| Port | Service | Access | +| ----- | ----------- | -------------------------- | +| 22 | SSH | Public (with fail2ban) | +| 80 | nginx HTTP | Redirect โ†’ HTTPS | +| 443 | nginx HTTPS | Via Cloudflare Proxy | +| 20128 | OmniRoute | Localhost only (via nginx) | diff --git a/docs/i18n/da/src/lib/a2a/README.md b/docs/i18n/da/src/lib/a2a/README.md new file mode 100644 index 0000000000..5c5fee9245 --- /dev/null +++ b/docs/i18n/da/src/lib/a2a/README.md @@ -0,0 +1,752 @@ +# OmniRoute A2A Server (Dansk) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../../../src/lib/a2a/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../../../es/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../../../fr/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../../../de/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../../../it/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../../../ru/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../../../zh-CN/src/lib/a2a/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../../../ja/src/lib/a2a/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../../../ko/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../../../ar/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../../../in/src/lib/a2a/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../../../th/src/lib/a2a/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../../../vi/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../../../id/src/lib/a2a/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../../../ms/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../../../nl/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../../../pl/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../../../sv/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../../../no/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../../../da/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../../../fi/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../../../pt/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../../../ro/src/lib/a2a/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../../../hu/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../../../bg/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../../../sk/src/lib/a2a/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../../../uk-UA/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../../../he/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../../../phi/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../../../pt-BR/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../../../cs/src/lib/a2a/README.md) + +--- + +> **Agent-to-Agent Protocol v0.3** โ€” Enables any AI agent to use OmniRoute as an intelligent routing agent via JSON-RPC 2.0. + +The A2A Server exposes OmniRoute as a **first-class agent** that other agents can discover, delegate tasks to, and collaborate with using the [A2A Protocol](https://google.github.io/A2A/). + +--- + +## Arkitektur + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Orchestrator Agent โ”‚ +โ”‚ (LangChain, CrewAI, AutoGen, Custom Agent) โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ 1. GET /.well-known/agent.json (discover) + โ”‚ 2. POST /a2a (JSON-RPC 2.0) + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ OmniRoute A2A Server โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Task Manager โ”‚ โ”‚ Skill Engine โ”‚ โ”‚ SSE Streaming โ”‚ โ”‚ +โ”‚ โ”‚ (lifecycle) โ”‚โ”€โ”€โ”‚ (registry) โ”‚โ”€โ”€โ”‚ (real-time) โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ +โ”‚ Skills: โ”‚ โ”‚ +โ”‚ โ”œโ”€ smart-routing โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ””โ”€ quota-management โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ Routing Decision Logger โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ OmniRoute Gateway (internal) + /v1/chat/completions, /api/combos, /api/usage/quota +``` + +--- + +## Kom hurtigt i gang + +### Agent Discovery + +Every A2A-compatible agent exposes an **Agent Card** at `/.well-known/agent.json`: + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +**Response:** + +```json +{ + "name": "OmniRoute", + "description": "Intelligent AI gateway with auto-routing across 50+ providers", + "url": "http://localhost:20128/a2a", + "version": "1.8.1", + "capabilities": { + "streaming": true, + "pushNotifications": false + }, + "skills": [ + { + "id": "smart-routing", + "name": "Smart Routing", + "description": "Routes prompts through OmniRoute intelligent pipeline", + "tags": ["routing", "llm", "multi-provider", "cost-optimization"], + "examples": [ + "Write a hello world in Python", + "Explain quantum computing using the cheapest provider" + ] + }, + { + "id": "quota-management", + "name": "Quota Management", + "description": "Natural-language queries about provider quotas", + "tags": ["quota", "analytics", "cost"], + "examples": [ + "Which provider has the most quota remaining?", + "Suggest a free combo for coding" + ] + } + ], + "authentication": { + "schemes": ["bearer"], + "apiKeyHeader": "Authorization" + } +} +``` + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Send a message to a skill and receive the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python hello world"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "a1b2c3d4-...", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "print('Hello, World!')" }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.0030)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "2026-03-04T..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"Quantum computing..."}}} + +: heartbeat 2026-03-04T21:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Running Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Skills Reference + +### `smart-routing` + +Routes prompts through OmniRoute's intelligent pipeline with full observability. + +**Parameters (in `metadata`):** + +| Parameter | Type | Default | Description | +| --------- | -------- | ------------ | ---------------------------------------------------------------------------------------- | +| `model` | `string` | `"auto"` | Target model (e.g., `claude-sonnet-4`, `gpt-4o`, `auto`) | +| `combo` | `string` | active combo | Specific combo to route through | +| `budget` | `number` | none | Maximum cost in USD for this request | +| `role` | `string` | none | Task role hint: `coding`, `review`, `planning`, `analysis`, `debugging`, `documentation` | + +**Returns:** + +| Field | Description | +| ------------------------------ | --------------------------------------------------------- | +| `artifacts[].content` | The LLM response text | +| `metadata.routing_explanation` | Human-readable explanation of routing decision | +| `metadata.cost_envelope` | Estimated vs actual cost with currency | +| `metadata.resilience_trace` | Array of events (primary_selected, fallback_needed, etc.) | +| `metadata.policy_verdict` | Whether the request was allowed and why | + +### `quota-management` + +Answers natural-language queries about provider quotas. + +**Query types (inferred from message content):** + +| Query Pattern | Response Type | +| ---------------------------------------------- | -------------------------------------------------------- | +| Contains `"ranking"`, `"most quota"`, `"best"` | Providers ranked by remaining quota | +| Contains `"free"`, `"suggest"` | Lists free combos or suggests free-tier providers | +| Default | Full quota summary with warnings for low-quota providers | + +--- + +## Task Lifecycle + +``` +submitted โ”€โ”€โ†’ working โ”€โ”€โ†’ completed + โ”€โ”€โ†’ failed + โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ†’ cancelled +``` + +| State | Description | +| ----------- | ----------------------------------------------------- | +| `submitted` | Task created, queued for execution | +| `working` | Skill handler is executing | +| `completed` | Execution succeeded, artifacts available | +| `failed` | Execution failed or task expired (TTL: 5 min default) | +| `cancelled` | Cancelled by client via `tasks/cancel` | + +- Terminal states: `completed`, `failed`, `cancelled` (no further transitions) +- Expired tasks in `submitted` or `working` are auto-marked as `failed` +- Tasks are garbage-collected after 2ร— TTL + +--- + +## Client Examples + +### Python โ€” Orchestrator Agent + +```python +""" +A2A Client โ€” Python example. +Discovers OmniRoute agent, sends a task, and processes the result. +""" +import requests +import json + +BASE_URL = "http://localhost:20128" +API_KEY = "your-api-key" +HEADERS = { + "Content-Type": "application/json", + "Authorization": f"Bearer {API_KEY}", +} + +# 1. Discover agent capabilities +agent_card = requests.get(f"{BASE_URL}/.well-known/agent.json").json() +print(f"Agent: {agent_card['name']} v{agent_card['version']}") +print(f"Skills: {[s['id'] for s in agent_card['skills']]}") + +# 2. Send a smart-routing task +response = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python quicksort implementation"}], + "metadata": { + "model": "auto", + "combo": "fast-coding", + "budget": 0.10, + } + } +}) +result = response.json()["result"] +print(f"\n๐Ÿ“ Response: {result['artifacts'][0]['content'][:200]}...") +print(f"๐Ÿ”€ Routing: {result['metadata']['routing_explanation']}") +print(f"๐Ÿ’ฐ Cost: ${result['metadata']['cost_envelope']['actual']}") +print(f"๐Ÿ›ก๏ธ Policy: {result['metadata']['policy_verdict']['reason']}") + +# 3. Query quota status +quota_resp = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-2", + "method": "message/send", + "params": { + "skill": "quota-management", + "messages": [{"role": "user", "content": "Which provider has the most quota remaining?"}], + } +}) +quota_result = quota_resp.json()["result"] +print(f"\n๐Ÿ“Š Quota: {quota_result['artifacts'][0]['content']}") +``` + +### TypeScript โ€” Multi-Agent Orchestrator + +```typescript +/** + * A2A Client โ€” TypeScript example. + * Shows agent discovery, task delegation, and streaming. + */ + +const BASE_URL = "http://localhost:20128"; +const API_KEY = "your-api-key"; + +interface JsonRpcResponse { + jsonrpc: "2.0"; + id: string | number; + result?: T; + error?: { code: number; message: string }; +} + +async function a2aCall(method: string, params: Record): Promise { + const resp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: `${method}-${Date.now()}`, + method, + params, + }), + }); + const json: JsonRpcResponse = await resp.json(); + if (json.error) throw new Error(`[${json.error.code}] ${json.error.message}`); + return json.result!; +} + +// โ”€โ”€ Agent Discovery โ”€โ”€ +const agentCard = await fetch(`${BASE_URL}/.well-known/agent.json`).then((r) => r.json()); +console.log(`Connected to: ${agentCard.name} (${agentCard.skills.length} skills)`); + +// โ”€โ”€ Smart Routing: Send a coding task โ”€โ”€ +const routingResult = await a2aCall("message/send", { + skill: "smart-routing", + messages: [{ role: "user", content: "Implement a Redis cache wrapper in TypeScript" }], + metadata: { model: "claude-sonnet-4", role: "coding" }, +}); +console.log("Response:", routingResult.artifacts[0].content); +console.log("Provider:", routingResult.metadata.routing_explanation); + +// โ”€โ”€ Quota Management: Find free alternatives โ”€โ”€ +const quotaResult = await a2aCall("message/send", { + skill: "quota-management", + messages: [{ role: "user", content: "Suggest free combos for documentation" }], +}); +console.log("Free combos:", quotaResult.artifacts[0].content); + +// โ”€โ”€ Streaming: Real-time response โ”€โ”€ +const streamResp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "stream-1", + method: "message/stream", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Explain microservices architecture" }], + }, + }), +}); + +const reader = streamResp.body!.getReader(); +const decoder = new TextDecoder(); +while (true) { + const { done, value } = await reader.read(); + if (done) break; + const chunk = decoder.decode(value); + for (const line of chunk.split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + if (event.params.chunk) { + process.stdout.write(event.params.chunk.content); + } + if (event.params.task.state === "completed") { + console.log("\nโœ… Stream completed"); + } + } + } +} +``` + +### Python โ€” LangChain A2A Integration + +```python +""" +LangChain integration โ€” Use OmniRoute A2A as a custom LLM. +""" +from langchain.llms.base import BaseLLM +from langchain.schema import LLMResult, Generation +import requests +from typing import List, Optional + +class OmniRouteA2A(BaseLLM): + base_url: str = "http://localhost:20128" + api_key: str = "" + model: str = "auto" + combo: Optional[str] = None + + @property + def _llm_type(self) -> str: + return "omniroute-a2a" + + def _call(self, prompt: str, stop: Optional[List[str]] = None, **kwargs) -> str: + response = requests.post( + f"{self.base_url}/a2a", + headers={ + "Content-Type": "application/json", + "Authorization": f"Bearer {self.api_key}", + }, + json={ + "jsonrpc": "2.0", + "id": "langchain-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": prompt}], + "metadata": { + "model": self.model, + **({"combo": self.combo} if self.combo else {}), + }, + }, + }, + ) + result = response.json()["result"] + return result["artifacts"][0]["content"] + + def _generate(self, prompts: List[str], stop=None, **kwargs) -> LLMResult: + return LLMResult( + generations=[[Generation(text=self._call(p, stop))] for p in prompts] + ) + +# Usage +llm = OmniRouteA2A( + base_url="http://localhost:20128", + api_key="your-key", + model="auto", + combo="fast-coding", +) +result = llm("Write a Python function to merge two sorted lists") +print(result) +``` + +### Go โ€” A2A Client + +```go +package main + +import ( + "bytes" + "encoding/json" + "fmt" + "io" + "net/http" +) + +const baseURL = "http://localhost:20128" +const apiKey = "your-api-key" + +type JsonRpcRequest struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Method string `json:"method"` + Params interface{} `json:"params"` +} + +type JsonRpcResponse struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Result interface{} `json:"result"` + Error *struct { + Code int `json:"code"` + Message string `json:"message"` + } `json:"error"` +} + +func a2aCall(method string, params interface{}) (*JsonRpcResponse, error) { + body, _ := json.Marshal(JsonRpcRequest{ + Jsonrpc: "2.0", + ID: "go-1", + Method: method, + Params: params, + }) + + req, _ := http.NewRequest("POST", baseURL+"/a2a", bytes.NewReader(body)) + req.Header.Set("Content-Type", "application/json") + req.Header.Set("Authorization", "Bearer "+apiKey) + + resp, err := http.DefaultClient.Do(req) + if err != nil { + return nil, err + } + defer resp.Body.Close() + data, _ := io.ReadAll(resp.Body) + + var result JsonRpcResponse + json.Unmarshal(data, &result) + return &result, nil +} + +func main() { + // Discover agent + resp, _ := http.Get(baseURL + "/.well-known/agent.json") + defer resp.Body.Close() + body, _ := io.ReadAll(resp.Body) + fmt.Println("Agent Card:", string(body)) + + // Send smart-routing task + result, _ := a2aCall("message/send", map[string]interface{}{ + "skill": "smart-routing", + "messages": []map[string]string{{"role": "user", "content": "Hello from Go!"}}, + "metadata": map[string]interface{}{"model": "auto"}, + }) + out, _ := json.MarshalIndent(result.Result, "", " ") + fmt.Println("Result:", string(out)) +} +``` + +--- + +## Use Cases + +### ๐Ÿค– Use Case 1: Multi-Agent Coding Pipeline + +An orchestrator agent delegates code generation to OmniRoute, then passes the output to a review agent. + +```python +def coding_pipeline(task: str): + # Step 1: Generate code via OmniRoute A2A + code_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Write production-quality code: {task}"} + ], metadata={"model": "auto", "role": "coding"}) + code = code_result["artifacts"][0]["content"] + + # Step 2: Review the code via OmniRoute A2A (different model) + review_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Review this code for bugs and improvements:\n\n{code}"} + ], metadata={"model": "auto", "role": "review"}) + review = review_result["artifacts"][0]["content"] + + # Step 3: Check costs + print(f"Code cost: ${code_result['metadata']['cost_envelope']['actual']}") + print(f"Review cost: ${review_result['metadata']['cost_envelope']['actual']}") + + return {"code": code, "review": review} +``` + +### ๐Ÿ’ก Use Case 2: Quota-Aware Agent Swarm + +Multiple agents share quota through OmniRoute, using the quota skill to coordinate. + +```python +async def quota_aware_agent(agent_name: str, task: str): + # Check quota before starting + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Which provider has the most quota remaining?"} + ]) + print(f"[{agent_name}] {quota['artifacts'][0]['content']}") + + # Send request with budget constraint + result = a2a_send("smart-routing", [ + {"role": "user", "content": task} + ], metadata={"budget": 0.05}) + + policy = result["metadata"]["policy_verdict"] + if not policy["allowed"]: + print(f"[{agent_name}] โš ๏ธ Budget exceeded: {policy['reason']}") + # Fall back to free combo + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Suggest free combos"} + ]) + print(f"[{agent_name}] Free alternatives: {quota['artifacts'][0]['content']}") + + return result +``` + +### ๐Ÿ“Š Use Case 3: Real-Time Streaming Dashboard + +A monitoring agent streams responses and displays progress in real-time. + +```typescript +async function streamingDashboard(prompt: string) { + const response = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { "Content-Type": "application/json", Authorization: `Bearer ${API_KEY}` }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "dash-1", + method: "message/stream", + params: { skill: "smart-routing", messages: [{ role: "user", content: prompt }] }, + }), + }); + + let totalChunks = 0; + const reader = response.body!.getReader(); + const decoder = new TextDecoder(); + + while (true) { + const { done, value } = await reader.read(); + if (done) break; + + for (const line of decoder.decode(value).split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + const state = event.params.task.state; + + if (state === "working" && event.params.chunk) { + totalChunks++; + process.stdout.write( + `\r[Chunk ${totalChunks}] ${event.params.chunk.content.slice(0, 50)}...` + ); + } + if (state === "completed") { + const meta = event.params.metadata; + console.log( + `\nโœ… Done | Cost: $${meta?.cost_envelope?.actual || 0} | Route: ${meta?.routing_explanation || "N/A"}` + ); + } + if (state === "failed") { + console.error(`\nโŒ Failed: ${event.params.metadata?.error}`); + } + } + } + } +} +``` + +### ๐Ÿ” Use Case 4: Task Polling Pattern + +For long-running tasks, poll the task status instead of waiting synchronously. + +```python +import time + +def poll_task(task_id: str, timeout: int = 60): + """Poll task status until completion or timeout.""" + start = time.time() + while time.time() - start < timeout: + result = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "poll-1", + "method": "tasks/get", + "params": {"taskId": task_id}, + }).json() + + task = result["result"]["task"] + state = task["state"] + print(f" Task {task_id[:8]}... state={state}") + + if state in ("completed", "failed", "cancelled"): + return task + time.sleep(2) + + # Timeout โ€” cancel the task + requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "cancel-1", + "method": "tasks/cancel", + "params": {"taskId": task_id}, + }) + raise TimeoutError(f"Task {task_id} timed out after {timeout}s") +``` + +--- + +## Error Codes + +| Code | Constant | Meaning | +| ------ | ------------------------ | ---------------------------------------- | +| -32700 | โ€” | Parse error (invalid JSON) | +| -32600 | `INVALID_REQUEST` | Invalid JSON-RPC request or unauthorized | +| -32601 | `METHOD_NOT_FOUND` | Unknown method or skill | +| -32602 | `INVALID_PARAMS` | Missing or invalid parameters | +| -32603 | `INTERNAL_ERROR` | Skill execution failed | +| -32001 | `TASK_NOT_FOUND` | Task ID not found | +| -32002 | `TASK_ALREADY_COMPLETED` | Cannot modify a completed task | +| -32003 | `UNAUTHORIZED` | Invalid or missing API key | +| -32004 | `BUDGET_EXCEEDED` | Request exceeds configured budget | +| -32005 | `PROVIDER_UNAVAILABLE` | No available providers | + +--- + +## Authentication + +All `/a2a` requests require a Bearer token via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server (`OMNIROUTE_API_KEY` is empty), authentication is bypassed. + +--- + +## File Structure + +``` +src/lib/a2a/ +โ”œโ”€โ”€ taskManager.ts # Task lifecycle (create/update/cancel/list), TTL, cleanup +โ”œโ”€โ”€ taskExecution.ts # Generic task executor with state management +โ”œโ”€โ”€ streaming.ts # SSE stream formatting, heartbeat, chunk/completion events +โ”œโ”€โ”€ routingLogger.ts # Routing decision logger (stats, history, retention) +โ””โ”€โ”€ skills/ + โ”œโ”€โ”€ smartRouting.ts # Smart routing skill (routes via /v1/chat/completions) + โ””โ”€โ”€ quotaManagement.ts # Quota management skill (natural-language quota queries) + +src/app/a2a/ +โ””โ”€โ”€ route.ts # Next.js API route handler (JSON-RPC 2.0 dispatch) + +open-sse/mcp-server/ +โ””โ”€โ”€ schemas/a2a.ts # Zod schemas (AgentCard, Task, JSON-RPC, SSE events) +``` + +--- + +## Comparison: MCP vs A2A + +| Feature | MCP Server | A2A Server | +| ----------------- | ---------------------------- | ------------------------------------------------- | +| **Protocol** | Model Context Protocol | Agent-to-Agent Protocol v0.3 | +| **Transport** | stdio / HTTP | HTTP (JSON-RPC 2.0) | +| **Discovery** | Tool listing via MCP | `/.well-known/agent.json` | +| **Granularity** | 16 individual tools | 2 high-level skills | +| **Best for** | IDE agents (Cursor, VS Code) | Multi-agent systems (LangChain, CrewAI) | +| **Streaming** | Not supported | SSE via `message/stream` | +| **Task tracking** | No | Full lifecycle (submitted โ†’ completed) | +| **Observability** | Audit log per tool call | Cost envelope + resilience trace + policy verdict | + +--- + +## Licens + +Part of [OmniRoute](https://github.com/diegosouzapw/OmniRoute) โ€” MIT License. diff --git a/docs/i18n/de/CHANGELOG.md b/docs/i18n/de/CHANGELOG.md index 0dbc256214..ae7ea387c4 100644 --- a/docs/i18n/de/CHANGELOG.md +++ b/docs/i18n/de/CHANGELOG.md @@ -1,12 +1,92 @@ # Changelog (Deutsch) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CHANGELOG.md) --- - ## [Unreleased] +### ๐Ÿ› ๏ธ Maintenance + +- **AGENTS.md rewrite:** Condensed from 297โ†’153 lines. Added build/lint/test commands (including single-test execution), code style guidelines (Prettier, TypeScript, ESLint, naming, imports, error handling, security), and trimmed verbose architecture tables for AI agent consumption. + +## [3.4.2] - 2026-04-01 + +### ๐Ÿ› Bug Fixes + +- **CI Stabilization:** Fixed failing analytics/settings Playwright selectors and request assertions so GitHub Actions E2E runs pass reliably across localized UIs and switch-based controls. +- **Deterministic Tests:** Removed date-sensitive quota fixtures from Copilot usage tests and aligned idempotency/model catalog tests with the merged runtime behavior. +- **MCP Type Hardening:** Removed zero-budget explicit `any` regressions from the MCP server tool registration path, restoring the `check:any-budget:t11` workflow gate. + +### ๐Ÿ› ๏ธ Maintenance + +- **Release Branch Integration:** Consolidated the active feature branches into `release/v3.4.2` on top of current `main` and validated the branch with lint, unit, coverage, build, and CI-mode E2E runs. + +## [3.4.1] - 2026-03-31 + +> [!WARNING] +> **BREAKING CHANGE: request logging, retention, and logging environment variables have been redesigned.** +> On the first startup after upgrading, OmniRoute archives legacy request logs from `DATA_DIR/logs/`, legacy `DATA_DIR/call_logs/`, and `DATA_DIR/log.txt` into `DATA_DIR/log_archives/*.zip`, then removes the deprecated layout and switches to the new unified artifact format under `DATA_DIR/call_logs/`. + +### โœจ New Features + +- **.ENV Migration Utility:** Included `scripts/migrate-env.mjs` to seamlessly migrate `= 18 < 24 (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` | `20128` | Server port | +| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | Base URL for frontend | +| `JWT_SECRET` | (generate above) | JWT signing secret | +| `INITIAL_PASSWORD` | `CHANGEME` | First login password | +| `APP_LOG_LEVEL` | `info` | Log verbosity level | + +### Dashboard Settings + +The dashboard provides UI toggles for features that can also be configured via environment variables: + +| Setting Location | Toggle | Description | +| ------------------- | ------------------ | ------------------------------ | +| Settings โ†’ Advanced | Debug Mode | Enable debug request logs (UI) | +| Settings โ†’ General | Sidebar Visibility | Show/hide sidebar sections | + +These settings are stored in the database and persist across restarts, overriding env var defaults when set. + +### 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:20128/dashboard` +- **API**: `http://localhost:20128/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`, `mcp`, `a2a`, `memory`, `skills`. + +--- + +## Running Tests + +```bash +# All tests (unit + vitest + ecosystem + e2e) +npm run test:all + +# Single test file (Node.js native test runner โ€” most tests use this) +node --import tsx/esm --test tests/unit/your-file.test.mjs + +# Vitest (MCP server, autoCombo, cache) +npm run test:vitest + +# E2E tests (requires Playwright) +npm run test:e2e + +# Protocol clients E2E (MCP transports, A2A) +npm run test:protocols:e2e + +# Ecosystem compatibility tests +npm run test:ecosystem + +# Coverage (55% min statements/lines/functions; 60% branches) +npm run test:coverage +npm run coverage:report + +# Lint + format check +npm run lint +npm run check +``` + +Coverage notes: + +- `npm run test:coverage` measures source coverage for the main unit test suite, excludes `tests/**`, and includes `open-sse/**` +- `npm run coverage:report` prints the detailed file-by-file report from the latest coverage run +- `npm run test:coverage:legacy` preserves the older metric for historical comparison +- See `docs/COVERAGE_PLAN.md` for the phased coverage improvement roadmap + +Current test status: **122 unit test files** covering: + +- Provider translators and format conversion +- Rate limiting, circuit breaker, and resilience +- Semantic cache, idempotency, progress tracking +- Database operations and schema (21 DB modules) +- OAuth flows and authentication +- API endpoint validation (Zod v4) +- MCP server tools and scope enforcement +- Memory and Skills systems + +--- + +## Code Style + +- **ESLint** โ€” Run `npm run lint` before committing +- **Prettier** โ€” Auto-formatted via `lint-staged` on commit (2 spaces, semicolons, double quotes, 100 char width, es5 trailing commas) +- **TypeScript** โ€” All `src/` code uses `.ts`/`.tsx`; `open-sse/` uses `.ts`/`.js`; document with TSDoc (`@param`, `@returns`, `@throws`) +- **No `eval()`** โ€” ESLint enforces `no-eval`, `no-implied-eval`, `no-new-func` +- **Zod validation** โ€” Use Zod v4 schemas for all API input validation +- **Naming**: Files = camelCase/kebab-case, components = PascalCase, constants = UPPER_SNAKE + +--- + +## Project Structure + +``` +src/ # TypeScript (.ts / .tsx) +โ”œโ”€โ”€ app/ # Next.js 16 App Router +โ”‚ โ”œโ”€โ”€ (dashboard)/ # Dashboard pages (23 sections) +โ”‚ โ”œโ”€โ”€ api/ # API routes (51 directories) +โ”‚ โ””โ”€โ”€ login/ # Auth pages (.tsx) +โ”œโ”€โ”€ domain/ # Policy engine (policyEngine, comboResolver, costRules, etc.) +โ”œโ”€โ”€ lib/ # Core business logic (.ts) +โ”‚ โ”œโ”€โ”€ a2a/ # Agent-to-Agent v0.3 protocol server +โ”‚ โ”œโ”€โ”€ acp/ # Agent Communication Protocol registry +โ”‚ โ”œโ”€โ”€ compliance/ # Compliance policy engine +โ”‚ โ”œโ”€โ”€ db/ # SQLite database layer (21 modules + 16 migrations) +โ”‚ โ”œโ”€โ”€ memory/ # Persistent conversational memory +โ”‚ โ”œโ”€โ”€ oauth/ # OAuth providers, services, and utilities +โ”‚ โ”œโ”€โ”€ skills/ # Extensible skill framework +โ”‚ โ”œโ”€โ”€ usage/ # Usage tracking and cost calculation +โ”‚ โ””โ”€โ”€ localDb.ts # Re-export layer only โ€” never add logic here +โ”œโ”€โ”€ middleware/ # Request middleware (promptInjectionGuard) +โ”œโ”€โ”€ mitm/ # MITM proxy (cert, DNS, target routing) +โ”œโ”€โ”€ shared/ +โ”‚ โ”œโ”€โ”€ components/ # React components (.tsx) +โ”‚ โ”œโ”€โ”€ constants/ # Provider definitions (60+), MCP scopes, routing strategies +โ”‚ โ”œโ”€โ”€ utils/ # Circuit breaker, sanitizer, auth helpers +โ”‚ โ””โ”€โ”€ validation/ # Zod v4 schemas +โ””โ”€โ”€ sse/ # SSE proxy pipeline + +open-sse/ # @omniroute/open-sse workspace +โ”œโ”€โ”€ executors/ # 14 provider-specific request executors +โ”œโ”€โ”€ handlers/ # 11 request handlers (chat, responses, embeddings, images, etc.) +โ”œโ”€โ”€ mcp-server/ # MCP server (25 tools, 3 transports, 10 scopes) +โ”œโ”€โ”€ services/ # 36+ services (combo, autoCombo, rateLimitManager, etc.) +โ”œโ”€โ”€ translator/ # Format translators (OpenAI โ†” Claude โ†” Gemini โ†” Responses โ†” Ollama) +โ”œโ”€โ”€ transformer/ # Responses API transformer +โ””โ”€โ”€ utils/ # 22 utility modules (stream, TLS, proxy, logging) + +electron/ # Electron desktop app (cross-platform) + +tests/ +โ”œโ”€โ”€ unit/ # Node.js test runner (122 test files) +โ”œโ”€โ”€ integration/ # Integration tests +โ”œโ”€โ”€ e2e/ # Playwright tests +โ”œโ”€โ”€ security/ # Security tests +โ”œโ”€โ”€ translator/ # Translator-specific tests +โ””โ”€โ”€ load/ # Load tests + +docs/ # Documentation +โ”œโ”€โ”€ ARCHITECTURE.md # System architecture +โ”œโ”€โ”€ API_REFERENCE.md # All endpoints +โ”œโ”€โ”€ USER_GUIDE.md # Provider setup, CLI integration +โ”œโ”€โ”€ TROUBLESHOOTING.md # Common issues +โ”œโ”€โ”€ MCP-SERVER.md # MCP server (25 tools) +โ”œโ”€โ”€ A2A-SERVER.md # A2A agent protocol +โ”œโ”€โ”€ AUTO-COMBO.md # Auto-combo engine +โ”œโ”€โ”€ CLI-TOOLS.md # CLI tools integration +โ”œโ”€โ”€ COVERAGE_PLAN.md # Test coverage improvement plan +โ”œโ”€โ”€ openapi.yaml # OpenAPI specification +โ””โ”€โ”€ adr/ # Architecture Decision Records +``` + +--- + +## Adding a New Provider + +### Step 1: Register Provider Constants + +Add to `src/shared/constants/providers.ts` โ€” Zod-validated at module load. + +### Step 2: Add Executor (if custom logic needed) + +Create executor in `open-sse/executors/your-provider.ts` extending the base executor. + +### Step 3: Add Translator (if non-OpenAI format) + +Create request/response translators in `open-sse/translator/`. + +### Step 4: Add OAuth Config (if OAuth-based) + +Add OAuth credentials in `src/lib/oauth/constants/oauth.ts` and service in `src/lib/oauth/services/`. + +### Step 5: Register Models + +Add model definitions in `open-sse/config/providerRegistry.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 +- [ ] All inputs validated with Zod schemas +- [ ] CHANGELOG updated (if user-facing change) +- [ ] Documentation updated (if applicable) + +--- + +## Releasing + +Releases are managed via the `/generate-release` workflow. When a new GitHub Release is created, the package is **automatically published to npm** via GitHub Actions. + +--- + +## Getting Help + +- **Architecture**: See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) +- **API Reference**: See [`docs/API_REFERENCE.md`](docs/API_REFERENCE.md) +- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **ADRs**: See `docs/adr/` for architectural decision records diff --git a/docs/i18n/de/README.md b/docs/i18n/de/README.md index 68d8f05f40..d6311e4947 100644 --- a/docs/i18n/de/README.md +++ b/docs/i18n/de/README.md @@ -1,12 +1,12 @@ # ๐Ÿš€ OmniRoute โ€” The Free AI Gateway (Deutsch) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/README.md) --- ### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback. -_Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._ +_Your universal API proxy โ€” one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._ **Chat Completions โ€ข Embeddings โ€ข Image Generation โ€ข Video โ€ข Music โ€ข Audio โ€ข Reranking โ€ข **Web Search** โ€ข MCP Server โ€ข A2A Protocol โ€ข 100% TypeScript** @@ -46,15 +46,17 @@ _Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now wi > - `APP_LOG_FILE_PATH` > - `APP_LOG_MAX_FILE_SIZE` > - `APP_LOG_RETENTION_DAYS` +> - `APP_LOG_MAX_FILES` > - `APP_LOG_LEVEL` > - `APP_LOG_FORMAT` > - `CALL_LOG_RETENTION_DAYS` +> - `CALL_LOG_MAX_ENTRIES` > > For release details and upgrade notes, see the [CHANGELOG](CHANGELOG.md). --- -## ๐Ÿ†• What's New in v3.0.0 +## ๐Ÿ†• What's New > **Upgrading from v2.9.5?** โ€” See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes. @@ -274,7 +276,7 @@ Developers pay $20โ€“200/month for Claude Pro, Codex Pro, or GitHub Copilot. Eve - **Smart 4-Tier Fallback** โ€” If subscription quota runs out, automatically redirects to API Key โ†’ Cheap โ†’ Free with zero manual intervention - **Real-Time Quota Tracking** โ€” Shows token consumption in real-time with reset countdown (5h, daily, weekly) - **Multi-Account Support** โ€” Multiple accounts per provider with auto round-robin โ€” when one runs out, switches to the next -- **Custom Combos** โ€” Customizable fallback chains with 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Custom Combos** โ€” Customizable fallback chains with 9 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random) - **Codex Business Quotas** โ€” Business/Team workspace quota monitoring directly in the dashboard @@ -286,7 +288,7 @@ OpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If **How OmniRoute solves it:** -- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 67+ providers +- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 60+ providers - **Format Translation** โ€” Automatic and transparent: OpenAI โ†” Claude โ†” Gemini โ†” Responses API - **Response Sanitization** โ€” Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+ - **Role Normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI providers; `system` โ†’ `user` for GLM/ERNIE @@ -372,7 +374,7 @@ Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code.. - **CLI Tools Dashboard** โ€” Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline - **GitHub Copilot Config Generator** โ€” Generates `chatLanguageModels.json` for VS Code with bulk model selection - **Onboarding Wizard** โ€” Guided 4-step setup for first-time users -- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 67+ providers +- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 60+ providers @@ -419,7 +421,7 @@ When a call fails, the dev doesn't know if it was a rate limit, expired token, w - **SQLite Proxy Logs** โ€” Persistent logs that survive server restarts - **Translator Playground** โ€” 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time) - **Request Telemetry** โ€” p50/p95/p99 latency + X-Request-Id tracing -- **File-Based Logging with Rotation** โ€” Console interceptor captures everything to JSON log with size-based rotation +- **File-Based Logging with Rotation** โ€” App logs rotate by size, retention days, and archive count; call log artifacts rotate by retention days and file count - **System Info Report** โ€” `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage. @@ -514,7 +516,7 @@ Developers who want all responses in a specific language, with a specific tone, - **System Prompt Injection** โ€” Global prompt applied to all requests - **Thinking Budget Validation** โ€” Reasoning token allocation control per request (passthrough, auto, custom, adaptive) -- **6 Routing Strategies** โ€” Global strategies that determine how requests are distributed +- **9 Routing Strategies** โ€” Global strategies that determine how requests are distributed - **Wildcard Router** โ€” `provider/*` patterns route dynamically to any provider - **Combo Enable/Disable Toggle** โ€” Toggle combos directly from the dashboard - **Provider Toggle** โ€” Enable/disable all connections for a provider with one click @@ -581,7 +583,7 @@ Different clients should have least-privilege access to tool categories. **How OmniRoute solves it:** -- 9 granular MCP scopes for controlled tool access +- 10 granular MCP scopes for controlled tool access - Scope enforcement and visibility in MCP management UI - Safe default posture for operational tooling @@ -1325,19 +1327,19 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. ### ๐Ÿค– Agent & Protocol Operations (v2.0) -| Feature | What It Does | -| ------------------------------------- | -------------------------------------------------------------------------------------------------- | -| ๐Ÿ”ง **MCP Server (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) | -| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | -| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | -| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | -| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | -| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | -| ๐Ÿ” **MCP Scope Enforcement** | 9 granular scope permissions for controlled tool access | -| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | -| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | -| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | -| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | +| Feature | What It Does | +| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| ๐Ÿ”ง **MCP Server (25 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools | +| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | +| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | +| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | +| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | +| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | +| ๐Ÿ” **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access | +| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | +| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | +| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | +| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | ### ๐Ÿง  Routing & Intelligence @@ -1348,7 +1350,7 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. | ๐Ÿ”„ **Format Translation** | OpenAI โ†” Claude โ†” Gemini โ†” Responses with schema-safe conversions | | ๐Ÿ‘ฅ **Multi-Account Support** | Multiple accounts per provider with intelligent selection | | ๐Ÿ”„ **Auto Token Refresh** | OAuth tokens refresh automatically with retry | -| ๐ŸŽจ **Custom Combos** | 6 balancing strategies + fallback chain control | +| ๐ŸŽจ **Custom Combos** | 9 balancing strategies + fallback chain control | | ๐ŸŒ **Wildcard Router** | `provider/*` dynamic routing | | ๐Ÿง  **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits | | ๐Ÿ”€ **Model Aliases** | Built-in + custom model aliasing and migration safety | @@ -1949,6 +1951,7 @@ opencode - Request artifacts are written to `DATA_DIR/call_logs/` as one JSON file per request - Enable pipeline capture from Dashboard โ†’ Logs โ†’ Request Logs if you need detailed per-stage payloads - Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log` +- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed **Connection test shows "Invalid" for OpenAI-compatible providers** diff --git a/docs/i18n/de/RELEASE_CHECKLIST.md b/docs/i18n/de/RELEASE_CHECKLIST.md deleted file mode 100644 index 903e812c3f..0000000000 --- a/docs/i18n/de/RELEASE_CHECKLIST.md +++ /dev/null @@ -1,37 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/RELEASE_CHECKLIST.md) - ---- - -# Release Checklist - -Use this checklist before tagging or publishing a new OmniRoute release. - -## Version and Changelog - -1. Bump `package.json` version (`x.y.z`) in the release branch. -2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: - - `## [x.y.z] โ€” YYYY-MM-DD` -3. Keep `## [Unreleased]` as the first changelog section for upcoming work. -4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. - -## API Docs - -1. Update `docs/openapi.yaml`: - - `info.version` must equal `package.json` version. -2. Validate endpoint examples if API contracts changed. - -## Runtime Docs - -1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. -2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. -3. Update localized docs if source docs changed significantly. - -## Automated Check - -Run the sync guard locally before opening PR: - -```bash -npm run check:docs-sync -``` - -CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/de/SECURITY.md b/docs/i18n/de/SECURITY.md new file mode 100644 index 0000000000..8777153cde --- /dev/null +++ b/docs/i18n/de/SECURITY.md @@ -0,0 +1,179 @@ +# Security Policy (Deutsch) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../SECURITY.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/SECURITY.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/SECURITY.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/SECURITY.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/SECURITY.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/SECURITY.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/SECURITY.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/SECURITY.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/SECURITY.md) + +--- + +## 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 | +| ------- | -------------- | +| 3.4.x | โœ… Active | +| 3.0.x | โœ… Security | +| < 3.0.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 | +| **MCP Scopes** | 10 granular scopes for MCP tool access control | + +### ๐Ÿ›ก๏ธ 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:::` +- 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** | Allowlist/blocklist IP ranges in dashboard | +| **Rate Limiting** | Per-provider rate limits with automatic backoff | +| **Anti-Thundering Herd** | Mutex + per-connection locking prevents cascading 502s | +| **TLS Fingerprint** | Browser-like TLS fingerprint spoofing to reduce bot detection | +| **CLI Fingerprint** | Per-provider header/body ordering to match native CLI signatures | + +### ๐Ÿ”Œ Resilience & Availability + +| 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 `CALL_LOG_RETENTION_DAYS` | +| **No-Log Opt-out** | Per API key `noLog` flag disables request logging | +| **Audit Log** | Administrative actions tracked in `audit_log` table | +| **MCP Audit** | SQLite-backed audit logging for all MCP tool calls | +| **Zod Validation** | All API inputs validated with Zod v4 schemas at module load | + +--- + +## 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 +- Provider constants validated at module load via Zod (`src/shared/validation/providerSchema.ts`) diff --git a/docs/i18n/de/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/de/VM_DEPLOYMENT_GUIDE.md deleted file mode 100644 index d9ebae328d..0000000000 --- a/docs/i18n/de/VM_DEPLOYMENT_GUIDE.md +++ /dev/null @@ -1,401 +0,0 @@ -# OmniRoute โ€“ Bereitstellungshandbuch auf VM mit Cloudflare - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](../pt-BR/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](../es/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](../fr/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](../it/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](../ru/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](../zh-CN/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](../de/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](../in/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](../th/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](../uk-UA/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](../ar/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](../ja/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](../vi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](../bg/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](../da/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](../fi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](../he/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](../hu/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](../id/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](../ko/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](../ms/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](../nl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](../no/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](../pt/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](../ro/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](../pl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](../sk/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](../sv/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](../phi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](../cs/VM_DEPLOYMENT_GUIDE.md) - -Vollstรคndige Anleitung zur Installation und Konfiguration von OmniRoute auf einer VM (VPS) mit รผber Cloudflare verwalteter Domรคne. - ---- - -## Voraussetzungen - -| Artikel | Minimum | Empfohlen | -| ------------------ | -------------------------- | ---------------- | -| **CPU** | 1 vCPU | 2 vCPU | -| **RAM** | 1 GB | 2 GB | -| **Festplatte** | 10 GB SSD | 25 GB SSD | -| **Betriebssystem** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS | -| **Domรคne** | Registriert bei Cloudflare | โ€” | -| **Docker** | Docker Engine 24+ | Docker 27+ | - -**Getestete Anbieter**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. - ---- - -## 1. Konfigurieren Sie die VM - -### 1.1 Erstellen Sie die Instanz - -Bei Ihrem bevorzugten VPS-Anbieter: - -- Wรคhlen Sie Ubuntu 24.04 LTS -- Wรคhlen Sie den Mindestplan (1 vCPU / 1 GB RAM) -- Legen Sie ein sicheres Root-Passwort fest oder konfigurieren Sie den SSH-Schlรผssel -- Notieren Sie sich die **รถffentliche IP** (z. B. `203.0.113.10`) - -### 1.2 Verbindung รผber SSH herstellen - -```bash -ssh root@203.0.113.10 -``` - -### 1.3 Aktualisieren Sie das System - -```bash -apt update && apt upgrade -y -``` - -### 1.4 Docker installieren - -```bash -# Install dependencies -apt install -y ca-certificates curl gnupg - -# Add official Docker repository -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 Nginx installieren - -```bash -apt install -y nginx -``` - -### 1.6 Firewall (UFW) konfigurieren - -```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 -``` - -> **Tipp**: Fรผr maximale Sicherheit beschrรคnken Sie die Ports 80 und 443 nur auf Cloudflare-IPs. Siehe den Abschnitt [Advanced Security](#advanced-security). - ---- - -## 2. OmniRoute installieren - -### 2.1 Konfigurationsverzeichnis erstellen - -```bash -mkdir -p /opt/omniroute -``` - -### 2.2 Umgebungsvariablendatei erstellen - -```bash -cat > /opt/omniroute/.env << โ€˜EOFโ€™ -# === Security === -JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY -INITIAL_PASSWORD=YourSecurePassword123! -API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY -STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY -STORAGE_ENCRYPTION_KEY_VERSION=v1 -MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT - -# === 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 (change to your domain) === -BASE_URL=https://llms.seudominio.com -NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com - -# === Cloud Sync (optional) === -# CLOUD_URL=https://cloud.omniroute.online -# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online -EOF -``` - -> โš ๏ธ **WICHTIG**: Generieren Sie einzigartige geheime Schlรผssel! Verwenden Sie `openssl rand -hex 32` fรผr jeden Schlรผssel. - -### 2.3 Starten Sie den 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 Stellen Sie sicher, dass es ausgefรผhrt wird - -```bash -docker ps | grep omniroute -docker logs omniroute --tail 20 -``` - -Es sollte Folgendes anzeigen: `[DB] SQLite database ready` und `listening on port 20128`. - ---- - -## 3. Nginx (Reverse Proxy) konfigurieren - -### 3.1 SSL-Zertifikat generieren (Cloudflare Origin) - -Im Cloudflare-Dashboard: - -1. Gehen Sie zu **SSL/TLS โ†’ Ursprungsserver** -2. Klicken Sie auf **Zertifikat erstellen** -3. Behalten Sie die Standardeinstellungen bei (15 Jahre, \*.yourdomain.com) -4. Kopieren Sie das **Ursprungszertifikat** und den **Privaten Schlรผssel** - -```bash -mkdir -p /etc/nginx/ssl - -# Paste the certificate -nano /etc/nginx/ssl/origin.crt - -# Paste the private key -nano /etc/nginx/ssl/origin.key - -chmod 600 /etc/nginx/ssl/origin.key -``` - -### 3.2 Nginx-Konfiguration - -```bash -cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ -# Default server โ€” blocks direct access via 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.yourdomain.com; # Change to your domain - - 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.yourdomain.com; - return 301 https://$server_name$request_uri; -} -NGINX -``` - -### 3.3 Aktivieren und testen - -```bash -# Remove default configuration -rm -f /etc/nginx/sites-enabled/default - -# Enable OmniRoute -ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute - -# Test and reload -nginx -t && systemctl reload nginx -``` - ---- - -## 4. Konfigurieren Sie Cloudflare DNS - -### 4.1 DNS-Eintrag hinzufรผgen - -Im Cloudflare-Dashboard โ†’ DNS: - -| Geben Sie | ein Name | Inhalt | Proxy | -| --------- | -------- | ---------------------- | -------- | -| A | `llms` | `203.0.113.10` (VM-IP) | โœ… Proxy | - -### 4.2 SSL konfigurieren - -Unter **SSL/TLS โ†’ รœbersicht**: - -- Modus: **Vollstรคndig (Streng)** - -Unter **SSL/TLS โ†’ Edge-Zertifikate**: - -- Immer HTTPS verwenden: โœ… Ein -- Mindest-TLS-Version: TLS 1.2 -- Automatische HTTPS-Rewrites: โœ… Ein - -### 4.3 Testen - -```bash -curl -sI https://llms.seudominio.com/health -# Should return HTTP/2 200 -``` - ---- - -## 5. Betrieb und Wartung - -### Upgrade auf eine neue Version - -```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 -``` - -### Protokolle anzeigen - -```bash -docker logs -f omniroute # Real-time stream -docker logs omniroute --tail 50 # Last 50 lines -``` - -### Manuelle Datenbanksicherung - -```bash -# Copy data from the volume to the host -docker cp omniroute:/app/data ./backup-$(date +%F) - -# Or compress the entire volume -docker run --rm -v omniroute-data:/data -v $(pwd):/backup \ - alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data -``` - -### Aus Backup wiederherstellen - -```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. Erweiterte Sicherheit - -### Nginx auf Cloudflare-IPs beschrรคnken - -```bash -cat > /etc/nginx/cloudflare-ips.conf << โ€˜CFโ€™ -# Cloudflare IPv4 ranges โ€” update periodically -# 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 -``` - -Fรผgen Sie Folgendes zu `nginx.conf` im Block `http {}` hinzu: - -```nginx -include /etc/nginx/cloudflare-ips.conf; -``` - -### Fail2ban installieren - -```bash -apt install -y fail2ban -systemctl enable fail2ban -systemctl start fail2ban - -# Check status -fail2ban-client status sshd -``` - -### Blockieren Sie den direkten Zugriff auf den Docker-Port - -```bash -# Prevent direct external access to port 20128 -iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP -iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT - -# Persist the rules -apt install -y iptables-persistent -netfilter-persistent save -``` - ---- - -## 7. Bereitstellung fรผr Cloudflare-Worker (optional) - -Fรผr den Fernzugriff รผber Cloudflare Workers (ohne die VM direkt verfรผgbar zu machen): - -```bash -# In the local repository -cd omnirouteCloud -npm install -npx wrangler login -npx wrangler deploy -``` - -Die vollstรคndige Dokumentation finden Sie unter [omnirouteCloud/README.md](../omnirouteCloud/README.md). - ---- - -## Portzusammenfassung - -| Hafen | Service | Zugriff | -| ----- | ----------- | -------------------------- | -| 22 | SSH | ร–ffentlich (mit fail2ban) | -| 80 | nginx HTTP | Weiterleiten โ†’ HTTPS | -| 443 | nginx HTTPS | รœber Cloudflare-Proxy | -| 20128 | OmniRoute | Nur Localhost (รผber Nginx) | diff --git a/docs/i18n/de/docs/A2A-SERVER.md b/docs/i18n/de/docs/A2A-SERVER.md new file mode 100644 index 0000000000..6eb01b9fca --- /dev/null +++ b/docs/i18n/de/docs/A2A-SERVER.md @@ -0,0 +1,200 @@ +# OmniRoute A2A Server Documentation (Deutsch) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/A2A-SERVER.md) + +--- + +> Agent-to-Agent Protocol v0.3 โ€” OmniRoute as an intelligent routing agent + +## Agent Discovery + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements. + +--- + +## Authentication + +All `/a2a` requests require an API key via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server, authentication is bypassed. + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Sends a message to a skill and waits for the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a hello world in Python"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "uuid", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "..." }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}} + +: heartbeat 2026-03-03T17:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Available Skills + +| Skill | Description | +| :----------------- | :------------------------------------------------------------------------------------------------------------------------------ | +| `smart-routing` | Routes prompts through OmniRoute's intelligent pipeline. Returns response with routing explanation, cost, and resilience trace. | +| `quota-management` | Answers natural-language queries about provider quotas, suggests free combos, and provides quota rankings. | + +--- + +## Task Lifecycle + +``` +submitted โ†’ working โ†’ completed + โ†’ failed + โ†’ cancelled +``` + +- Tasks expire after 5 minutes (configurable) +- Terminal states: `completed`, `failed`, `cancelled` +- Event log tracks every state transition + +--- + +## Error Codes + +| Code | Meaning | +| :----- | :----------------------------- | +| -32700 | Parse error (invalid JSON) | +| -32600 | Invalid request / Unauthorized | +| -32601 | Method or skill not found | +| -32602 | Invalid params | +| -32603 | Internal error | + +--- + +## Integration Examples + +### Python (requests) + +```python +import requests + +resp = requests.post("http://localhost:20128/a2a", json={ + "jsonrpc": "2.0", "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Hello"}] + } +}, headers={"Authorization": "Bearer YOUR_KEY"}) + +result = resp.json()["result"] +print(result["artifacts"][0]["content"]) +print(result["metadata"]["routing_explanation"]) +``` + +### TypeScript (fetch) + +```typescript +const resp = await fetch("http://localhost:20128/a2a", { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: "Bearer YOUR_KEY", + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "1", + method: "message/send", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Hello" }], + }, + }), +}); +const { result } = await resp.json(); +console.log(result.metadata.routing_explanation); +``` diff --git a/docs/i18n/de/docs/API_REFERENCE.md b/docs/i18n/de/docs/API_REFERENCE.md new file mode 100644 index 0000000000..da1cbbde6e --- /dev/null +++ b/docs/i18n/de/docs/API_REFERENCE.md @@ -0,0 +1,465 @@ +# API Reference (Deutsch) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/API_REFERENCE.md) + +--- + +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 | +| `X-Session-Id` | Request | Sticky session key for external session affinity | +| `x_session_id` | Request | Underscore variant also accepted (direct HTTP) | +| `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 | +| `X-OmniRoute-Session-Id` | Response | Effective session ID used by OmniRoute | + +> Nginx note: if you rely on underscore headers (for example `x_session_id`), enable `underscores_in_headers 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/stats + +# Clear all caches +DELETE /api/cache/stats +``` + +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/PATCH | 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 + provider summary (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`) | +| `/api/cache/stats` | 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 | + +### Tunnels + +| Endpoint | Method | Description | +| -------------------------- | ------ | ----------------------------------------------------------------------- | +| `/api/tunnels/cloudflared` | GET | Read Cloudflare Quick Tunnel install/runtime status for the dashboard | +| `/api/tunnels/cloudflared` | POST | Enable or disable the Cloudflare Quick Tunnel (`action=enable/disable`) | + +### 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`. + +### ACP Agents + +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | + +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). + +### Resilience & Rate Limits + +| Endpoint | Method | Description | +| ----------------------- | --------- | ------------------------------- | +| `/api/resilience` | GET/PATCH | 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` diff --git a/docs/i18n/de/docs/ARCHITECTURE.md b/docs/i18n/de/docs/ARCHITECTURE.md new file mode 100644 index 0000000000..b46b692b63 --- /dev/null +++ b/docs/i18n/de/docs/ARCHITECTURE.md @@ -0,0 +1,814 @@ +# OmniRoute Architecture (Deutsch) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/ARCHITECTURE.md) + +--- + +_Last updated: 2026-03-28_ + +## 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 (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developerโ†’system, systemโ†’user) for cross-provider compatibility +- Structured output conversion (json_schema โ†’ Gemini responseSchema) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) +- Global system prompt injection +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout โ†’ budget โ†’ fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) + +Primary runtime model: + +- Next.js 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.) + +## Dashboard Surface (Current) + +Main pages under `src/app/(dashboard)/dashboard/`: + +- `/dashboard` โ€” quick start + provider overview +- `/dashboard/endpoint` โ€” endpoint proxy + MCP + A2A + API endpoint tabs +- `/dashboard/providers` โ€” provider connections and credentials +- `/dashboard/combos` โ€” combo strategies, templates, model routing rules +- `/dashboard/costs` โ€” cost aggregation and pricing visibility +- `/dashboard/analytics` โ€” usage analytics and evaluations +- `/dashboard/limits` โ€” quota/rate controls +- `/dashboard/cli-tools` โ€” CLI onboarding, runtime detection, config generation +- `/dashboard/agents` โ€” detected ACP agents + custom agent registration +- `/dashboard/media` โ€” image/video/music playground +- `/dashboard/search-tools` โ€” search provider testing and history +- `/dashboard/health` โ€” uptime, circuit breakers, rate limits +- `/dashboard/logs` โ€” request/proxy/audit/console logs +- `/dashboard/settings` โ€” system settings tabs (general, routing, combo defaults, etc.) +- `/dashboard/api-manager` โ€” API key lifecycle and model permissions + +## 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[(storage.sqlite)] + UDB[(usage tables + log artifacts)] + end + + subgraph Upstreams[Upstream Providers] + P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/Qoder/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/route.ts` (GET) +- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- OAuth: `src/app/api/oauth/*` +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` +- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI tooling helpers: `src/app/api/cli-tools/*` +- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) +- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) โ€” provider profiles, circuit breaker, rate limit state +- Resilience reset: `src/app/api/resilience/reset` (POST) โ€” reset breakers + cooldowns +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) +- Telemetry: `src/app/api/telemetry/summary` (GET) +- Budget: `src/app/api/usage/budget` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Policies: `src/app/api/policies` (GET/POST) + +## 2) SSE + 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` +- Response sanitization: `open-sse/handlers/responseSanitizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.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`, `qoder.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 (SQLite): + +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** + +Usage persistence: + +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present + +Domain State DB (SQLite): + +- `src/lib/db/domainState.ts` โ€” CRUD operations 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`, `src/shared/services/modelSyncScheduler.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Periodic task: `src/shared/services/modelSyncScheduler.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. Combo routing adds one extra guard: provider-scoped 400s such as upstream content-block and role-validation failures are treated as model-local failures so later combo targets can still run. + +## 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: + +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` + +## Deployment Topology + +```mermaid +flowchart LR + 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[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] + end + + subgraph External[External Services] + Providers[AI Providers] + SyncCloud[Cloud Sync Service] + end + + CLI --> Next + Browser --> Next + Next --> Core + Next --> MainDB + Core --> MainDB + Core --> UsageDB + Core --> Providers + Next --> SyncCloud +``` + +## Module Mapping (Decision-Critical) + +### Route and API Modules + +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle +- `src/app/api/models/alias`: alias management +- `src/app/api/combos*`: fallback combo management +- `src/app/api/pricing`: pricing overrides for cost calculation +- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers +- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) +- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) +- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) +- `src/app/api/sessions`: active session listing (GET) +- `src/app/api/rate-limits`: per-account rate limit status (GET) + +### Routing and Execution Core + +- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior + +### Translation Registry and Format Converters + +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` +- Format constants: `open-sse/translator/formats.ts` + +### Persistence + +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables + +## Provider Executor Coverage (Strategy Pattern) + +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. + +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, Qoder, 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 | +| Qoder | openai | OAuth (Basic) | โœ… | โœ… | โœ… | โš ๏ธ Per request | +| OpenRouter | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| GLM/Kimi/MiniMax | claude | API Key | โœ… | โœ… | โŒ | โŒ | +| DeepSeek | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Groq | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| xAI (Grok) | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Mistral | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Perplexity | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Together AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Fireworks AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Cerebras | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Cohere | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| NVIDIA NIM | openai | API Key | โœ… | โœ… | โŒ | โŒ | + +## Format Translation Coverage + +Detected source formats include: + +- `openai` +- `openai-responses` +- `claude` +- `gemini` + +Target formats include: + +- OpenAI chat/Responses +- Claude +- Gemini/Gemini-CLI/Antigravity envelope +- Kiro +- Cursor + +Translations use **OpenAI as the hub format** โ€” all conversions go through OpenAI as intermediate: + +``` +Source Format โ†’ OpenAI (hub) โ†’ Target Format +``` + +Translations are selected dynamically based on source payload shape and provider target format. + +Additional processing layers in the translation pipeline: + +- **Response sanitization** โ€” Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI targets; merges `system` โ†’ `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** โ€” Parses `...` blocks from content into `reasoning_content` field +- **Structured output** โ€” Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` + +## Supported API Endpoints + +| 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` | Provider Models | Provider model metadata backing custom and managed available models | + +## 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 `/logs//` 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 + +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON โ†’ SQLite migration compatibility path + +## Observability and Operational Signals + +Runtime visibility sources: + +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- four-stage detailed payload captures in SQLite (`request_detail_logs`) when `settings.detailed_logs_enabled=true` +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption + +Detailed request payload capture stores up to four JSON payload stages per routed call: + +- raw request received from the client +- translated request actually sent upstream +- provider response reconstructed as JSON; streamed responses are compacted to the final summary plus stream metadata +- final client response returned by OmniRoute; streamed responses are stored in the same compact summary form + +## Security-Sensitive Boundaries + +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics + +## Environment and Runtime Matrix + +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` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). + +## Operational Verification Checklist + +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: +- `GET /api/settings` +- `GET /api/v1/models` +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/de/docs/AUTO-COMBO.md b/docs/i18n/de/docs/AUTO-COMBO.md new file mode 100644 index 0000000000..d44b6de558 --- /dev/null +++ b/docs/i18n/de/docs/AUTO-COMBO.md @@ -0,0 +1,67 @@ +# OmniRoute Auto-Combo Engine (Deutsch) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/AUTO-COMBO.md) + +--- + +> Self-managing model chains with adaptive scoring + +## How It Works + +The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**: + +| Factor | Weight | Description | +| :--------- | :----- | :---------------------------------------------- | +| Quota | 0.20 | Remaining capacity [0..1] | +| Health | 0.25 | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 | +| CostInv | 0.20 | Inverse cost (cheaper = higher score) | +| LatencyInv | 0.15 | Inverse p95 latency (faster = higher) | +| TaskFit | 0.10 | Model ร— task type fitness score | +| Stability | 0.10 | Low variance in latency/errors | + +## Mode Packs + +| Pack | Focus | Key Weight | +| :---------------------- | :----------- | :--------------- | +| ๐Ÿš€ **Ship Fast** | Speed | latencyInv: 0.35 | +| ๐Ÿ’ฐ **Cost Saver** | Economy | costInv: 0.40 | +| ๐ŸŽฏ **Quality First** | Best model | taskFit: 0.40 | +| ๐Ÿ“ก **Offline Friendly** | Availability | quota: 0.40 | + +## Self-Healing + +- **Temporary exclusion**: Score < 0.2 โ†’ excluded for 5 min (progressive backoff, max 30 min) +- **Circuit breaker awareness**: OPEN โ†’ auto-excluded; HALF_OPEN โ†’ probe requests +- **Incident mode**: >50% OPEN โ†’ disable exploration, maximize stability +- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout + +## Bandit Exploration + +5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode. + +## API + +```bash +# Create auto-combo +curl -X POST http://localhost:20128/api/combos/auto \ + -H "Content-Type: application/json" \ + -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}' + +# List auto-combos +curl http://localhost:20128/api/combos/auto +``` + +## Task Fitness + +30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` โ†’ high coding score). + +## Files + +| File | Purpose | +| :------------------------------------------- | :------------------------------------ | +| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization | +| `open-sse/services/autoCombo/taskFitness.ts` | Model ร— task fitness lookup | +| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap | +| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode | +| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles | +| `src/app/api/combos/auto/route.ts` | REST API | diff --git a/docs/i18n/de/docs/CLI-TOOLS.md b/docs/i18n/de/docs/CLI-TOOLS.md new file mode 100644 index 0000000000..7427bf004d --- /dev/null +++ b/docs/i18n/de/docs/CLI-TOOLS.md @@ -0,0 +1,348 @@ +# CLI Tools Setup Guide โ€” OmniRoute (Deutsch) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CLI-TOOLS.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CLI-TOOLS.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CLI-TOOLS.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CLI-TOOLS.md) + +--- + +This guide explains how to install and configure all supported AI coding CLI tools +to use **OmniRoute** as the unified backend, giving you centralized key management, +cost tracking, model switching, and request logging across every tool. + +--- + +## How It Works + +``` +Claude / Codex / OpenCode / Cline / KiloCode / Continue / Kiro / Cursor / Copilot + โ”‚ + โ–ผ (all point to OmniRoute) + http://YOUR_SERVER:20128/v1 + โ”‚ + โ–ผ (OmniRoute routes to the right provider) + Anthropic / OpenAI / Gemini / DeepSeek / Groq / Mistral / ... +``` + +**Benefits:** + +- One API key to manage all tools +- Cost tracking across all CLIs in the dashboard +- Model switching without reconfiguring every tool +- Works locally and on remote servers (VPS) + +--- + +## Supported Tools (Dashboard Source of Truth) + +The dashboard cards in `/dashboard/cli-tools` are generated from `src/shared/constants/cliTools.ts`. +Current list (v3.0.0-rc.16): + +| Tool | ID | Command | Setup Mode | Install Method | +| ------------------ | ------------- | ---------- | ---------- | -------------- | +| **Claude Code** | `claude` | `claude` | env | npm | +| **OpenAI Codex** | `codex` | `codex` | custom | npm | +| **Factory Droid** | `droid` | `droid` | custom | bundled/CLI | +| **OpenClaw** | `openclaw` | `openclaw` | custom | bundled/CLI | +| **Cursor** | `cursor` | app | guide | desktop app | +| **Cline** | `cline` | `cline` | custom | npm | +| **Kilo Code** | `kilo` | `kilocode` | custom | npm | +| **Continue** | `continue` | extension | guide | VS Code | +| **Antigravity** | `antigravity` | internal | mitm | OmniRoute | +| **GitHub Copilot** | `copilot` | extension | custom | VS Code | +| **OpenCode** | `opencode` | `opencode` | guide | npm | +| **Kiro AI** | `kiro` | app/cli | mitm | desktop/CLI | + +### CLI fingerprint sync (Agents + Settings) + +`/dashboard/agents` and `Settings > CLI Fingerprint` use `src/shared/constants/cliCompatProviders.ts`. +This keeps provider IDs aligned with CLI cards and legacy IDs. + +| CLI ID | Fingerprint Provider ID | +| ---------------------------------------------------------------------------------------------------- | ----------------------- | +| `kilo` | `kilocode` | +| `copilot` | `github` | +| `claude` / `codex` / `antigravity` / `kiro` / `cursor` / `cline` / `opencode` / `droid` / `openclaw` | same ID | + +Legacy IDs still accepted for compatibility: `copilot`, `kimi-coding`, `qwen`. + +--- + +## Step 1 โ€” Get an OmniRoute API Key + +1. Open the OmniRoute dashboard โ†’ **API Manager** (`/dashboard/api-manager`) +2. Click **Create API Key** +3. Give it a name (e.g. `cli-tools`) and select all permissions +4. Copy the key โ€” you'll need it for every CLI below + +> Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` + +--- + +## Step 2 โ€” Install CLI Tools + +All npm-based tools require Node.js 18+: + +```bash +# Claude Code (Anthropic) +npm install -g @anthropic-ai/claude-code + +# OpenAI Codex +npm install -g @openai/codex + +# OpenCode +npm install -g opencode-ai + +# Cline +npm install -g cline + +# KiloCode +npm install -g kilocode + +# Kiro CLI (Amazon โ€” requires curl + unzip) +apt-get install -y unzip # on Debian/Ubuntu +curl -fsSL https://cli.kiro.dev/install | bash +export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc +``` + +**Verify:** + +```bash +claude --version # 2.x.x +codex --version # 0.x.x +opencode --version # x.x.x +cline --version # 2.x.x +kilocode --version # x.x.x (or: kilo --version) +kiro-cli --version # 1.x.x +``` + +--- + +## Step 3 โ€” Set Global Environment Variables + +Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`: + +```bash +# OmniRoute Universal Endpoint +export OPENAI_BASE_URL="http://localhost:20128/v1" +export OPENAI_API_KEY="sk-your-omniroute-key" +export ANTHROPIC_BASE_URL="http://localhost:20128/v1" +export ANTHROPIC_API_KEY="sk-your-omniroute-key" +export GEMINI_BASE_URL="http://localhost:20128/v1" +export GEMINI_API_KEY="sk-your-omniroute-key" +``` + +> For a **remote server** replace `localhost:20128` with the server IP or domain, +> e.g. `http://192.168.0.15:20128`. + +--- + +## Step 4 โ€” Configure Each Tool + +### Claude Code + +```bash +# Via CLI: +claude config set --global api-base-url http://localhost:20128/v1 + +# Or create ~/.claude/settings.json: +mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF +{ + "apiBaseUrl": "http://localhost:20128/v1", + "apiKey": "sk-your-omniroute-key" +} +EOF +``` + +**Test:** `claude "say hello"` + +--- + +### OpenAI Codex + +```bash +mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF +model: auto +apiKey: sk-your-omniroute-key +apiBaseUrl: http://localhost:20128/v1 +EOF +``` + +**Test:** `codex "what is 2+2?"` + +--- + +### OpenCode + +```bash +mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF +[provider.openai] +base_url = "http://localhost:20128/v1" +api_key = "sk-your-omniroute-key" +EOF +``` + +**Test:** `opencode` + +--- + +### Cline (CLI or VS Code) + +**CLI mode:** + +```bash +mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF +{ + "apiProvider": "openai", + "openAiBaseUrl": "http://localhost:20128/v1", + "openAiApiKey": "sk-your-omniroute-key" +} +EOF +``` + +**VS Code mode:** +Cline extension settings โ†’ API Provider: `OpenAI Compatible` โ†’ Base URL: `http://localhost:20128/v1` + +Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ Cline โ†’ Apply Config**. + +--- + +### KiloCode (CLI or VS Code) + +**CLI mode:** + +```bash +kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key +``` + +**VS Code settings:** + +```json +{ + "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", + "kilo-code.apiKey": "sk-your-omniroute-key" +} +``` + +Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ KiloCode โ†’ Apply Config**. + +--- + +### Continue (VS Code Extension) + +Edit `~/.continue/config.yaml`: + +```yaml +models: + - name: OmniRoute + provider: openai + model: auto + apiBase: http://localhost:20128/v1 + apiKey: sk-your-omniroute-key + default: true +``` + +Restart VS Code after editing. + +--- + +### Kiro CLI (Amazon) + +```bash +# Login to your AWS/Kiro account: +kiro-cli login + +# The CLI uses its own auth โ€” OmniRoute is not needed as backend for Kiro CLI itself. +# Use kiro-cli alongside OmniRoute for other tools. +kiro-cli status +``` + +--- + +### Cursor (Desktop App) + +> **Note:** Cursor routes requests through its cloud. For OmniRoute integration, +> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL. + +Via GUI: **Settings โ†’ Models โ†’ OpenAI API Key** + +- Base URL: `https://your-domain.com/v1` +- API Key: your OmniRoute key + +--- + +## Dashboard Auto-Configuration + +The OmniRoute dashboard automates configuration for most tools: + +1. Go to `http://localhost:20128/dashboard/cli-tools` +2. Expand any tool card +3. Select your API key from the dropdown +4. Click **Apply Config** (if tool is detected as installed) +5. Or copy the generated config snippet manually + +--- + +## Built-in Agents: Droid & OpenClaw + +**Droid** and **OpenClaw** are AI agents built directly into OmniRoute โ€” no installation needed. +They run as internal routes and use OmniRoute's model routing automatically. + +- Access: `http://localhost:20128/dashboard/agents` +- Configure: same combos and providers as all other tools +- No API key or CLI install required + +--- + +## Available API Endpoints + +| Endpoint | Description | Use For | +| -------------------------- | ----------------------------- | --------------------------- | +| `/v1/chat/completions` | Standard chat (all providers) | All modern tools | +| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows | +| `/v1/completions` | Legacy text completions | Older tools using `prompt:` | +| `/v1/embeddings` | Text embeddings | RAG, search | +| `/v1/images/generations` | Image generation | DALL-E, Flux, etc. | +| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS | +| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI | + +--- + +## Fehlerbehebung + +| Error | Cause | Fix | +| ------------------------- | ----------------------- | ------------------------------------------ | +| `Connection refused` | OmniRoute not running | `pm2 start omniroute` | +| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` | +| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` | +| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` | +| CLI shows "not installed" | Binary not in PATH | Check `which ` | +| `kiro-cli: not found` | Not in PATH | `export PATH="$HOME/.local/bin:$PATH"` | + +--- + +## Quick Setup Script (One Command) + +```bash +# Install all CLIs and configure for OmniRoute (replace with your key and server URL) +OMNIROUTE_URL="http://localhost:20128/v1" +OMNIROUTE_KEY="sk-your-omniroute-key" + +npm install -g @anthropic-ai/claude-code @openai/codex opencode-ai cline kilocode + +# Kiro CLI +apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash + +# Write configs +mkdir -p ~/.claude ~/.codex ~/.config/opencode ~/.continue + +cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" +cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" +cat >> ~/.bashrc << EOF +export OPENAI_BASE_URL="$OMNIROUTE_URL" +export OPENAI_API_KEY="$OMNIROUTE_KEY" +export ANTHROPIC_BASE_URL="$OMNIROUTE_URL" +export ANTHROPIC_API_KEY="$OMNIROUTE_KEY" +EOF + +source ~/.bashrc +echo "โœ… All CLIs installed and configured for OmniRoute" +``` diff --git a/docs/i18n/de/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/de/docs/CODEBASE_DOCUMENTATION.md new file mode 100644 index 0000000000..3f0c42f791 --- /dev/null +++ b/docs/i18n/de/docs/CODEBASE_DOCUMENTATION.md @@ -0,0 +1,591 @@ +# omniroute โ€” Codebase Documentation (Deutsch) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CODEBASE_DOCUMENTATION.md) + +--- + +> 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
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, Qoder, 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. + +#### Architektur + +```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 | +| Qoder | 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"] +``` diff --git a/docs/i18n/de/docs/COVERAGE_PLAN.md b/docs/i18n/de/docs/COVERAGE_PLAN.md new file mode 100644 index 0000000000..5c994afb44 --- /dev/null +++ b/docs/i18n/de/docs/COVERAGE_PLAN.md @@ -0,0 +1,170 @@ +# Test Coverage Plan (Deutsch) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/COVERAGE_PLAN.md) + +--- + +Last updated: 2026-03-28 + +## Baseline + +There are multiple coverage numbers depending on how the report is computed. For planning, only one of them is useful. + +| Metric | Scope | Statements / Lines | Branches | Functions | Notes | +| -------------------- | ----------------------------------------------------- | -----------------: | -------: | --------: | --------------------------------------------------- | +| Legacy | Old `npm run test:coverage` | 79.42% | 75.15% | 67.94% | Inflated: counts test files and excludes `open-sse` | +| Diagnostic | Source-only, excluding tests and excluding `open-sse` | 68.16% | 63.55% | 64.06% | Useful only to isolate `src/**` | +| Recommended baseline | Source-only, excluding tests and including `open-sse` | 56.95% | 66.05% | 57.80% | This is the project-wide baseline to improve | + +The recommended baseline is the number to optimize against. + +## Rules + +- Coverage targets apply to source files, not to `tests/**`. +- `open-sse/**` is part of the product and must remain in scope. +- New code should not reduce coverage in touched areas. +- Prefer testing behavior and branch outcomes over implementation details. +- Prefer temp SQLite databases and small fixtures over broad mocks for `src/lib/db/**`. + +## Current command set + +- `npm run test:coverage` + - Main source coverage gate for the unit test suite + - Generates `text-summary`, `html`, `json-summary`, and `lcov` +- `npm run coverage:report` + - Detailed file-by-file report from the latest run +- `npm run test:coverage:legacy` + - Historical comparison only + +## Milestones + +| Phase | Target | Focus | +| ------- | ---------------------: | ------------------------------------------------- | +| Phase 1 | 60% statements / lines | Quick wins and low-risk utility coverage | +| Phase 2 | 65% statements / lines | DB and route foundations | +| Phase 3 | 70% statements / lines | Provider validation and usage analytics | +| Phase 4 | 75% statements / lines | `open-sse` translators and helpers | +| Phase 5 | 80% statements / lines | `open-sse` handlers and executor branches | +| Phase 6 | 85% statements / lines | Harder edge cases, branch debt, regression suites | +| Phase 7 | 90% statements / lines | Final sweep, gap closure, strict ratchet | + +Branches and functions should ratchet upward with each phase, but the primary hard target is statements / lines. + +## Priority hotspots + +These files or areas offer the best return for the next phases: + +1. `open-sse/handlers` + - `chatCore.ts` at 7.57% + - Overall directory at 29.07% +2. `open-sse/translator/request` + - Overall directory at 36.39% + - Many translators are still near single-digit coverage +3. `open-sse/translator/response` + - Overall directory at 8.07% +4. `open-sse/executors` + - Overall directory at 36.62% +5. `src/lib/db` + - `models.ts` at 20.66% + - `registeredKeys.ts` at 34.46% + - `modelComboMappings.ts` at 36.25% + - `settings.ts` at 46.40% + - `webhooks.ts` at 33.33% +6. `src/lib/usage` + - `usageHistory.ts` at 21.12% + - `usageStats.ts` at 9.56% + - `costCalculator.ts` at 30.00% +7. `src/lib/providers` + - `validation.ts` at 41.16% +8. Low-risk utility and API files for early gains + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/api/errorResponse.ts` + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +## Execution checklist + +### Phase 1: 56.95% -> 60% + +- [x] Fix coverage metric so it reflects source code instead of test files +- [x] Keep a legacy coverage script for comparison +- [x] Record the baseline and hotspots in-repo +- [ ] Add focused tests for low-risk utilities: + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/fetchTimeout.ts` + - `src/lib/api/errorResponse.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/display/names.ts` +- [ ] Add route tests for: + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +### Phase 2: 60% -> 65% + +- [ ] Add DB-backed tests for: + - `src/lib/db/modelComboMappings.ts` + - `src/lib/db/settings.ts` + - `src/lib/db/registeredKeys.ts` +- [ ] Cover branch behavior in: + - `src/lib/providers/validation.ts` + - `src/app/api/v1/embeddings/route.ts` + - `src/app/api/v1/moderations/route.ts` + +### Phase 3: 65% -> 70% + +- [ ] Add usage analytics tests for: + - `src/lib/usage/usageHistory.ts` + - `src/lib/usage/usageStats.ts` + - `src/lib/usage/costCalculator.ts` +- [ ] Expand route coverage for proxy management and settings branches + +### Phase 4: 70% -> 75% + +- [ ] Cover translator helpers and central translation paths: + - `open-sse/translator/index.ts` + - `open-sse/translator/helpers/*` + - `open-sse/translator/request/*` + - `open-sse/translator/response/*` + +### Phase 5: 75% -> 80% + +- [ ] Add handler-level tests for: + - `open-sse/handlers/chatCore.ts` + - `open-sse/handlers/responsesHandler.js` + - `open-sse/handlers/imageGeneration.js` + - `open-sse/handlers/embeddings.js` +- [ ] Add executor branch coverage for provider-specific auth, retries, and endpoint overrides + +### Phase 6: 80% -> 85% + +- [ ] Merge more edge-case suites into the main coverage path +- [ ] Increase function coverage for DB modules with weak constructor/helper coverage +- [ ] Close branch gaps in `settings.ts`, `registeredKeys.ts`, `validation.ts`, and translator helpers + +### Phase 7: 85% -> 90% + +- [ ] Treat the remaining low-coverage files as blockers +- [ ] Add regression tests for every uncovered production bug fixed during the push to 90% +- [ ] Raise the coverage gate in CI only after the local baseline is stable for at least two consecutive runs + +## Ratchet policy + +Update `npm run test:coverage` thresholds only after the project actually exceeds the next milestone with a comfortable buffer. + +Recommended ratchet sequence: + +1. 55/60/55 +2. 60/62/58 +3. 65/64/62 +4. 70/66/66 +5. 75/70/72 +6. 80/75/78 +7. 85/80/84 +8. 90/85/88 + +Order is `statements-lines / branches / functions`. + +## Known gap + +The current coverage command measures the main Node unit suite and includes source reached from it, including `open-sse`. It does not yet merge Vitest coverage into a single unified report. That merge is worth doing later, but it is not a blocker for starting the 60% -> 80% climb. diff --git a/docs/i18n/de/docs/FEATURES.md b/docs/i18n/de/docs/FEATURES.md index 72b1b15eba..31b04fba54 100644 --- a/docs/i18n/de/docs/FEATURES.md +++ b/docs/i18n/de/docs/FEATURES.md @@ -1,6 +1,6 @@ # OmniRoute โ€” Dashboard Features Gallery (Deutsch) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/FEATURES.md) --- @@ -10,7 +10,7 @@ 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). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. ![Providers Dashboard](screenshots/01-providers.png) diff --git a/docs/i18n/de/docs/MCP-SERVER.md b/docs/i18n/de/docs/MCP-SERVER.md new file mode 100644 index 0000000000..73e478960f --- /dev/null +++ b/docs/i18n/de/docs/MCP-SERVER.md @@ -0,0 +1,87 @@ +# OmniRoute MCP Server Documentation (Deutsch) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/MCP-SERVER.md) + +--- + +> Model Context Protocol server with 16 intelligent tools + +## Installieren + +OmniRoute MCP is built-in. Start it with: + +```bash +omniroute --mcp +``` + +Or via the open-sse transport: + +```bash +# HTTP streamable transport (port 20130) +omniroute --dev # MCP auto-starts on /mcp endpoint +``` + +## IDE Configuration + +See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup. + +--- + +## Essential Tools (8) + +| Tool | Description | +| :------------------------------ | :--------------------------------------- | +| `omniroute_get_health` | Gateway health, circuit breakers, uptime | +| `omniroute_list_combos` | All configured combos with models | +| `omniroute_get_combo_metrics` | Performance metrics for a specific combo | +| `omniroute_switch_combo` | Switch active combo by ID/name | +| `omniroute_check_quota` | Quota status per provider or all | +| `omniroute_route_request` | Send a chat completion through OmniRoute | +| `omniroute_cost_report` | Cost analytics for a time period | +| `omniroute_list_models_catalog` | Full model catalog with capabilities | + +## Advanced Tools (8) + +| Tool | Description | +| :--------------------------------- | :---------------------------------------------------------- | +| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | +| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | +| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | +| `omniroute_test_combo` | Live-test all models in a combo via a real upstream request | +| `omniroute_get_provider_metrics` | Detailed metrics for one provider | +| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | +| `omniroute_explain_route` | Explain a past routing decision | +| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | + +## Authentication + +MCP tools are authenticated via API key scopes. Each tool requires specific scopes: + +| Scope | Tools | +| :------------- | :----------------------------------------------- | +| `read:health` | get_health, get_provider_metrics | +| `read:combos` | list_combos, get_combo_metrics | +| `write:combos` | switch_combo | +| `read:quota` | check_quota | +| `write:route` | route_request, simulate_route, test_combo | +| `read:usage` | cost_report, get_session_snapshot, explain_route | +| `write:config` | set_budget_guard, set_resilience_profile | +| `read:models` | list_models_catalog, best_combo_for_task | + +## Audit Logging + +Every tool call is logged to `mcp_tool_audit` with: + +- Tool name, arguments, result +- Duration (ms), success/failure +- API key hash, timestamp + +## Files + +| File | Purpose | +| :------------------------------------------- | :------------------------------------------ | +| `open-sse/mcp-server/server.ts` | MCP server creation + 16 tool registrations | +| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport | +| `open-sse/mcp-server/auth.ts` | API key + scope validation | +| `open-sse/mcp-server/audit.ts` | Tool call audit logging | +| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers | diff --git a/docs/i18n/de/docs/RELEASE_CHECKLIST.md b/docs/i18n/de/docs/RELEASE_CHECKLIST.md new file mode 100644 index 0000000000..1b7db4cafa --- /dev/null +++ b/docs/i18n/de/docs/RELEASE_CHECKLIST.md @@ -0,0 +1,37 @@ +# Release Checklist (Deutsch) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/RELEASE_CHECKLIST.md) + +--- + +Use this checklist before tagging or publishing a new OmniRoute release. + +## Version and Changelog + +1. Bump `package.json` version (`x.y.z`) in the release branch. +2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: + - `## [x.y.z] โ€” YYYY-MM-DD` +3. Keep `## [Unreleased]` as the first changelog section for upcoming work. +4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. + +## API Docs + +1. Update `docs/openapi.yaml`: + - `info.version` must equal `package.json` version. +2. Validate endpoint examples if API contracts changed. + +## Runtime Docs + +1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. +2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. +3. Update localized docs if source docs changed significantly. + +## Automated Check + +Run the sync guard locally before opening PR: + +```bash +npm run check:docs-sync +``` + +CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/de/docs/TROUBLESHOOTING.md b/docs/i18n/de/docs/TROUBLESHOOTING.md new file mode 100644 index 0000000000..02ab03bcf8 --- /dev/null +++ b/docs/i18n/de/docs/TROUBLESHOOTING.md @@ -0,0 +1,256 @@ +# Troubleshooting (Deutsch) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/TROUBLESHOOTING.md) + +--- + +Common problems and solutions for OmniRoute. + +--- + +## Quick Fixes + +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | + +--- + +## Provider Issues + +### "Language model did not provide messages" + +**Cause:** Provider quota exhausted. + +**Fix:** + +1. 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, Qoder) 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}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) + +--- + +## Circuit Breaker Issues + +### Provider stuck in OPEN state + +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. + +**Fix:** + +1. 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 +- **SDK returns raw string instead of object** โ€” Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** โ€” Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** โ€” Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** โ€” Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` + +--- + +## Resilience Settings + +### Auto rate-limit not triggering + +- 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. + +--- + +## Optional RAG / LLM failure taxonomy (16 problems) + +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` โ€ฆ `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard โ†’ Health** for real-time system status +- **Translator**: Use **Dashboard โ†’ Translator** to debug format issues diff --git a/docs/i18n/de/USER_GUIDE.md b/docs/i18n/de/docs/USER_GUIDE.md similarity index 82% rename from docs/i18n/de/USER_GUIDE.md rename to docs/i18n/de/docs/USER_GUIDE.md index 2e6793c4c4..0280efc638 100644 --- a/docs/i18n/de/USER_GUIDE.md +++ b/docs/i18n/de/docs/USER_GUIDE.md @@ -1,8 +1,6 @@ # User Guide (Deutsch) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/USER_GUIDE.md) - -> ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/USER_GUIDE.md) --- @@ -320,7 +318,7 @@ Model: cc/claude-opus-4-6 --- -## ๐Ÿš€ Deployment +## Bereitstellung ### Global npm install (Recommended) @@ -511,23 +509,26 @@ post_install() { ### Environment Variables -| Variable | Default | Description | -| ------------------------- | ------------------------------------ | ------------------------------------------------------- | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | -| `INITIAL_PASSWORD` | `123456` | First login password | -| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | -| `PORT` | framework default | Service port (`20128` in examples) | -| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | -| `NODE_ENV` | runtime default | Set `production` for deploy | -| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | -| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | -| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | -| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | -| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | -| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | -| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | -| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | +| 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/*` | +| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand | +| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | For the full environment variable reference, see the [README](../README.md). @@ -598,6 +599,11 @@ curl -X POST http://localhost:20128/api/provider-models \ Or use Dashboard: **Providers โ†’ [Provider] โ†’ Custom Models**. +Notes: + +- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers. +- The **Custom Models** section is intended for providers that do not expose managed available-model imports. + ### Dedicated Provider Routes Route requests directly to a specific provider with model validation: @@ -642,6 +648,14 @@ Returns models grouped by provider with types (`chat`, `embedding`, `image`). - Automatic background sync with timeout + fail-fast - Prefer server-side `BASE_URL`/`CLOUD_URL` in production +### Cloudflare Quick Tunnel + +- Available in **Dashboard โ†’ Endpoints** for Docker and other self-hosted deployments +- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint +- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary +- Tunnel URLs are ephemeral and change every time you stop/start the tunnel +- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download + ### LLM Gateway Intelligence (Phase 9) - **Semantic Cache** โ€” Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) @@ -757,11 +771,11 @@ OmniRoute implements provider-level resilience with four components: 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 | +| 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 unless `DISABLE_SQLITE_AUTO_BACKUP=true` | ```bash # API: Export database @@ -787,10 +801,11 @@ curl -X POST http://localhost:20128/api/db-backups/import \ ### Settings Dashboard -The settings page is organized into 5 tabs for easy navigation: +The settings page is organized into 6 tabs for easy navigation: | Tab | Contents | | -------------- | ---------------------------------------------------------------------------------------------- | +| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility | | **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | | **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | | **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | diff --git a/docs/i18n/de/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/de/docs/VM_DEPLOYMENT_GUIDE.md new file mode 100644 index 0000000000..158a27774b --- /dev/null +++ b/docs/i18n/de/docs/VM_DEPLOYMENT_GUIDE.md @@ -0,0 +1,403 @@ +# OmniRoute โ€” Deployment Guide on VM with Cloudflare (Deutsch) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/VM_DEPLOYMENT_GUIDE.md) + +--- + +Complete guide to install and configure OmniRoute on a VM (VPS) with domain managed via Cloudflare. + +--- + +## Prerequisites + +| Item | Minimum | Recommended | +| ---------- | ------------------------ | ---------------- | +| **CPU** | 1 vCPU | 2 vCPU | +| **RAM** | 1 GB | 2 GB | +| **Disk** | 10 GB SSD | 25 GB SSD | +| **OS** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS | +| **Domain** | Registered on Cloudflare | โ€” | +| **Docker** | Docker Engine 24+ | Docker 27+ | + +**Tested providers**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. + +--- + +## 1. Configure the VM + +### 1.1 Create the instance + +On your preferred VPS provider: + +- Choose Ubuntu 24.04 LTS +- Select the minimum plan (1 vCPU / 1 GB RAM) +- Set a strong root password or configure SSH key +- Note the **public IP** (e.g., `203.0.113.10`) + +### 1.2 Connect via SSH + +```bash +ssh root@203.0.113.10 +``` + +### 1.3 Update the system + +```bash +apt update && apt upgrade -y +``` + +### 1.4 Install Docker + +```bash +# Install dependencies +apt install -y ca-certificates curl gnupg + +# Add official Docker repository +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 Install nginx + +```bash +apt install -y nginx +``` + +### 1.6 Configure 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 +``` + +> **Tip**: For maximum security, restrict ports 80 and 443 to Cloudflare IPs only. See the [Advanced Security](#advanced-security) section. + +--- + +## 2. Install OmniRoute + +### 2.1 Create configuration directory + +```bash +mkdir -p /opt/omniroute +``` + +### 2.2 Create environment variables file + +```bash +cat > /opt/omniroute/.env << โ€˜EOFโ€™ +# === Security === +JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY +INITIAL_PASSWORD=YourSecurePassword123! +API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY +STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY +STORAGE_ENCRYPTION_KEY_VERSION=v1 +MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT + +# === 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 (change to your domain) === +BASE_URL=https://llms.seudominio.com +NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com + +# === Cloud Sync (optional) === +# CLOUD_URL=https://cloud.omniroute.online +# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online +EOF +``` + +> โš ๏ธ **IMPORTANT**: Generate unique secret keys! Use `openssl rand -hex 32` for each key. + +### 2.3 Start the 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 Verify that it is running + +```bash +docker ps | grep omniroute +docker logs omniroute --tail 20 +``` + +It should display: `[DB] SQLite database ready` and `listening on port 20128`. + +--- + +## 3. Configure nginx (Reverse Proxy) + +### 3.1 Generate SSL certificate (Cloudflare Origin) + +In the Cloudflare dashboard: + +1. Go to **SSL/TLS โ†’ Origin Server** +2. Click **Create Certificate** +3. Keep the defaults (15 years, \*.yourdomain.com) +4. Copy the **Origin Certificate** and the **Private Key** + +```bash +mkdir -p /etc/nginx/ssl + +# Paste the certificate +nano /etc/nginx/ssl/origin.crt + +# Paste the private key +nano /etc/nginx/ssl/origin.key + +chmod 600 /etc/nginx/ssl/origin.key +``` + +### 3.2 Nginx Configuration + +```bash +cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ +# Default server โ€” blocks direct access via 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.yourdomain.com; # Change to your domain + + 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.yourdomain.com; + return 301 https://$server_name$request_uri; +} +NGINX +``` + +### 3.3 Enable and Test + +```bash +# Remove default configuration +rm -f /etc/nginx/sites-enabled/default + +# Enable OmniRoute +ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute + +# Test and reload +nginx -t && systemctl reload nginx +``` + +--- + +## 4. Configure Cloudflare DNS + +### 4.1 Add DNS record + +In the Cloudflare dashboard โ†’ DNS: + +| Type | Name | Content | Proxy | +| ---- | ------ | ---------------------- | ---------- | +| A | `llms` | `203.0.113.10` (VM IP) | โœ… Proxied | + +### 4.2 Configure SSL + +Under **SSL/TLS โ†’ Overview**: + +- Mode: **Full (Strict)** + +Under **SSL/TLS โ†’ Edge Certificates**: + +- Always Use HTTPS: โœ… On +- Minimum TLS Version: TLS 1.2 +- Automatic HTTPS Rewrites: โœ… On + +### 4.3 Testing + +```bash +curl -sI https://llms.seudominio.com/health +# Should return HTTP/2 200 +``` + +--- + +## 5. Operations and Maintenance + +### Upgrade to a new version + +```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 +``` + +### View logs + +```bash +docker logs -f omniroute # Real-time stream +docker logs omniroute --tail 50 # Last 50 lines +``` + +### Manual database backup + +```bash +# Copy data from the volume to the host +docker cp omniroute:/app/data ./backup-$(date +%F) + +# Or compress the entire volume +docker run --rm -v omniroute-data:/data -v $(pwd):/backup \ + alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data +``` + +### Restore from 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. Advanced Security + +### Restrict nginx to Cloudflare IPs + +```bash +cat > /etc/nginx/cloudflare-ips.conf << โ€˜CFโ€™ +# Cloudflare IPv4 ranges โ€” update periodically +# 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 +``` + +Add the following to `nginx.conf` inside the `http {}` block: + +```nginx +include /etc/nginx/cloudflare-ips.conf; +``` + +### Install fail2ban + +```bash +apt install -y fail2ban +systemctl enable fail2ban +systemctl start fail2ban + +# Check status +fail2ban-client status sshd +``` + +### Block direct access to the Docker port + +```bash +# Prevent direct external access to port 20128 +iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP +iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT + +# Persist the rules +apt install -y iptables-persistent +netfilter-persistent save +``` + +--- + +## 7. Deploy to Cloudflare Workers (Optional) + +For remote access via Cloudflare Workers (without exposing the VM directly): + +```bash +# In the local repository +cd omnirouteCloud +npm install +npx wrangler login +npx wrangler deploy +``` + +See the full documentation at [omnirouteCloud/README.md](../omnirouteCloud/README.md). + +--- + +## Port Summary + +| Port | Service | Access | +| ----- | ----------- | -------------------------- | +| 22 | SSH | Public (with fail2ban) | +| 80 | nginx HTTP | Redirect โ†’ HTTPS | +| 443 | nginx HTTPS | Via Cloudflare Proxy | +| 20128 | OmniRoute | Localhost only (via nginx) | diff --git a/docs/i18n/de/src/lib/a2a/README.md b/docs/i18n/de/src/lib/a2a/README.md new file mode 100644 index 0000000000..4946f4b98b --- /dev/null +++ b/docs/i18n/de/src/lib/a2a/README.md @@ -0,0 +1,752 @@ +# OmniRoute A2A Server (Deutsch) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../../../src/lib/a2a/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../../../es/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../../../fr/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../../../de/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../../../it/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../../../ru/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../../../zh-CN/src/lib/a2a/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../../../ja/src/lib/a2a/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../../../ko/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../../../ar/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../../../in/src/lib/a2a/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../../../th/src/lib/a2a/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../../../vi/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../../../id/src/lib/a2a/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../../../ms/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../../../nl/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../../../pl/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../../../sv/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../../../no/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../../../da/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../../../fi/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../../../pt/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../../../ro/src/lib/a2a/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../../../hu/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../../../bg/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../../../sk/src/lib/a2a/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../../../uk-UA/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../../../he/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../../../phi/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../../../pt-BR/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../../../cs/src/lib/a2a/README.md) + +--- + +> **Agent-to-Agent Protocol v0.3** โ€” Enables any AI agent to use OmniRoute as an intelligent routing agent via JSON-RPC 2.0. + +The A2A Server exposes OmniRoute as a **first-class agent** that other agents can discover, delegate tasks to, and collaborate with using the [A2A Protocol](https://google.github.io/A2A/). + +--- + +## Architektur + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Orchestrator Agent โ”‚ +โ”‚ (LangChain, CrewAI, AutoGen, Custom Agent) โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ 1. GET /.well-known/agent.json (discover) + โ”‚ 2. POST /a2a (JSON-RPC 2.0) + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ OmniRoute A2A Server โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Task Manager โ”‚ โ”‚ Skill Engine โ”‚ โ”‚ SSE Streaming โ”‚ โ”‚ +โ”‚ โ”‚ (lifecycle) โ”‚โ”€โ”€โ”‚ (registry) โ”‚โ”€โ”€โ”‚ (real-time) โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ +โ”‚ Skills: โ”‚ โ”‚ +โ”‚ โ”œโ”€ smart-routing โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ””โ”€ quota-management โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ Routing Decision Logger โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ OmniRoute Gateway (internal) + /v1/chat/completions, /api/combos, /api/usage/quota +``` + +--- + +## Schnellstart + +### Agent Discovery + +Every A2A-compatible agent exposes an **Agent Card** at `/.well-known/agent.json`: + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +**Response:** + +```json +{ + "name": "OmniRoute", + "description": "Intelligent AI gateway with auto-routing across 50+ providers", + "url": "http://localhost:20128/a2a", + "version": "1.8.1", + "capabilities": { + "streaming": true, + "pushNotifications": false + }, + "skills": [ + { + "id": "smart-routing", + "name": "Smart Routing", + "description": "Routes prompts through OmniRoute intelligent pipeline", + "tags": ["routing", "llm", "multi-provider", "cost-optimization"], + "examples": [ + "Write a hello world in Python", + "Explain quantum computing using the cheapest provider" + ] + }, + { + "id": "quota-management", + "name": "Quota Management", + "description": "Natural-language queries about provider quotas", + "tags": ["quota", "analytics", "cost"], + "examples": [ + "Which provider has the most quota remaining?", + "Suggest a free combo for coding" + ] + } + ], + "authentication": { + "schemes": ["bearer"], + "apiKeyHeader": "Authorization" + } +} +``` + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Send a message to a skill and receive the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python hello world"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "a1b2c3d4-...", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "print('Hello, World!')" }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.0030)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "2026-03-04T..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"Quantum computing..."}}} + +: heartbeat 2026-03-04T21:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Running Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Skills Reference + +### `smart-routing` + +Routes prompts through OmniRoute's intelligent pipeline with full observability. + +**Parameters (in `metadata`):** + +| Parameter | Type | Default | Description | +| --------- | -------- | ------------ | ---------------------------------------------------------------------------------------- | +| `model` | `string` | `"auto"` | Target model (e.g., `claude-sonnet-4`, `gpt-4o`, `auto`) | +| `combo` | `string` | active combo | Specific combo to route through | +| `budget` | `number` | none | Maximum cost in USD for this request | +| `role` | `string` | none | Task role hint: `coding`, `review`, `planning`, `analysis`, `debugging`, `documentation` | + +**Returns:** + +| Field | Description | +| ------------------------------ | --------------------------------------------------------- | +| `artifacts[].content` | The LLM response text | +| `metadata.routing_explanation` | Human-readable explanation of routing decision | +| `metadata.cost_envelope` | Estimated vs actual cost with currency | +| `metadata.resilience_trace` | Array of events (primary_selected, fallback_needed, etc.) | +| `metadata.policy_verdict` | Whether the request was allowed and why | + +### `quota-management` + +Answers natural-language queries about provider quotas. + +**Query types (inferred from message content):** + +| Query Pattern | Response Type | +| ---------------------------------------------- | -------------------------------------------------------- | +| Contains `"ranking"`, `"most quota"`, `"best"` | Providers ranked by remaining quota | +| Contains `"free"`, `"suggest"` | Lists free combos or suggests free-tier providers | +| Default | Full quota summary with warnings for low-quota providers | + +--- + +## Task Lifecycle + +``` +submitted โ”€โ”€โ†’ working โ”€โ”€โ†’ completed + โ”€โ”€โ†’ failed + โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ†’ cancelled +``` + +| State | Description | +| ----------- | ----------------------------------------------------- | +| `submitted` | Task created, queued for execution | +| `working` | Skill handler is executing | +| `completed` | Execution succeeded, artifacts available | +| `failed` | Execution failed or task expired (TTL: 5 min default) | +| `cancelled` | Cancelled by client via `tasks/cancel` | + +- Terminal states: `completed`, `failed`, `cancelled` (no further transitions) +- Expired tasks in `submitted` or `working` are auto-marked as `failed` +- Tasks are garbage-collected after 2ร— TTL + +--- + +## Client Examples + +### Python โ€” Orchestrator Agent + +```python +""" +A2A Client โ€” Python example. +Discovers OmniRoute agent, sends a task, and processes the result. +""" +import requests +import json + +BASE_URL = "http://localhost:20128" +API_KEY = "your-api-key" +HEADERS = { + "Content-Type": "application/json", + "Authorization": f"Bearer {API_KEY}", +} + +# 1. Discover agent capabilities +agent_card = requests.get(f"{BASE_URL}/.well-known/agent.json").json() +print(f"Agent: {agent_card['name']} v{agent_card['version']}") +print(f"Skills: {[s['id'] for s in agent_card['skills']]}") + +# 2. Send a smart-routing task +response = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python quicksort implementation"}], + "metadata": { + "model": "auto", + "combo": "fast-coding", + "budget": 0.10, + } + } +}) +result = response.json()["result"] +print(f"\n๐Ÿ“ Response: {result['artifacts'][0]['content'][:200]}...") +print(f"๐Ÿ”€ Routing: {result['metadata']['routing_explanation']}") +print(f"๐Ÿ’ฐ Cost: ${result['metadata']['cost_envelope']['actual']}") +print(f"๐Ÿ›ก๏ธ Policy: {result['metadata']['policy_verdict']['reason']}") + +# 3. Query quota status +quota_resp = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-2", + "method": "message/send", + "params": { + "skill": "quota-management", + "messages": [{"role": "user", "content": "Which provider has the most quota remaining?"}], + } +}) +quota_result = quota_resp.json()["result"] +print(f"\n๐Ÿ“Š Quota: {quota_result['artifacts'][0]['content']}") +``` + +### TypeScript โ€” Multi-Agent Orchestrator + +```typescript +/** + * A2A Client โ€” TypeScript example. + * Shows agent discovery, task delegation, and streaming. + */ + +const BASE_URL = "http://localhost:20128"; +const API_KEY = "your-api-key"; + +interface JsonRpcResponse { + jsonrpc: "2.0"; + id: string | number; + result?: T; + error?: { code: number; message: string }; +} + +async function a2aCall(method: string, params: Record): Promise { + const resp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: `${method}-${Date.now()}`, + method, + params, + }), + }); + const json: JsonRpcResponse = await resp.json(); + if (json.error) throw new Error(`[${json.error.code}] ${json.error.message}`); + return json.result!; +} + +// โ”€โ”€ Agent Discovery โ”€โ”€ +const agentCard = await fetch(`${BASE_URL}/.well-known/agent.json`).then((r) => r.json()); +console.log(`Connected to: ${agentCard.name} (${agentCard.skills.length} skills)`); + +// โ”€โ”€ Smart Routing: Send a coding task โ”€โ”€ +const routingResult = await a2aCall("message/send", { + skill: "smart-routing", + messages: [{ role: "user", content: "Implement a Redis cache wrapper in TypeScript" }], + metadata: { model: "claude-sonnet-4", role: "coding" }, +}); +console.log("Response:", routingResult.artifacts[0].content); +console.log("Provider:", routingResult.metadata.routing_explanation); + +// โ”€โ”€ Quota Management: Find free alternatives โ”€โ”€ +const quotaResult = await a2aCall("message/send", { + skill: "quota-management", + messages: [{ role: "user", content: "Suggest free combos for documentation" }], +}); +console.log("Free combos:", quotaResult.artifacts[0].content); + +// โ”€โ”€ Streaming: Real-time response โ”€โ”€ +const streamResp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "stream-1", + method: "message/stream", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Explain microservices architecture" }], + }, + }), +}); + +const reader = streamResp.body!.getReader(); +const decoder = new TextDecoder(); +while (true) { + const { done, value } = await reader.read(); + if (done) break; + const chunk = decoder.decode(value); + for (const line of chunk.split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + if (event.params.chunk) { + process.stdout.write(event.params.chunk.content); + } + if (event.params.task.state === "completed") { + console.log("\nโœ… Stream completed"); + } + } + } +} +``` + +### Python โ€” LangChain A2A Integration + +```python +""" +LangChain integration โ€” Use OmniRoute A2A as a custom LLM. +""" +from langchain.llms.base import BaseLLM +from langchain.schema import LLMResult, Generation +import requests +from typing import List, Optional + +class OmniRouteA2A(BaseLLM): + base_url: str = "http://localhost:20128" + api_key: str = "" + model: str = "auto" + combo: Optional[str] = None + + @property + def _llm_type(self) -> str: + return "omniroute-a2a" + + def _call(self, prompt: str, stop: Optional[List[str]] = None, **kwargs) -> str: + response = requests.post( + f"{self.base_url}/a2a", + headers={ + "Content-Type": "application/json", + "Authorization": f"Bearer {self.api_key}", + }, + json={ + "jsonrpc": "2.0", + "id": "langchain-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": prompt}], + "metadata": { + "model": self.model, + **({"combo": self.combo} if self.combo else {}), + }, + }, + }, + ) + result = response.json()["result"] + return result["artifacts"][0]["content"] + + def _generate(self, prompts: List[str], stop=None, **kwargs) -> LLMResult: + return LLMResult( + generations=[[Generation(text=self._call(p, stop))] for p in prompts] + ) + +# Usage +llm = OmniRouteA2A( + base_url="http://localhost:20128", + api_key="your-key", + model="auto", + combo="fast-coding", +) +result = llm("Write a Python function to merge two sorted lists") +print(result) +``` + +### Go โ€” A2A Client + +```go +package main + +import ( + "bytes" + "encoding/json" + "fmt" + "io" + "net/http" +) + +const baseURL = "http://localhost:20128" +const apiKey = "your-api-key" + +type JsonRpcRequest struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Method string `json:"method"` + Params interface{} `json:"params"` +} + +type JsonRpcResponse struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Result interface{} `json:"result"` + Error *struct { + Code int `json:"code"` + Message string `json:"message"` + } `json:"error"` +} + +func a2aCall(method string, params interface{}) (*JsonRpcResponse, error) { + body, _ := json.Marshal(JsonRpcRequest{ + Jsonrpc: "2.0", + ID: "go-1", + Method: method, + Params: params, + }) + + req, _ := http.NewRequest("POST", baseURL+"/a2a", bytes.NewReader(body)) + req.Header.Set("Content-Type", "application/json") + req.Header.Set("Authorization", "Bearer "+apiKey) + + resp, err := http.DefaultClient.Do(req) + if err != nil { + return nil, err + } + defer resp.Body.Close() + data, _ := io.ReadAll(resp.Body) + + var result JsonRpcResponse + json.Unmarshal(data, &result) + return &result, nil +} + +func main() { + // Discover agent + resp, _ := http.Get(baseURL + "/.well-known/agent.json") + defer resp.Body.Close() + body, _ := io.ReadAll(resp.Body) + fmt.Println("Agent Card:", string(body)) + + // Send smart-routing task + result, _ := a2aCall("message/send", map[string]interface{}{ + "skill": "smart-routing", + "messages": []map[string]string{{"role": "user", "content": "Hello from Go!"}}, + "metadata": map[string]interface{}{"model": "auto"}, + }) + out, _ := json.MarshalIndent(result.Result, "", " ") + fmt.Println("Result:", string(out)) +} +``` + +--- + +## Use Cases + +### ๐Ÿค– Use Case 1: Multi-Agent Coding Pipeline + +An orchestrator agent delegates code generation to OmniRoute, then passes the output to a review agent. + +```python +def coding_pipeline(task: str): + # Step 1: Generate code via OmniRoute A2A + code_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Write production-quality code: {task}"} + ], metadata={"model": "auto", "role": "coding"}) + code = code_result["artifacts"][0]["content"] + + # Step 2: Review the code via OmniRoute A2A (different model) + review_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Review this code for bugs and improvements:\n\n{code}"} + ], metadata={"model": "auto", "role": "review"}) + review = review_result["artifacts"][0]["content"] + + # Step 3: Check costs + print(f"Code cost: ${code_result['metadata']['cost_envelope']['actual']}") + print(f"Review cost: ${review_result['metadata']['cost_envelope']['actual']}") + + return {"code": code, "review": review} +``` + +### ๐Ÿ’ก Use Case 2: Quota-Aware Agent Swarm + +Multiple agents share quota through OmniRoute, using the quota skill to coordinate. + +```python +async def quota_aware_agent(agent_name: str, task: str): + # Check quota before starting + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Which provider has the most quota remaining?"} + ]) + print(f"[{agent_name}] {quota['artifacts'][0]['content']}") + + # Send request with budget constraint + result = a2a_send("smart-routing", [ + {"role": "user", "content": task} + ], metadata={"budget": 0.05}) + + policy = result["metadata"]["policy_verdict"] + if not policy["allowed"]: + print(f"[{agent_name}] โš ๏ธ Budget exceeded: {policy['reason']}") + # Fall back to free combo + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Suggest free combos"} + ]) + print(f"[{agent_name}] Free alternatives: {quota['artifacts'][0]['content']}") + + return result +``` + +### ๐Ÿ“Š Use Case 3: Real-Time Streaming Dashboard + +A monitoring agent streams responses and displays progress in real-time. + +```typescript +async function streamingDashboard(prompt: string) { + const response = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { "Content-Type": "application/json", Authorization: `Bearer ${API_KEY}` }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "dash-1", + method: "message/stream", + params: { skill: "smart-routing", messages: [{ role: "user", content: prompt }] }, + }), + }); + + let totalChunks = 0; + const reader = response.body!.getReader(); + const decoder = new TextDecoder(); + + while (true) { + const { done, value } = await reader.read(); + if (done) break; + + for (const line of decoder.decode(value).split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + const state = event.params.task.state; + + if (state === "working" && event.params.chunk) { + totalChunks++; + process.stdout.write( + `\r[Chunk ${totalChunks}] ${event.params.chunk.content.slice(0, 50)}...` + ); + } + if (state === "completed") { + const meta = event.params.metadata; + console.log( + `\nโœ… Done | Cost: $${meta?.cost_envelope?.actual || 0} | Route: ${meta?.routing_explanation || "N/A"}` + ); + } + if (state === "failed") { + console.error(`\nโŒ Failed: ${event.params.metadata?.error}`); + } + } + } + } +} +``` + +### ๐Ÿ” Use Case 4: Task Polling Pattern + +For long-running tasks, poll the task status instead of waiting synchronously. + +```python +import time + +def poll_task(task_id: str, timeout: int = 60): + """Poll task status until completion or timeout.""" + start = time.time() + while time.time() - start < timeout: + result = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "poll-1", + "method": "tasks/get", + "params": {"taskId": task_id}, + }).json() + + task = result["result"]["task"] + state = task["state"] + print(f" Task {task_id[:8]}... state={state}") + + if state in ("completed", "failed", "cancelled"): + return task + time.sleep(2) + + # Timeout โ€” cancel the task + requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "cancel-1", + "method": "tasks/cancel", + "params": {"taskId": task_id}, + }) + raise TimeoutError(f"Task {task_id} timed out after {timeout}s") +``` + +--- + +## Error Codes + +| Code | Constant | Meaning | +| ------ | ------------------------ | ---------------------------------------- | +| -32700 | โ€” | Parse error (invalid JSON) | +| -32600 | `INVALID_REQUEST` | Invalid JSON-RPC request or unauthorized | +| -32601 | `METHOD_NOT_FOUND` | Unknown method or skill | +| -32602 | `INVALID_PARAMS` | Missing or invalid parameters | +| -32603 | `INTERNAL_ERROR` | Skill execution failed | +| -32001 | `TASK_NOT_FOUND` | Task ID not found | +| -32002 | `TASK_ALREADY_COMPLETED` | Cannot modify a completed task | +| -32003 | `UNAUTHORIZED` | Invalid or missing API key | +| -32004 | `BUDGET_EXCEEDED` | Request exceeds configured budget | +| -32005 | `PROVIDER_UNAVAILABLE` | No available providers | + +--- + +## Authentication + +All `/a2a` requests require a Bearer token via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server (`OMNIROUTE_API_KEY` is empty), authentication is bypassed. + +--- + +## File Structure + +``` +src/lib/a2a/ +โ”œโ”€โ”€ taskManager.ts # Task lifecycle (create/update/cancel/list), TTL, cleanup +โ”œโ”€โ”€ taskExecution.ts # Generic task executor with state management +โ”œโ”€โ”€ streaming.ts # SSE stream formatting, heartbeat, chunk/completion events +โ”œโ”€โ”€ routingLogger.ts # Routing decision logger (stats, history, retention) +โ””โ”€โ”€ skills/ + โ”œโ”€โ”€ smartRouting.ts # Smart routing skill (routes via /v1/chat/completions) + โ””โ”€โ”€ quotaManagement.ts # Quota management skill (natural-language quota queries) + +src/app/a2a/ +โ””โ”€โ”€ route.ts # Next.js API route handler (JSON-RPC 2.0 dispatch) + +open-sse/mcp-server/ +โ””โ”€โ”€ schemas/a2a.ts # Zod schemas (AgentCard, Task, JSON-RPC, SSE events) +``` + +--- + +## Comparison: MCP vs A2A + +| Feature | MCP Server | A2A Server | +| ----------------- | ---------------------------- | ------------------------------------------------- | +| **Protocol** | Model Context Protocol | Agent-to-Agent Protocol v0.3 | +| **Transport** | stdio / HTTP | HTTP (JSON-RPC 2.0) | +| **Discovery** | Tool listing via MCP | `/.well-known/agent.json` | +| **Granularity** | 16 individual tools | 2 high-level skills | +| **Best for** | IDE agents (Cursor, VS Code) | Multi-agent systems (LangChain, CrewAI) | +| **Streaming** | Not supported | SSE via `message/stream` | +| **Task tracking** | No | Full lifecycle (submitted โ†’ completed) | +| **Observability** | Audit log per tool call | Cost envelope + resilience trace + policy verdict | + +--- + +## Lizenz + +Part of [OmniRoute](https://github.com/diegosouzapw/OmniRoute) โ€” MIT License. diff --git a/docs/i18n/es/A2A-SERVER.md b/docs/i18n/es/A2A-SERVER.md deleted file mode 100644 index 01531ff482..0000000000 --- a/docs/i18n/es/A2A-SERVER.md +++ /dev/null @@ -1,200 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/A2A-SERVER.md) - ---- - -# OmniRoute A2A Server Documentation - -> Agent-to-Agent Protocol v0.3 โ€” OmniRoute as an intelligent routing agent - -## Agent Discovery - -```bash -curl http://localhost:20128/.well-known/agent.json -``` - -Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements. - ---- - -## Authentication - -All `/a2a` requests require an API key via the `Authorization` header: - -``` -Authorization: Bearer YOUR_OMNIROUTE_API_KEY -``` - -If no API key is configured on the server, authentication is bypassed. - ---- - -## JSON-RPC 2.0 Methods - -### `message/send` โ€” Synchronous Execution - -Sends a message to a skill and waits for the complete response. - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{ - "jsonrpc": "2.0", - "id": "1", - "method": "message/send", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Write a hello world in Python"}], - "metadata": {"model": "auto", "combo": "fast-coding"} - } - }' -``` - -**Response:** - -```json -{ - "jsonrpc": "2.0", - "id": "1", - "result": { - "task": { "id": "uuid", "state": "completed" }, - "artifacts": [{ "type": "text", "content": "..." }], - "metadata": { - "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)", - "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, - "resilience_trace": [ - { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." } - ], - "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } - } - } -} -``` - -### `message/stream` โ€” SSE Streaming - -Same as `message/send` but returns Server-Sent Events for real-time streaming. - -```bash -curl -N -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{ - "jsonrpc": "2.0", - "id": "1", - "method": "message/stream", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Explain quantum computing"}] - } - }' -``` - -**SSE Events:** - -``` -data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}} - -: heartbeat 2026-03-03T17:00:00Z - -data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} -``` - -### `tasks/get` โ€” Query Task Status - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' -``` - -### `tasks/cancel` โ€” Cancel a Task - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' -``` - ---- - -## Available Skills - -| Skill | Description | -| :----------------- | :------------------------------------------------------------------------------------------------------------------------------ | -| `smart-routing` | Routes prompts through OmniRoute's intelligent pipeline. Returns response with routing explanation, cost, and resilience trace. | -| `quota-management` | Answers natural-language queries about provider quotas, suggests free combos, and provides quota rankings. | - ---- - -## Task Lifecycle - -``` -submitted โ†’ working โ†’ completed - โ†’ failed - โ†’ cancelled -``` - -- Tasks expire after 5 minutes (configurable) -- Terminal states: `completed`, `failed`, `cancelled` -- Event log tracks every state transition - ---- - -## Error Codes - -| Code | Meaning | -| :----- | :----------------------------- | -| -32700 | Parse error (invalid JSON) | -| -32600 | Invalid request / Unauthorized | -| -32601 | Method or skill not found | -| -32602 | Invalid params | -| -32603 | Internal error | - ---- - -## Integration Examples - -### Python (requests) - -```python -import requests - -resp = requests.post("http://localhost:20128/a2a", json={ - "jsonrpc": "2.0", "id": "1", - "method": "message/send", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Hello"}] - } -}, headers={"Authorization": "Bearer YOUR_KEY"}) - -result = resp.json()["result"] -print(result["artifacts"][0]["content"]) -print(result["metadata"]["routing_explanation"]) -``` - -### TypeScript (fetch) - -```typescript -const resp = await fetch("http://localhost:20128/a2a", { - method: "POST", - headers: { - "Content-Type": "application/json", - Authorization: "Bearer YOUR_KEY", - }, - body: JSON.stringify({ - jsonrpc: "2.0", - id: "1", - method: "message/send", - params: { - skill: "smart-routing", - messages: [{ role: "user", content: "Hello" }], - }, - }), -}); -const { result } = await resp.json(); -console.log(result.metadata.routing_explanation); -``` diff --git a/docs/i18n/es/API_REFERENCE.md b/docs/i18n/es/API_REFERENCE.md deleted file mode 100644 index b878605221..0000000000 --- a/docs/i18n/es/API_REFERENCE.md +++ /dev/null @@ -1,455 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/API_REFERENCE.md) - ---- - -# API Reference - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/API_REFERENCE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/API_REFERENCE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/API_REFERENCE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/API_REFERENCE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/API_REFERENCE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/API_REFERENCE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/API_REFERENCE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/API_REFERENCE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/API_REFERENCE.md) - -Complete reference for all OmniRoute API endpoints. - ---- - -## Table of Contents - -- [Chat Completions](#chat-completions) -- [Embeddings](#embeddings) -- [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`. - -### ACP Agents - -| Endpoint | Method | Description | -| ----------------- | ------ | -------------------------------------------------------- | -| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | -| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | -| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | - -GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). - -### Resilience & Rate Limits - -| Endpoint | Method | Description | -| ----------------------- | ------- | ------------------------------- | -| `/api/resilience` | 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` diff --git a/docs/i18n/es/ARCHITECTURE.md b/docs/i18n/es/ARCHITECTURE.md deleted file mode 100644 index 4ea06a29f2..0000000000 --- a/docs/i18n/es/ARCHITECTURE.md +++ /dev/null @@ -1,787 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/ARCHITECTURE.md) - ---- - -# OmniRoute Architecture - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/ARCHITECTURE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/ARCHITECTURE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/ARCHITECTURE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/ARCHITECTURE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/ARCHITECTURE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/ARCHITECTURE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/ARCHITECTURE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/ARCHITECTURE.md) - -_Last updated: 2026-03-04_ - -## 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 (`...`) for reasoning models -- Response sanitization for strict OpenAI SDK compatibility -- Role normalization (developerโ†’system, systemโ†’user) for cross-provider compatibility -- Structured output conversion (json_schema โ†’ Gemini responseSchema) -- Local persistence for providers, keys, aliases, combos, settings, pricing -- Usage/cost tracking and request logging -- Optional cloud sync for multi-device/state sync -- IP allowlist/blocklist for API access control -- Thinking budget management (passthrough/auto/custom/adaptive) -- Global system prompt injection -- Session tracking and fingerprinting -- Per-account enhanced rate limiting with provider-specific profiles -- Circuit breaker pattern for provider resilience -- Anti-thundering herd protection with mutex locking -- Signature-based request deduplication cache -- Domain layer: model availability, cost rules, fallback policy, lockout policy -- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) -- Policy engine for centralized request evaluation (lockout โ†’ budget โ†’ fallback) -- Request telemetry with p50/p95/p99 latency aggregation -- Correlation ID (X-Request-Id) for end-to-end tracing -- Compliance audit logging with opt-out per API key -- Eval framework for LLM quality assurance -- Resilience UI dashboard with real-time circuit breaker status -- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) - -Primary runtime model: - -- Next.js 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[(storage.sqlite)] - UDB[(usage tables + log artifacts)] - end - - subgraph Upstreams[Upstream Providers] - P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/Qoder/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/route.ts` (GET) -- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) -- OAuth: `src/app/api/oauth/*` -- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` -- Usage: `src/app/api/usage/*` -- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` -- CLI tooling helpers: `src/app/api/cli-tools/*` -- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) -- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) -- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) -- Sessions: `src/app/api/sessions` (GET) -- Rate limits: `src/app/api/rate-limits` (GET) -- Resilience: `src/app/api/resilience` (GET/PATCH) โ€” provider profiles, circuit breaker, rate limit state -- Resilience reset: `src/app/api/resilience/reset` (POST) โ€” reset breakers + cooldowns -- Cache stats: `src/app/api/cache/stats` (GET/DELETE) -- Model availability: `src/app/api/models/availability` (GET/POST) -- Telemetry: `src/app/api/telemetry/summary` (GET) -- Budget: `src/app/api/usage/budget` (GET/POST) -- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) -- Compliance audit: `src/app/api/compliance/audit-log` (GET) -- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) -- Policies: `src/app/api/policies` (GET/POST) - -## 2) SSE + 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` -- Response sanitization: `open-sse/handlers/responseSanitizer.ts` -- Role normalization: `open-sse/services/roleNormalizer.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`, `qoder.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 (SQLite): - -- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) -- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) -- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) -- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** - -Usage persistence: - -- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) -- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` -- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) -- legacy JSON files are migrated to SQLite by startup migrations when present - -Domain State DB (SQLite): - -- `src/lib/db/domainState.ts` โ€” CRUD operations 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: - -- primary runtime DB: `${DATA_DIR}/storage.sqlite` -- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) -- structured call payload archives: `${DATA_DIR}/call_logs/` -- optional translator/request debug sessions: `/logs/...` - -## Deployment Topology - -```mermaid -flowchart LR - 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[(storage.sqlite)] - UsageDB[(usage tables + log artifacts)] - end - - subgraph External[External Services] - Providers[AI Providers] - SyncCloud[Cloud Sync Service] - end - - CLI --> Next - Browser --> Next - Next --> Core - Next --> MainDB - Core --> MainDB - Core --> UsageDB - Core --> Providers - Next --> SyncCloud -``` - -## Module Mapping (Decision-Critical) - -### Route and API Modules - -- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs -- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) -- `src/app/api/providers*`: provider CRUD, validation, testing -- `src/app/api/provider-nodes*`: custom compatible node management -- `src/app/api/provider-models`: custom model management (CRUD) -- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) -- `src/app/api/oauth/*`: OAuth/device-code flows -- `src/app/api/keys*`: local API key lifecycle -- `src/app/api/models/alias`: alias management -- `src/app/api/combos*`: fallback combo management -- `src/app/api/pricing`: pricing overrides for cost calculation -- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) -- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) -- `src/app/api/usage/*`: usage and logs APIs -- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers -- `src/app/api/cli-tools/*`: local CLI config writers/checkers -- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) -- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) -- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) -- `src/app/api/sessions`: active session listing (GET) -- `src/app/api/rate-limits`: per-account rate limit status (GET) - -### Routing and Execution Core - -- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop -- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup -- `open-sse/executors/*`: provider-specific network and format behavior - -### Translation Registry and Format Converters - -- `open-sse/translator/index.ts`: translator registry and orchestration -- Request translators: `open-sse/translator/request/*` -- Response translators: `open-sse/translator/response/*` -- Format constants: `open-sse/translator/formats.ts` - -### Persistence - -- `src/lib/db/*`: persistent config/state and domain persistence on SQLite -- `src/lib/localDb.ts`: compatibility re-export for DB modules -- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables - -## Provider Executor Coverage (Strategy Pattern) - -Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. - -| Executor | Provider(s) | Special Handling | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | -| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, Qoder, 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 | -| Qoder | openai | OAuth (Basic) | โœ… | โœ… | โœ… | โš ๏ธ Per request | -| OpenRouter | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| GLM/Kimi/MiniMax | claude | API Key | โœ… | โœ… | โŒ | โŒ | -| DeepSeek | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Groq | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| xAI (Grok) | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Mistral | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Perplexity | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Together AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Fireworks AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Cerebras | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Cohere | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| NVIDIA NIM | openai | API Key | โœ… | โœ… | โŒ | โŒ | - -## Format Translation Coverage - -Detected source formats include: - -- `openai` -- `openai-responses` -- `claude` -- `gemini` - -Target formats include: - -- OpenAI chat/Responses -- Claude -- Gemini/Gemini-CLI/Antigravity envelope -- Kiro -- Cursor - -Translations use **OpenAI as the hub format** โ€” all conversions go through OpenAI as intermediate: - -``` -Source Format โ†’ OpenAI (hub) โ†’ Target Format -``` - -Translations are selected dynamically based on source payload shape and provider target format. - -Additional processing layers in the translation pipeline: - -- **Response sanitization** โ€” Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance -- **Role normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI targets; merges `system` โ†’ `user` for models that reject the system role (GLM, ERNIE) -- **Think tag extraction** โ€” Parses `...` blocks from content into `reasoning_content` field -- **Structured output** โ€” Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` - -## Supported API Endpoints - -| 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 `/logs//` 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 - -- SQLite schema migrations and auto-upgrade hooks at startup -- legacy JSON โ†’ SQLite migration compatibility path - -## Observability and Operational Signals - -Runtime visibility sources: - -- console logs from `src/sse/utils/logger.ts` -- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) -- textual request status log in `log.txt` (optional/compat) -- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` -- dashboard usage endpoints (`/api/usage/*`) for UI consumption - -## Security-Sensitive Boundaries - -- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing -- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning -- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format -- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level -- Cloud sync endpoints rely on API key auth + machine id semantics - -## Environment and Runtime Matrix - -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` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. -2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. -3. Request logger writes full headers/body when enabled; treat log directory as sensitive. -4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. -5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. -6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). -7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). -8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). - -## Operational Verification Checklist - -- Build from source: `npm run build` -- Build Docker image: `docker build -t omniroute .` -- Start service and verify: -- `GET /api/settings` -- `GET /api/v1/models` -- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/es/AUTO-COMBO.md b/docs/i18n/es/AUTO-COMBO.md deleted file mode 100644 index 2166e41dff..0000000000 --- a/docs/i18n/es/AUTO-COMBO.md +++ /dev/null @@ -1,67 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/AUTO-COMBO.md) - ---- - -# OmniRoute Auto-Combo Engine - -> Self-managing model chains with adaptive scoring - -## How It Works - -The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**: - -| Factor | Weight | Description | -| :--------- | :----- | :---------------------------------------------- | -| Quota | 0.20 | Remaining capacity [0..1] | -| Health | 0.25 | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 | -| CostInv | 0.20 | Inverse cost (cheaper = higher score) | -| LatencyInv | 0.15 | Inverse p95 latency (faster = higher) | -| TaskFit | 0.10 | Model ร— task type fitness score | -| Stability | 0.10 | Low variance in latency/errors | - -## Mode Packs - -| Pack | Focus | Key Weight | -| :---------------------- | :----------- | :--------------- | -| ๐Ÿš€ **Ship Fast** | Speed | latencyInv: 0.35 | -| ๐Ÿ’ฐ **Cost Saver** | Economy | costInv: 0.40 | -| ๐ŸŽฏ **Quality First** | Best model | taskFit: 0.40 | -| ๐Ÿ“ก **Offline Friendly** | Availability | quota: 0.40 | - -## Self-Healing - -- **Temporary exclusion**: Score < 0.2 โ†’ excluded for 5 min (progressive backoff, max 30 min) -- **Circuit breaker awareness**: OPEN โ†’ auto-excluded; HALF_OPEN โ†’ probe requests -- **Incident mode**: >50% OPEN โ†’ disable exploration, maximize stability -- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout - -## Bandit Exploration - -5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode. - -## API - -```bash -# Create auto-combo -curl -X POST http://localhost:20128/api/combos/auto \ - -H "Content-Type: application/json" \ - -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}' - -# List auto-combos -curl http://localhost:20128/api/combos/auto -``` - -## Task Fitness - -30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` โ†’ high coding score). - -## Files - -| File | Purpose | -| :------------------------------------------- | :------------------------------------ | -| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization | -| `open-sse/services/autoCombo/taskFitness.ts` | Model ร— task fitness lookup | -| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap | -| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode | -| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles | -| `src/app/api/combos/auto/route.ts` | REST API | diff --git a/docs/i18n/es/CHANGELOG.md b/docs/i18n/es/CHANGELOG.md index eb4136c683..9e8c1dfb8b 100644 --- a/docs/i18n/es/CHANGELOG.md +++ b/docs/i18n/es/CHANGELOG.md @@ -1,12 +1,92 @@ # Changelog (Espaรฑol) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CHANGELOG.md) --- - ## [Unreleased] +### ๐Ÿ› ๏ธ Maintenance + +- **AGENTS.md rewrite:** Condensed from 297โ†’153 lines. Added build/lint/test commands (including single-test execution), code style guidelines (Prettier, TypeScript, ESLint, naming, imports, error handling, security), and trimmed verbose architecture tables for AI agent consumption. + +## [3.4.2] - 2026-04-01 + +### ๐Ÿ› Bug Fixes + +- **CI Stabilization:** Fixed failing analytics/settings Playwright selectors and request assertions so GitHub Actions E2E runs pass reliably across localized UIs and switch-based controls. +- **Deterministic Tests:** Removed date-sensitive quota fixtures from Copilot usage tests and aligned idempotency/model catalog tests with the merged runtime behavior. +- **MCP Type Hardening:** Removed zero-budget explicit `any` regressions from the MCP server tool registration path, restoring the `check:any-budget:t11` workflow gate. + +### ๐Ÿ› ๏ธ Maintenance + +- **Release Branch Integration:** Consolidated the active feature branches into `release/v3.4.2` on top of current `main` and validated the branch with lint, unit, coverage, build, and CI-mode E2E runs. + +## [3.4.1] - 2026-03-31 + +> [!WARNING] +> **BREAKING CHANGE: request logging, retention, and logging environment variables have been redesigned.** +> On the first startup after upgrading, OmniRoute archives legacy request logs from `DATA_DIR/logs/`, legacy `DATA_DIR/call_logs/`, and `DATA_DIR/log.txt` into `DATA_DIR/log_archives/*.zip`, then removes the deprecated layout and switches to the new unified artifact format under `DATA_DIR/call_logs/`. + +### โœจ New Features + +- **.ENV Migration Utility:** Included `scripts/migrate-env.mjs` to seamlessly migrate ` Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` - ---- - -## Step 2 โ€” Install CLI Tools - -All npm-based tools require Node.js 18+: - -```bash -# Claude Code (Anthropic) -npm install -g @anthropic-ai/claude-code - -# OpenAI Codex -npm install -g @openai/codex - -# Gemini CLI (Google) -npm install -g @google/gemini-cli - -# OpenCode -npm install -g opencode-ai - -# Cline -npm install -g cline - -# KiloCode -npm install -g kilecode - -# Kiro CLI (Amazon โ€” requires curl + unzip) -apt-get install -y unzip # on Debian/Ubuntu -curl -fsSL https://cli.kiro.dev/install | bash -export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc -``` - -**Verify:** - -```bash -claude --version # 2.x.x -codex --version # 0.x.x -gemini --version # 0.x.x -opencode --version # x.x.x -cline --version # 2.x.x -kilocode --version # x.x.x (or: kilo --version) -kiro-cli --version # 1.x.x -``` - ---- - -## Step 3 โ€” Set Global Environment Variables - -Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`: - -```bash -# OmniRoute Universal Endpoint -export OPENAI_BASE_URL="http://localhost:20128/v1" -export OPENAI_API_KEY="sk-your-omniroute-key" -export ANTHROPIC_BASE_URL="http://localhost:20128/v1" -export ANTHROPIC_API_KEY="sk-your-omniroute-key" -export GEMINI_BASE_URL="http://localhost:20128/v1" -export GEMINI_API_KEY="sk-your-omniroute-key" -``` - -> For a **remote server** replace `localhost:20128` with the server IP or domain, -> e.g. `http://192.168.0.15:20128`. - ---- - -## Step 4 โ€” Configure Each Tool - -### Claude Code - -```bash -# Via CLI: -claude config set --global api-base-url http://localhost:20128/v1 - -# Or create ~/.claude/settings.json: -mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF -{ - "apiBaseUrl": "http://localhost:20128/v1", - "apiKey": "sk-your-omniroute-key" -} -EOF -``` - -**Test:** `claude "say hello"` - ---- - -### OpenAI Codex - -```bash -mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF -model: auto -apiKey: sk-your-omniroute-key -apiBaseUrl: http://localhost:20128/v1 -EOF -``` - -**Test:** `codex "what is 2+2?"` - ---- - -### Gemini CLI - -```bash -mkdir -p ~/.gemini && cat > ~/.gemini/settings.json << EOF -{ - "apiKey": "sk-your-omniroute-key", - "baseUrl": "http://localhost:20128/v1" -} -EOF -``` - -**Test:** `gemini "hello"` - ---- - -### OpenCode - -```bash -mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF -[provider.openai] -base_url = "http://localhost:20128/v1" -api_key = "sk-your-omniroute-key" -EOF -``` - -**Test:** `opencode` - ---- - -### Cline (CLI or VS Code) - -**CLI mode:** - -```bash -mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF -{ - "apiProvider": "openai", - "openAiBaseUrl": "http://localhost:20128/v1", - "openAiApiKey": "sk-your-omniroute-key" -} -EOF -``` - -**VS Code mode:** -Cline extension settings โ†’ API Provider: `OpenAI Compatible` โ†’ Base URL: `http://localhost:20128/v1` - -Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ Cline โ†’ Apply Config**. - ---- - -### KiloCode (CLI or VS Code) - -**CLI mode:** - -```bash -kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key -``` - -**VS Code settings:** - -```json -{ - "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", - "kilo-code.apiKey": "sk-your-omniroute-key" -} -``` - -Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ KiloCode โ†’ Apply Config**. - ---- - -### Continue (VS Code Extension) - -Edit `~/.continue/config.yaml`: - -```yaml -models: - - name: OmniRoute - provider: openai - model: auto - apiBase: http://localhost:20128/v1 - apiKey: sk-your-omniroute-key - default: true -``` - -Restart VS Code after editing. - ---- - -### Kiro CLI (Amazon) - -```bash -# Login to your AWS/Kiro account: -kiro-cli login - -# The CLI uses its own auth โ€” OmniRoute is not needed as backend for Kiro CLI itself. -# Use kiro-cli alongside OmniRoute for other tools. -kiro-cli status -``` - ---- - -### Cursor (Desktop App) - -> **Note:** Cursor routes requests through its cloud. For OmniRoute integration, -> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL. - -Via GUI: **Settings โ†’ Models โ†’ OpenAI API Key** - -- Base URL: `https://your-domain.com/v1` -- API Key: your OmniRoute key - ---- - -## Dashboard Auto-Configuration - -The OmniRoute dashboard automates configuration for most tools: - -1. Go to `http://localhost:20128/dashboard/cli-tools` -2. Expand any tool card -3. Select your API key from the dropdown -4. Click **Apply Config** (if tool is detected as installed) -5. Or copy the generated config snippet manually - ---- - -## Built-in Agents: Droid & OpenClaw - -**Droid** and **OpenClaw** are AI agents built directly into OmniRoute โ€” no installation needed. -They run as internal routes and use OmniRoute's model routing automatically. - -- Access: `http://localhost:20128/dashboard/agents` -- Configure: same combos and providers as all other tools -- No API key or CLI install required - ---- - -## Available API Endpoints - -| Endpoint | Description | Use For | -| -------------------------- | ----------------------------- | --------------------------- | -| `/v1/chat/completions` | Standard chat (all providers) | All modern tools | -| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows | -| `/v1/completions` | Legacy text completions | Older tools using `prompt:` | -| `/v1/embeddings` | Text embeddings | RAG, search | -| `/v1/images/generations` | Image generation | DALL-E, Flux, etc. | -| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS | -| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI | - ---- - -## Troubleshooting - -| Error | Cause | Fix | -| ------------------------- | ----------------------- | ------------------------------------------ | -| `Connection refused` | OmniRoute not running | `pm2 start omniroute` | -| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` | -| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` | -| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` | -| CLI shows "not installed" | Binary not in PATH | Check `which ` | -| `kiro-cli: not found` | Not in PATH | `export PATH="$HOME/.local/bin:$PATH"` | - ---- - -## Quick Setup Script (One Command) - -```bash -# Install all CLIs and configure for OmniRoute (replace with your key and server URL) -OMNIROUTE_URL="http://localhost:20128/v1" -OMNIROUTE_KEY="sk-your-omniroute-key" - -npm install -g @anthropic-ai/claude-code @openai/codex @google/gemini-cli opencode-ai cline kilecode - -# Kiro CLI -apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash - -# Write configs -mkdir -p ~/.claude ~/.codex ~/.gemini ~/.config/opencode ~/.continue - -cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" -cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" -cat > ~/.gemini/settings.json <<< "{\"apiKey\":\"$OMNIROUTE_KEY\",\"baseUrl\":\"$OMNIROUTE_URL\"}" -cat >> ~/.bashrc << EOF -export OPENAI_BASE_URL="$OMNIROUTE_URL" -export OPENAI_API_KEY="$OMNIROUTE_KEY" -export ANTHROPIC_BASE_URL="$OMNIROUTE_URL" -export ANTHROPIC_API_KEY="$OMNIROUTE_KEY" -EOF - -source ~/.bashrc -echo "โœ… All CLIs installed and configured for OmniRoute" -``` diff --git a/docs/i18n/es/CODEBASE_DOCUMENTATION.md b/docs/i18n/es/CODEBASE_DOCUMENTATION.md deleted file mode 100644 index e2d7950052..0000000000 --- a/docs/i18n/es/CODEBASE_DOCUMENTATION.md +++ /dev/null @@ -1,593 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CODEBASE_DOCUMENTATION.md) - ---- - -# omniroute โ€” Codebase Documentation - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) - -> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. - ---- - -## 1. 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
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, Qoder, 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 | -| Qoder | 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"] -``` diff --git a/docs/i18n/es/CONTRIBUTING.md b/docs/i18n/es/CONTRIBUTING.md new file mode 100644 index 0000000000..579e24e47a --- /dev/null +++ b/docs/i18n/es/CONTRIBUTING.md @@ -0,0 +1,299 @@ +# Contributing to OmniRoute (Espaรฑol) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CONTRIBUTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CONTRIBUTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CONTRIBUTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CONTRIBUTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CONTRIBUTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CONTRIBUTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CONTRIBUTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CONTRIBUTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CONTRIBUTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CONTRIBUTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CONTRIBUTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CONTRIBUTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CONTRIBUTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CONTRIBUTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CONTRIBUTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CONTRIBUTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CONTRIBUTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CONTRIBUTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CONTRIBUTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CONTRIBUTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CONTRIBUTING.md) + +--- + +Thank you for your interest in contributing! This guide covers everything you need to get started. + +--- + +## Development Setup + +### Prerequisites + +- **Node.js** >= 18 < 24 (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` | `20128` | Server port | +| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | Base URL for frontend | +| `JWT_SECRET` | (generate above) | JWT signing secret | +| `INITIAL_PASSWORD` | `CHANGEME` | First login password | +| `APP_LOG_LEVEL` | `info` | Log verbosity level | + +### Dashboard Settings + +The dashboard provides UI toggles for features that can also be configured via environment variables: + +| Setting Location | Toggle | Description | +| ------------------- | ------------------ | ------------------------------ | +| Settings โ†’ Advanced | Debug Mode | Enable debug request logs (UI) | +| Settings โ†’ General | Sidebar Visibility | Show/hide sidebar sections | + +These settings are stored in the database and persist across restarts, overriding env var defaults when set. + +### 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:20128/dashboard` +- **API**: `http://localhost:20128/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`, `mcp`, `a2a`, `memory`, `skills`. + +--- + +## Running Tests + +```bash +# All tests (unit + vitest + ecosystem + e2e) +npm run test:all + +# Single test file (Node.js native test runner โ€” most tests use this) +node --import tsx/esm --test tests/unit/your-file.test.mjs + +# Vitest (MCP server, autoCombo, cache) +npm run test:vitest + +# E2E tests (requires Playwright) +npm run test:e2e + +# Protocol clients E2E (MCP transports, A2A) +npm run test:protocols:e2e + +# Ecosystem compatibility tests +npm run test:ecosystem + +# Coverage (55% min statements/lines/functions; 60% branches) +npm run test:coverage +npm run coverage:report + +# Lint + format check +npm run lint +npm run check +``` + +Coverage notes: + +- `npm run test:coverage` measures source coverage for the main unit test suite, excludes `tests/**`, and includes `open-sse/**` +- `npm run coverage:report` prints the detailed file-by-file report from the latest coverage run +- `npm run test:coverage:legacy` preserves the older metric for historical comparison +- See `docs/COVERAGE_PLAN.md` for the phased coverage improvement roadmap + +Current test status: **122 unit test files** covering: + +- Provider translators and format conversion +- Rate limiting, circuit breaker, and resilience +- Semantic cache, idempotency, progress tracking +- Database operations and schema (21 DB modules) +- OAuth flows and authentication +- API endpoint validation (Zod v4) +- MCP server tools and scope enforcement +- Memory and Skills systems + +--- + +## Code Style + +- **ESLint** โ€” Run `npm run lint` before committing +- **Prettier** โ€” Auto-formatted via `lint-staged` on commit (2 spaces, semicolons, double quotes, 100 char width, es5 trailing commas) +- **TypeScript** โ€” All `src/` code uses `.ts`/`.tsx`; `open-sse/` uses `.ts`/`.js`; document with TSDoc (`@param`, `@returns`, `@throws`) +- **No `eval()`** โ€” ESLint enforces `no-eval`, `no-implied-eval`, `no-new-func` +- **Zod validation** โ€” Use Zod v4 schemas for all API input validation +- **Naming**: Files = camelCase/kebab-case, components = PascalCase, constants = UPPER_SNAKE + +--- + +## Project Structure + +``` +src/ # TypeScript (.ts / .tsx) +โ”œโ”€โ”€ app/ # Next.js 16 App Router +โ”‚ โ”œโ”€โ”€ (dashboard)/ # Dashboard pages (23 sections) +โ”‚ โ”œโ”€โ”€ api/ # API routes (51 directories) +โ”‚ โ””โ”€โ”€ login/ # Auth pages (.tsx) +โ”œโ”€โ”€ domain/ # Policy engine (policyEngine, comboResolver, costRules, etc.) +โ”œโ”€โ”€ lib/ # Core business logic (.ts) +โ”‚ โ”œโ”€โ”€ a2a/ # Agent-to-Agent v0.3 protocol server +โ”‚ โ”œโ”€โ”€ acp/ # Agent Communication Protocol registry +โ”‚ โ”œโ”€โ”€ compliance/ # Compliance policy engine +โ”‚ โ”œโ”€โ”€ db/ # SQLite database layer (21 modules + 16 migrations) +โ”‚ โ”œโ”€โ”€ memory/ # Persistent conversational memory +โ”‚ โ”œโ”€โ”€ oauth/ # OAuth providers, services, and utilities +โ”‚ โ”œโ”€โ”€ skills/ # Extensible skill framework +โ”‚ โ”œโ”€โ”€ usage/ # Usage tracking and cost calculation +โ”‚ โ””โ”€โ”€ localDb.ts # Re-export layer only โ€” never add logic here +โ”œโ”€โ”€ middleware/ # Request middleware (promptInjectionGuard) +โ”œโ”€โ”€ mitm/ # MITM proxy (cert, DNS, target routing) +โ”œโ”€โ”€ shared/ +โ”‚ โ”œโ”€โ”€ components/ # React components (.tsx) +โ”‚ โ”œโ”€โ”€ constants/ # Provider definitions (60+), MCP scopes, routing strategies +โ”‚ โ”œโ”€โ”€ utils/ # Circuit breaker, sanitizer, auth helpers +โ”‚ โ””โ”€โ”€ validation/ # Zod v4 schemas +โ””โ”€โ”€ sse/ # SSE proxy pipeline + +open-sse/ # @omniroute/open-sse workspace +โ”œโ”€โ”€ executors/ # 14 provider-specific request executors +โ”œโ”€โ”€ handlers/ # 11 request handlers (chat, responses, embeddings, images, etc.) +โ”œโ”€โ”€ mcp-server/ # MCP server (25 tools, 3 transports, 10 scopes) +โ”œโ”€โ”€ services/ # 36+ services (combo, autoCombo, rateLimitManager, etc.) +โ”œโ”€โ”€ translator/ # Format translators (OpenAI โ†” Claude โ†” Gemini โ†” Responses โ†” Ollama) +โ”œโ”€โ”€ transformer/ # Responses API transformer +โ””โ”€โ”€ utils/ # 22 utility modules (stream, TLS, proxy, logging) + +electron/ # Electron desktop app (cross-platform) + +tests/ +โ”œโ”€โ”€ unit/ # Node.js test runner (122 test files) +โ”œโ”€โ”€ integration/ # Integration tests +โ”œโ”€โ”€ e2e/ # Playwright tests +โ”œโ”€โ”€ security/ # Security tests +โ”œโ”€โ”€ translator/ # Translator-specific tests +โ””โ”€โ”€ load/ # Load tests + +docs/ # Documentation +โ”œโ”€โ”€ ARCHITECTURE.md # System architecture +โ”œโ”€โ”€ API_REFERENCE.md # All endpoints +โ”œโ”€โ”€ USER_GUIDE.md # Provider setup, CLI integration +โ”œโ”€โ”€ TROUBLESHOOTING.md # Common issues +โ”œโ”€โ”€ MCP-SERVER.md # MCP server (25 tools) +โ”œโ”€โ”€ A2A-SERVER.md # A2A agent protocol +โ”œโ”€โ”€ AUTO-COMBO.md # Auto-combo engine +โ”œโ”€โ”€ CLI-TOOLS.md # CLI tools integration +โ”œโ”€โ”€ COVERAGE_PLAN.md # Test coverage improvement plan +โ”œโ”€โ”€ openapi.yaml # OpenAPI specification +โ””โ”€โ”€ adr/ # Architecture Decision Records +``` + +--- + +## Adding a New Provider + +### Step 1: Register Provider Constants + +Add to `src/shared/constants/providers.ts` โ€” Zod-validated at module load. + +### Step 2: Add Executor (if custom logic needed) + +Create executor in `open-sse/executors/your-provider.ts` extending the base executor. + +### Step 3: Add Translator (if non-OpenAI format) + +Create request/response translators in `open-sse/translator/`. + +### Step 4: Add OAuth Config (if OAuth-based) + +Add OAuth credentials in `src/lib/oauth/constants/oauth.ts` and service in `src/lib/oauth/services/`. + +### Step 5: Register Models + +Add model definitions in `open-sse/config/providerRegistry.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 +- [ ] All inputs validated with Zod schemas +- [ ] CHANGELOG updated (if user-facing change) +- [ ] Documentation updated (if applicable) + +--- + +## Releasing + +Releases are managed via the `/generate-release` workflow. When a new GitHub Release is created, the package is **automatically published to npm** via GitHub Actions. + +--- + +## Getting Help + +- **Architecture**: See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) +- **API Reference**: See [`docs/API_REFERENCE.md`](docs/API_REFERENCE.md) +- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **ADRs**: See `docs/adr/` for architectural decision records diff --git a/docs/i18n/es/FEATURES.md b/docs/i18n/es/FEATURES.md deleted file mode 100644 index f648fe35d9..0000000000 --- a/docs/i18n/es/FEATURES.md +++ /dev/null @@ -1,147 +0,0 @@ -# OmniRoute โ€” Dashboard Features Gallery (Espaรฑol) - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) - -> ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../docs/FEATURES.md) - ---- - -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 (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. - -![Providers Dashboard](screenshots/01-providers.png) - ---- - -## ๐ŸŽจ Combos - -Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. - -![Combos Dashboard](screenshots/02-combos.png) - ---- - -## ๐Ÿ“Š Analytics - -Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. - -![Analytics Dashboard](screenshots/03-analytics.png) - ---- - -## ๐Ÿฅ System Health - -Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. - -![Health Dashboard](screenshots/04-health.png) - ---- - -## ๐Ÿ”ง Translator Playground - -Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). - -![Translator Playground](screenshots/05-translator.png) - ---- - -## ๐ŸŽฎ Model Playground _(v2.0.9+)_ - -Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. - ---- - -## ๐ŸŽจ Themes _(v2.0.5+)_ - -Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. - ---- - -## โš™๏ธ Settings - -Comprehensive settings panel with tabs: - -- **General** โ€” System storage, backup management (export/import database) -- **Appearance** โ€” Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls -- **Security** โ€” API endpoint protection, custom provider blocking, IP filtering, session info -- **Routing** โ€” Model aliases, background task degradation -- **Resilience** โ€” Rate limit persistence, circuit breaker tuning -- **Advanced** โ€” Configuration overrides - -![Settings Dashboard](screenshots/06-settings.png) - ---- - -## ๐Ÿ”ง CLI Tools - -One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. - -![CLI Tools Dashboard](screenshots/07-cli-tools.png) - ---- - -## ๐Ÿค– CLI Agents _(v2.0.11+)_ - -Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: - -- **Installation status** โ€” Installed / Not Found with version detection -- **Protocol badges** โ€” stdio, HTTP, etc. -- **Custom agents** โ€” Register any CLI tool via form (name, binary, version command, spawn args) -- **CLI Fingerprint Matching** โ€” Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP - ---- - -## ๐Ÿ–ผ๏ธ Media _(v2.0.3+)_ - -Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. - ---- - -## ๐Ÿ“ Request Logs - -Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. - -![Usage Logs](screenshots/08-usage.png) - ---- - -## ๐ŸŒ API Endpoint - -Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. - -![Endpoint Dashboard](screenshots/09-endpoint.png) - ---- - -## ๐Ÿ”‘ API Key Management - -Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. - ---- - -## ๐Ÿ“‹ Audit Log - -Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. - ---- - -## ๐Ÿ–ฅ๏ธ Desktop Application - -Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. - -Key features: - -- Server readiness polling (no blank screen on cold start) -- System tray with port management -- Content Security Policy -- Single-instance lock -- Auto-update on restart -- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) -- Hardened Electron build packaging โ€” symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+) - -๐Ÿ“– See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/es/MCP-SERVER.md b/docs/i18n/es/MCP-SERVER.md deleted file mode 100644 index 829acd30b1..0000000000 --- a/docs/i18n/es/MCP-SERVER.md +++ /dev/null @@ -1,87 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/MCP-SERVER.md) - ---- - -# OmniRoute MCP Server Documentation - -> Model Context Protocol server with 16 intelligent tools - -## Installation - -OmniRoute MCP is built-in. Start it with: - -```bash -omniroute --mcp -``` - -Or via the open-sse transport: - -```bash -# HTTP streamable transport (port 20130) -omniroute --dev # MCP auto-starts on /mcp endpoint -``` - -## IDE Configuration - -See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup. - ---- - -## Essential Tools (8) - -| Tool | Description | -| :------------------------------ | :--------------------------------------- | -| `omniroute_get_health` | Gateway health, circuit breakers, uptime | -| `omniroute_list_combos` | All configured combos with models | -| `omniroute_get_combo_metrics` | Performance metrics for a specific combo | -| `omniroute_switch_combo` | Switch active combo by ID/name | -| `omniroute_check_quota` | Quota status per provider or all | -| `omniroute_route_request` | Send a chat completion through OmniRoute | -| `omniroute_cost_report` | Cost analytics for a time period | -| `omniroute_list_models_catalog` | Full model catalog with capabilities | - -## Advanced Tools (8) - -| Tool | Description | -| :--------------------------------- | :---------------------------------------------- | -| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | -| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | -| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | -| `omniroute_test_combo` | Live-test all models in a combo | -| `omniroute_get_provider_metrics` | Detailed metrics for one provider | -| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | -| `omniroute_explain_route` | Explain a past routing decision | -| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | - -## Authentication - -MCP tools are authenticated via API key scopes. Each tool requires specific scopes: - -| Scope | Tools | -| :------------- | :----------------------------------------------- | -| `read:health` | get_health, get_provider_metrics | -| `read:combos` | list_combos, get_combo_metrics | -| `write:combos` | switch_combo | -| `read:quota` | check_quota | -| `write:route` | route_request, simulate_route, test_combo | -| `read:usage` | cost_report, get_session_snapshot, explain_route | -| `write:config` | set_budget_guard, set_resilience_profile | -| `read:models` | list_models_catalog, best_combo_for_task | - -## Audit Logging - -Every tool call is logged to `mcp_tool_audit` with: - -- Tool name, arguments, result -- Duration (ms), success/failure -- API key hash, timestamp - -## Files - -| File | Purpose | -| :------------------------------------------- | :------------------------------------------ | -| `open-sse/mcp-server/server.ts` | MCP server creation + 16 tool registrations | -| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport | -| `open-sse/mcp-server/auth.ts` | API key + scope validation | -| `open-sse/mcp-server/audit.ts` | Tool call audit logging | -| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers | diff --git a/docs/i18n/es/README.md b/docs/i18n/es/README.md index 353490ed9e..c58dcde5e1 100644 --- a/docs/i18n/es/README.md +++ b/docs/i18n/es/README.md @@ -1,12 +1,12 @@ # ๐Ÿš€ OmniRoute โ€” The Free AI Gateway (Espaรฑol) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/README.md) --- ### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback. -_Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._ +_Your universal API proxy โ€” one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._ **Chat Completions โ€ข Embeddings โ€ข Image Generation โ€ข Video โ€ข Music โ€ข Audio โ€ข Reranking โ€ข **Web Search** โ€ข MCP Server โ€ข A2A Protocol โ€ข 100% TypeScript** @@ -46,15 +46,17 @@ _Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now wi > - `APP_LOG_FILE_PATH` > - `APP_LOG_MAX_FILE_SIZE` > - `APP_LOG_RETENTION_DAYS` +> - `APP_LOG_MAX_FILES` > - `APP_LOG_LEVEL` > - `APP_LOG_FORMAT` > - `CALL_LOG_RETENTION_DAYS` +> - `CALL_LOG_MAX_ENTRIES` > > For release details and upgrade notes, see the [CHANGELOG](CHANGELOG.md). --- -## ๐Ÿ†• What's New in v3.0.0 +## ๐Ÿ†• What's New > **Upgrading from v2.9.5?** โ€” See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes. @@ -274,7 +276,7 @@ Developers pay $20โ€“200/month for Claude Pro, Codex Pro, or GitHub Copilot. Eve - **Smart 4-Tier Fallback** โ€” If subscription quota runs out, automatically redirects to API Key โ†’ Cheap โ†’ Free with zero manual intervention - **Real-Time Quota Tracking** โ€” Shows token consumption in real-time with reset countdown (5h, daily, weekly) - **Multi-Account Support** โ€” Multiple accounts per provider with auto round-robin โ€” when one runs out, switches to the next -- **Custom Combos** โ€” Customizable fallback chains with 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Custom Combos** โ€” Customizable fallback chains with 9 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random) - **Codex Business Quotas** โ€” Business/Team workspace quota monitoring directly in the dashboard @@ -286,7 +288,7 @@ OpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If **How OmniRoute solves it:** -- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 67+ providers +- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 60+ providers - **Format Translation** โ€” Automatic and transparent: OpenAI โ†” Claude โ†” Gemini โ†” Responses API - **Response Sanitization** โ€” Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+ - **Role Normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI providers; `system` โ†’ `user` for GLM/ERNIE @@ -372,7 +374,7 @@ Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code.. - **CLI Tools Dashboard** โ€” Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline - **GitHub Copilot Config Generator** โ€” Generates `chatLanguageModels.json` for VS Code with bulk model selection - **Onboarding Wizard** โ€” Guided 4-step setup for first-time users -- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 67+ providers +- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 60+ providers @@ -419,7 +421,7 @@ When a call fails, the dev doesn't know if it was a rate limit, expired token, w - **SQLite Proxy Logs** โ€” Persistent logs that survive server restarts - **Translator Playground** โ€” 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time) - **Request Telemetry** โ€” p50/p95/p99 latency + X-Request-Id tracing -- **File-Based Logging with Rotation** โ€” Console interceptor captures everything to JSON log with size-based rotation +- **File-Based Logging with Rotation** โ€” App logs rotate by size, retention days, and archive count; call log artifacts rotate by retention days and file count - **System Info Report** โ€” `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage. @@ -514,7 +516,7 @@ Developers who want all responses in a specific language, with a specific tone, - **System Prompt Injection** โ€” Global prompt applied to all requests - **Thinking Budget Validation** โ€” Reasoning token allocation control per request (passthrough, auto, custom, adaptive) -- **6 Routing Strategies** โ€” Global strategies that determine how requests are distributed +- **9 Routing Strategies** โ€” Global strategies that determine how requests are distributed - **Wildcard Router** โ€” `provider/*` patterns route dynamically to any provider - **Combo Enable/Disable Toggle** โ€” Toggle combos directly from the dashboard - **Provider Toggle** โ€” Enable/disable all connections for a provider with one click @@ -581,7 +583,7 @@ Different clients should have least-privilege access to tool categories. **How OmniRoute solves it:** -- 9 granular MCP scopes for controlled tool access +- 10 granular MCP scopes for controlled tool access - Scope enforcement and visibility in MCP management UI - Safe default posture for operational tooling @@ -1325,19 +1327,19 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. ### ๐Ÿค– Agent & Protocol Operations (v2.0) -| Feature | What It Does | -| ------------------------------------- | -------------------------------------------------------------------------------------------------- | -| ๐Ÿ”ง **MCP Server (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) | -| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | -| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | -| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | -| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | -| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | -| ๐Ÿ” **MCP Scope Enforcement** | 9 granular scope permissions for controlled tool access | -| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | -| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | -| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | -| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | +| Feature | What It Does | +| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| ๐Ÿ”ง **MCP Server (25 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools | +| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | +| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | +| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | +| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | +| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | +| ๐Ÿ” **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access | +| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | +| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | +| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | +| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | ### ๐Ÿง  Routing & Intelligence @@ -1348,7 +1350,7 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. | ๐Ÿ”„ **Format Translation** | OpenAI โ†” Claude โ†” Gemini โ†” Responses with schema-safe conversions | | ๐Ÿ‘ฅ **Multi-Account Support** | Multiple accounts per provider with intelligent selection | | ๐Ÿ”„ **Auto Token Refresh** | OAuth tokens refresh automatically with retry | -| ๐ŸŽจ **Custom Combos** | 6 balancing strategies + fallback chain control | +| ๐ŸŽจ **Custom Combos** | 9 balancing strategies + fallback chain control | | ๐ŸŒ **Wildcard Router** | `provider/*` dynamic routing | | ๐Ÿง  **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits | | ๐Ÿ”€ **Model Aliases** | Built-in + custom model aliasing and migration safety | @@ -1949,6 +1951,7 @@ opencode - Request artifacts are written to `DATA_DIR/call_logs/` as one JSON file per request - Enable pipeline capture from Dashboard โ†’ Logs โ†’ Request Logs if you need detailed per-stage payloads - Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log` +- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed **Connection test shows "Invalid" for OpenAI-compatible providers** diff --git a/docs/i18n/es/RELEASE_CHECKLIST.md b/docs/i18n/es/RELEASE_CHECKLIST.md deleted file mode 100644 index 903e812c3f..0000000000 --- a/docs/i18n/es/RELEASE_CHECKLIST.md +++ /dev/null @@ -1,37 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/RELEASE_CHECKLIST.md) - ---- - -# Release Checklist - -Use this checklist before tagging or publishing a new OmniRoute release. - -## Version and Changelog - -1. Bump `package.json` version (`x.y.z`) in the release branch. -2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: - - `## [x.y.z] โ€” YYYY-MM-DD` -3. Keep `## [Unreleased]` as the first changelog section for upcoming work. -4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. - -## API Docs - -1. Update `docs/openapi.yaml`: - - `info.version` must equal `package.json` version. -2. Validate endpoint examples if API contracts changed. - -## Runtime Docs - -1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. -2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. -3. Update localized docs if source docs changed significantly. - -## Automated Check - -Run the sync guard locally before opening PR: - -```bash -npm run check:docs-sync -``` - -CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/es/SECURITY.md b/docs/i18n/es/SECURITY.md new file mode 100644 index 0000000000..6e78dbc9b5 --- /dev/null +++ b/docs/i18n/es/SECURITY.md @@ -0,0 +1,179 @@ +# Security Policy (Espaรฑol) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../SECURITY.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/SECURITY.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/SECURITY.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/SECURITY.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/SECURITY.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/SECURITY.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/SECURITY.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/SECURITY.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/SECURITY.md) + +--- + +## 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 | +| ------- | -------------- | +| 3.4.x | โœ… Active | +| 3.0.x | โœ… Security | +| < 3.0.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 | +| **MCP Scopes** | 10 granular scopes for MCP tool access control | + +### ๐Ÿ›ก๏ธ 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:::` +- 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** | Allowlist/blocklist IP ranges in dashboard | +| **Rate Limiting** | Per-provider rate limits with automatic backoff | +| **Anti-Thundering Herd** | Mutex + per-connection locking prevents cascading 502s | +| **TLS Fingerprint** | Browser-like TLS fingerprint spoofing to reduce bot detection | +| **CLI Fingerprint** | Per-provider header/body ordering to match native CLI signatures | + +### ๐Ÿ”Œ Resilience & Availability + +| 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 `CALL_LOG_RETENTION_DAYS` | +| **No-Log Opt-out** | Per API key `noLog` flag disables request logging | +| **Audit Log** | Administrative actions tracked in `audit_log` table | +| **MCP Audit** | SQLite-backed audit logging for all MCP tool calls | +| **Zod Validation** | All API inputs validated with Zod v4 schemas at module load | + +--- + +## 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 +- Provider constants validated at module load via Zod (`src/shared/validation/providerSchema.ts`) diff --git a/docs/i18n/es/TROUBLESHOOTING.md b/docs/i18n/es/TROUBLESHOOTING.md deleted file mode 100644 index 63c148000a..0000000000 --- a/docs/i18n/es/TROUBLESHOOTING.md +++ /dev/null @@ -1,258 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/TROUBLESHOOTING.md) - ---- - -# Troubleshooting - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/TROUBLESHOOTING.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/TROUBLESHOOTING.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/TROUBLESHOOTING.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/TROUBLESHOOTING.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/TROUBLESHOOTING.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/TROUBLESHOOTING.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/TROUBLESHOOTING.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/TROUBLESHOOTING.md) - -Common problems and solutions for OmniRoute. - ---- - -## Quick Fixes - -| Problem | Solution | -| ----------------------------- | ------------------------------------------------------------------ | -| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | -| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | -| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | -| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | -| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | - ---- - -## Provider Issues - -### "Language model did not provide messages" - -**Cause:** Provider quota exhausted. - -**Fix:** - -1. 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, Qoder) 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}/storage.sqlite` (providers, combos, aliases, keys, settings) -- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` -- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) - ---- - -## Circuit Breaker Issues - -### Provider stuck in OPEN state - -When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. - -**Fix:** - -1. 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 -- **SDK returns raw string instead of object** โ€” Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures -- **GLM/ERNIE rejects `system` role** โ€” Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models -- **`developer` role not recognized** โ€” Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers -- **`json_schema` not working with Gemini** โ€” Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` - ---- - -## Resilience Settings - -### Auto rate-limit not triggering - -- 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. - ---- - -## Optional RAG / LLM failure taxonomy (16 problems) - -Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. - -In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. - -If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: - -- retrieval drift and broken context boundaries -- empty or stale indexes and vector stores -- embedding versus semantic mismatch -- prompt assembly and context window issues -- logic collapse and overconfident answers -- long chain and agent coordination failures -- multi agent memory and role drift -- deployment and bootstrap ordering problems - -The idea is simple: - -1. When you investigate a bad response, capture: - - user task and request - - route or provider combo in OmniRoute - - any RAG context used downstream (retrieved documents, tool calls, etc) -2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` โ€ฆ `No.16`). -3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. -4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. - -Full text and concrete recipes live here (MIT license, text only): - -[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) - -You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. - ---- - -## Still Stuck? - -- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details -- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints -- **Health Dashboard**: Check **Dashboard โ†’ Health** for real-time system status -- **Translator**: Use **Dashboard โ†’ Translator** to debug format issues diff --git a/docs/i18n/es/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/es/VM_DEPLOYMENT_GUIDE.md deleted file mode 100644 index aef093802e..0000000000 --- a/docs/i18n/es/VM_DEPLOYMENT_GUIDE.md +++ /dev/null @@ -1,401 +0,0 @@ -# OmniRoute: Guรญa de implementaciรณn en VM con Cloudflare - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](../pt-BR/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](../es/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](../fr/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](../it/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](../ru/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](../zh-CN/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](../de/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](../in/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](../th/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](../uk-UA/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](../ar/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](../ja/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](../vi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](../bg/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](../da/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](../fi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](../he/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](../hu/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](../id/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](../ko/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](../ms/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](../nl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](../no/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](../pt/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](../ro/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](../pl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](../sk/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](../sv/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](../phi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](../cs/VM_DEPLOYMENT_GUIDE.md) - -Guรญa completa para instalar y configurar OmniRoute en una VM (VPS) con dominio administrado vรญa Cloudflare. - ---- - -## Requisitos previos - -| Artรญculo | Mรญnimo | Recomendado | -| -------------- | ------------------------ | --------------------- | -| **procesador** | 1 CPU virtual | 2 CPU virtuales | -| **RAM** | 1 GB | 2 GB | -| **Disco** | SSD de 10 GB | SSD de 25 GB | -| **SO** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS | -| **Dominio** | Registrado en Cloudflare | โ€” | -| **Acoplador** | Motor Docker 24+ | Ventana acoplable 27+ | - -**Proveedores probados**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. - ---- - -## 1. Configurar la mรกquina virtual - -### 1.1 Crear la instancia - -En su proveedor VPS preferido: - -- Elija Ubuntu 24.04 LTS -- Seleccione el plan mรญnimo (1 vCPU / 1 GB de RAM) -- Establezca una contraseรฑa de root segura o configure la clave SSH -- Tenga en cuenta la **IP pรบblica** (por ejemplo, `203.0.113.10`) - -### 1.2 Conectarse vรญa SSH - -```bash -ssh root@203.0.113.10 -``` - -### 1.3 Actualizar el sistema - -```bash -apt update && apt upgrade -y -``` - -### 1.4 Instalar Docker - -```bash -# Install dependencies -apt install -y ca-certificates curl gnupg - -# Add official Docker repository -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 el cortafuegos (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 -``` - -> **Consejo**: Para mรกxima seguridad, restrinja los puertos 80 y 443 solo a las IP de Cloudflare. Consulte la secciรณn [Advanced Security](#advanced-security). - ---- - -## 2. Instalar OmniRoute - -### 2.1 Crear directorio de configuraciรณn - -```bash -mkdir -p /opt/omniroute -``` - -### 2.2 Crear archivo de variables de entorno - -```bash -cat > /opt/omniroute/.env << โ€˜EOFโ€™ -# === Security === -JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY -INITIAL_PASSWORD=YourSecurePassword123! -API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY -STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY -STORAGE_ENCRYPTION_KEY_VERSION=v1 -MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT - -# === 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 (change to your domain) === -BASE_URL=https://llms.seudominio.com -NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com - -# === Cloud Sync (optional) === -# CLOUD_URL=https://cloud.omniroute.online -# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online -EOF -``` - -> โš ๏ธ **IMPORTANTE**: ยกGenera claves secretas รบnicas! Utilice `openssl rand -hex 32` para cada clave. - -### 2.3 Iniciar el contenedor - -```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 que estรฉ funcionando - -```bash -docker ps | grep omniroute -docker logs omniroute --tail 20 -``` - -Deberรญa mostrar: `[DB] SQLite database ready` y `listening on port 20128`. - ---- - -## 3. Configurar nginx (Proxy inverso) - -### 3.1 Generar certificado SSL (Origen Cloudflare) - -En el panel de Cloudflare: - -1. Vaya a **SSL/TLS โ†’ Servidor de origen** -2. Haga clic en **Crear certificado** -3. Mantenga los valores predeterminados (15 aรฑos, \*.sudominio.com) -4. Copie el **Certificado de Origen** y la **Clave Privada** - -```bash -mkdir -p /etc/nginx/ssl - -# Paste the certificate -nano /etc/nginx/ssl/origin.crt - -# Paste the private key -nano /etc/nginx/ssl/origin.key - -chmod 600 /etc/nginx/ssl/origin.key -``` - -### 3.2 Configuraciรณn de Nginx - -```bash -cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ -# Default server โ€” blocks direct access via 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.yourdomain.com; # Change to your domain - - 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.yourdomain.com; - return 301 https://$server_name$request_uri; -} -NGINX -``` - -### 3.3 Habilitar y probar - -```bash -# Remove default configuration -rm -f /etc/nginx/sites-enabled/default - -# Enable OmniRoute -ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute - -# Test and reload -nginx -t && systemctl reload nginx -``` - ---- - -## 4. Configurar DNS de Cloudflare - -### 4.1 Agregar registro DNS - -En el panel de Cloudflare โ†’ DNS: - -| Tipo | Nombre | Contenido | Apoderado | -| ---- | ------ | ----------------------------------------- | ------------ | -| Un | `llms` | `203.0.113.10` (IP de la mรกquina virtual) | โœ… Apoderado | - -### 4.2 Configurar SSL - -En **SSL/TLS โ†’ Descripciรณn general**: - -- Modo: **Completo (Estricto)** - -En **SSL/TLS โ†’ Certificados perimetrales**: - -- Utilice siempre HTTPS: โœ… Activado -- Versiรณn mรญnima de TLS: TLS 1.2 -- Reescrituras HTTPS automรกticas: โœ… Activado - -### 4.3 Pruebas - -```bash -curl -sI https://llms.seudominio.com/health -# Should return HTTP/2 200 -``` - ---- - -## 5. Operaciones y Mantenimiento - -### Actualizar a una nueva versiรณn - -```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 registros - -```bash -docker logs -f omniroute # Real-time stream -docker logs omniroute --tail 50 # Last 50 lines -``` - -### Copia de seguridad manual de la base de datos - -```bash -# Copy data from the volume to the host -docker cp omniroute:/app/data ./backup-$(date +%F) - -# Or compress the entire volume -docker run --rm -v omniroute-data:/data -v $(pwd):/backup \ - alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data -``` - -### Restaurar desde copia de seguridad - -```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. Seguridad avanzada - -### Restringir nginx a las IP de Cloudflare - -```bash -cat > /etc/nginx/cloudflare-ips.conf << โ€˜CFโ€™ -# Cloudflare IPv4 ranges โ€” update periodically -# 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 -``` - -Agregue lo siguiente a `nginx.conf` dentro del bloque `http {}`: - -```nginx -include /etc/nginx/cloudflare-ips.conf; -``` - -### Instalar fail2ban - -```bash -apt install -y fail2ban -systemctl enable fail2ban -systemctl start fail2ban - -# Check status -fail2ban-client status sshd -``` - -### Bloquear el acceso directo al puerto Docker - -```bash -# Prevent direct external access to port 20128 -iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP -iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT - -# Persist the rules -apt install -y iptables-persistent -netfilter-persistent save -``` - ---- - -## 7. Implementaciรณn para trabajadores de Cloudflare (opcional) - -Para acceso remoto a travรฉs de Cloudflare Workers (sin exponer la VM directamente): - -```bash -# In the local repository -cd omnirouteCloud -npm install -npx wrangler login -npx wrangler deploy -``` - -Consulte la documentaciรณn completa en [omnirouteCloud/README.md](../omnirouteCloud/README.md). - ---- - -## Resumen de puerto - -| Puerto | Servicio | Acceso | -| ------ | ----------- | ---------------------------------- | -| 22 | SSH | Pรบblico (con fail2ban) | -| 80 | nginxHTTP | Redirigir โ†’ HTTPS | -| 443 | nginx HTTPS | A travรฉs del proxy de Cloudflare | -| 20128 | OmniRuta | Solo localhost (a travรฉs de nginx) | diff --git a/docs/i18n/es/docs/A2A-SERVER.md b/docs/i18n/es/docs/A2A-SERVER.md new file mode 100644 index 0000000000..f3dd07d543 --- /dev/null +++ b/docs/i18n/es/docs/A2A-SERVER.md @@ -0,0 +1,200 @@ +# OmniRoute A2A Server Documentation (Espaรฑol) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/A2A-SERVER.md) + +--- + +> Agent-to-Agent Protocol v0.3 โ€” OmniRoute as an intelligent routing agent + +## Agent Discovery + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements. + +--- + +## Authentication + +All `/a2a` requests require an API key via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server, authentication is bypassed. + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Sends a message to a skill and waits for the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a hello world in Python"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "uuid", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "..." }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}} + +: heartbeat 2026-03-03T17:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Available Skills + +| Skill | Description | +| :----------------- | :------------------------------------------------------------------------------------------------------------------------------ | +| `smart-routing` | Routes prompts through OmniRoute's intelligent pipeline. Returns response with routing explanation, cost, and resilience trace. | +| `quota-management` | Answers natural-language queries about provider quotas, suggests free combos, and provides quota rankings. | + +--- + +## Task Lifecycle + +``` +submitted โ†’ working โ†’ completed + โ†’ failed + โ†’ cancelled +``` + +- Tasks expire after 5 minutes (configurable) +- Terminal states: `completed`, `failed`, `cancelled` +- Event log tracks every state transition + +--- + +## Error Codes + +| Code | Meaning | +| :----- | :----------------------------- | +| -32700 | Parse error (invalid JSON) | +| -32600 | Invalid request / Unauthorized | +| -32601 | Method or skill not found | +| -32602 | Invalid params | +| -32603 | Internal error | + +--- + +## Integration Examples + +### Python (requests) + +```python +import requests + +resp = requests.post("http://localhost:20128/a2a", json={ + "jsonrpc": "2.0", "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Hello"}] + } +}, headers={"Authorization": "Bearer YOUR_KEY"}) + +result = resp.json()["result"] +print(result["artifacts"][0]["content"]) +print(result["metadata"]["routing_explanation"]) +``` + +### TypeScript (fetch) + +```typescript +const resp = await fetch("http://localhost:20128/a2a", { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: "Bearer YOUR_KEY", + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "1", + method: "message/send", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Hello" }], + }, + }), +}); +const { result } = await resp.json(); +console.log(result.metadata.routing_explanation); +``` diff --git a/docs/i18n/es/docs/API_REFERENCE.md b/docs/i18n/es/docs/API_REFERENCE.md new file mode 100644 index 0000000000..7e10627f3e --- /dev/null +++ b/docs/i18n/es/docs/API_REFERENCE.md @@ -0,0 +1,465 @@ +# API Reference (Espaรฑol) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/API_REFERENCE.md) + +--- + +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 | +| `X-Session-Id` | Request | Sticky session key for external session affinity | +| `x_session_id` | Request | Underscore variant also accepted (direct HTTP) | +| `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 | +| `X-OmniRoute-Session-Id` | Response | Effective session ID used by OmniRoute | + +> Nginx note: if you rely on underscore headers (for example `x_session_id`), enable `underscores_in_headers 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/stats + +# Clear all caches +DELETE /api/cache/stats +``` + +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/PATCH | 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 + provider summary (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`) | +| `/api/cache/stats` | 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 | + +### Tunnels + +| Endpoint | Method | Description | +| -------------------------- | ------ | ----------------------------------------------------------------------- | +| `/api/tunnels/cloudflared` | GET | Read Cloudflare Quick Tunnel install/runtime status for the dashboard | +| `/api/tunnels/cloudflared` | POST | Enable or disable the Cloudflare Quick Tunnel (`action=enable/disable`) | + +### 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`. + +### ACP Agents + +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | + +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). + +### Resilience & Rate Limits + +| Endpoint | Method | Description | +| ----------------------- | --------- | ------------------------------- | +| `/api/resilience` | GET/PATCH | 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` diff --git a/docs/i18n/es/docs/ARCHITECTURE.md b/docs/i18n/es/docs/ARCHITECTURE.md new file mode 100644 index 0000000000..ff05a4f0ef --- /dev/null +++ b/docs/i18n/es/docs/ARCHITECTURE.md @@ -0,0 +1,814 @@ +# OmniRoute Architecture (Espaรฑol) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/ARCHITECTURE.md) + +--- + +_Last updated: 2026-03-28_ + +## 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 (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developerโ†’system, systemโ†’user) for cross-provider compatibility +- Structured output conversion (json_schema โ†’ Gemini responseSchema) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) +- Global system prompt injection +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout โ†’ budget โ†’ fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) + +Primary runtime model: + +- Next.js 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.) + +## Dashboard Surface (Current) + +Main pages under `src/app/(dashboard)/dashboard/`: + +- `/dashboard` โ€” quick start + provider overview +- `/dashboard/endpoint` โ€” endpoint proxy + MCP + A2A + API endpoint tabs +- `/dashboard/providers` โ€” provider connections and credentials +- `/dashboard/combos` โ€” combo strategies, templates, model routing rules +- `/dashboard/costs` โ€” cost aggregation and pricing visibility +- `/dashboard/analytics` โ€” usage analytics and evaluations +- `/dashboard/limits` โ€” quota/rate controls +- `/dashboard/cli-tools` โ€” CLI onboarding, runtime detection, config generation +- `/dashboard/agents` โ€” detected ACP agents + custom agent registration +- `/dashboard/media` โ€” image/video/music playground +- `/dashboard/search-tools` โ€” search provider testing and history +- `/dashboard/health` โ€” uptime, circuit breakers, rate limits +- `/dashboard/logs` โ€” request/proxy/audit/console logs +- `/dashboard/settings` โ€” system settings tabs (general, routing, combo defaults, etc.) +- `/dashboard/api-manager` โ€” API key lifecycle and model permissions + +## 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[(storage.sqlite)] + UDB[(usage tables + log artifacts)] + end + + subgraph Upstreams[Upstream Providers] + P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/Qoder/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/route.ts` (GET) +- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- OAuth: `src/app/api/oauth/*` +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` +- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI tooling helpers: `src/app/api/cli-tools/*` +- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) +- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) โ€” provider profiles, circuit breaker, rate limit state +- Resilience reset: `src/app/api/resilience/reset` (POST) โ€” reset breakers + cooldowns +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) +- Telemetry: `src/app/api/telemetry/summary` (GET) +- Budget: `src/app/api/usage/budget` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Policies: `src/app/api/policies` (GET/POST) + +## 2) SSE + 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` +- Response sanitization: `open-sse/handlers/responseSanitizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.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`, `qoder.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 (SQLite): + +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** + +Usage persistence: + +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present + +Domain State DB (SQLite): + +- `src/lib/db/domainState.ts` โ€” CRUD operations 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`, `src/shared/services/modelSyncScheduler.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Periodic task: `src/shared/services/modelSyncScheduler.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. Combo routing adds one extra guard: provider-scoped 400s such as upstream content-block and role-validation failures are treated as model-local failures so later combo targets can still run. + +## 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: + +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` + +## Deployment Topology + +```mermaid +flowchart LR + 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[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] + end + + subgraph External[External Services] + Providers[AI Providers] + SyncCloud[Cloud Sync Service] + end + + CLI --> Next + Browser --> Next + Next --> Core + Next --> MainDB + Core --> MainDB + Core --> UsageDB + Core --> Providers + Next --> SyncCloud +``` + +## Module Mapping (Decision-Critical) + +### Route and API Modules + +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle +- `src/app/api/models/alias`: alias management +- `src/app/api/combos*`: fallback combo management +- `src/app/api/pricing`: pricing overrides for cost calculation +- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers +- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) +- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) +- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) +- `src/app/api/sessions`: active session listing (GET) +- `src/app/api/rate-limits`: per-account rate limit status (GET) + +### Routing and Execution Core + +- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior + +### Translation Registry and Format Converters + +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` +- Format constants: `open-sse/translator/formats.ts` + +### Persistence + +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables + +## Provider Executor Coverage (Strategy Pattern) + +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. + +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, Qoder, 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 | +| Qoder | openai | OAuth (Basic) | โœ… | โœ… | โœ… | โš ๏ธ Per request | +| OpenRouter | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| GLM/Kimi/MiniMax | claude | API Key | โœ… | โœ… | โŒ | โŒ | +| DeepSeek | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Groq | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| xAI (Grok) | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Mistral | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Perplexity | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Together AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Fireworks AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Cerebras | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Cohere | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| NVIDIA NIM | openai | API Key | โœ… | โœ… | โŒ | โŒ | + +## Format Translation Coverage + +Detected source formats include: + +- `openai` +- `openai-responses` +- `claude` +- `gemini` + +Target formats include: + +- OpenAI chat/Responses +- Claude +- Gemini/Gemini-CLI/Antigravity envelope +- Kiro +- Cursor + +Translations use **OpenAI as the hub format** โ€” all conversions go through OpenAI as intermediate: + +``` +Source Format โ†’ OpenAI (hub) โ†’ Target Format +``` + +Translations are selected dynamically based on source payload shape and provider target format. + +Additional processing layers in the translation pipeline: + +- **Response sanitization** โ€” Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI targets; merges `system` โ†’ `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** โ€” Parses `...` blocks from content into `reasoning_content` field +- **Structured output** โ€” Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` + +## Supported API Endpoints + +| 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` | Provider Models | Provider model metadata backing custom and managed available models | + +## 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 `/logs//` 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 + +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON โ†’ SQLite migration compatibility path + +## Observability and Operational Signals + +Runtime visibility sources: + +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- four-stage detailed payload captures in SQLite (`request_detail_logs`) when `settings.detailed_logs_enabled=true` +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption + +Detailed request payload capture stores up to four JSON payload stages per routed call: + +- raw request received from the client +- translated request actually sent upstream +- provider response reconstructed as JSON; streamed responses are compacted to the final summary plus stream metadata +- final client response returned by OmniRoute; streamed responses are stored in the same compact summary form + +## Security-Sensitive Boundaries + +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics + +## Environment and Runtime Matrix + +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` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). + +## Operational Verification Checklist + +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: +- `GET /api/settings` +- `GET /api/v1/models` +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/es/docs/AUTO-COMBO.md b/docs/i18n/es/docs/AUTO-COMBO.md new file mode 100644 index 0000000000..24ba8b36ad --- /dev/null +++ b/docs/i18n/es/docs/AUTO-COMBO.md @@ -0,0 +1,67 @@ +# OmniRoute Auto-Combo Engine (Espaรฑol) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/AUTO-COMBO.md) + +--- + +> Self-managing model chains with adaptive scoring + +## How It Works + +The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**: + +| Factor | Weight | Description | +| :--------- | :----- | :---------------------------------------------- | +| Quota | 0.20 | Remaining capacity [0..1] | +| Health | 0.25 | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 | +| CostInv | 0.20 | Inverse cost (cheaper = higher score) | +| LatencyInv | 0.15 | Inverse p95 latency (faster = higher) | +| TaskFit | 0.10 | Model ร— task type fitness score | +| Stability | 0.10 | Low variance in latency/errors | + +## Mode Packs + +| Pack | Focus | Key Weight | +| :---------------------- | :----------- | :--------------- | +| ๐Ÿš€ **Ship Fast** | Speed | latencyInv: 0.35 | +| ๐Ÿ’ฐ **Cost Saver** | Economy | costInv: 0.40 | +| ๐ŸŽฏ **Quality First** | Best model | taskFit: 0.40 | +| ๐Ÿ“ก **Offline Friendly** | Availability | quota: 0.40 | + +## Self-Healing + +- **Temporary exclusion**: Score < 0.2 โ†’ excluded for 5 min (progressive backoff, max 30 min) +- **Circuit breaker awareness**: OPEN โ†’ auto-excluded; HALF_OPEN โ†’ probe requests +- **Incident mode**: >50% OPEN โ†’ disable exploration, maximize stability +- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout + +## Bandit Exploration + +5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode. + +## API + +```bash +# Create auto-combo +curl -X POST http://localhost:20128/api/combos/auto \ + -H "Content-Type: application/json" \ + -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}' + +# List auto-combos +curl http://localhost:20128/api/combos/auto +``` + +## Task Fitness + +30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` โ†’ high coding score). + +## Files + +| File | Purpose | +| :------------------------------------------- | :------------------------------------ | +| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization | +| `open-sse/services/autoCombo/taskFitness.ts` | Model ร— task fitness lookup | +| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap | +| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode | +| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles | +| `src/app/api/combos/auto/route.ts` | REST API | diff --git a/docs/i18n/es/docs/CLI-TOOLS.md b/docs/i18n/es/docs/CLI-TOOLS.md new file mode 100644 index 0000000000..885a3a6614 --- /dev/null +++ b/docs/i18n/es/docs/CLI-TOOLS.md @@ -0,0 +1,348 @@ +# CLI Tools Setup Guide โ€” OmniRoute (Espaรฑol) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CLI-TOOLS.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CLI-TOOLS.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CLI-TOOLS.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CLI-TOOLS.md) + +--- + +This guide explains how to install and configure all supported AI coding CLI tools +to use **OmniRoute** as the unified backend, giving you centralized key management, +cost tracking, model switching, and request logging across every tool. + +--- + +## How It Works + +``` +Claude / Codex / OpenCode / Cline / KiloCode / Continue / Kiro / Cursor / Copilot + โ”‚ + โ–ผ (all point to OmniRoute) + http://YOUR_SERVER:20128/v1 + โ”‚ + โ–ผ (OmniRoute routes to the right provider) + Anthropic / OpenAI / Gemini / DeepSeek / Groq / Mistral / ... +``` + +**Benefits:** + +- One API key to manage all tools +- Cost tracking across all CLIs in the dashboard +- Model switching without reconfiguring every tool +- Works locally and on remote servers (VPS) + +--- + +## Supported Tools (Dashboard Source of Truth) + +The dashboard cards in `/dashboard/cli-tools` are generated from `src/shared/constants/cliTools.ts`. +Current list (v3.0.0-rc.16): + +| Tool | ID | Command | Setup Mode | Install Method | +| ------------------ | ------------- | ---------- | ---------- | -------------- | +| **Claude Code** | `claude` | `claude` | env | npm | +| **OpenAI Codex** | `codex` | `codex` | custom | npm | +| **Factory Droid** | `droid` | `droid` | custom | bundled/CLI | +| **OpenClaw** | `openclaw` | `openclaw` | custom | bundled/CLI | +| **Cursor** | `cursor` | app | guide | desktop app | +| **Cline** | `cline` | `cline` | custom | npm | +| **Kilo Code** | `kilo` | `kilocode` | custom | npm | +| **Continue** | `continue` | extension | guide | VS Code | +| **Antigravity** | `antigravity` | internal | mitm | OmniRoute | +| **GitHub Copilot** | `copilot` | extension | custom | VS Code | +| **OpenCode** | `opencode` | `opencode` | guide | npm | +| **Kiro AI** | `kiro` | app/cli | mitm | desktop/CLI | + +### CLI fingerprint sync (Agents + Settings) + +`/dashboard/agents` and `Settings > CLI Fingerprint` use `src/shared/constants/cliCompatProviders.ts`. +This keeps provider IDs aligned with CLI cards and legacy IDs. + +| CLI ID | Fingerprint Provider ID | +| ---------------------------------------------------------------------------------------------------- | ----------------------- | +| `kilo` | `kilocode` | +| `copilot` | `github` | +| `claude` / `codex` / `antigravity` / `kiro` / `cursor` / `cline` / `opencode` / `droid` / `openclaw` | same ID | + +Legacy IDs still accepted for compatibility: `copilot`, `kimi-coding`, `qwen`. + +--- + +## Step 1 โ€” Get an OmniRoute API Key + +1. Open the OmniRoute dashboard โ†’ **API Manager** (`/dashboard/api-manager`) +2. Click **Create API Key** +3. Give it a name (e.g. `cli-tools`) and select all permissions +4. Copy the key โ€” you'll need it for every CLI below + +> Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` + +--- + +## Step 2 โ€” Install CLI Tools + +All npm-based tools require Node.js 18+: + +```bash +# Claude Code (Anthropic) +npm install -g @anthropic-ai/claude-code + +# OpenAI Codex +npm install -g @openai/codex + +# OpenCode +npm install -g opencode-ai + +# Cline +npm install -g cline + +# KiloCode +npm install -g kilocode + +# Kiro CLI (Amazon โ€” requires curl + unzip) +apt-get install -y unzip # on Debian/Ubuntu +curl -fsSL https://cli.kiro.dev/install | bash +export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc +``` + +**Verify:** + +```bash +claude --version # 2.x.x +codex --version # 0.x.x +opencode --version # x.x.x +cline --version # 2.x.x +kilocode --version # x.x.x (or: kilo --version) +kiro-cli --version # 1.x.x +``` + +--- + +## Step 3 โ€” Set Global Environment Variables + +Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`: + +```bash +# OmniRoute Universal Endpoint +export OPENAI_BASE_URL="http://localhost:20128/v1" +export OPENAI_API_KEY="sk-your-omniroute-key" +export ANTHROPIC_BASE_URL="http://localhost:20128/v1" +export ANTHROPIC_API_KEY="sk-your-omniroute-key" +export GEMINI_BASE_URL="http://localhost:20128/v1" +export GEMINI_API_KEY="sk-your-omniroute-key" +``` + +> For a **remote server** replace `localhost:20128` with the server IP or domain, +> e.g. `http://192.168.0.15:20128`. + +--- + +## Step 4 โ€” Configure Each Tool + +### Claude Code + +```bash +# Via CLI: +claude config set --global api-base-url http://localhost:20128/v1 + +# Or create ~/.claude/settings.json: +mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF +{ + "apiBaseUrl": "http://localhost:20128/v1", + "apiKey": "sk-your-omniroute-key" +} +EOF +``` + +**Test:** `claude "say hello"` + +--- + +### OpenAI Codex + +```bash +mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF +model: auto +apiKey: sk-your-omniroute-key +apiBaseUrl: http://localhost:20128/v1 +EOF +``` + +**Test:** `codex "what is 2+2?"` + +--- + +### OpenCode + +```bash +mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF +[provider.openai] +base_url = "http://localhost:20128/v1" +api_key = "sk-your-omniroute-key" +EOF +``` + +**Test:** `opencode` + +--- + +### Cline (CLI or VS Code) + +**CLI mode:** + +```bash +mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF +{ + "apiProvider": "openai", + "openAiBaseUrl": "http://localhost:20128/v1", + "openAiApiKey": "sk-your-omniroute-key" +} +EOF +``` + +**VS Code mode:** +Cline extension settings โ†’ API Provider: `OpenAI Compatible` โ†’ Base URL: `http://localhost:20128/v1` + +Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ Cline โ†’ Apply Config**. + +--- + +### KiloCode (CLI or VS Code) + +**CLI mode:** + +```bash +kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key +``` + +**VS Code settings:** + +```json +{ + "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", + "kilo-code.apiKey": "sk-your-omniroute-key" +} +``` + +Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ KiloCode โ†’ Apply Config**. + +--- + +### Continue (VS Code Extension) + +Edit `~/.continue/config.yaml`: + +```yaml +models: + - name: OmniRoute + provider: openai + model: auto + apiBase: http://localhost:20128/v1 + apiKey: sk-your-omniroute-key + default: true +``` + +Restart VS Code after editing. + +--- + +### Kiro CLI (Amazon) + +```bash +# Login to your AWS/Kiro account: +kiro-cli login + +# The CLI uses its own auth โ€” OmniRoute is not needed as backend for Kiro CLI itself. +# Use kiro-cli alongside OmniRoute for other tools. +kiro-cli status +``` + +--- + +### Cursor (Desktop App) + +> **Note:** Cursor routes requests through its cloud. For OmniRoute integration, +> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL. + +Via GUI: **Settings โ†’ Models โ†’ OpenAI API Key** + +- Base URL: `https://your-domain.com/v1` +- API Key: your OmniRoute key + +--- + +## Dashboard Auto-Configuration + +The OmniRoute dashboard automates configuration for most tools: + +1. Go to `http://localhost:20128/dashboard/cli-tools` +2. Expand any tool card +3. Select your API key from the dropdown +4. Click **Apply Config** (if tool is detected as installed) +5. Or copy the generated config snippet manually + +--- + +## Built-in Agents: Droid & OpenClaw + +**Droid** and **OpenClaw** are AI agents built directly into OmniRoute โ€” no installation needed. +They run as internal routes and use OmniRoute's model routing automatically. + +- Access: `http://localhost:20128/dashboard/agents` +- Configure: same combos and providers as all other tools +- No API key or CLI install required + +--- + +## Available API Endpoints + +| Endpoint | Description | Use For | +| -------------------------- | ----------------------------- | --------------------------- | +| `/v1/chat/completions` | Standard chat (all providers) | All modern tools | +| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows | +| `/v1/completions` | Legacy text completions | Older tools using `prompt:` | +| `/v1/embeddings` | Text embeddings | RAG, search | +| `/v1/images/generations` | Image generation | DALL-E, Flux, etc. | +| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS | +| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI | + +--- + +## Soluciรณn de Problemas + +| Error | Cause | Fix | +| ------------------------- | ----------------------- | ------------------------------------------ | +| `Connection refused` | OmniRoute not running | `pm2 start omniroute` | +| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` | +| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` | +| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` | +| CLI shows "not installed" | Binary not in PATH | Check `which ` | +| `kiro-cli: not found` | Not in PATH | `export PATH="$HOME/.local/bin:$PATH"` | + +--- + +## Quick Setup Script (One Command) + +```bash +# Install all CLIs and configure for OmniRoute (replace with your key and server URL) +OMNIROUTE_URL="http://localhost:20128/v1" +OMNIROUTE_KEY="sk-your-omniroute-key" + +npm install -g @anthropic-ai/claude-code @openai/codex opencode-ai cline kilocode + +# Kiro CLI +apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash + +# Write configs +mkdir -p ~/.claude ~/.codex ~/.config/opencode ~/.continue + +cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" +cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" +cat >> ~/.bashrc << EOF +export OPENAI_BASE_URL="$OMNIROUTE_URL" +export OPENAI_API_KEY="$OMNIROUTE_KEY" +export ANTHROPIC_BASE_URL="$OMNIROUTE_URL" +export ANTHROPIC_API_KEY="$OMNIROUTE_KEY" +EOF + +source ~/.bashrc +echo "โœ… All CLIs installed and configured for OmniRoute" +``` diff --git a/docs/i18n/es/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/es/docs/CODEBASE_DOCUMENTATION.md new file mode 100644 index 0000000000..16356b1ed7 --- /dev/null +++ b/docs/i18n/es/docs/CODEBASE_DOCUMENTATION.md @@ -0,0 +1,591 @@ +# omniroute โ€” Codebase Documentation (Espaรฑol) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CODEBASE_DOCUMENTATION.md) + +--- + +> 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
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, Qoder, 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. + +#### Arquitectura + +```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 | +| Qoder | 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"] +``` diff --git a/docs/i18n/es/docs/COVERAGE_PLAN.md b/docs/i18n/es/docs/COVERAGE_PLAN.md new file mode 100644 index 0000000000..21babefd0c --- /dev/null +++ b/docs/i18n/es/docs/COVERAGE_PLAN.md @@ -0,0 +1,170 @@ +# Test Coverage Plan (Espaรฑol) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/COVERAGE_PLAN.md) + +--- + +Last updated: 2026-03-28 + +## Baseline + +There are multiple coverage numbers depending on how the report is computed. For planning, only one of them is useful. + +| Metric | Scope | Statements / Lines | Branches | Functions | Notes | +| -------------------- | ----------------------------------------------------- | -----------------: | -------: | --------: | --------------------------------------------------- | +| Legacy | Old `npm run test:coverage` | 79.42% | 75.15% | 67.94% | Inflated: counts test files and excludes `open-sse` | +| Diagnostic | Source-only, excluding tests and excluding `open-sse` | 68.16% | 63.55% | 64.06% | Useful only to isolate `src/**` | +| Recommended baseline | Source-only, excluding tests and including `open-sse` | 56.95% | 66.05% | 57.80% | This is the project-wide baseline to improve | + +The recommended baseline is the number to optimize against. + +## Rules + +- Coverage targets apply to source files, not to `tests/**`. +- `open-sse/**` is part of the product and must remain in scope. +- New code should not reduce coverage in touched areas. +- Prefer testing behavior and branch outcomes over implementation details. +- Prefer temp SQLite databases and small fixtures over broad mocks for `src/lib/db/**`. + +## Current command set + +- `npm run test:coverage` + - Main source coverage gate for the unit test suite + - Generates `text-summary`, `html`, `json-summary`, and `lcov` +- `npm run coverage:report` + - Detailed file-by-file report from the latest run +- `npm run test:coverage:legacy` + - Historical comparison only + +## Milestones + +| Phase | Target | Focus | +| ------- | ---------------------: | ------------------------------------------------- | +| Phase 1 | 60% statements / lines | Quick wins and low-risk utility coverage | +| Phase 2 | 65% statements / lines | DB and route foundations | +| Phase 3 | 70% statements / lines | Provider validation and usage analytics | +| Phase 4 | 75% statements / lines | `open-sse` translators and helpers | +| Phase 5 | 80% statements / lines | `open-sse` handlers and executor branches | +| Phase 6 | 85% statements / lines | Harder edge cases, branch debt, regression suites | +| Phase 7 | 90% statements / lines | Final sweep, gap closure, strict ratchet | + +Branches and functions should ratchet upward with each phase, but the primary hard target is statements / lines. + +## Priority hotspots + +These files or areas offer the best return for the next phases: + +1. `open-sse/handlers` + - `chatCore.ts` at 7.57% + - Overall directory at 29.07% +2. `open-sse/translator/request` + - Overall directory at 36.39% + - Many translators are still near single-digit coverage +3. `open-sse/translator/response` + - Overall directory at 8.07% +4. `open-sse/executors` + - Overall directory at 36.62% +5. `src/lib/db` + - `models.ts` at 20.66% + - `registeredKeys.ts` at 34.46% + - `modelComboMappings.ts` at 36.25% + - `settings.ts` at 46.40% + - `webhooks.ts` at 33.33% +6. `src/lib/usage` + - `usageHistory.ts` at 21.12% + - `usageStats.ts` at 9.56% + - `costCalculator.ts` at 30.00% +7. `src/lib/providers` + - `validation.ts` at 41.16% +8. Low-risk utility and API files for early gains + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/api/errorResponse.ts` + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +## Execution checklist + +### Phase 1: 56.95% -> 60% + +- [x] Fix coverage metric so it reflects source code instead of test files +- [x] Keep a legacy coverage script for comparison +- [x] Record the baseline and hotspots in-repo +- [ ] Add focused tests for low-risk utilities: + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/fetchTimeout.ts` + - `src/lib/api/errorResponse.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/display/names.ts` +- [ ] Add route tests for: + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +### Phase 2: 60% -> 65% + +- [ ] Add DB-backed tests for: + - `src/lib/db/modelComboMappings.ts` + - `src/lib/db/settings.ts` + - `src/lib/db/registeredKeys.ts` +- [ ] Cover branch behavior in: + - `src/lib/providers/validation.ts` + - `src/app/api/v1/embeddings/route.ts` + - `src/app/api/v1/moderations/route.ts` + +### Phase 3: 65% -> 70% + +- [ ] Add usage analytics tests for: + - `src/lib/usage/usageHistory.ts` + - `src/lib/usage/usageStats.ts` + - `src/lib/usage/costCalculator.ts` +- [ ] Expand route coverage for proxy management and settings branches + +### Phase 4: 70% -> 75% + +- [ ] Cover translator helpers and central translation paths: + - `open-sse/translator/index.ts` + - `open-sse/translator/helpers/*` + - `open-sse/translator/request/*` + - `open-sse/translator/response/*` + +### Phase 5: 75% -> 80% + +- [ ] Add handler-level tests for: + - `open-sse/handlers/chatCore.ts` + - `open-sse/handlers/responsesHandler.js` + - `open-sse/handlers/imageGeneration.js` + - `open-sse/handlers/embeddings.js` +- [ ] Add executor branch coverage for provider-specific auth, retries, and endpoint overrides + +### Phase 6: 80% -> 85% + +- [ ] Merge more edge-case suites into the main coverage path +- [ ] Increase function coverage for DB modules with weak constructor/helper coverage +- [ ] Close branch gaps in `settings.ts`, `registeredKeys.ts`, `validation.ts`, and translator helpers + +### Phase 7: 85% -> 90% + +- [ ] Treat the remaining low-coverage files as blockers +- [ ] Add regression tests for every uncovered production bug fixed during the push to 90% +- [ ] Raise the coverage gate in CI only after the local baseline is stable for at least two consecutive runs + +## Ratchet policy + +Update `npm run test:coverage` thresholds only after the project actually exceeds the next milestone with a comfortable buffer. + +Recommended ratchet sequence: + +1. 55/60/55 +2. 60/62/58 +3. 65/64/62 +4. 70/66/66 +5. 75/70/72 +6. 80/75/78 +7. 85/80/84 +8. 90/85/88 + +Order is `statements-lines / branches / functions`. + +## Known gap + +The current coverage command measures the main Node unit suite and includes source reached from it, including `open-sse`. It does not yet merge Vitest coverage into a single unified report. That merge is worth doing later, but it is not a blocker for starting the 60% -> 80% climb. diff --git a/docs/i18n/es/docs/FEATURES.md b/docs/i18n/es/docs/FEATURES.md index 4d8f9bcc3a..88fb1e7670 100644 --- a/docs/i18n/es/docs/FEATURES.md +++ b/docs/i18n/es/docs/FEATURES.md @@ -1,6 +1,6 @@ # OmniRoute โ€” Dashboard Features Gallery (Espaรฑol) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/FEATURES.md) --- @@ -10,7 +10,7 @@ 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). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. ![Providers Dashboard](screenshots/01-providers.png) diff --git a/docs/i18n/es/docs/MCP-SERVER.md b/docs/i18n/es/docs/MCP-SERVER.md new file mode 100644 index 0000000000..822bdf14eb --- /dev/null +++ b/docs/i18n/es/docs/MCP-SERVER.md @@ -0,0 +1,87 @@ +# OmniRoute MCP Server Documentation (Espaรฑol) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/MCP-SERVER.md) + +--- + +> Model Context Protocol server with 16 intelligent tools + +## Instalar + +OmniRoute MCP is built-in. Start it with: + +```bash +omniroute --mcp +``` + +Or via the open-sse transport: + +```bash +# HTTP streamable transport (port 20130) +omniroute --dev # MCP auto-starts on /mcp endpoint +``` + +## IDE Configuration + +See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup. + +--- + +## Essential Tools (8) + +| Tool | Description | +| :------------------------------ | :--------------------------------------- | +| `omniroute_get_health` | Gateway health, circuit breakers, uptime | +| `omniroute_list_combos` | All configured combos with models | +| `omniroute_get_combo_metrics` | Performance metrics for a specific combo | +| `omniroute_switch_combo` | Switch active combo by ID/name | +| `omniroute_check_quota` | Quota status per provider or all | +| `omniroute_route_request` | Send a chat completion through OmniRoute | +| `omniroute_cost_report` | Cost analytics for a time period | +| `omniroute_list_models_catalog` | Full model catalog with capabilities | + +## Advanced Tools (8) + +| Tool | Description | +| :--------------------------------- | :---------------------------------------------------------- | +| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | +| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | +| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | +| `omniroute_test_combo` | Live-test all models in a combo via a real upstream request | +| `omniroute_get_provider_metrics` | Detailed metrics for one provider | +| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | +| `omniroute_explain_route` | Explain a past routing decision | +| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | + +## Authentication + +MCP tools are authenticated via API key scopes. Each tool requires specific scopes: + +| Scope | Tools | +| :------------- | :----------------------------------------------- | +| `read:health` | get_health, get_provider_metrics | +| `read:combos` | list_combos, get_combo_metrics | +| `write:combos` | switch_combo | +| `read:quota` | check_quota | +| `write:route` | route_request, simulate_route, test_combo | +| `read:usage` | cost_report, get_session_snapshot, explain_route | +| `write:config` | set_budget_guard, set_resilience_profile | +| `read:models` | list_models_catalog, best_combo_for_task | + +## Audit Logging + +Every tool call is logged to `mcp_tool_audit` with: + +- Tool name, arguments, result +- Duration (ms), success/failure +- API key hash, timestamp + +## Files + +| File | Purpose | +| :------------------------------------------- | :------------------------------------------ | +| `open-sse/mcp-server/server.ts` | MCP server creation + 16 tool registrations | +| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport | +| `open-sse/mcp-server/auth.ts` | API key + scope validation | +| `open-sse/mcp-server/audit.ts` | Tool call audit logging | +| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers | diff --git a/docs/i18n/es/docs/RELEASE_CHECKLIST.md b/docs/i18n/es/docs/RELEASE_CHECKLIST.md new file mode 100644 index 0000000000..d0964eabda --- /dev/null +++ b/docs/i18n/es/docs/RELEASE_CHECKLIST.md @@ -0,0 +1,37 @@ +# Release Checklist (Espaรฑol) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/RELEASE_CHECKLIST.md) + +--- + +Use this checklist before tagging or publishing a new OmniRoute release. + +## Version and Changelog + +1. Bump `package.json` version (`x.y.z`) in the release branch. +2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: + - `## [x.y.z] โ€” YYYY-MM-DD` +3. Keep `## [Unreleased]` as the first changelog section for upcoming work. +4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. + +## API Docs + +1. Update `docs/openapi.yaml`: + - `info.version` must equal `package.json` version. +2. Validate endpoint examples if API contracts changed. + +## Runtime Docs + +1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. +2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. +3. Update localized docs if source docs changed significantly. + +## Automated Check + +Run the sync guard locally before opening PR: + +```bash +npm run check:docs-sync +``` + +CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/es/docs/TROUBLESHOOTING.md b/docs/i18n/es/docs/TROUBLESHOOTING.md new file mode 100644 index 0000000000..6ec65ff780 --- /dev/null +++ b/docs/i18n/es/docs/TROUBLESHOOTING.md @@ -0,0 +1,256 @@ +# Troubleshooting (Espaรฑol) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/TROUBLESHOOTING.md) + +--- + +Common problems and solutions for OmniRoute. + +--- + +## Quick Fixes + +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | + +--- + +## Provider Issues + +### "Language model did not provide messages" + +**Cause:** Provider quota exhausted. + +**Fix:** + +1. 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, Qoder) 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}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) + +--- + +## Circuit Breaker Issues + +### Provider stuck in OPEN state + +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. + +**Fix:** + +1. 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 +- **SDK returns raw string instead of object** โ€” Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** โ€” Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** โ€” Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** โ€” Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` + +--- + +## Resilience Settings + +### Auto rate-limit not triggering + +- 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. + +--- + +## Optional RAG / LLM failure taxonomy (16 problems) + +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` โ€ฆ `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard โ†’ Health** for real-time system status +- **Translator**: Use **Dashboard โ†’ Translator** to debug format issues diff --git a/docs/i18n/es/USER_GUIDE.md b/docs/i18n/es/docs/USER_GUIDE.md similarity index 82% rename from docs/i18n/es/USER_GUIDE.md rename to docs/i18n/es/docs/USER_GUIDE.md index 89023b75bb..668cae9c29 100644 --- a/docs/i18n/es/USER_GUIDE.md +++ b/docs/i18n/es/docs/USER_GUIDE.md @@ -1,8 +1,6 @@ # User Guide (Espaรฑol) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/USER_GUIDE.md) - -> ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/USER_GUIDE.md) --- @@ -320,7 +318,7 @@ Model: cc/claude-opus-4-6 --- -## ๐Ÿš€ Deployment +## Despliegue ### Global npm install (Recommended) @@ -511,23 +509,26 @@ post_install() { ### Environment Variables -| Variable | Default | Description | -| ------------------------- | ------------------------------------ | ------------------------------------------------------- | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | -| `INITIAL_PASSWORD` | `123456` | First login password | -| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | -| `PORT` | framework default | Service port (`20128` in examples) | -| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | -| `NODE_ENV` | runtime default | Set `production` for deploy | -| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | -| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | -| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | -| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | -| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | -| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | -| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | -| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | +| 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/*` | +| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand | +| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | For the full environment variable reference, see the [README](../README.md). @@ -598,6 +599,11 @@ curl -X POST http://localhost:20128/api/provider-models \ Or use Dashboard: **Providers โ†’ [Provider] โ†’ Custom Models**. +Notes: + +- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers. +- The **Custom Models** section is intended for providers that do not expose managed available-model imports. + ### Dedicated Provider Routes Route requests directly to a specific provider with model validation: @@ -642,6 +648,14 @@ Returns models grouped by provider with types (`chat`, `embedding`, `image`). - Automatic background sync with timeout + fail-fast - Prefer server-side `BASE_URL`/`CLOUD_URL` in production +### Cloudflare Quick Tunnel + +- Available in **Dashboard โ†’ Endpoints** for Docker and other self-hosted deployments +- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint +- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary +- Tunnel URLs are ephemeral and change every time you stop/start the tunnel +- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download + ### LLM Gateway Intelligence (Phase 9) - **Semantic Cache** โ€” Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) @@ -757,11 +771,11 @@ OmniRoute implements provider-level resilience with four components: 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 | +| 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 unless `DISABLE_SQLITE_AUTO_BACKUP=true` | ```bash # API: Export database @@ -787,10 +801,11 @@ curl -X POST http://localhost:20128/api/db-backups/import \ ### Settings Dashboard -The settings page is organized into 5 tabs for easy navigation: +The settings page is organized into 6 tabs for easy navigation: | Tab | Contents | | -------------- | ---------------------------------------------------------------------------------------------- | +| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility | | **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | | **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | | **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | diff --git a/docs/i18n/no/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/es/docs/VM_DEPLOYMENT_GUIDE.md similarity index 58% rename from docs/i18n/no/VM_DEPLOYMENT_GUIDE.md rename to docs/i18n/es/docs/VM_DEPLOYMENT_GUIDE.md index a4067dc9ce..a6e66d22a8 100644 --- a/docs/i18n/no/VM_DEPLOYMENT_GUIDE.md +++ b/docs/i18n/es/docs/VM_DEPLOYMENT_GUIDE.md @@ -1,50 +1,52 @@ -# OmniRoute โ€” Implementeringsveiledning pรฅ VM med Cloudflare +# OmniRoute โ€” Deployment Guide on VM with Cloudflare (Espaรฑol) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](../pt-BR/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](../es/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](../fr/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](../it/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](../ru/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](../zh-CN/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](../de/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](../in/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](../th/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](../uk-UA/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](../ar/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](../ja/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](../vi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](../bg/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](../da/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](../fi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](../he/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](../hu/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](../id/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](../ko/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](../ms/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](../nl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](../no/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](../pt/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](../ro/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](../pl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](../sk/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](../sv/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](../phi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](../cs/VM_DEPLOYMENT_GUIDE.md) - -Komplett veiledning for รฅ installere og konfigurere OmniRoute pรฅ en VM (VPS) med domene administrert via Cloudflare. +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/VM_DEPLOYMENT_GUIDE.md) --- -## Forutsetninger +Complete guide to install and configure OmniRoute on a VM (VPS) with domain managed via Cloudflare. -| Vare | Minimum | Anbefalt | +--- + +## Prerequisites + +| Item | Minimum | Recommended | | ---------- | ------------------------ | ---------------- | | **CPU** | 1 vCPU | 2 vCPU | | **RAM** | 1 GB | 2 GB | | **Disk** | 10 GB SSD | 25 GB SSD | | **OS** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS | -| **Domene** | Registrert pรฅ Cloudflare | โ€” | -| **Dokker** | Docker Engine 24+ | Docker 27+ | +| **Domain** | Registered on Cloudflare | โ€” | +| **Docker** | Docker Engine 24+ | Docker 27+ | -**Testede leverandรธrer**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. +**Tested providers**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. --- -## 1. Konfigurer VM +## 1. Configure the VM -### 1.1 Opprett forekomsten +### 1.1 Create the instance -Pรฅ din foretrukne VPS-leverandรธr: +On your preferred VPS provider: -- Velg Ubuntu 24.04 LTS -- Velg minimumsplanen (1 vCPU / 1 GB RAM) -- Angi et sterkt root-passord eller konfigurer SSH-nรธkkel - โ€“ Legg merke til **offentlig IP** (f.eks. `203.0.113.10`) +- Choose Ubuntu 24.04 LTS +- Select the minimum plan (1 vCPU / 1 GB RAM) +- Set a strong root password or configure SSH key +- Note the **public IP** (e.g., `203.0.113.10`) -### 1.2 Koble til via SSH +### 1.2 Connect via SSH ```bash ssh root@203.0.113.10 ``` -### 1.3 Oppdater systemet +### 1.3 Update the system ```bash apt update && apt upgrade -y ``` -### 1.4 Installer Docker +### 1.4 Install Docker ```bash # Install dependencies @@ -59,13 +61,13 @@ apt update apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin ``` -### 1.5 Installer nginx +### 1.5 Install nginx ```bash apt install -y nginx ``` -### 1.6 Konfigurer brannmur (UFW) +### 1.6 Configure Firewall (UFW) ```bash ufw default deny incoming @@ -76,19 +78,19 @@ ufw allow 443/tcp # HTTPS ufw enable ``` -> **Tips**: For maksimal sikkerhet, begrense portene 80 og 443 til bare Cloudflare IP-er. Se avsnittet [Advanced Security](#advanced-security). +> **Tip**: For maximum security, restrict ports 80 and 443 to Cloudflare IPs only. See the [Advanced Security](#advanced-security) section. --- -## 2. Installer OmniRoute +## 2. Install OmniRoute -### 2.1 Opprett konfigurasjonskatalog +### 2.1 Create configuration directory ```bash mkdir -p /opt/omniroute ``` -### 2.2 Lag miljรธvariabler-fil +### 2.2 Create environment variables file ```bash cat > /opt/omniroute/.env << โ€˜EOFโ€™ @@ -120,9 +122,9 @@ NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com EOF ``` -> โš ๏ธ **VIKTIG**: Generer unike hemmelige nรธkler! Bruk `openssl rand -hex 32` for hver nรธkkel. +> โš ๏ธ **IMPORTANT**: Generate unique secret keys! Use `openssl rand -hex 32` for each key. -### 2.3 Start beholderen +### 2.3 Start the container ```bash docker pull diegosouzapw/omniroute:latest @@ -136,27 +138,27 @@ docker run -d \ diegosouzapw/omniroute:latest ``` -### 2.4 Bekreft at den kjรธrer +### 2.4 Verify that it is running ```bash docker ps | grep omniroute docker logs omniroute --tail 20 ``` -Den skal vise: `[DB] SQLite database ready` og `listening on port 20128`. +It should display: `[DB] SQLite database ready` and `listening on port 20128`. --- -## 3. Konfigurer nginx (omvendt proxy) +## 3. Configure nginx (Reverse Proxy) -### 3.1 Generer SSL-sertifikat (Cloudflare Origin) +### 3.1 Generate SSL certificate (Cloudflare Origin) -I Cloudflare-dashbordet: +In the Cloudflare dashboard: -1. Gรฅ til **SSL/TLS โ†’ Origin Server** -2. Klikk pรฅ **Opprett sertifikat** -3. Behold standardinnstillingene (15 รฅr, \*.dittdomene.com) -4. Kopier **opprinnelsessertifikatet** og **privatnรธkkelen** +1. Go to **SSL/TLS โ†’ Origin Server** +2. Click **Create Certificate** +3. Keep the defaults (15 years, \*.yourdomain.com) +4. Copy the **Origin Certificate** and the **Private Key** ```bash mkdir -p /etc/nginx/ssl @@ -170,7 +172,7 @@ nano /etc/nginx/ssl/origin.key chmod 600 /etc/nginx/ssl/origin.key ``` -### 3.2 Nginx-konfigurasjon +### 3.2 Nginx Configuration ```bash cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ @@ -228,7 +230,7 @@ server { NGINX ``` -### 3.3 Aktiver og test +### 3.3 Enable and Test ```bash # Remove default configuration @@ -243,27 +245,27 @@ nginx -t && systemctl reload nginx --- -## 4. Konfigurer Cloudflare DNS +## 4. Configure Cloudflare DNS -### 4.1 Legg til DNS-post +### 4.1 Add DNS record -I Cloudflare-dashbordet โ†’ DNS: +In the Cloudflare dashboard โ†’ DNS: -| Skriv inn | Navn | Innhold | Fullmakt | -| --------- | ------ | ---------------------- | ----------- | -| A | `llms` | `203.0.113.10` (VM IP) | โœ… Fullmakt | +| Type | Name | Content | Proxy | +| ---- | ------ | ---------------------- | ---------- | +| A | `llms` | `203.0.113.10` (VM IP) | โœ… Proxied | -### 4.2 Konfigurer SSL +### 4.2 Configure SSL -Under **SSL/TLS โ†’ Oversikt**: +Under **SSL/TLS โ†’ Overview**: -- Modus: **Full (Streng)** +- Mode: **Full (Strict)** Under **SSL/TLS โ†’ Edge Certificates**: -- Bruk alltid HTTPS: โœ… Pรฅ -- Minimum TLS-versjon: TLS 1.2 -- Automatiske HTTPS-omskrivinger: โœ… Pรฅ +- Always Use HTTPS: โœ… On +- Minimum TLS Version: TLS 1.2 +- Automatic HTTPS Rewrites: โœ… On ### 4.3 Testing @@ -274,9 +276,9 @@ curl -sI https://llms.seudominio.com/health --- -## 5. Drift og vedlikehold +## 5. Operations and Maintenance -### Oppgrader til en ny versjon +### Upgrade to a new version ```bash docker pull diegosouzapw/omniroute:latest @@ -288,14 +290,14 @@ docker run -d --name omniroute --restart unless-stopped \ diegosouzapw/omniroute:latest ``` -### Vis logger +### View logs ```bash docker logs -f omniroute # Real-time stream docker logs omniroute --tail 50 # Last 50 lines ``` -### Manuell sikkerhetskopiering av database +### Manual database backup ```bash # Copy data from the volume to the host @@ -306,7 +308,7 @@ docker run --rm -v omniroute-data:/data -v $(pwd):/backup \ alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data ``` -### Gjenopprett fra sikkerhetskopi +### Restore from backup ```bash docker stop omniroute @@ -317,9 +319,9 @@ docker start omniroute --- -## 6. Avansert sikkerhet +## 6. Advanced Security -### Begrens nginx til Cloudflare IP-er +### Restrict nginx to Cloudflare IPs ```bash cat > /etc/nginx/cloudflare-ips.conf << โ€˜CFโ€™ @@ -344,13 +346,13 @@ real_ip_header CF-Connecting-IP; CF ``` -Legg til fรธlgende til `nginx.conf` inne i `http {}`-blokken: +Add the following to `nginx.conf` inside the `http {}` block: ```nginx include /etc/nginx/cloudflare-ips.conf; ``` -### Installer fail2ban +### Install fail2ban ```bash apt install -y fail2ban @@ -361,7 +363,7 @@ systemctl start fail2ban fail2ban-client status sshd ``` -### Blokker direkte tilgang til Docker-porten +### Block direct access to the Docker port ```bash # Prevent direct external access to port 20128 @@ -375,9 +377,9 @@ netfilter-persistent save --- -## 7. Distribuer til Cloudflare-arbeidere (valgfritt) +## 7. Deploy to Cloudflare Workers (Optional) -For ekstern tilgang via Cloudflare Workers (uten รฅ eksponere VM direkte): +For remote access via Cloudflare Workers (without exposing the VM directly): ```bash # In the local repository @@ -387,15 +389,15 @@ npx wrangler login npx wrangler deploy ``` -Se hele dokumentasjonen pรฅ [omnirouteCloud/README.md](../omnirouteCloud/README.md). +See the full documentation at [omnirouteCloud/README.md](../omnirouteCloud/README.md). --- -## Portsammendrag +## Port Summary -| Port | Service | Tilgang | +| Port | Service | Access | | ----- | ----------- | -------------------------- | -| 22 | SSH | Offentlig (med fail2ban) | -| 80 | nginx HTTP | Omdirigere โ†’ HTTPS | +| 22 | SSH | Public (with fail2ban) | +| 80 | nginx HTTP | Redirect โ†’ HTTPS | | 443 | nginx HTTPS | Via Cloudflare Proxy | -| 20128 | OmniRoute | Kun lokal vert (via nginx) | +| 20128 | OmniRoute | Localhost only (via nginx) | diff --git a/docs/i18n/es/src/lib/a2a/README.md b/docs/i18n/es/src/lib/a2a/README.md new file mode 100644 index 0000000000..07dfb276ed --- /dev/null +++ b/docs/i18n/es/src/lib/a2a/README.md @@ -0,0 +1,752 @@ +# OmniRoute A2A Server (Espaรฑol) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../../../src/lib/a2a/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../../../es/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../../../fr/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../../../de/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../../../it/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../../../ru/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../../../zh-CN/src/lib/a2a/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../../../ja/src/lib/a2a/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../../../ko/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../../../ar/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../../../in/src/lib/a2a/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../../../th/src/lib/a2a/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../../../vi/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../../../id/src/lib/a2a/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../../../ms/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../../../nl/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../../../pl/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../../../sv/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../../../no/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../../../da/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../../../fi/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../../../pt/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../../../ro/src/lib/a2a/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../../../hu/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../../../bg/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../../../sk/src/lib/a2a/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../../../uk-UA/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../../../he/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../../../phi/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../../../pt-BR/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../../../cs/src/lib/a2a/README.md) + +--- + +> **Agent-to-Agent Protocol v0.3** โ€” Enables any AI agent to use OmniRoute as an intelligent routing agent via JSON-RPC 2.0. + +The A2A Server exposes OmniRoute as a **first-class agent** that other agents can discover, delegate tasks to, and collaborate with using the [A2A Protocol](https://google.github.io/A2A/). + +--- + +## Arquitectura + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Orchestrator Agent โ”‚ +โ”‚ (LangChain, CrewAI, AutoGen, Custom Agent) โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ 1. GET /.well-known/agent.json (discover) + โ”‚ 2. POST /a2a (JSON-RPC 2.0) + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ OmniRoute A2A Server โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Task Manager โ”‚ โ”‚ Skill Engine โ”‚ โ”‚ SSE Streaming โ”‚ โ”‚ +โ”‚ โ”‚ (lifecycle) โ”‚โ”€โ”€โ”‚ (registry) โ”‚โ”€โ”€โ”‚ (real-time) โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ +โ”‚ Skills: โ”‚ โ”‚ +โ”‚ โ”œโ”€ smart-routing โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ””โ”€ quota-management โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ Routing Decision Logger โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ OmniRoute Gateway (internal) + /v1/chat/completions, /api/combos, /api/usage/quota +``` + +--- + +## Inicio Rรกpido + +### Agent Discovery + +Every A2A-compatible agent exposes an **Agent Card** at `/.well-known/agent.json`: + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +**Response:** + +```json +{ + "name": "OmniRoute", + "description": "Intelligent AI gateway with auto-routing across 50+ providers", + "url": "http://localhost:20128/a2a", + "version": "1.8.1", + "capabilities": { + "streaming": true, + "pushNotifications": false + }, + "skills": [ + { + "id": "smart-routing", + "name": "Smart Routing", + "description": "Routes prompts through OmniRoute intelligent pipeline", + "tags": ["routing", "llm", "multi-provider", "cost-optimization"], + "examples": [ + "Write a hello world in Python", + "Explain quantum computing using the cheapest provider" + ] + }, + { + "id": "quota-management", + "name": "Quota Management", + "description": "Natural-language queries about provider quotas", + "tags": ["quota", "analytics", "cost"], + "examples": [ + "Which provider has the most quota remaining?", + "Suggest a free combo for coding" + ] + } + ], + "authentication": { + "schemes": ["bearer"], + "apiKeyHeader": "Authorization" + } +} +``` + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Send a message to a skill and receive the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python hello world"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "a1b2c3d4-...", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "print('Hello, World!')" }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.0030)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "2026-03-04T..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"Quantum computing..."}}} + +: heartbeat 2026-03-04T21:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Running Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Skills Reference + +### `smart-routing` + +Routes prompts through OmniRoute's intelligent pipeline with full observability. + +**Parameters (in `metadata`):** + +| Parameter | Type | Default | Description | +| --------- | -------- | ------------ | ---------------------------------------------------------------------------------------- | +| `model` | `string` | `"auto"` | Target model (e.g., `claude-sonnet-4`, `gpt-4o`, `auto`) | +| `combo` | `string` | active combo | Specific combo to route through | +| `budget` | `number` | none | Maximum cost in USD for this request | +| `role` | `string` | none | Task role hint: `coding`, `review`, `planning`, `analysis`, `debugging`, `documentation` | + +**Returns:** + +| Field | Description | +| ------------------------------ | --------------------------------------------------------- | +| `artifacts[].content` | The LLM response text | +| `metadata.routing_explanation` | Human-readable explanation of routing decision | +| `metadata.cost_envelope` | Estimated vs actual cost with currency | +| `metadata.resilience_trace` | Array of events (primary_selected, fallback_needed, etc.) | +| `metadata.policy_verdict` | Whether the request was allowed and why | + +### `quota-management` + +Answers natural-language queries about provider quotas. + +**Query types (inferred from message content):** + +| Query Pattern | Response Type | +| ---------------------------------------------- | -------------------------------------------------------- | +| Contains `"ranking"`, `"most quota"`, `"best"` | Providers ranked by remaining quota | +| Contains `"free"`, `"suggest"` | Lists free combos or suggests free-tier providers | +| Default | Full quota summary with warnings for low-quota providers | + +--- + +## Task Lifecycle + +``` +submitted โ”€โ”€โ†’ working โ”€โ”€โ†’ completed + โ”€โ”€โ†’ failed + โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ†’ cancelled +``` + +| State | Description | +| ----------- | ----------------------------------------------------- | +| `submitted` | Task created, queued for execution | +| `working` | Skill handler is executing | +| `completed` | Execution succeeded, artifacts available | +| `failed` | Execution failed or task expired (TTL: 5 min default) | +| `cancelled` | Cancelled by client via `tasks/cancel` | + +- Terminal states: `completed`, `failed`, `cancelled` (no further transitions) +- Expired tasks in `submitted` or `working` are auto-marked as `failed` +- Tasks are garbage-collected after 2ร— TTL + +--- + +## Client Examples + +### Python โ€” Orchestrator Agent + +```python +""" +A2A Client โ€” Python example. +Discovers OmniRoute agent, sends a task, and processes the result. +""" +import requests +import json + +BASE_URL = "http://localhost:20128" +API_KEY = "your-api-key" +HEADERS = { + "Content-Type": "application/json", + "Authorization": f"Bearer {API_KEY}", +} + +# 1. Discover agent capabilities +agent_card = requests.get(f"{BASE_URL}/.well-known/agent.json").json() +print(f"Agent: {agent_card['name']} v{agent_card['version']}") +print(f"Skills: {[s['id'] for s in agent_card['skills']]}") + +# 2. Send a smart-routing task +response = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python quicksort implementation"}], + "metadata": { + "model": "auto", + "combo": "fast-coding", + "budget": 0.10, + } + } +}) +result = response.json()["result"] +print(f"\n๐Ÿ“ Response: {result['artifacts'][0]['content'][:200]}...") +print(f"๐Ÿ”€ Routing: {result['metadata']['routing_explanation']}") +print(f"๐Ÿ’ฐ Cost: ${result['metadata']['cost_envelope']['actual']}") +print(f"๐Ÿ›ก๏ธ Policy: {result['metadata']['policy_verdict']['reason']}") + +# 3. Query quota status +quota_resp = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-2", + "method": "message/send", + "params": { + "skill": "quota-management", + "messages": [{"role": "user", "content": "Which provider has the most quota remaining?"}], + } +}) +quota_result = quota_resp.json()["result"] +print(f"\n๐Ÿ“Š Quota: {quota_result['artifacts'][0]['content']}") +``` + +### TypeScript โ€” Multi-Agent Orchestrator + +```typescript +/** + * A2A Client โ€” TypeScript example. + * Shows agent discovery, task delegation, and streaming. + */ + +const BASE_URL = "http://localhost:20128"; +const API_KEY = "your-api-key"; + +interface JsonRpcResponse { + jsonrpc: "2.0"; + id: string | number; + result?: T; + error?: { code: number; message: string }; +} + +async function a2aCall(method: string, params: Record): Promise { + const resp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: `${method}-${Date.now()}`, + method, + params, + }), + }); + const json: JsonRpcResponse = await resp.json(); + if (json.error) throw new Error(`[${json.error.code}] ${json.error.message}`); + return json.result!; +} + +// โ”€โ”€ Agent Discovery โ”€โ”€ +const agentCard = await fetch(`${BASE_URL}/.well-known/agent.json`).then((r) => r.json()); +console.log(`Connected to: ${agentCard.name} (${agentCard.skills.length} skills)`); + +// โ”€โ”€ Smart Routing: Send a coding task โ”€โ”€ +const routingResult = await a2aCall("message/send", { + skill: "smart-routing", + messages: [{ role: "user", content: "Implement a Redis cache wrapper in TypeScript" }], + metadata: { model: "claude-sonnet-4", role: "coding" }, +}); +console.log("Response:", routingResult.artifacts[0].content); +console.log("Provider:", routingResult.metadata.routing_explanation); + +// โ”€โ”€ Quota Management: Find free alternatives โ”€โ”€ +const quotaResult = await a2aCall("message/send", { + skill: "quota-management", + messages: [{ role: "user", content: "Suggest free combos for documentation" }], +}); +console.log("Free combos:", quotaResult.artifacts[0].content); + +// โ”€โ”€ Streaming: Real-time response โ”€โ”€ +const streamResp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "stream-1", + method: "message/stream", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Explain microservices architecture" }], + }, + }), +}); + +const reader = streamResp.body!.getReader(); +const decoder = new TextDecoder(); +while (true) { + const { done, value } = await reader.read(); + if (done) break; + const chunk = decoder.decode(value); + for (const line of chunk.split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + if (event.params.chunk) { + process.stdout.write(event.params.chunk.content); + } + if (event.params.task.state === "completed") { + console.log("\nโœ… Stream completed"); + } + } + } +} +``` + +### Python โ€” LangChain A2A Integration + +```python +""" +LangChain integration โ€” Use OmniRoute A2A as a custom LLM. +""" +from langchain.llms.base import BaseLLM +from langchain.schema import LLMResult, Generation +import requests +from typing import List, Optional + +class OmniRouteA2A(BaseLLM): + base_url: str = "http://localhost:20128" + api_key: str = "" + model: str = "auto" + combo: Optional[str] = None + + @property + def _llm_type(self) -> str: + return "omniroute-a2a" + + def _call(self, prompt: str, stop: Optional[List[str]] = None, **kwargs) -> str: + response = requests.post( + f"{self.base_url}/a2a", + headers={ + "Content-Type": "application/json", + "Authorization": f"Bearer {self.api_key}", + }, + json={ + "jsonrpc": "2.0", + "id": "langchain-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": prompt}], + "metadata": { + "model": self.model, + **({"combo": self.combo} if self.combo else {}), + }, + }, + }, + ) + result = response.json()["result"] + return result["artifacts"][0]["content"] + + def _generate(self, prompts: List[str], stop=None, **kwargs) -> LLMResult: + return LLMResult( + generations=[[Generation(text=self._call(p, stop))] for p in prompts] + ) + +# Usage +llm = OmniRouteA2A( + base_url="http://localhost:20128", + api_key="your-key", + model="auto", + combo="fast-coding", +) +result = llm("Write a Python function to merge two sorted lists") +print(result) +``` + +### Go โ€” A2A Client + +```go +package main + +import ( + "bytes" + "encoding/json" + "fmt" + "io" + "net/http" +) + +const baseURL = "http://localhost:20128" +const apiKey = "your-api-key" + +type JsonRpcRequest struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Method string `json:"method"` + Params interface{} `json:"params"` +} + +type JsonRpcResponse struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Result interface{} `json:"result"` + Error *struct { + Code int `json:"code"` + Message string `json:"message"` + } `json:"error"` +} + +func a2aCall(method string, params interface{}) (*JsonRpcResponse, error) { + body, _ := json.Marshal(JsonRpcRequest{ + Jsonrpc: "2.0", + ID: "go-1", + Method: method, + Params: params, + }) + + req, _ := http.NewRequest("POST", baseURL+"/a2a", bytes.NewReader(body)) + req.Header.Set("Content-Type", "application/json") + req.Header.Set("Authorization", "Bearer "+apiKey) + + resp, err := http.DefaultClient.Do(req) + if err != nil { + return nil, err + } + defer resp.Body.Close() + data, _ := io.ReadAll(resp.Body) + + var result JsonRpcResponse + json.Unmarshal(data, &result) + return &result, nil +} + +func main() { + // Discover agent + resp, _ := http.Get(baseURL + "/.well-known/agent.json") + defer resp.Body.Close() + body, _ := io.ReadAll(resp.Body) + fmt.Println("Agent Card:", string(body)) + + // Send smart-routing task + result, _ := a2aCall("message/send", map[string]interface{}{ + "skill": "smart-routing", + "messages": []map[string]string{{"role": "user", "content": "Hello from Go!"}}, + "metadata": map[string]interface{}{"model": "auto"}, + }) + out, _ := json.MarshalIndent(result.Result, "", " ") + fmt.Println("Result:", string(out)) +} +``` + +--- + +## Use Cases + +### ๐Ÿค– Use Case 1: Multi-Agent Coding Pipeline + +An orchestrator agent delegates code generation to OmniRoute, then passes the output to a review agent. + +```python +def coding_pipeline(task: str): + # Step 1: Generate code via OmniRoute A2A + code_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Write production-quality code: {task}"} + ], metadata={"model": "auto", "role": "coding"}) + code = code_result["artifacts"][0]["content"] + + # Step 2: Review the code via OmniRoute A2A (different model) + review_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Review this code for bugs and improvements:\n\n{code}"} + ], metadata={"model": "auto", "role": "review"}) + review = review_result["artifacts"][0]["content"] + + # Step 3: Check costs + print(f"Code cost: ${code_result['metadata']['cost_envelope']['actual']}") + print(f"Review cost: ${review_result['metadata']['cost_envelope']['actual']}") + + return {"code": code, "review": review} +``` + +### ๐Ÿ’ก Use Case 2: Quota-Aware Agent Swarm + +Multiple agents share quota through OmniRoute, using the quota skill to coordinate. + +```python +async def quota_aware_agent(agent_name: str, task: str): + # Check quota before starting + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Which provider has the most quota remaining?"} + ]) + print(f"[{agent_name}] {quota['artifacts'][0]['content']}") + + # Send request with budget constraint + result = a2a_send("smart-routing", [ + {"role": "user", "content": task} + ], metadata={"budget": 0.05}) + + policy = result["metadata"]["policy_verdict"] + if not policy["allowed"]: + print(f"[{agent_name}] โš ๏ธ Budget exceeded: {policy['reason']}") + # Fall back to free combo + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Suggest free combos"} + ]) + print(f"[{agent_name}] Free alternatives: {quota['artifacts'][0]['content']}") + + return result +``` + +### ๐Ÿ“Š Use Case 3: Real-Time Streaming Dashboard + +A monitoring agent streams responses and displays progress in real-time. + +```typescript +async function streamingDashboard(prompt: string) { + const response = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { "Content-Type": "application/json", Authorization: `Bearer ${API_KEY}` }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "dash-1", + method: "message/stream", + params: { skill: "smart-routing", messages: [{ role: "user", content: prompt }] }, + }), + }); + + let totalChunks = 0; + const reader = response.body!.getReader(); + const decoder = new TextDecoder(); + + while (true) { + const { done, value } = await reader.read(); + if (done) break; + + for (const line of decoder.decode(value).split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + const state = event.params.task.state; + + if (state === "working" && event.params.chunk) { + totalChunks++; + process.stdout.write( + `\r[Chunk ${totalChunks}] ${event.params.chunk.content.slice(0, 50)}...` + ); + } + if (state === "completed") { + const meta = event.params.metadata; + console.log( + `\nโœ… Done | Cost: $${meta?.cost_envelope?.actual || 0} | Route: ${meta?.routing_explanation || "N/A"}` + ); + } + if (state === "failed") { + console.error(`\nโŒ Failed: ${event.params.metadata?.error}`); + } + } + } + } +} +``` + +### ๐Ÿ” Use Case 4: Task Polling Pattern + +For long-running tasks, poll the task status instead of waiting synchronously. + +```python +import time + +def poll_task(task_id: str, timeout: int = 60): + """Poll task status until completion or timeout.""" + start = time.time() + while time.time() - start < timeout: + result = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "poll-1", + "method": "tasks/get", + "params": {"taskId": task_id}, + }).json() + + task = result["result"]["task"] + state = task["state"] + print(f" Task {task_id[:8]}... state={state}") + + if state in ("completed", "failed", "cancelled"): + return task + time.sleep(2) + + # Timeout โ€” cancel the task + requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "cancel-1", + "method": "tasks/cancel", + "params": {"taskId": task_id}, + }) + raise TimeoutError(f"Task {task_id} timed out after {timeout}s") +``` + +--- + +## Error Codes + +| Code | Constant | Meaning | +| ------ | ------------------------ | ---------------------------------------- | +| -32700 | โ€” | Parse error (invalid JSON) | +| -32600 | `INVALID_REQUEST` | Invalid JSON-RPC request or unauthorized | +| -32601 | `METHOD_NOT_FOUND` | Unknown method or skill | +| -32602 | `INVALID_PARAMS` | Missing or invalid parameters | +| -32603 | `INTERNAL_ERROR` | Skill execution failed | +| -32001 | `TASK_NOT_FOUND` | Task ID not found | +| -32002 | `TASK_ALREADY_COMPLETED` | Cannot modify a completed task | +| -32003 | `UNAUTHORIZED` | Invalid or missing API key | +| -32004 | `BUDGET_EXCEEDED` | Request exceeds configured budget | +| -32005 | `PROVIDER_UNAVAILABLE` | No available providers | + +--- + +## Authentication + +All `/a2a` requests require a Bearer token via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server (`OMNIROUTE_API_KEY` is empty), authentication is bypassed. + +--- + +## File Structure + +``` +src/lib/a2a/ +โ”œโ”€โ”€ taskManager.ts # Task lifecycle (create/update/cancel/list), TTL, cleanup +โ”œโ”€โ”€ taskExecution.ts # Generic task executor with state management +โ”œโ”€โ”€ streaming.ts # SSE stream formatting, heartbeat, chunk/completion events +โ”œโ”€โ”€ routingLogger.ts # Routing decision logger (stats, history, retention) +โ””โ”€โ”€ skills/ + โ”œโ”€โ”€ smartRouting.ts # Smart routing skill (routes via /v1/chat/completions) + โ””โ”€โ”€ quotaManagement.ts # Quota management skill (natural-language quota queries) + +src/app/a2a/ +โ””โ”€โ”€ route.ts # Next.js API route handler (JSON-RPC 2.0 dispatch) + +open-sse/mcp-server/ +โ””โ”€โ”€ schemas/a2a.ts # Zod schemas (AgentCard, Task, JSON-RPC, SSE events) +``` + +--- + +## Comparison: MCP vs A2A + +| Feature | MCP Server | A2A Server | +| ----------------- | ---------------------------- | ------------------------------------------------- | +| **Protocol** | Model Context Protocol | Agent-to-Agent Protocol v0.3 | +| **Transport** | stdio / HTTP | HTTP (JSON-RPC 2.0) | +| **Discovery** | Tool listing via MCP | `/.well-known/agent.json` | +| **Granularity** | 16 individual tools | 2 high-level skills | +| **Best for** | IDE agents (Cursor, VS Code) | Multi-agent systems (LangChain, CrewAI) | +| **Streaming** | Not supported | SSE via `message/stream` | +| **Task tracking** | No | Full lifecycle (submitted โ†’ completed) | +| **Observability** | Audit log per tool call | Cost envelope + resilience trace + policy verdict | + +--- + +## Licencia + +Part of [OmniRoute](https://github.com/diegosouzapw/OmniRoute) โ€” MIT License. diff --git a/docs/i18n/fi/A2A-SERVER.md b/docs/i18n/fi/A2A-SERVER.md deleted file mode 100644 index 01531ff482..0000000000 --- a/docs/i18n/fi/A2A-SERVER.md +++ /dev/null @@ -1,200 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/A2A-SERVER.md) - ---- - -# OmniRoute A2A Server Documentation - -> Agent-to-Agent Protocol v0.3 โ€” OmniRoute as an intelligent routing agent - -## Agent Discovery - -```bash -curl http://localhost:20128/.well-known/agent.json -``` - -Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements. - ---- - -## Authentication - -All `/a2a` requests require an API key via the `Authorization` header: - -``` -Authorization: Bearer YOUR_OMNIROUTE_API_KEY -``` - -If no API key is configured on the server, authentication is bypassed. - ---- - -## JSON-RPC 2.0 Methods - -### `message/send` โ€” Synchronous Execution - -Sends a message to a skill and waits for the complete response. - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{ - "jsonrpc": "2.0", - "id": "1", - "method": "message/send", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Write a hello world in Python"}], - "metadata": {"model": "auto", "combo": "fast-coding"} - } - }' -``` - -**Response:** - -```json -{ - "jsonrpc": "2.0", - "id": "1", - "result": { - "task": { "id": "uuid", "state": "completed" }, - "artifacts": [{ "type": "text", "content": "..." }], - "metadata": { - "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)", - "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, - "resilience_trace": [ - { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." } - ], - "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } - } - } -} -``` - -### `message/stream` โ€” SSE Streaming - -Same as `message/send` but returns Server-Sent Events for real-time streaming. - -```bash -curl -N -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{ - "jsonrpc": "2.0", - "id": "1", - "method": "message/stream", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Explain quantum computing"}] - } - }' -``` - -**SSE Events:** - -``` -data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}} - -: heartbeat 2026-03-03T17:00:00Z - -data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} -``` - -### `tasks/get` โ€” Query Task Status - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' -``` - -### `tasks/cancel` โ€” Cancel a Task - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' -``` - ---- - -## Available Skills - -| Skill | Description | -| :----------------- | :------------------------------------------------------------------------------------------------------------------------------ | -| `smart-routing` | Routes prompts through OmniRoute's intelligent pipeline. Returns response with routing explanation, cost, and resilience trace. | -| `quota-management` | Answers natural-language queries about provider quotas, suggests free combos, and provides quota rankings. | - ---- - -## Task Lifecycle - -``` -submitted โ†’ working โ†’ completed - โ†’ failed - โ†’ cancelled -``` - -- Tasks expire after 5 minutes (configurable) -- Terminal states: `completed`, `failed`, `cancelled` -- Event log tracks every state transition - ---- - -## Error Codes - -| Code | Meaning | -| :----- | :----------------------------- | -| -32700 | Parse error (invalid JSON) | -| -32600 | Invalid request / Unauthorized | -| -32601 | Method or skill not found | -| -32602 | Invalid params | -| -32603 | Internal error | - ---- - -## Integration Examples - -### Python (requests) - -```python -import requests - -resp = requests.post("http://localhost:20128/a2a", json={ - "jsonrpc": "2.0", "id": "1", - "method": "message/send", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Hello"}] - } -}, headers={"Authorization": "Bearer YOUR_KEY"}) - -result = resp.json()["result"] -print(result["artifacts"][0]["content"]) -print(result["metadata"]["routing_explanation"]) -``` - -### TypeScript (fetch) - -```typescript -const resp = await fetch("http://localhost:20128/a2a", { - method: "POST", - headers: { - "Content-Type": "application/json", - Authorization: "Bearer YOUR_KEY", - }, - body: JSON.stringify({ - jsonrpc: "2.0", - id: "1", - method: "message/send", - params: { - skill: "smart-routing", - messages: [{ role: "user", content: "Hello" }], - }, - }), -}); -const { result } = await resp.json(); -console.log(result.metadata.routing_explanation); -``` diff --git a/docs/i18n/fi/API_REFERENCE.md b/docs/i18n/fi/API_REFERENCE.md deleted file mode 100644 index b878605221..0000000000 --- a/docs/i18n/fi/API_REFERENCE.md +++ /dev/null @@ -1,455 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/API_REFERENCE.md) - ---- - -# API Reference - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/API_REFERENCE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/API_REFERENCE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/API_REFERENCE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/API_REFERENCE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/API_REFERENCE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/API_REFERENCE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/API_REFERENCE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/API_REFERENCE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/API_REFERENCE.md) - -Complete reference for all OmniRoute API endpoints. - ---- - -## Table of Contents - -- [Chat Completions](#chat-completions) -- [Embeddings](#embeddings) -- [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`. - -### ACP Agents - -| Endpoint | Method | Description | -| ----------------- | ------ | -------------------------------------------------------- | -| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | -| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | -| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | - -GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). - -### Resilience & Rate Limits - -| Endpoint | Method | Description | -| ----------------------- | ------- | ------------------------------- | -| `/api/resilience` | 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` diff --git a/docs/i18n/fi/ARCHITECTURE.md b/docs/i18n/fi/ARCHITECTURE.md deleted file mode 100644 index 4ea06a29f2..0000000000 --- a/docs/i18n/fi/ARCHITECTURE.md +++ /dev/null @@ -1,787 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/ARCHITECTURE.md) - ---- - -# OmniRoute Architecture - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/ARCHITECTURE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/ARCHITECTURE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/ARCHITECTURE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/ARCHITECTURE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/ARCHITECTURE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/ARCHITECTURE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/ARCHITECTURE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/ARCHITECTURE.md) - -_Last updated: 2026-03-04_ - -## 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 (`...`) for reasoning models -- Response sanitization for strict OpenAI SDK compatibility -- Role normalization (developerโ†’system, systemโ†’user) for cross-provider compatibility -- Structured output conversion (json_schema โ†’ Gemini responseSchema) -- Local persistence for providers, keys, aliases, combos, settings, pricing -- Usage/cost tracking and request logging -- Optional cloud sync for multi-device/state sync -- IP allowlist/blocklist for API access control -- Thinking budget management (passthrough/auto/custom/adaptive) -- Global system prompt injection -- Session tracking and fingerprinting -- Per-account enhanced rate limiting with provider-specific profiles -- Circuit breaker pattern for provider resilience -- Anti-thundering herd protection with mutex locking -- Signature-based request deduplication cache -- Domain layer: model availability, cost rules, fallback policy, lockout policy -- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) -- Policy engine for centralized request evaluation (lockout โ†’ budget โ†’ fallback) -- Request telemetry with p50/p95/p99 latency aggregation -- Correlation ID (X-Request-Id) for end-to-end tracing -- Compliance audit logging with opt-out per API key -- Eval framework for LLM quality assurance -- Resilience UI dashboard with real-time circuit breaker status -- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) - -Primary runtime model: - -- Next.js 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[(storage.sqlite)] - UDB[(usage tables + log artifacts)] - end - - subgraph Upstreams[Upstream Providers] - P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/Qoder/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/route.ts` (GET) -- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) -- OAuth: `src/app/api/oauth/*` -- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` -- Usage: `src/app/api/usage/*` -- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` -- CLI tooling helpers: `src/app/api/cli-tools/*` -- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) -- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) -- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) -- Sessions: `src/app/api/sessions` (GET) -- Rate limits: `src/app/api/rate-limits` (GET) -- Resilience: `src/app/api/resilience` (GET/PATCH) โ€” provider profiles, circuit breaker, rate limit state -- Resilience reset: `src/app/api/resilience/reset` (POST) โ€” reset breakers + cooldowns -- Cache stats: `src/app/api/cache/stats` (GET/DELETE) -- Model availability: `src/app/api/models/availability` (GET/POST) -- Telemetry: `src/app/api/telemetry/summary` (GET) -- Budget: `src/app/api/usage/budget` (GET/POST) -- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) -- Compliance audit: `src/app/api/compliance/audit-log` (GET) -- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) -- Policies: `src/app/api/policies` (GET/POST) - -## 2) SSE + 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` -- Response sanitization: `open-sse/handlers/responseSanitizer.ts` -- Role normalization: `open-sse/services/roleNormalizer.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`, `qoder.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 (SQLite): - -- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) -- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) -- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) -- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** - -Usage persistence: - -- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) -- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` -- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) -- legacy JSON files are migrated to SQLite by startup migrations when present - -Domain State DB (SQLite): - -- `src/lib/db/domainState.ts` โ€” CRUD operations 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: - -- primary runtime DB: `${DATA_DIR}/storage.sqlite` -- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) -- structured call payload archives: `${DATA_DIR}/call_logs/` -- optional translator/request debug sessions: `/logs/...` - -## Deployment Topology - -```mermaid -flowchart LR - 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[(storage.sqlite)] - UsageDB[(usage tables + log artifacts)] - end - - subgraph External[External Services] - Providers[AI Providers] - SyncCloud[Cloud Sync Service] - end - - CLI --> Next - Browser --> Next - Next --> Core - Next --> MainDB - Core --> MainDB - Core --> UsageDB - Core --> Providers - Next --> SyncCloud -``` - -## Module Mapping (Decision-Critical) - -### Route and API Modules - -- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs -- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) -- `src/app/api/providers*`: provider CRUD, validation, testing -- `src/app/api/provider-nodes*`: custom compatible node management -- `src/app/api/provider-models`: custom model management (CRUD) -- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) -- `src/app/api/oauth/*`: OAuth/device-code flows -- `src/app/api/keys*`: local API key lifecycle -- `src/app/api/models/alias`: alias management -- `src/app/api/combos*`: fallback combo management -- `src/app/api/pricing`: pricing overrides for cost calculation -- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) -- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) -- `src/app/api/usage/*`: usage and logs APIs -- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers -- `src/app/api/cli-tools/*`: local CLI config writers/checkers -- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) -- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) -- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) -- `src/app/api/sessions`: active session listing (GET) -- `src/app/api/rate-limits`: per-account rate limit status (GET) - -### Routing and Execution Core - -- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop -- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup -- `open-sse/executors/*`: provider-specific network and format behavior - -### Translation Registry and Format Converters - -- `open-sse/translator/index.ts`: translator registry and orchestration -- Request translators: `open-sse/translator/request/*` -- Response translators: `open-sse/translator/response/*` -- Format constants: `open-sse/translator/formats.ts` - -### Persistence - -- `src/lib/db/*`: persistent config/state and domain persistence on SQLite -- `src/lib/localDb.ts`: compatibility re-export for DB modules -- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables - -## Provider Executor Coverage (Strategy Pattern) - -Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. - -| Executor | Provider(s) | Special Handling | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | -| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, Qoder, 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 | -| Qoder | openai | OAuth (Basic) | โœ… | โœ… | โœ… | โš ๏ธ Per request | -| OpenRouter | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| GLM/Kimi/MiniMax | claude | API Key | โœ… | โœ… | โŒ | โŒ | -| DeepSeek | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Groq | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| xAI (Grok) | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Mistral | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Perplexity | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Together AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Fireworks AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Cerebras | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Cohere | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| NVIDIA NIM | openai | API Key | โœ… | โœ… | โŒ | โŒ | - -## Format Translation Coverage - -Detected source formats include: - -- `openai` -- `openai-responses` -- `claude` -- `gemini` - -Target formats include: - -- OpenAI chat/Responses -- Claude -- Gemini/Gemini-CLI/Antigravity envelope -- Kiro -- Cursor - -Translations use **OpenAI as the hub format** โ€” all conversions go through OpenAI as intermediate: - -``` -Source Format โ†’ OpenAI (hub) โ†’ Target Format -``` - -Translations are selected dynamically based on source payload shape and provider target format. - -Additional processing layers in the translation pipeline: - -- **Response sanitization** โ€” Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance -- **Role normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI targets; merges `system` โ†’ `user` for models that reject the system role (GLM, ERNIE) -- **Think tag extraction** โ€” Parses `...` blocks from content into `reasoning_content` field -- **Structured output** โ€” Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` - -## Supported API Endpoints - -| 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 `/logs//` 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 - -- SQLite schema migrations and auto-upgrade hooks at startup -- legacy JSON โ†’ SQLite migration compatibility path - -## Observability and Operational Signals - -Runtime visibility sources: - -- console logs from `src/sse/utils/logger.ts` -- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) -- textual request status log in `log.txt` (optional/compat) -- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` -- dashboard usage endpoints (`/api/usage/*`) for UI consumption - -## Security-Sensitive Boundaries - -- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing -- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning -- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format -- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level -- Cloud sync endpoints rely on API key auth + machine id semantics - -## Environment and Runtime Matrix - -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` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. -2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. -3. Request logger writes full headers/body when enabled; treat log directory as sensitive. -4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. -5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. -6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). -7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). -8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). - -## Operational Verification Checklist - -- Build from source: `npm run build` -- Build Docker image: `docker build -t omniroute .` -- Start service and verify: -- `GET /api/settings` -- `GET /api/v1/models` -- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/fi/AUTO-COMBO.md b/docs/i18n/fi/AUTO-COMBO.md deleted file mode 100644 index 2166e41dff..0000000000 --- a/docs/i18n/fi/AUTO-COMBO.md +++ /dev/null @@ -1,67 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/AUTO-COMBO.md) - ---- - -# OmniRoute Auto-Combo Engine - -> Self-managing model chains with adaptive scoring - -## How It Works - -The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**: - -| Factor | Weight | Description | -| :--------- | :----- | :---------------------------------------------- | -| Quota | 0.20 | Remaining capacity [0..1] | -| Health | 0.25 | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 | -| CostInv | 0.20 | Inverse cost (cheaper = higher score) | -| LatencyInv | 0.15 | Inverse p95 latency (faster = higher) | -| TaskFit | 0.10 | Model ร— task type fitness score | -| Stability | 0.10 | Low variance in latency/errors | - -## Mode Packs - -| Pack | Focus | Key Weight | -| :---------------------- | :----------- | :--------------- | -| ๐Ÿš€ **Ship Fast** | Speed | latencyInv: 0.35 | -| ๐Ÿ’ฐ **Cost Saver** | Economy | costInv: 0.40 | -| ๐ŸŽฏ **Quality First** | Best model | taskFit: 0.40 | -| ๐Ÿ“ก **Offline Friendly** | Availability | quota: 0.40 | - -## Self-Healing - -- **Temporary exclusion**: Score < 0.2 โ†’ excluded for 5 min (progressive backoff, max 30 min) -- **Circuit breaker awareness**: OPEN โ†’ auto-excluded; HALF_OPEN โ†’ probe requests -- **Incident mode**: >50% OPEN โ†’ disable exploration, maximize stability -- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout - -## Bandit Exploration - -5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode. - -## API - -```bash -# Create auto-combo -curl -X POST http://localhost:20128/api/combos/auto \ - -H "Content-Type: application/json" \ - -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}' - -# List auto-combos -curl http://localhost:20128/api/combos/auto -``` - -## Task Fitness - -30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` โ†’ high coding score). - -## Files - -| File | Purpose | -| :------------------------------------------- | :------------------------------------ | -| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization | -| `open-sse/services/autoCombo/taskFitness.ts` | Model ร— task fitness lookup | -| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap | -| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode | -| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles | -| `src/app/api/combos/auto/route.ts` | REST API | diff --git a/docs/i18n/fi/CHANGELOG.md b/docs/i18n/fi/CHANGELOG.md index 5aa4367d18..852d728046 100644 --- a/docs/i18n/fi/CHANGELOG.md +++ b/docs/i18n/fi/CHANGELOG.md @@ -1,12 +1,92 @@ # Changelog (Suomi) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CHANGELOG.md) --- - ## [Unreleased] +### ๐Ÿ› ๏ธ Maintenance + +- **AGENTS.md rewrite:** Condensed from 297โ†’153 lines. Added build/lint/test commands (including single-test execution), code style guidelines (Prettier, TypeScript, ESLint, naming, imports, error handling, security), and trimmed verbose architecture tables for AI agent consumption. + +## [3.4.2] - 2026-04-01 + +### ๐Ÿ› Bug Fixes + +- **CI Stabilization:** Fixed failing analytics/settings Playwright selectors and request assertions so GitHub Actions E2E runs pass reliably across localized UIs and switch-based controls. +- **Deterministic Tests:** Removed date-sensitive quota fixtures from Copilot usage tests and aligned idempotency/model catalog tests with the merged runtime behavior. +- **MCP Type Hardening:** Removed zero-budget explicit `any` regressions from the MCP server tool registration path, restoring the `check:any-budget:t11` workflow gate. + +### ๐Ÿ› ๏ธ Maintenance + +- **Release Branch Integration:** Consolidated the active feature branches into `release/v3.4.2` on top of current `main` and validated the branch with lint, unit, coverage, build, and CI-mode E2E runs. + +## [3.4.1] - 2026-03-31 + +> [!WARNING] +> **BREAKING CHANGE: request logging, retention, and logging environment variables have been redesigned.** +> On the first startup after upgrading, OmniRoute archives legacy request logs from `DATA_DIR/logs/`, legacy `DATA_DIR/call_logs/`, and `DATA_DIR/log.txt` into `DATA_DIR/log_archives/*.zip`, then removes the deprecated layout and switches to the new unified artifact format under `DATA_DIR/call_logs/`. + +### โœจ New Features + +- **.ENV Migration Utility:** Included `scripts/migrate-env.mjs` to seamlessly migrate ` Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` - ---- - -## Step 2 โ€” Install CLI Tools - -All npm-based tools require Node.js 18+: - -```bash -# Claude Code (Anthropic) -npm install -g @anthropic-ai/claude-code - -# OpenAI Codex -npm install -g @openai/codex - -# Gemini CLI (Google) -npm install -g @google/gemini-cli - -# OpenCode -npm install -g opencode-ai - -# Cline -npm install -g cline - -# KiloCode -npm install -g kilecode - -# Kiro CLI (Amazon โ€” requires curl + unzip) -apt-get install -y unzip # on Debian/Ubuntu -curl -fsSL https://cli.kiro.dev/install | bash -export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc -``` - -**Verify:** - -```bash -claude --version # 2.x.x -codex --version # 0.x.x -gemini --version # 0.x.x -opencode --version # x.x.x -cline --version # 2.x.x -kilocode --version # x.x.x (or: kilo --version) -kiro-cli --version # 1.x.x -``` - ---- - -## Step 3 โ€” Set Global Environment Variables - -Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`: - -```bash -# OmniRoute Universal Endpoint -export OPENAI_BASE_URL="http://localhost:20128/v1" -export OPENAI_API_KEY="sk-your-omniroute-key" -export ANTHROPIC_BASE_URL="http://localhost:20128/v1" -export ANTHROPIC_API_KEY="sk-your-omniroute-key" -export GEMINI_BASE_URL="http://localhost:20128/v1" -export GEMINI_API_KEY="sk-your-omniroute-key" -``` - -> For a **remote server** replace `localhost:20128` with the server IP or domain, -> e.g. `http://192.168.0.15:20128`. - ---- - -## Step 4 โ€” Configure Each Tool - -### Claude Code - -```bash -# Via CLI: -claude config set --global api-base-url http://localhost:20128/v1 - -# Or create ~/.claude/settings.json: -mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF -{ - "apiBaseUrl": "http://localhost:20128/v1", - "apiKey": "sk-your-omniroute-key" -} -EOF -``` - -**Test:** `claude "say hello"` - ---- - -### OpenAI Codex - -```bash -mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF -model: auto -apiKey: sk-your-omniroute-key -apiBaseUrl: http://localhost:20128/v1 -EOF -``` - -**Test:** `codex "what is 2+2?"` - ---- - -### Gemini CLI - -```bash -mkdir -p ~/.gemini && cat > ~/.gemini/settings.json << EOF -{ - "apiKey": "sk-your-omniroute-key", - "baseUrl": "http://localhost:20128/v1" -} -EOF -``` - -**Test:** `gemini "hello"` - ---- - -### OpenCode - -```bash -mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF -[provider.openai] -base_url = "http://localhost:20128/v1" -api_key = "sk-your-omniroute-key" -EOF -``` - -**Test:** `opencode` - ---- - -### Cline (CLI or VS Code) - -**CLI mode:** - -```bash -mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF -{ - "apiProvider": "openai", - "openAiBaseUrl": "http://localhost:20128/v1", - "openAiApiKey": "sk-your-omniroute-key" -} -EOF -``` - -**VS Code mode:** -Cline extension settings โ†’ API Provider: `OpenAI Compatible` โ†’ Base URL: `http://localhost:20128/v1` - -Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ Cline โ†’ Apply Config**. - ---- - -### KiloCode (CLI or VS Code) - -**CLI mode:** - -```bash -kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key -``` - -**VS Code settings:** - -```json -{ - "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", - "kilo-code.apiKey": "sk-your-omniroute-key" -} -``` - -Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ KiloCode โ†’ Apply Config**. - ---- - -### Continue (VS Code Extension) - -Edit `~/.continue/config.yaml`: - -```yaml -models: - - name: OmniRoute - provider: openai - model: auto - apiBase: http://localhost:20128/v1 - apiKey: sk-your-omniroute-key - default: true -``` - -Restart VS Code after editing. - ---- - -### Kiro CLI (Amazon) - -```bash -# Login to your AWS/Kiro account: -kiro-cli login - -# The CLI uses its own auth โ€” OmniRoute is not needed as backend for Kiro CLI itself. -# Use kiro-cli alongside OmniRoute for other tools. -kiro-cli status -``` - ---- - -### Cursor (Desktop App) - -> **Note:** Cursor routes requests through its cloud. For OmniRoute integration, -> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL. - -Via GUI: **Settings โ†’ Models โ†’ OpenAI API Key** - -- Base URL: `https://your-domain.com/v1` -- API Key: your OmniRoute key - ---- - -## Dashboard Auto-Configuration - -The OmniRoute dashboard automates configuration for most tools: - -1. Go to `http://localhost:20128/dashboard/cli-tools` -2. Expand any tool card -3. Select your API key from the dropdown -4. Click **Apply Config** (if tool is detected as installed) -5. Or copy the generated config snippet manually - ---- - -## Built-in Agents: Droid & OpenClaw - -**Droid** and **OpenClaw** are AI agents built directly into OmniRoute โ€” no installation needed. -They run as internal routes and use OmniRoute's model routing automatically. - -- Access: `http://localhost:20128/dashboard/agents` -- Configure: same combos and providers as all other tools -- No API key or CLI install required - ---- - -## Available API Endpoints - -| Endpoint | Description | Use For | -| -------------------------- | ----------------------------- | --------------------------- | -| `/v1/chat/completions` | Standard chat (all providers) | All modern tools | -| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows | -| `/v1/completions` | Legacy text completions | Older tools using `prompt:` | -| `/v1/embeddings` | Text embeddings | RAG, search | -| `/v1/images/generations` | Image generation | DALL-E, Flux, etc. | -| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS | -| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI | - ---- - -## Troubleshooting - -| Error | Cause | Fix | -| ------------------------- | ----------------------- | ------------------------------------------ | -| `Connection refused` | OmniRoute not running | `pm2 start omniroute` | -| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` | -| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` | -| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` | -| CLI shows "not installed" | Binary not in PATH | Check `which ` | -| `kiro-cli: not found` | Not in PATH | `export PATH="$HOME/.local/bin:$PATH"` | - ---- - -## Quick Setup Script (One Command) - -```bash -# Install all CLIs and configure for OmniRoute (replace with your key and server URL) -OMNIROUTE_URL="http://localhost:20128/v1" -OMNIROUTE_KEY="sk-your-omniroute-key" - -npm install -g @anthropic-ai/claude-code @openai/codex @google/gemini-cli opencode-ai cline kilecode - -# Kiro CLI -apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash - -# Write configs -mkdir -p ~/.claude ~/.codex ~/.gemini ~/.config/opencode ~/.continue - -cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" -cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" -cat > ~/.gemini/settings.json <<< "{\"apiKey\":\"$OMNIROUTE_KEY\",\"baseUrl\":\"$OMNIROUTE_URL\"}" -cat >> ~/.bashrc << EOF -export OPENAI_BASE_URL="$OMNIROUTE_URL" -export OPENAI_API_KEY="$OMNIROUTE_KEY" -export ANTHROPIC_BASE_URL="$OMNIROUTE_URL" -export ANTHROPIC_API_KEY="$OMNIROUTE_KEY" -EOF - -source ~/.bashrc -echo "โœ… All CLIs installed and configured for OmniRoute" -``` diff --git a/docs/i18n/fi/CODEBASE_DOCUMENTATION.md b/docs/i18n/fi/CODEBASE_DOCUMENTATION.md deleted file mode 100644 index e2d7950052..0000000000 --- a/docs/i18n/fi/CODEBASE_DOCUMENTATION.md +++ /dev/null @@ -1,593 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CODEBASE_DOCUMENTATION.md) - ---- - -# omniroute โ€” Codebase Documentation - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) - -> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. - ---- - -## 1. 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
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, Qoder, 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 | -| Qoder | 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"] -``` diff --git a/docs/i18n/fi/CONTRIBUTING.md b/docs/i18n/fi/CONTRIBUTING.md new file mode 100644 index 0000000000..993c124278 --- /dev/null +++ b/docs/i18n/fi/CONTRIBUTING.md @@ -0,0 +1,299 @@ +# Contributing to OmniRoute (Suomi) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CONTRIBUTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CONTRIBUTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CONTRIBUTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CONTRIBUTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CONTRIBUTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CONTRIBUTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CONTRIBUTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CONTRIBUTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CONTRIBUTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CONTRIBUTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CONTRIBUTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CONTRIBUTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CONTRIBUTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CONTRIBUTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CONTRIBUTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CONTRIBUTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CONTRIBUTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CONTRIBUTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CONTRIBUTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CONTRIBUTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CONTRIBUTING.md) + +--- + +Thank you for your interest in contributing! This guide covers everything you need to get started. + +--- + +## Development Setup + +### Prerequisites + +- **Node.js** >= 18 < 24 (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` | `20128` | Server port | +| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | Base URL for frontend | +| `JWT_SECRET` | (generate above) | JWT signing secret | +| `INITIAL_PASSWORD` | `CHANGEME` | First login password | +| `APP_LOG_LEVEL` | `info` | Log verbosity level | + +### Dashboard Settings + +The dashboard provides UI toggles for features that can also be configured via environment variables: + +| Setting Location | Toggle | Description | +| ------------------- | ------------------ | ------------------------------ | +| Settings โ†’ Advanced | Debug Mode | Enable debug request logs (UI) | +| Settings โ†’ General | Sidebar Visibility | Show/hide sidebar sections | + +These settings are stored in the database and persist across restarts, overriding env var defaults when set. + +### 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:20128/dashboard` +- **API**: `http://localhost:20128/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`, `mcp`, `a2a`, `memory`, `skills`. + +--- + +## Running Tests + +```bash +# All tests (unit + vitest + ecosystem + e2e) +npm run test:all + +# Single test file (Node.js native test runner โ€” most tests use this) +node --import tsx/esm --test tests/unit/your-file.test.mjs + +# Vitest (MCP server, autoCombo, cache) +npm run test:vitest + +# E2E tests (requires Playwright) +npm run test:e2e + +# Protocol clients E2E (MCP transports, A2A) +npm run test:protocols:e2e + +# Ecosystem compatibility tests +npm run test:ecosystem + +# Coverage (55% min statements/lines/functions; 60% branches) +npm run test:coverage +npm run coverage:report + +# Lint + format check +npm run lint +npm run check +``` + +Coverage notes: + +- `npm run test:coverage` measures source coverage for the main unit test suite, excludes `tests/**`, and includes `open-sse/**` +- `npm run coverage:report` prints the detailed file-by-file report from the latest coverage run +- `npm run test:coverage:legacy` preserves the older metric for historical comparison +- See `docs/COVERAGE_PLAN.md` for the phased coverage improvement roadmap + +Current test status: **122 unit test files** covering: + +- Provider translators and format conversion +- Rate limiting, circuit breaker, and resilience +- Semantic cache, idempotency, progress tracking +- Database operations and schema (21 DB modules) +- OAuth flows and authentication +- API endpoint validation (Zod v4) +- MCP server tools and scope enforcement +- Memory and Skills systems + +--- + +## Code Style + +- **ESLint** โ€” Run `npm run lint` before committing +- **Prettier** โ€” Auto-formatted via `lint-staged` on commit (2 spaces, semicolons, double quotes, 100 char width, es5 trailing commas) +- **TypeScript** โ€” All `src/` code uses `.ts`/`.tsx`; `open-sse/` uses `.ts`/`.js`; document with TSDoc (`@param`, `@returns`, `@throws`) +- **No `eval()`** โ€” ESLint enforces `no-eval`, `no-implied-eval`, `no-new-func` +- **Zod validation** โ€” Use Zod v4 schemas for all API input validation +- **Naming**: Files = camelCase/kebab-case, components = PascalCase, constants = UPPER_SNAKE + +--- + +## Project Structure + +``` +src/ # TypeScript (.ts / .tsx) +โ”œโ”€โ”€ app/ # Next.js 16 App Router +โ”‚ โ”œโ”€โ”€ (dashboard)/ # Dashboard pages (23 sections) +โ”‚ โ”œโ”€โ”€ api/ # API routes (51 directories) +โ”‚ โ””โ”€โ”€ login/ # Auth pages (.tsx) +โ”œโ”€โ”€ domain/ # Policy engine (policyEngine, comboResolver, costRules, etc.) +โ”œโ”€โ”€ lib/ # Core business logic (.ts) +โ”‚ โ”œโ”€โ”€ a2a/ # Agent-to-Agent v0.3 protocol server +โ”‚ โ”œโ”€โ”€ acp/ # Agent Communication Protocol registry +โ”‚ โ”œโ”€โ”€ compliance/ # Compliance policy engine +โ”‚ โ”œโ”€โ”€ db/ # SQLite database layer (21 modules + 16 migrations) +โ”‚ โ”œโ”€โ”€ memory/ # Persistent conversational memory +โ”‚ โ”œโ”€โ”€ oauth/ # OAuth providers, services, and utilities +โ”‚ โ”œโ”€โ”€ skills/ # Extensible skill framework +โ”‚ โ”œโ”€โ”€ usage/ # Usage tracking and cost calculation +โ”‚ โ””โ”€โ”€ localDb.ts # Re-export layer only โ€” never add logic here +โ”œโ”€โ”€ middleware/ # Request middleware (promptInjectionGuard) +โ”œโ”€โ”€ mitm/ # MITM proxy (cert, DNS, target routing) +โ”œโ”€โ”€ shared/ +โ”‚ โ”œโ”€โ”€ components/ # React components (.tsx) +โ”‚ โ”œโ”€โ”€ constants/ # Provider definitions (60+), MCP scopes, routing strategies +โ”‚ โ”œโ”€โ”€ utils/ # Circuit breaker, sanitizer, auth helpers +โ”‚ โ””โ”€โ”€ validation/ # Zod v4 schemas +โ””โ”€โ”€ sse/ # SSE proxy pipeline + +open-sse/ # @omniroute/open-sse workspace +โ”œโ”€โ”€ executors/ # 14 provider-specific request executors +โ”œโ”€โ”€ handlers/ # 11 request handlers (chat, responses, embeddings, images, etc.) +โ”œโ”€โ”€ mcp-server/ # MCP server (25 tools, 3 transports, 10 scopes) +โ”œโ”€โ”€ services/ # 36+ services (combo, autoCombo, rateLimitManager, etc.) +โ”œโ”€โ”€ translator/ # Format translators (OpenAI โ†” Claude โ†” Gemini โ†” Responses โ†” Ollama) +โ”œโ”€โ”€ transformer/ # Responses API transformer +โ””โ”€โ”€ utils/ # 22 utility modules (stream, TLS, proxy, logging) + +electron/ # Electron desktop app (cross-platform) + +tests/ +โ”œโ”€โ”€ unit/ # Node.js test runner (122 test files) +โ”œโ”€โ”€ integration/ # Integration tests +โ”œโ”€โ”€ e2e/ # Playwright tests +โ”œโ”€โ”€ security/ # Security tests +โ”œโ”€โ”€ translator/ # Translator-specific tests +โ””โ”€โ”€ load/ # Load tests + +docs/ # Documentation +โ”œโ”€โ”€ ARCHITECTURE.md # System architecture +โ”œโ”€โ”€ API_REFERENCE.md # All endpoints +โ”œโ”€โ”€ USER_GUIDE.md # Provider setup, CLI integration +โ”œโ”€โ”€ TROUBLESHOOTING.md # Common issues +โ”œโ”€โ”€ MCP-SERVER.md # MCP server (25 tools) +โ”œโ”€โ”€ A2A-SERVER.md # A2A agent protocol +โ”œโ”€โ”€ AUTO-COMBO.md # Auto-combo engine +โ”œโ”€โ”€ CLI-TOOLS.md # CLI tools integration +โ”œโ”€โ”€ COVERAGE_PLAN.md # Test coverage improvement plan +โ”œโ”€โ”€ openapi.yaml # OpenAPI specification +โ””โ”€โ”€ adr/ # Architecture Decision Records +``` + +--- + +## Adding a New Provider + +### Step 1: Register Provider Constants + +Add to `src/shared/constants/providers.ts` โ€” Zod-validated at module load. + +### Step 2: Add Executor (if custom logic needed) + +Create executor in `open-sse/executors/your-provider.ts` extending the base executor. + +### Step 3: Add Translator (if non-OpenAI format) + +Create request/response translators in `open-sse/translator/`. + +### Step 4: Add OAuth Config (if OAuth-based) + +Add OAuth credentials in `src/lib/oauth/constants/oauth.ts` and service in `src/lib/oauth/services/`. + +### Step 5: Register Models + +Add model definitions in `open-sse/config/providerRegistry.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 +- [ ] All inputs validated with Zod schemas +- [ ] CHANGELOG updated (if user-facing change) +- [ ] Documentation updated (if applicable) + +--- + +## Releasing + +Releases are managed via the `/generate-release` workflow. When a new GitHub Release is created, the package is **automatically published to npm** via GitHub Actions. + +--- + +## Getting Help + +- **Architecture**: See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) +- **API Reference**: See [`docs/API_REFERENCE.md`](docs/API_REFERENCE.md) +- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **ADRs**: See `docs/adr/` for architectural decision records diff --git a/docs/i18n/fi/FEATURES.md b/docs/i18n/fi/FEATURES.md deleted file mode 100644 index 564e8059c9..0000000000 --- a/docs/i18n/fi/FEATURES.md +++ /dev/null @@ -1,147 +0,0 @@ -# OmniRoute โ€” Dashboard Features Gallery (Suomi) - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) - -> ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../docs/FEATURES.md) - ---- - -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 (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. - -![Providers Dashboard](screenshots/01-providers.png) - ---- - -## ๐ŸŽจ Combos - -Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. - -![Combos Dashboard](screenshots/02-combos.png) - ---- - -## ๐Ÿ“Š Analytics - -Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. - -![Analytics Dashboard](screenshots/03-analytics.png) - ---- - -## ๐Ÿฅ System Health - -Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. - -![Health Dashboard](screenshots/04-health.png) - ---- - -## ๐Ÿ”ง Translator Playground - -Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). - -![Translator Playground](screenshots/05-translator.png) - ---- - -## ๐ŸŽฎ Model Playground _(v2.0.9+)_ - -Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. - ---- - -## ๐ŸŽจ Themes _(v2.0.5+)_ - -Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. - ---- - -## โš™๏ธ Settings - -Comprehensive settings panel with tabs: - -- **General** โ€” System storage, backup management (export/import database) -- **Appearance** โ€” Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls -- **Security** โ€” API endpoint protection, custom provider blocking, IP filtering, session info -- **Routing** โ€” Model aliases, background task degradation -- **Resilience** โ€” Rate limit persistence, circuit breaker tuning -- **Advanced** โ€” Configuration overrides - -![Settings Dashboard](screenshots/06-settings.png) - ---- - -## ๐Ÿ”ง CLI Tools - -One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. - -![CLI Tools Dashboard](screenshots/07-cli-tools.png) - ---- - -## ๐Ÿค– CLI Agents _(v2.0.11+)_ - -Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: - -- **Installation status** โ€” Installed / Not Found with version detection -- **Protocol badges** โ€” stdio, HTTP, etc. -- **Custom agents** โ€” Register any CLI tool via form (name, binary, version command, spawn args) -- **CLI Fingerprint Matching** โ€” Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP - ---- - -## ๐Ÿ–ผ๏ธ Media _(v2.0.3+)_ - -Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. - ---- - -## ๐Ÿ“ Request Logs - -Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. - -![Usage Logs](screenshots/08-usage.png) - ---- - -## ๐ŸŒ API Endpoint - -Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. - -![Endpoint Dashboard](screenshots/09-endpoint.png) - ---- - -## ๐Ÿ”‘ API Key Management - -Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. - ---- - -## ๐Ÿ“‹ Audit Log - -Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. - ---- - -## ๐Ÿ–ฅ๏ธ Desktop Application - -Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. - -Key features: - -- Server readiness polling (no blank screen on cold start) -- System tray with port management -- Content Security Policy -- Single-instance lock -- Auto-update on restart -- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) -- Hardened Electron build packaging โ€” symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+) - -๐Ÿ“– See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/fi/MCP-SERVER.md b/docs/i18n/fi/MCP-SERVER.md deleted file mode 100644 index 829acd30b1..0000000000 --- a/docs/i18n/fi/MCP-SERVER.md +++ /dev/null @@ -1,87 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/MCP-SERVER.md) - ---- - -# OmniRoute MCP Server Documentation - -> Model Context Protocol server with 16 intelligent tools - -## Installation - -OmniRoute MCP is built-in. Start it with: - -```bash -omniroute --mcp -``` - -Or via the open-sse transport: - -```bash -# HTTP streamable transport (port 20130) -omniroute --dev # MCP auto-starts on /mcp endpoint -``` - -## IDE Configuration - -See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup. - ---- - -## Essential Tools (8) - -| Tool | Description | -| :------------------------------ | :--------------------------------------- | -| `omniroute_get_health` | Gateway health, circuit breakers, uptime | -| `omniroute_list_combos` | All configured combos with models | -| `omniroute_get_combo_metrics` | Performance metrics for a specific combo | -| `omniroute_switch_combo` | Switch active combo by ID/name | -| `omniroute_check_quota` | Quota status per provider or all | -| `omniroute_route_request` | Send a chat completion through OmniRoute | -| `omniroute_cost_report` | Cost analytics for a time period | -| `omniroute_list_models_catalog` | Full model catalog with capabilities | - -## Advanced Tools (8) - -| Tool | Description | -| :--------------------------------- | :---------------------------------------------- | -| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | -| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | -| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | -| `omniroute_test_combo` | Live-test all models in a combo | -| `omniroute_get_provider_metrics` | Detailed metrics for one provider | -| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | -| `omniroute_explain_route` | Explain a past routing decision | -| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | - -## Authentication - -MCP tools are authenticated via API key scopes. Each tool requires specific scopes: - -| Scope | Tools | -| :------------- | :----------------------------------------------- | -| `read:health` | get_health, get_provider_metrics | -| `read:combos` | list_combos, get_combo_metrics | -| `write:combos` | switch_combo | -| `read:quota` | check_quota | -| `write:route` | route_request, simulate_route, test_combo | -| `read:usage` | cost_report, get_session_snapshot, explain_route | -| `write:config` | set_budget_guard, set_resilience_profile | -| `read:models` | list_models_catalog, best_combo_for_task | - -## Audit Logging - -Every tool call is logged to `mcp_tool_audit` with: - -- Tool name, arguments, result -- Duration (ms), success/failure -- API key hash, timestamp - -## Files - -| File | Purpose | -| :------------------------------------------- | :------------------------------------------ | -| `open-sse/mcp-server/server.ts` | MCP server creation + 16 tool registrations | -| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport | -| `open-sse/mcp-server/auth.ts` | API key + scope validation | -| `open-sse/mcp-server/audit.ts` | Tool call audit logging | -| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers | diff --git a/docs/i18n/fi/README.md b/docs/i18n/fi/README.md index aa443b3a79..3478a21b3a 100644 --- a/docs/i18n/fi/README.md +++ b/docs/i18n/fi/README.md @@ -1,12 +1,12 @@ # ๐Ÿš€ OmniRoute โ€” The Free AI Gateway (Suomi) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/README.md) --- ### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback. -_Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._ +_Your universal API proxy โ€” one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._ **Chat Completions โ€ข Embeddings โ€ข Image Generation โ€ข Video โ€ข Music โ€ข Audio โ€ข Reranking โ€ข **Web Search** โ€ข MCP Server โ€ข A2A Protocol โ€ข 100% TypeScript** @@ -46,15 +46,17 @@ _Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now wi > - `APP_LOG_FILE_PATH` > - `APP_LOG_MAX_FILE_SIZE` > - `APP_LOG_RETENTION_DAYS` +> - `APP_LOG_MAX_FILES` > - `APP_LOG_LEVEL` > - `APP_LOG_FORMAT` > - `CALL_LOG_RETENTION_DAYS` +> - `CALL_LOG_MAX_ENTRIES` > > For release details and upgrade notes, see the [CHANGELOG](CHANGELOG.md). --- -## ๐Ÿ†• What's New in v3.0.0 +## ๐Ÿ†• What's New > **Upgrading from v2.9.5?** โ€” See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes. @@ -274,7 +276,7 @@ Developers pay $20โ€“200/month for Claude Pro, Codex Pro, or GitHub Copilot. Eve - **Smart 4-Tier Fallback** โ€” If subscription quota runs out, automatically redirects to API Key โ†’ Cheap โ†’ Free with zero manual intervention - **Real-Time Quota Tracking** โ€” Shows token consumption in real-time with reset countdown (5h, daily, weekly) - **Multi-Account Support** โ€” Multiple accounts per provider with auto round-robin โ€” when one runs out, switches to the next -- **Custom Combos** โ€” Customizable fallback chains with 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Custom Combos** โ€” Customizable fallback chains with 9 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random) - **Codex Business Quotas** โ€” Business/Team workspace quota monitoring directly in the dashboard @@ -286,7 +288,7 @@ OpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If **How OmniRoute solves it:** -- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 67+ providers +- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 60+ providers - **Format Translation** โ€” Automatic and transparent: OpenAI โ†” Claude โ†” Gemini โ†” Responses API - **Response Sanitization** โ€” Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+ - **Role Normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI providers; `system` โ†’ `user` for GLM/ERNIE @@ -372,7 +374,7 @@ Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code.. - **CLI Tools Dashboard** โ€” Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline - **GitHub Copilot Config Generator** โ€” Generates `chatLanguageModels.json` for VS Code with bulk model selection - **Onboarding Wizard** โ€” Guided 4-step setup for first-time users -- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 67+ providers +- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 60+ providers @@ -419,7 +421,7 @@ When a call fails, the dev doesn't know if it was a rate limit, expired token, w - **SQLite Proxy Logs** โ€” Persistent logs that survive server restarts - **Translator Playground** โ€” 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time) - **Request Telemetry** โ€” p50/p95/p99 latency + X-Request-Id tracing -- **File-Based Logging with Rotation** โ€” Console interceptor captures everything to JSON log with size-based rotation +- **File-Based Logging with Rotation** โ€” App logs rotate by size, retention days, and archive count; call log artifacts rotate by retention days and file count - **System Info Report** โ€” `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage. @@ -514,7 +516,7 @@ Developers who want all responses in a specific language, with a specific tone, - **System Prompt Injection** โ€” Global prompt applied to all requests - **Thinking Budget Validation** โ€” Reasoning token allocation control per request (passthrough, auto, custom, adaptive) -- **6 Routing Strategies** โ€” Global strategies that determine how requests are distributed +- **9 Routing Strategies** โ€” Global strategies that determine how requests are distributed - **Wildcard Router** โ€” `provider/*` patterns route dynamically to any provider - **Combo Enable/Disable Toggle** โ€” Toggle combos directly from the dashboard - **Provider Toggle** โ€” Enable/disable all connections for a provider with one click @@ -581,7 +583,7 @@ Different clients should have least-privilege access to tool categories. **How OmniRoute solves it:** -- 9 granular MCP scopes for controlled tool access +- 10 granular MCP scopes for controlled tool access - Scope enforcement and visibility in MCP management UI - Safe default posture for operational tooling @@ -1325,19 +1327,19 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. ### ๐Ÿค– Agent & Protocol Operations (v2.0) -| Feature | What It Does | -| ------------------------------------- | -------------------------------------------------------------------------------------------------- | -| ๐Ÿ”ง **MCP Server (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) | -| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | -| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | -| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | -| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | -| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | -| ๐Ÿ” **MCP Scope Enforcement** | 9 granular scope permissions for controlled tool access | -| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | -| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | -| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | -| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | +| Feature | What It Does | +| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| ๐Ÿ”ง **MCP Server (25 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools | +| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | +| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | +| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | +| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | +| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | +| ๐Ÿ” **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access | +| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | +| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | +| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | +| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | ### ๐Ÿง  Routing & Intelligence @@ -1348,7 +1350,7 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. | ๐Ÿ”„ **Format Translation** | OpenAI โ†” Claude โ†” Gemini โ†” Responses with schema-safe conversions | | ๐Ÿ‘ฅ **Multi-Account Support** | Multiple accounts per provider with intelligent selection | | ๐Ÿ”„ **Auto Token Refresh** | OAuth tokens refresh automatically with retry | -| ๐ŸŽจ **Custom Combos** | 6 balancing strategies + fallback chain control | +| ๐ŸŽจ **Custom Combos** | 9 balancing strategies + fallback chain control | | ๐ŸŒ **Wildcard Router** | `provider/*` dynamic routing | | ๐Ÿง  **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits | | ๐Ÿ”€ **Model Aliases** | Built-in + custom model aliasing and migration safety | @@ -1949,6 +1951,7 @@ opencode - Request artifacts are written to `DATA_DIR/call_logs/` as one JSON file per request - Enable pipeline capture from Dashboard โ†’ Logs โ†’ Request Logs if you need detailed per-stage payloads - Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log` +- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed **Connection test shows "Invalid" for OpenAI-compatible providers** diff --git a/docs/i18n/fi/RELEASE_CHECKLIST.md b/docs/i18n/fi/RELEASE_CHECKLIST.md deleted file mode 100644 index 903e812c3f..0000000000 --- a/docs/i18n/fi/RELEASE_CHECKLIST.md +++ /dev/null @@ -1,37 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/RELEASE_CHECKLIST.md) - ---- - -# Release Checklist - -Use this checklist before tagging or publishing a new OmniRoute release. - -## Version and Changelog - -1. Bump `package.json` version (`x.y.z`) in the release branch. -2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: - - `## [x.y.z] โ€” YYYY-MM-DD` -3. Keep `## [Unreleased]` as the first changelog section for upcoming work. -4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. - -## API Docs - -1. Update `docs/openapi.yaml`: - - `info.version` must equal `package.json` version. -2. Validate endpoint examples if API contracts changed. - -## Runtime Docs - -1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. -2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. -3. Update localized docs if source docs changed significantly. - -## Automated Check - -Run the sync guard locally before opening PR: - -```bash -npm run check:docs-sync -``` - -CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/fi/SECURITY.md b/docs/i18n/fi/SECURITY.md new file mode 100644 index 0000000000..74b366c597 --- /dev/null +++ b/docs/i18n/fi/SECURITY.md @@ -0,0 +1,179 @@ +# Security Policy (Suomi) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../SECURITY.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/SECURITY.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/SECURITY.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/SECURITY.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/SECURITY.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/SECURITY.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/SECURITY.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/SECURITY.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/SECURITY.md) + +--- + +## 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 | +| ------- | -------------- | +| 3.4.x | โœ… Active | +| 3.0.x | โœ… Security | +| < 3.0.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 | +| **MCP Scopes** | 10 granular scopes for MCP tool access control | + +### ๐Ÿ›ก๏ธ 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:::` +- 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** | Allowlist/blocklist IP ranges in dashboard | +| **Rate Limiting** | Per-provider rate limits with automatic backoff | +| **Anti-Thundering Herd** | Mutex + per-connection locking prevents cascading 502s | +| **TLS Fingerprint** | Browser-like TLS fingerprint spoofing to reduce bot detection | +| **CLI Fingerprint** | Per-provider header/body ordering to match native CLI signatures | + +### ๐Ÿ”Œ Resilience & Availability + +| 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 `CALL_LOG_RETENTION_DAYS` | +| **No-Log Opt-out** | Per API key `noLog` flag disables request logging | +| **Audit Log** | Administrative actions tracked in `audit_log` table | +| **MCP Audit** | SQLite-backed audit logging for all MCP tool calls | +| **Zod Validation** | All API inputs validated with Zod v4 schemas at module load | + +--- + +## 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 +- Provider constants validated at module load via Zod (`src/shared/validation/providerSchema.ts`) diff --git a/docs/i18n/fi/TROUBLESHOOTING.md b/docs/i18n/fi/TROUBLESHOOTING.md deleted file mode 100644 index 63c148000a..0000000000 --- a/docs/i18n/fi/TROUBLESHOOTING.md +++ /dev/null @@ -1,258 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/TROUBLESHOOTING.md) - ---- - -# Troubleshooting - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/TROUBLESHOOTING.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/TROUBLESHOOTING.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/TROUBLESHOOTING.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/TROUBLESHOOTING.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/TROUBLESHOOTING.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/TROUBLESHOOTING.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/TROUBLESHOOTING.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/TROUBLESHOOTING.md) - -Common problems and solutions for OmniRoute. - ---- - -## Quick Fixes - -| Problem | Solution | -| ----------------------------- | ------------------------------------------------------------------ | -| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | -| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | -| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | -| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | -| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | - ---- - -## Provider Issues - -### "Language model did not provide messages" - -**Cause:** Provider quota exhausted. - -**Fix:** - -1. 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, Qoder) 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}/storage.sqlite` (providers, combos, aliases, keys, settings) -- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` -- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) - ---- - -## Circuit Breaker Issues - -### Provider stuck in OPEN state - -When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. - -**Fix:** - -1. 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 -- **SDK returns raw string instead of object** โ€” Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures -- **GLM/ERNIE rejects `system` role** โ€” Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models -- **`developer` role not recognized** โ€” Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers -- **`json_schema` not working with Gemini** โ€” Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` - ---- - -## Resilience Settings - -### Auto rate-limit not triggering - -- 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. - ---- - -## Optional RAG / LLM failure taxonomy (16 problems) - -Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. - -In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. - -If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: - -- retrieval drift and broken context boundaries -- empty or stale indexes and vector stores -- embedding versus semantic mismatch -- prompt assembly and context window issues -- logic collapse and overconfident answers -- long chain and agent coordination failures -- multi agent memory and role drift -- deployment and bootstrap ordering problems - -The idea is simple: - -1. When you investigate a bad response, capture: - - user task and request - - route or provider combo in OmniRoute - - any RAG context used downstream (retrieved documents, tool calls, etc) -2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` โ€ฆ `No.16`). -3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. -4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. - -Full text and concrete recipes live here (MIT license, text only): - -[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) - -You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. - ---- - -## Still Stuck? - -- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details -- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints -- **Health Dashboard**: Check **Dashboard โ†’ Health** for real-time system status -- **Translator**: Use **Dashboard โ†’ Translator** to debug format issues diff --git a/docs/i18n/fi/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/fi/VM_DEPLOYMENT_GUIDE.md deleted file mode 100644 index 924077cc35..0000000000 --- a/docs/i18n/fi/VM_DEPLOYMENT_GUIDE.md +++ /dev/null @@ -1,401 +0,0 @@ -# OmniRoute โ€” Kรคyttรถรถnottoopas VM:ssรค Cloudflaren kanssa - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](../pt-BR/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](../es/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](../fr/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](../it/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](../ru/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](../zh-CN/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](../de/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](../in/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](../th/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](../uk-UA/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](../ar/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](../ja/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](../vi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](../bg/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](../da/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](../fi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](../he/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](../hu/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](../id/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](../ko/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](../ms/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](../nl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](../no/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](../pt/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](../ro/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](../pl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](../sk/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](../sv/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](../phi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](../cs/VM_DEPLOYMENT_GUIDE.md) - -Tรคydellinen opas OmniRouten asentamiseen ja mรครคrittรคmiseen VM:lle (VPS), jonka toimialuetta hallitaan Cloudflaren kautta. - ---- - -## Edellytykset - -| Tuote | Minimi | Suositeltava | -| ----------- | ------------------------- | ---------------- | -| **CPU** | 1 vCPU | 2 vCPU | -| **RAM** | 1 Gt | 2 Gt | -| **Levy** | 10 Gt SSD | 25 Gt SSD | -| **OS** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS | -| **Domain** | Rekisterรถity Cloudflareen | โ€” | -| **Dokkeri** | Docker Engine 24+ | Docker 27+ | - -**Testatut palveluntarjoajat**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. - ---- - -## 1. Mรครคritรค virtuaalikone - -### 1.1 Luo ilmentymรค - -Valitsemallasi VPS-palveluntarjoajalla: - -- Valitse Ubuntu 24.04 LTS -- Valitse vรคhimmรคissuunnitelma (1 vCPU / 1 Gt RAM) -- Aseta vahva root-salasana tai mรครคritรค SSH-avain -- Huomaa **julkinen IP** (esim. `203.0.113.10`) - -### 1.2 Yhdistรค SSH:n kautta - -```bash -ssh root@203.0.113.10 -``` - -### 1.3 Pรคivitรค jรคrjestelmรค - -```bash -apt update && apt upgrade -y -``` - -### 1.4 Asenna Docker - -```bash -# Install dependencies -apt install -y ca-certificates curl gnupg - -# Add official Docker repository -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 Asenna nginx - -```bash -apt install -y nginx -``` - -### 1.6 Mรครคritรค palomuuri (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 -``` - -> **Vinkki**: Maksimaalista turvallisuutta varten rajaa portit 80 ja 443 vain Cloudflaren IP-osoitteisiin. Katso osio [Advanced Security](#advanced-security). - ---- - -## 2. Asenna OmniRoute - -### 2.1 Luo asetushakemisto - -```bash -mkdir -p /opt/omniroute -``` - -### 2.2 Luo ympรคristรถmuuttujatiedosto - -```bash -cat > /opt/omniroute/.env << โ€˜EOFโ€™ -# === Security === -JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY -INITIAL_PASSWORD=YourSecurePassword123! -API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY -STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY -STORAGE_ENCRYPTION_KEY_VERSION=v1 -MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT - -# === 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 (change to your domain) === -BASE_URL=https://llms.seudominio.com -NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com - -# === Cloud Sync (optional) === -# CLOUD_URL=https://cloud.omniroute.online -# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online -EOF -``` - -> โš ๏ธ **Tร„RKEร„ร„**: Luo ainutlaatuisia salaisia avaimia! Kรคytรค `openssl rand -hex 32` jokaiselle avaimelle. - -### 2.3 Kรคynnistรค kontti - -```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 Varmista, ettรค se on kรคynnissรค - -```bash -docker ps | grep omniroute -docker logs omniroute --tail 20 -``` - -Sen pitรคisi nรคyttรครค: `[DB] SQLite database ready` ja `listening on port 20128`. - ---- - -## 3. Mรครคritรค nginx (kรครคnteinen vรคlityspalvelin) - -### 3.1 Luo SSL-varmenne (Cloudflare Origin) - -Cloudflare-hallintapaneelissa: - -1. Siirry kohtaan **SSL/TLS โ†’ Origin Server** -2. Napsauta **Luo varmenne** -3. Sรคilytรค oletusasetukset (15 vuotta, \*.omaverkkotunnus.com) -4. Kopioi **alkuperรคtodistus** ja **yksityinen avain** - -```bash -mkdir -p /etc/nginx/ssl - -# Paste the certificate -nano /etc/nginx/ssl/origin.crt - -# Paste the private key -nano /etc/nginx/ssl/origin.key - -chmod 600 /etc/nginx/ssl/origin.key -``` - -### 3.2 Nginx-kokoonpano - -```bash -cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ -# Default server โ€” blocks direct access via 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.yourdomain.com; # Change to your domain - - 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.yourdomain.com; - return 301 https://$server_name$request_uri; -} -NGINX -``` - -### 3.3 Ota kรคyttรถรถn ja testaa - -```bash -# Remove default configuration -rm -f /etc/nginx/sites-enabled/default - -# Enable OmniRoute -ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute - -# Test and reload -nginx -t && systemctl reload nginx -``` - ---- - -## 4. Mรครคritรค Cloudflare DNS - -### 4.1 Lisรครค DNS-tietue - -Cloudflaren kojelaudassa โ†’ DNS: - -| Tyyppi | Nimi | Sisรคltรถ | Vรคlityspalvelin | -| ------ | ------ | ---------------------- | ------------------ | -| A | `llms` | `203.0.113.10` (VM IP) | โœ… Vรคlityspalvelin | - -### 4.2 Mรครคritรค SSL - -Kohdassa **SSL/TLS โ†’ Yleiskatsaus**: - -- Tila: **Tรคysi (tiukka)** - -Alle **SSL/TLS โ†’ Edge-sertifikaatit**: - -- Kรคytรค aina HTTPS:รครค: โœ… Kรคytรถssรค -- TLS:n vรคhimmรคisversio: TLS 1.2 -- Automaattiset HTTPS-uudelleenkirjoitukset: โœ… Kรคytรถssรค - -### 4.3 Testaus - -```bash -curl -sI https://llms.seudominio.com/health -# Should return HTTP/2 200 -``` - ---- - -## 5. Kรคyttรถ ja huolto - -### Pรคivitรค uuteen versioon - -```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 -``` - -### Nรคytรค lokit - -```bash -docker logs -f omniroute # Real-time stream -docker logs omniroute --tail 50 # Last 50 lines -``` - -### Manuaalinen tietokannan varmuuskopiointi - -```bash -# Copy data from the volume to the host -docker cp omniroute:/app/data ./backup-$(date +%F) - -# Or compress the entire volume -docker run --rm -v omniroute-data:/data -v $(pwd):/backup \ - alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data -``` - -### Palauta varmuuskopiosta - -```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. Lisรคsuojaus - -### Rajoita nginx Cloudflaren IP-osoitteisiin - -```bash -cat > /etc/nginx/cloudflare-ips.conf << โ€˜CFโ€™ -# Cloudflare IPv4 ranges โ€” update periodically -# 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 -``` - -Lisรครค seuraava `nginx.conf` -lohkoon `http {}`: - -```nginx -include /etc/nginx/cloudflare-ips.conf; -``` - -### Asenna fail2ban - -```bash -apt install -y fail2ban -systemctl enable fail2ban -systemctl start fail2ban - -# Check status -fail2ban-client status sshd -``` - -### Estรค suora pรครคsy Docker-porttiin - -```bash -# Prevent direct external access to port 20128 -iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP -iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT - -# Persist the rules -apt install -y iptables-persistent -netfilter-persistent save -``` - ---- - -## 7. Ota kรคyttรถรถn Cloudflare-tyรถntekijรถille (valinnainen) - -Etรคkรคyttรถ Cloudflare Workersin kautta (paljastamatta virtuaalikonetta suoraan): - -```bash -# In the local repository -cd omnirouteCloud -npm install -npx wrangler login -npx wrangler deploy -``` - -Katso koko dokumentaatio osoitteessa [omnirouteCloud/README.md](../omnirouteCloud/README.md). - ---- - -## Portin yhteenveto - -| Portti | Palvelu | Pรครคsy | -| ------ | ----------- | ----------------------------------- | -| 22 | SSH | Julkinen (fail2banin kanssa) | -| 80 | nginx HTTP | Uudelleenohjaus โ†’ HTTPS | -| 443 | nginx HTTPS | Cloudflare-vรคlityspalvelimen kautta | -| 20128 | OmniRoute | Vain Localhost (nginxin kautta) | diff --git a/docs/i18n/ar/A2A-SERVER.md b/docs/i18n/fi/docs/A2A-SERVER.md similarity index 77% rename from docs/i18n/ar/A2A-SERVER.md rename to docs/i18n/fi/docs/A2A-SERVER.md index 01531ff482..4787d889f2 100644 --- a/docs/i18n/ar/A2A-SERVER.md +++ b/docs/i18n/fi/docs/A2A-SERVER.md @@ -1,9 +1,9 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/A2A-SERVER.md) +# OmniRoute A2A Server Documentation (Suomi) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/A2A-SERVER.md) --- -# OmniRoute A2A Server Documentation - > Agent-to-Agent Protocol v0.3 โ€” OmniRoute as an intelligent routing agent ## Agent Discovery diff --git a/docs/i18n/bg/API_REFERENCE.md b/docs/i18n/fi/docs/API_REFERENCE.md similarity index 74% rename from docs/i18n/bg/API_REFERENCE.md rename to docs/i18n/fi/docs/API_REFERENCE.md index b878605221..b78cf27fd0 100644 --- a/docs/i18n/bg/API_REFERENCE.md +++ b/docs/i18n/fi/docs/API_REFERENCE.md @@ -1,11 +1,9 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/API_REFERENCE.md) +# API Reference (Suomi) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/API_REFERENCE.md) --- -# API Reference - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/API_REFERENCE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/API_REFERENCE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/API_REFERENCE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/API_REFERENCE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/API_REFERENCE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/API_REFERENCE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/API_REFERENCE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/API_REFERENCE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/API_REFERENCE.md) - Complete reference for all OmniRoute API endpoints. --- @@ -42,15 +40,20 @@ Content-Type: application/json ### 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 | +| Header | Direction | Description | +| ------------------------ | --------- | ------------------------------------------------ | +| `X-OmniRoute-No-Cache` | Request | Set to `true` to bypass cache | +| `X-OmniRoute-Progress` | Request | Set to `true` for progress events | +| `X-Session-Id` | Request | Sticky session key for external session affinity | +| `x_session_id` | Request | Underscore variant also accepted (direct HTTP) | +| `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 | +| `X-OmniRoute-Session-Id` | Response | Effective session ID used by OmniRoute | + +> Nginx note: if you rely on underscore headers (for example `x_session_id`), enable `underscores_in_headers on;`. --- @@ -141,10 +144,10 @@ The provider prefix is auto-added if missing. Mismatched models return `400`. ```bash # Get cache stats -GET /api/cache +GET /api/cache/stats # Clear all caches -DELETE /api/cache +DELETE /api/cache/stats ``` Response example: @@ -215,23 +218,23 @@ Response example: ### 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 | +| Endpoint | Method | Description | +| ------------------------------- | ------------- | ---------------------- | +| `/api/settings` | GET/PUT/PATCH | 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 | +| Endpoint | Method | Description | +| ------------------------ | ---------- | ---------------------------------------------------------------------------------------------------- | +| `/api/sessions` | GET | Active session tracking | +| `/api/rate-limits` | GET | Per-account rate limits | +| `/api/monitoring/health` | GET | Health check + provider summary (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`) | +| `/api/cache/stats` | GET/DELETE | Cache stats / clear | ### Backup & Export/Import @@ -252,6 +255,13 @@ Response example: | `/api/sync/initialize` | POST | Initialize sync | | `/api/cloud/*` | Various | Cloud management | +### Tunnels + +| Endpoint | Method | Description | +| -------------------------- | ------ | ----------------------------------------------------------------------- | +| `/api/tunnels/cloudflared` | GET | Read Cloudflare Quick Tunnel install/runtime status for the dashboard | +| `/api/tunnels/cloudflared` | POST | Enable or disable the Cloudflare Quick Tunnel (`action=enable/disable`) | + ### CLI Tools | Endpoint | Method | Description | @@ -276,12 +286,12 @@ GET response includes `agents[]` (id, name, binary, version, installed, protocol ### 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 | +| Endpoint | Method | Description | +| ----------------------- | --------- | ------------------------------- | +| `/api/resilience` | GET/PATCH | 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 diff --git a/docs/i18n/de/ARCHITECTURE.md b/docs/i18n/fi/docs/ARCHITECTURE.md similarity index 89% rename from docs/i18n/de/ARCHITECTURE.md rename to docs/i18n/fi/docs/ARCHITECTURE.md index 4ea06a29f2..9be954d4a1 100644 --- a/docs/i18n/de/ARCHITECTURE.md +++ b/docs/i18n/fi/docs/ARCHITECTURE.md @@ -1,12 +1,10 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/ARCHITECTURE.md) +# OmniRoute Architecture (Suomi) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/ARCHITECTURE.md) --- -# OmniRoute Architecture - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/ARCHITECTURE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/ARCHITECTURE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/ARCHITECTURE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/ARCHITECTURE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/ARCHITECTURE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/ARCHITECTURE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/ARCHITECTURE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/ARCHITECTURE.md) - -_Last updated: 2026-03-04_ +_Last updated: 2026-03-28_ ## Executive Summary @@ -69,6 +67,26 @@ Primary runtime model: - Provider SLA/control plane outside local process - External CLI binaries themselves (Claude CLI, Codex CLI, etc.) +## Dashboard Surface (Current) + +Main pages under `src/app/(dashboard)/dashboard/`: + +- `/dashboard` โ€” quick start + provider overview +- `/dashboard/endpoint` โ€” endpoint proxy + MCP + A2A + API endpoint tabs +- `/dashboard/providers` โ€” provider connections and credentials +- `/dashboard/combos` โ€” combo strategies, templates, model routing rules +- `/dashboard/costs` โ€” cost aggregation and pricing visibility +- `/dashboard/analytics` โ€” usage analytics and evaluations +- `/dashboard/limits` โ€” quota/rate controls +- `/dashboard/cli-tools` โ€” CLI onboarding, runtime detection, config generation +- `/dashboard/agents` โ€” detected ACP agents + custom agent registration +- `/dashboard/media` โ€” image/video/music playground +- `/dashboard/search-tools` โ€” search provider testing and history +- `/dashboard/health` โ€” uptime, circuit breakers, rate limits +- `/dashboard/logs` โ€” request/proxy/audit/console logs +- `/dashboard/settings` โ€” system settings tabs (general, routing, combo defaults, etc.) +- `/dashboard/api-manager` โ€” API key lifecycle and model permissions + ## High-Level System Context ```mermaid @@ -258,8 +276,9 @@ Domain State DB (SQLite): ## 5) Cloud Sync -- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` +- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts`, `src/shared/services/modelSyncScheduler.ts` - Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Periodic task: `src/shared/services/modelSyncScheduler.ts` - Control route: `src/app/api/sync/cloud/route.ts` ## Request Lifecycle (`/v1/chat/completions`) @@ -339,7 +358,7 @@ flowchart TD Q -- No --> R[Return all unavailable] ``` -Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics. +Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics. Combo routing adds one extra guard: provider-scoped 400s such as upstream content-block and role-validation failures are treated as model-local failures so later combo targets can still run. ## OAuth Onboarding and Token Refresh Lifecycle @@ -669,25 +688,25 @@ Additional processing layers in the translation pipeline: ## 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 | +| 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` | Provider Models | Provider model metadata backing custom and managed available models | ## Bypass Handler @@ -739,10 +758,18 @@ Runtime visibility sources: - console logs from `src/sse/utils/logger.ts` - per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- four-stage detailed payload captures in SQLite (`request_detail_logs`) when `settings.detailed_logs_enabled=true` - textual request status log in `log.txt` (optional/compat) - optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` - dashboard usage endpoints (`/api/usage/*`) for UI consumption +Detailed request payload capture stores up to four JSON payload stages per routed call: + +- raw request received from the client +- translated request actually sent upstream +- provider response reconstructed as JSON; streamed responses are compacted to the final summary plus stream metadata +- final client response returned by OmniRoute; streamed responses are stored in the same compact summary form + ## Security-Sensitive Boundaries - JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing diff --git a/docs/i18n/de/AUTO-COMBO.md b/docs/i18n/fi/docs/AUTO-COMBO.md similarity index 65% rename from docs/i18n/de/AUTO-COMBO.md rename to docs/i18n/fi/docs/AUTO-COMBO.md index 2166e41dff..f2c5cfedb7 100644 --- a/docs/i18n/de/AUTO-COMBO.md +++ b/docs/i18n/fi/docs/AUTO-COMBO.md @@ -1,9 +1,9 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/AUTO-COMBO.md) +# OmniRoute Auto-Combo Engine (Suomi) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/AUTO-COMBO.md) --- -# OmniRoute Auto-Combo Engine - > Self-managing model chains with adaptive scoring ## How It Works diff --git a/docs/i18n/fi/docs/CLI-TOOLS.md b/docs/i18n/fi/docs/CLI-TOOLS.md new file mode 100644 index 0000000000..c44a72bd3c --- /dev/null +++ b/docs/i18n/fi/docs/CLI-TOOLS.md @@ -0,0 +1,348 @@ +# CLI Tools Setup Guide โ€” OmniRoute (Suomi) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CLI-TOOLS.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CLI-TOOLS.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CLI-TOOLS.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CLI-TOOLS.md) + +--- + +This guide explains how to install and configure all supported AI coding CLI tools +to use **OmniRoute** as the unified backend, giving you centralized key management, +cost tracking, model switching, and request logging across every tool. + +--- + +## How It Works + +``` +Claude / Codex / OpenCode / Cline / KiloCode / Continue / Kiro / Cursor / Copilot + โ”‚ + โ–ผ (all point to OmniRoute) + http://YOUR_SERVER:20128/v1 + โ”‚ + โ–ผ (OmniRoute routes to the right provider) + Anthropic / OpenAI / Gemini / DeepSeek / Groq / Mistral / ... +``` + +**Benefits:** + +- One API key to manage all tools +- Cost tracking across all CLIs in the dashboard +- Model switching without reconfiguring every tool +- Works locally and on remote servers (VPS) + +--- + +## Supported Tools (Dashboard Source of Truth) + +The dashboard cards in `/dashboard/cli-tools` are generated from `src/shared/constants/cliTools.ts`. +Current list (v3.0.0-rc.16): + +| Tool | ID | Command | Setup Mode | Install Method | +| ------------------ | ------------- | ---------- | ---------- | -------------- | +| **Claude Code** | `claude` | `claude` | env | npm | +| **OpenAI Codex** | `codex` | `codex` | custom | npm | +| **Factory Droid** | `droid` | `droid` | custom | bundled/CLI | +| **OpenClaw** | `openclaw` | `openclaw` | custom | bundled/CLI | +| **Cursor** | `cursor` | app | guide | desktop app | +| **Cline** | `cline` | `cline` | custom | npm | +| **Kilo Code** | `kilo` | `kilocode` | custom | npm | +| **Continue** | `continue` | extension | guide | VS Code | +| **Antigravity** | `antigravity` | internal | mitm | OmniRoute | +| **GitHub Copilot** | `copilot` | extension | custom | VS Code | +| **OpenCode** | `opencode` | `opencode` | guide | npm | +| **Kiro AI** | `kiro` | app/cli | mitm | desktop/CLI | + +### CLI fingerprint sync (Agents + Settings) + +`/dashboard/agents` and `Settings > CLI Fingerprint` use `src/shared/constants/cliCompatProviders.ts`. +This keeps provider IDs aligned with CLI cards and legacy IDs. + +| CLI ID | Fingerprint Provider ID | +| ---------------------------------------------------------------------------------------------------- | ----------------------- | +| `kilo` | `kilocode` | +| `copilot` | `github` | +| `claude` / `codex` / `antigravity` / `kiro` / `cursor` / `cline` / `opencode` / `droid` / `openclaw` | same ID | + +Legacy IDs still accepted for compatibility: `copilot`, `kimi-coding`, `qwen`. + +--- + +## Step 1 โ€” Get an OmniRoute API Key + +1. Open the OmniRoute dashboard โ†’ **API Manager** (`/dashboard/api-manager`) +2. Click **Create API Key** +3. Give it a name (e.g. `cli-tools`) and select all permissions +4. Copy the key โ€” you'll need it for every CLI below + +> Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` + +--- + +## Step 2 โ€” Install CLI Tools + +All npm-based tools require Node.js 18+: + +```bash +# Claude Code (Anthropic) +npm install -g @anthropic-ai/claude-code + +# OpenAI Codex +npm install -g @openai/codex + +# OpenCode +npm install -g opencode-ai + +# Cline +npm install -g cline + +# KiloCode +npm install -g kilocode + +# Kiro CLI (Amazon โ€” requires curl + unzip) +apt-get install -y unzip # on Debian/Ubuntu +curl -fsSL https://cli.kiro.dev/install | bash +export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc +``` + +**Verify:** + +```bash +claude --version # 2.x.x +codex --version # 0.x.x +opencode --version # x.x.x +cline --version # 2.x.x +kilocode --version # x.x.x (or: kilo --version) +kiro-cli --version # 1.x.x +``` + +--- + +## Step 3 โ€” Set Global Environment Variables + +Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`: + +```bash +# OmniRoute Universal Endpoint +export OPENAI_BASE_URL="http://localhost:20128/v1" +export OPENAI_API_KEY="sk-your-omniroute-key" +export ANTHROPIC_BASE_URL="http://localhost:20128/v1" +export ANTHROPIC_API_KEY="sk-your-omniroute-key" +export GEMINI_BASE_URL="http://localhost:20128/v1" +export GEMINI_API_KEY="sk-your-omniroute-key" +``` + +> For a **remote server** replace `localhost:20128` with the server IP or domain, +> e.g. `http://192.168.0.15:20128`. + +--- + +## Step 4 โ€” Configure Each Tool + +### Claude Code + +```bash +# Via CLI: +claude config set --global api-base-url http://localhost:20128/v1 + +# Or create ~/.claude/settings.json: +mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF +{ + "apiBaseUrl": "http://localhost:20128/v1", + "apiKey": "sk-your-omniroute-key" +} +EOF +``` + +**Test:** `claude "say hello"` + +--- + +### OpenAI Codex + +```bash +mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF +model: auto +apiKey: sk-your-omniroute-key +apiBaseUrl: http://localhost:20128/v1 +EOF +``` + +**Test:** `codex "what is 2+2?"` + +--- + +### OpenCode + +```bash +mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF +[provider.openai] +base_url = "http://localhost:20128/v1" +api_key = "sk-your-omniroute-key" +EOF +``` + +**Test:** `opencode` + +--- + +### Cline (CLI or VS Code) + +**CLI mode:** + +```bash +mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF +{ + "apiProvider": "openai", + "openAiBaseUrl": "http://localhost:20128/v1", + "openAiApiKey": "sk-your-omniroute-key" +} +EOF +``` + +**VS Code mode:** +Cline extension settings โ†’ API Provider: `OpenAI Compatible` โ†’ Base URL: `http://localhost:20128/v1` + +Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ Cline โ†’ Apply Config**. + +--- + +### KiloCode (CLI or VS Code) + +**CLI mode:** + +```bash +kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key +``` + +**VS Code settings:** + +```json +{ + "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", + "kilo-code.apiKey": "sk-your-omniroute-key" +} +``` + +Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ KiloCode โ†’ Apply Config**. + +--- + +### Continue (VS Code Extension) + +Edit `~/.continue/config.yaml`: + +```yaml +models: + - name: OmniRoute + provider: openai + model: auto + apiBase: http://localhost:20128/v1 + apiKey: sk-your-omniroute-key + default: true +``` + +Restart VS Code after editing. + +--- + +### Kiro CLI (Amazon) + +```bash +# Login to your AWS/Kiro account: +kiro-cli login + +# The CLI uses its own auth โ€” OmniRoute is not needed as backend for Kiro CLI itself. +# Use kiro-cli alongside OmniRoute for other tools. +kiro-cli status +``` + +--- + +### Cursor (Desktop App) + +> **Note:** Cursor routes requests through its cloud. For OmniRoute integration, +> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL. + +Via GUI: **Settings โ†’ Models โ†’ OpenAI API Key** + +- Base URL: `https://your-domain.com/v1` +- API Key: your OmniRoute key + +--- + +## Dashboard Auto-Configuration + +The OmniRoute dashboard automates configuration for most tools: + +1. Go to `http://localhost:20128/dashboard/cli-tools` +2. Expand any tool card +3. Select your API key from the dropdown +4. Click **Apply Config** (if tool is detected as installed) +5. Or copy the generated config snippet manually + +--- + +## Built-in Agents: Droid & OpenClaw + +**Droid** and **OpenClaw** are AI agents built directly into OmniRoute โ€” no installation needed. +They run as internal routes and use OmniRoute's model routing automatically. + +- Access: `http://localhost:20128/dashboard/agents` +- Configure: same combos and providers as all other tools +- No API key or CLI install required + +--- + +## Available API Endpoints + +| Endpoint | Description | Use For | +| -------------------------- | ----------------------------- | --------------------------- | +| `/v1/chat/completions` | Standard chat (all providers) | All modern tools | +| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows | +| `/v1/completions` | Legacy text completions | Older tools using `prompt:` | +| `/v1/embeddings` | Text embeddings | RAG, search | +| `/v1/images/generations` | Image generation | DALL-E, Flux, etc. | +| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS | +| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI | + +--- + +## Vianmรครคritys + +| Error | Cause | Fix | +| ------------------------- | ----------------------- | ------------------------------------------ | +| `Connection refused` | OmniRoute not running | `pm2 start omniroute` | +| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` | +| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` | +| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` | +| CLI shows "not installed" | Binary not in PATH | Check `which ` | +| `kiro-cli: not found` | Not in PATH | `export PATH="$HOME/.local/bin:$PATH"` | + +--- + +## Quick Setup Script (One Command) + +```bash +# Install all CLIs and configure for OmniRoute (replace with your key and server URL) +OMNIROUTE_URL="http://localhost:20128/v1" +OMNIROUTE_KEY="sk-your-omniroute-key" + +npm install -g @anthropic-ai/claude-code @openai/codex opencode-ai cline kilocode + +# Kiro CLI +apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash + +# Write configs +mkdir -p ~/.claude ~/.codex ~/.config/opencode ~/.continue + +cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" +cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" +cat >> ~/.bashrc << EOF +export OPENAI_BASE_URL="$OMNIROUTE_URL" +export OPENAI_API_KEY="$OMNIROUTE_KEY" +export ANTHROPIC_BASE_URL="$OMNIROUTE_URL" +export ANTHROPIC_API_KEY="$OMNIROUTE_KEY" +EOF + +source ~/.bashrc +echo "โœ… All CLIs installed and configured for OmniRoute" +``` diff --git a/docs/i18n/fi/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/fi/docs/CODEBASE_DOCUMENTATION.md new file mode 100644 index 0000000000..d39141da9b --- /dev/null +++ b/docs/i18n/fi/docs/CODEBASE_DOCUMENTATION.md @@ -0,0 +1,591 @@ +# omniroute โ€” Codebase Documentation (Suomi) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CODEBASE_DOCUMENTATION.md) + +--- + +> 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
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, Qoder, 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. + +#### Arkkitehtuuri + +```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 | +| Qoder | 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"] +``` diff --git a/docs/i18n/fi/docs/COVERAGE_PLAN.md b/docs/i18n/fi/docs/COVERAGE_PLAN.md new file mode 100644 index 0000000000..0cdd6d4213 --- /dev/null +++ b/docs/i18n/fi/docs/COVERAGE_PLAN.md @@ -0,0 +1,170 @@ +# Test Coverage Plan (Suomi) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/COVERAGE_PLAN.md) + +--- + +Last updated: 2026-03-28 + +## Baseline + +There are multiple coverage numbers depending on how the report is computed. For planning, only one of them is useful. + +| Metric | Scope | Statements / Lines | Branches | Functions | Notes | +| -------------------- | ----------------------------------------------------- | -----------------: | -------: | --------: | --------------------------------------------------- | +| Legacy | Old `npm run test:coverage` | 79.42% | 75.15% | 67.94% | Inflated: counts test files and excludes `open-sse` | +| Diagnostic | Source-only, excluding tests and excluding `open-sse` | 68.16% | 63.55% | 64.06% | Useful only to isolate `src/**` | +| Recommended baseline | Source-only, excluding tests and including `open-sse` | 56.95% | 66.05% | 57.80% | This is the project-wide baseline to improve | + +The recommended baseline is the number to optimize against. + +## Rules + +- Coverage targets apply to source files, not to `tests/**`. +- `open-sse/**` is part of the product and must remain in scope. +- New code should not reduce coverage in touched areas. +- Prefer testing behavior and branch outcomes over implementation details. +- Prefer temp SQLite databases and small fixtures over broad mocks for `src/lib/db/**`. + +## Current command set + +- `npm run test:coverage` + - Main source coverage gate for the unit test suite + - Generates `text-summary`, `html`, `json-summary`, and `lcov` +- `npm run coverage:report` + - Detailed file-by-file report from the latest run +- `npm run test:coverage:legacy` + - Historical comparison only + +## Milestones + +| Phase | Target | Focus | +| ------- | ---------------------: | ------------------------------------------------- | +| Phase 1 | 60% statements / lines | Quick wins and low-risk utility coverage | +| Phase 2 | 65% statements / lines | DB and route foundations | +| Phase 3 | 70% statements / lines | Provider validation and usage analytics | +| Phase 4 | 75% statements / lines | `open-sse` translators and helpers | +| Phase 5 | 80% statements / lines | `open-sse` handlers and executor branches | +| Phase 6 | 85% statements / lines | Harder edge cases, branch debt, regression suites | +| Phase 7 | 90% statements / lines | Final sweep, gap closure, strict ratchet | + +Branches and functions should ratchet upward with each phase, but the primary hard target is statements / lines. + +## Priority hotspots + +These files or areas offer the best return for the next phases: + +1. `open-sse/handlers` + - `chatCore.ts` at 7.57% + - Overall directory at 29.07% +2. `open-sse/translator/request` + - Overall directory at 36.39% + - Many translators are still near single-digit coverage +3. `open-sse/translator/response` + - Overall directory at 8.07% +4. `open-sse/executors` + - Overall directory at 36.62% +5. `src/lib/db` + - `models.ts` at 20.66% + - `registeredKeys.ts` at 34.46% + - `modelComboMappings.ts` at 36.25% + - `settings.ts` at 46.40% + - `webhooks.ts` at 33.33% +6. `src/lib/usage` + - `usageHistory.ts` at 21.12% + - `usageStats.ts` at 9.56% + - `costCalculator.ts` at 30.00% +7. `src/lib/providers` + - `validation.ts` at 41.16% +8. Low-risk utility and API files for early gains + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/api/errorResponse.ts` + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +## Execution checklist + +### Phase 1: 56.95% -> 60% + +- [x] Fix coverage metric so it reflects source code instead of test files +- [x] Keep a legacy coverage script for comparison +- [x] Record the baseline and hotspots in-repo +- [ ] Add focused tests for low-risk utilities: + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/fetchTimeout.ts` + - `src/lib/api/errorResponse.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/display/names.ts` +- [ ] Add route tests for: + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +### Phase 2: 60% -> 65% + +- [ ] Add DB-backed tests for: + - `src/lib/db/modelComboMappings.ts` + - `src/lib/db/settings.ts` + - `src/lib/db/registeredKeys.ts` +- [ ] Cover branch behavior in: + - `src/lib/providers/validation.ts` + - `src/app/api/v1/embeddings/route.ts` + - `src/app/api/v1/moderations/route.ts` + +### Phase 3: 65% -> 70% + +- [ ] Add usage analytics tests for: + - `src/lib/usage/usageHistory.ts` + - `src/lib/usage/usageStats.ts` + - `src/lib/usage/costCalculator.ts` +- [ ] Expand route coverage for proxy management and settings branches + +### Phase 4: 70% -> 75% + +- [ ] Cover translator helpers and central translation paths: + - `open-sse/translator/index.ts` + - `open-sse/translator/helpers/*` + - `open-sse/translator/request/*` + - `open-sse/translator/response/*` + +### Phase 5: 75% -> 80% + +- [ ] Add handler-level tests for: + - `open-sse/handlers/chatCore.ts` + - `open-sse/handlers/responsesHandler.js` + - `open-sse/handlers/imageGeneration.js` + - `open-sse/handlers/embeddings.js` +- [ ] Add executor branch coverage for provider-specific auth, retries, and endpoint overrides + +### Phase 6: 80% -> 85% + +- [ ] Merge more edge-case suites into the main coverage path +- [ ] Increase function coverage for DB modules with weak constructor/helper coverage +- [ ] Close branch gaps in `settings.ts`, `registeredKeys.ts`, `validation.ts`, and translator helpers + +### Phase 7: 85% -> 90% + +- [ ] Treat the remaining low-coverage files as blockers +- [ ] Add regression tests for every uncovered production bug fixed during the push to 90% +- [ ] Raise the coverage gate in CI only after the local baseline is stable for at least two consecutive runs + +## Ratchet policy + +Update `npm run test:coverage` thresholds only after the project actually exceeds the next milestone with a comfortable buffer. + +Recommended ratchet sequence: + +1. 55/60/55 +2. 60/62/58 +3. 65/64/62 +4. 70/66/66 +5. 75/70/72 +6. 80/75/78 +7. 85/80/84 +8. 90/85/88 + +Order is `statements-lines / branches / functions`. + +## Known gap + +The current coverage command measures the main Node unit suite and includes source reached from it, including `open-sse`. It does not yet merge Vitest coverage into a single unified report. That merge is worth doing later, but it is not a blocker for starting the 60% -> 80% climb. diff --git a/docs/i18n/fi/docs/FEATURES.md b/docs/i18n/fi/docs/FEATURES.md index 1acc4488ff..6d6dcbbd73 100644 --- a/docs/i18n/fi/docs/FEATURES.md +++ b/docs/i18n/fi/docs/FEATURES.md @@ -1,6 +1,6 @@ # OmniRoute โ€” Dashboard Features Gallery (Suomi) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/FEATURES.md) --- @@ -10,7 +10,7 @@ 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). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. ![Providers Dashboard](screenshots/01-providers.png) diff --git a/docs/i18n/ar/MCP-SERVER.md b/docs/i18n/fi/docs/MCP-SERVER.md similarity index 65% rename from docs/i18n/ar/MCP-SERVER.md rename to docs/i18n/fi/docs/MCP-SERVER.md index 829acd30b1..d2c249eb8d 100644 --- a/docs/i18n/ar/MCP-SERVER.md +++ b/docs/i18n/fi/docs/MCP-SERVER.md @@ -1,12 +1,12 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/MCP-SERVER.md) +# OmniRoute MCP Server Documentation (Suomi) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/MCP-SERVER.md) --- -# OmniRoute MCP Server Documentation - > Model Context Protocol server with 16 intelligent tools -## Installation +## Asenna OmniRoute MCP is built-in. Start it with: @@ -42,16 +42,16 @@ See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, ## Advanced Tools (8) -| Tool | Description | -| :--------------------------------- | :---------------------------------------------- | -| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | -| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | -| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | -| `omniroute_test_combo` | Live-test all models in a combo | -| `omniroute_get_provider_metrics` | Detailed metrics for one provider | -| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | -| `omniroute_explain_route` | Explain a past routing decision | -| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | +| Tool | Description | +| :--------------------------------- | :---------------------------------------------------------- | +| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | +| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | +| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | +| `omniroute_test_combo` | Live-test all models in a combo via a real upstream request | +| `omniroute_get_provider_metrics` | Detailed metrics for one provider | +| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | +| `omniroute_explain_route` | Explain a past routing decision | +| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | ## Authentication diff --git a/docs/i18n/fi/docs/RELEASE_CHECKLIST.md b/docs/i18n/fi/docs/RELEASE_CHECKLIST.md new file mode 100644 index 0000000000..2001c28287 --- /dev/null +++ b/docs/i18n/fi/docs/RELEASE_CHECKLIST.md @@ -0,0 +1,37 @@ +# Release Checklist (Suomi) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/RELEASE_CHECKLIST.md) + +--- + +Use this checklist before tagging or publishing a new OmniRoute release. + +## Version and Changelog + +1. Bump `package.json` version (`x.y.z`) in the release branch. +2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: + - `## [x.y.z] โ€” YYYY-MM-DD` +3. Keep `## [Unreleased]` as the first changelog section for upcoming work. +4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. + +## API Docs + +1. Update `docs/openapi.yaml`: + - `info.version` must equal `package.json` version. +2. Validate endpoint examples if API contracts changed. + +## Runtime Docs + +1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. +2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. +3. Update localized docs if source docs changed significantly. + +## Automated Check + +Run the sync guard locally before opening PR: + +```bash +npm run check:docs-sync +``` + +CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/fi/docs/TROUBLESHOOTING.md b/docs/i18n/fi/docs/TROUBLESHOOTING.md new file mode 100644 index 0000000000..696f624823 --- /dev/null +++ b/docs/i18n/fi/docs/TROUBLESHOOTING.md @@ -0,0 +1,256 @@ +# Troubleshooting (Suomi) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/TROUBLESHOOTING.md) + +--- + +Common problems and solutions for OmniRoute. + +--- + +## Quick Fixes + +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | + +--- + +## Provider Issues + +### "Language model did not provide messages" + +**Cause:** Provider quota exhausted. + +**Fix:** + +1. 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, Qoder) 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}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) + +--- + +## Circuit Breaker Issues + +### Provider stuck in OPEN state + +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. + +**Fix:** + +1. 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 +- **SDK returns raw string instead of object** โ€” Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** โ€” Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** โ€” Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** โ€” Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` + +--- + +## Resilience Settings + +### Auto rate-limit not triggering + +- 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. + +--- + +## Optional RAG / LLM failure taxonomy (16 problems) + +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` โ€ฆ `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard โ†’ Health** for real-time system status +- **Translator**: Use **Dashboard โ†’ Translator** to debug format issues diff --git a/docs/i18n/fi/USER_GUIDE.md b/docs/i18n/fi/docs/USER_GUIDE.md similarity index 82% rename from docs/i18n/fi/USER_GUIDE.md rename to docs/i18n/fi/docs/USER_GUIDE.md index 92bcd5e191..30508224f1 100644 --- a/docs/i18n/fi/USER_GUIDE.md +++ b/docs/i18n/fi/docs/USER_GUIDE.md @@ -1,8 +1,6 @@ # User Guide (Suomi) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/USER_GUIDE.md) - -> ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/USER_GUIDE.md) --- @@ -320,7 +318,7 @@ Model: cc/claude-opus-4-6 --- -## ๐Ÿš€ Deployment +## Kรคyttรถรถnotto ### Global npm install (Recommended) @@ -511,23 +509,26 @@ post_install() { ### Environment Variables -| Variable | Default | Description | -| ------------------------- | ------------------------------------ | ------------------------------------------------------- | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | -| `INITIAL_PASSWORD` | `123456` | First login password | -| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | -| `PORT` | framework default | Service port (`20128` in examples) | -| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | -| `NODE_ENV` | runtime default | Set `production` for deploy | -| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | -| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | -| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | -| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | -| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | -| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | -| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | -| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | +| 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/*` | +| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand | +| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | For the full environment variable reference, see the [README](../README.md). @@ -598,6 +599,11 @@ curl -X POST http://localhost:20128/api/provider-models \ Or use Dashboard: **Providers โ†’ [Provider] โ†’ Custom Models**. +Notes: + +- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers. +- The **Custom Models** section is intended for providers that do not expose managed available-model imports. + ### Dedicated Provider Routes Route requests directly to a specific provider with model validation: @@ -642,6 +648,14 @@ Returns models grouped by provider with types (`chat`, `embedding`, `image`). - Automatic background sync with timeout + fail-fast - Prefer server-side `BASE_URL`/`CLOUD_URL` in production +### Cloudflare Quick Tunnel + +- Available in **Dashboard โ†’ Endpoints** for Docker and other self-hosted deployments +- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint +- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary +- Tunnel URLs are ephemeral and change every time you stop/start the tunnel +- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download + ### LLM Gateway Intelligence (Phase 9) - **Semantic Cache** โ€” Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) @@ -757,11 +771,11 @@ OmniRoute implements provider-level resilience with four components: 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 | +| 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 unless `DISABLE_SQLITE_AUTO_BACKUP=true` | ```bash # API: Export database @@ -787,10 +801,11 @@ curl -X POST http://localhost:20128/api/db-backups/import \ ### Settings Dashboard -The settings page is organized into 5 tabs for easy navigation: +The settings page is organized into 6 tabs for easy navigation: | Tab | Contents | | -------------- | ---------------------------------------------------------------------------------------------- | +| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility | | **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | | **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | | **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | diff --git a/docs/i18n/fi/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/fi/docs/VM_DEPLOYMENT_GUIDE.md new file mode 100644 index 0000000000..2662210f72 --- /dev/null +++ b/docs/i18n/fi/docs/VM_DEPLOYMENT_GUIDE.md @@ -0,0 +1,403 @@ +# OmniRoute โ€” Deployment Guide on VM with Cloudflare (Suomi) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/VM_DEPLOYMENT_GUIDE.md) + +--- + +Complete guide to install and configure OmniRoute on a VM (VPS) with domain managed via Cloudflare. + +--- + +## Prerequisites + +| Item | Minimum | Recommended | +| ---------- | ------------------------ | ---------------- | +| **CPU** | 1 vCPU | 2 vCPU | +| **RAM** | 1 GB | 2 GB | +| **Disk** | 10 GB SSD | 25 GB SSD | +| **OS** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS | +| **Domain** | Registered on Cloudflare | โ€” | +| **Docker** | Docker Engine 24+ | Docker 27+ | + +**Tested providers**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. + +--- + +## 1. Configure the VM + +### 1.1 Create the instance + +On your preferred VPS provider: + +- Choose Ubuntu 24.04 LTS +- Select the minimum plan (1 vCPU / 1 GB RAM) +- Set a strong root password or configure SSH key +- Note the **public IP** (e.g., `203.0.113.10`) + +### 1.2 Connect via SSH + +```bash +ssh root@203.0.113.10 +``` + +### 1.3 Update the system + +```bash +apt update && apt upgrade -y +``` + +### 1.4 Install Docker + +```bash +# Install dependencies +apt install -y ca-certificates curl gnupg + +# Add official Docker repository +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 Install nginx + +```bash +apt install -y nginx +``` + +### 1.6 Configure 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 +``` + +> **Tip**: For maximum security, restrict ports 80 and 443 to Cloudflare IPs only. See the [Advanced Security](#advanced-security) section. + +--- + +## 2. Install OmniRoute + +### 2.1 Create configuration directory + +```bash +mkdir -p /opt/omniroute +``` + +### 2.2 Create environment variables file + +```bash +cat > /opt/omniroute/.env << โ€˜EOFโ€™ +# === Security === +JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY +INITIAL_PASSWORD=YourSecurePassword123! +API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY +STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY +STORAGE_ENCRYPTION_KEY_VERSION=v1 +MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT + +# === 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 (change to your domain) === +BASE_URL=https://llms.seudominio.com +NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com + +# === Cloud Sync (optional) === +# CLOUD_URL=https://cloud.omniroute.online +# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online +EOF +``` + +> โš ๏ธ **IMPORTANT**: Generate unique secret keys! Use `openssl rand -hex 32` for each key. + +### 2.3 Start the 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 Verify that it is running + +```bash +docker ps | grep omniroute +docker logs omniroute --tail 20 +``` + +It should display: `[DB] SQLite database ready` and `listening on port 20128`. + +--- + +## 3. Configure nginx (Reverse Proxy) + +### 3.1 Generate SSL certificate (Cloudflare Origin) + +In the Cloudflare dashboard: + +1. Go to **SSL/TLS โ†’ Origin Server** +2. Click **Create Certificate** +3. Keep the defaults (15 years, \*.yourdomain.com) +4. Copy the **Origin Certificate** and the **Private Key** + +```bash +mkdir -p /etc/nginx/ssl + +# Paste the certificate +nano /etc/nginx/ssl/origin.crt + +# Paste the private key +nano /etc/nginx/ssl/origin.key + +chmod 600 /etc/nginx/ssl/origin.key +``` + +### 3.2 Nginx Configuration + +```bash +cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ +# Default server โ€” blocks direct access via 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.yourdomain.com; # Change to your domain + + 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.yourdomain.com; + return 301 https://$server_name$request_uri; +} +NGINX +``` + +### 3.3 Enable and Test + +```bash +# Remove default configuration +rm -f /etc/nginx/sites-enabled/default + +# Enable OmniRoute +ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute + +# Test and reload +nginx -t && systemctl reload nginx +``` + +--- + +## 4. Configure Cloudflare DNS + +### 4.1 Add DNS record + +In the Cloudflare dashboard โ†’ DNS: + +| Type | Name | Content | Proxy | +| ---- | ------ | ---------------------- | ---------- | +| A | `llms` | `203.0.113.10` (VM IP) | โœ… Proxied | + +### 4.2 Configure SSL + +Under **SSL/TLS โ†’ Overview**: + +- Mode: **Full (Strict)** + +Under **SSL/TLS โ†’ Edge Certificates**: + +- Always Use HTTPS: โœ… On +- Minimum TLS Version: TLS 1.2 +- Automatic HTTPS Rewrites: โœ… On + +### 4.3 Testing + +```bash +curl -sI https://llms.seudominio.com/health +# Should return HTTP/2 200 +``` + +--- + +## 5. Operations and Maintenance + +### Upgrade to a new version + +```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 +``` + +### View logs + +```bash +docker logs -f omniroute # Real-time stream +docker logs omniroute --tail 50 # Last 50 lines +``` + +### Manual database backup + +```bash +# Copy data from the volume to the host +docker cp omniroute:/app/data ./backup-$(date +%F) + +# Or compress the entire volume +docker run --rm -v omniroute-data:/data -v $(pwd):/backup \ + alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data +``` + +### Restore from 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. Advanced Security + +### Restrict nginx to Cloudflare IPs + +```bash +cat > /etc/nginx/cloudflare-ips.conf << โ€˜CFโ€™ +# Cloudflare IPv4 ranges โ€” update periodically +# 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 +``` + +Add the following to `nginx.conf` inside the `http {}` block: + +```nginx +include /etc/nginx/cloudflare-ips.conf; +``` + +### Install fail2ban + +```bash +apt install -y fail2ban +systemctl enable fail2ban +systemctl start fail2ban + +# Check status +fail2ban-client status sshd +``` + +### Block direct access to the Docker port + +```bash +# Prevent direct external access to port 20128 +iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP +iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT + +# Persist the rules +apt install -y iptables-persistent +netfilter-persistent save +``` + +--- + +## 7. Deploy to Cloudflare Workers (Optional) + +For remote access via Cloudflare Workers (without exposing the VM directly): + +```bash +# In the local repository +cd omnirouteCloud +npm install +npx wrangler login +npx wrangler deploy +``` + +See the full documentation at [omnirouteCloud/README.md](../omnirouteCloud/README.md). + +--- + +## Port Summary + +| Port | Service | Access | +| ----- | ----------- | -------------------------- | +| 22 | SSH | Public (with fail2ban) | +| 80 | nginx HTTP | Redirect โ†’ HTTPS | +| 443 | nginx HTTPS | Via Cloudflare Proxy | +| 20128 | OmniRoute | Localhost only (via nginx) | diff --git a/docs/i18n/fi/src/lib/a2a/README.md b/docs/i18n/fi/src/lib/a2a/README.md new file mode 100644 index 0000000000..7287dc4172 --- /dev/null +++ b/docs/i18n/fi/src/lib/a2a/README.md @@ -0,0 +1,752 @@ +# OmniRoute A2A Server (Suomi) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../../../src/lib/a2a/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../../../es/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../../../fr/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../../../de/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../../../it/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../../../ru/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../../../zh-CN/src/lib/a2a/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../../../ja/src/lib/a2a/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../../../ko/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../../../ar/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../../../in/src/lib/a2a/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../../../th/src/lib/a2a/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../../../vi/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../../../id/src/lib/a2a/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../../../ms/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../../../nl/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../../../pl/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../../../sv/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../../../no/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../../../da/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../../../fi/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../../../pt/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../../../ro/src/lib/a2a/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../../../hu/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../../../bg/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../../../sk/src/lib/a2a/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../../../uk-UA/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../../../he/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../../../phi/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../../../pt-BR/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../../../cs/src/lib/a2a/README.md) + +--- + +> **Agent-to-Agent Protocol v0.3** โ€” Enables any AI agent to use OmniRoute as an intelligent routing agent via JSON-RPC 2.0. + +The A2A Server exposes OmniRoute as a **first-class agent** that other agents can discover, delegate tasks to, and collaborate with using the [A2A Protocol](https://google.github.io/A2A/). + +--- + +## Arkkitehtuuri + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Orchestrator Agent โ”‚ +โ”‚ (LangChain, CrewAI, AutoGen, Custom Agent) โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ 1. GET /.well-known/agent.json (discover) + โ”‚ 2. POST /a2a (JSON-RPC 2.0) + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ OmniRoute A2A Server โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Task Manager โ”‚ โ”‚ Skill Engine โ”‚ โ”‚ SSE Streaming โ”‚ โ”‚ +โ”‚ โ”‚ (lifecycle) โ”‚โ”€โ”€โ”‚ (registry) โ”‚โ”€โ”€โ”‚ (real-time) โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ +โ”‚ Skills: โ”‚ โ”‚ +โ”‚ โ”œโ”€ smart-routing โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ””โ”€ quota-management โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ Routing Decision Logger โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ OmniRoute Gateway (internal) + /v1/chat/completions, /api/combos, /api/usage/quota +``` + +--- + +## Pikakรคynnistys + +### Agent Discovery + +Every A2A-compatible agent exposes an **Agent Card** at `/.well-known/agent.json`: + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +**Response:** + +```json +{ + "name": "OmniRoute", + "description": "Intelligent AI gateway with auto-routing across 50+ providers", + "url": "http://localhost:20128/a2a", + "version": "1.8.1", + "capabilities": { + "streaming": true, + "pushNotifications": false + }, + "skills": [ + { + "id": "smart-routing", + "name": "Smart Routing", + "description": "Routes prompts through OmniRoute intelligent pipeline", + "tags": ["routing", "llm", "multi-provider", "cost-optimization"], + "examples": [ + "Write a hello world in Python", + "Explain quantum computing using the cheapest provider" + ] + }, + { + "id": "quota-management", + "name": "Quota Management", + "description": "Natural-language queries about provider quotas", + "tags": ["quota", "analytics", "cost"], + "examples": [ + "Which provider has the most quota remaining?", + "Suggest a free combo for coding" + ] + } + ], + "authentication": { + "schemes": ["bearer"], + "apiKeyHeader": "Authorization" + } +} +``` + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Send a message to a skill and receive the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python hello world"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "a1b2c3d4-...", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "print('Hello, World!')" }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.0030)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "2026-03-04T..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"Quantum computing..."}}} + +: heartbeat 2026-03-04T21:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Running Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Skills Reference + +### `smart-routing` + +Routes prompts through OmniRoute's intelligent pipeline with full observability. + +**Parameters (in `metadata`):** + +| Parameter | Type | Default | Description | +| --------- | -------- | ------------ | ---------------------------------------------------------------------------------------- | +| `model` | `string` | `"auto"` | Target model (e.g., `claude-sonnet-4`, `gpt-4o`, `auto`) | +| `combo` | `string` | active combo | Specific combo to route through | +| `budget` | `number` | none | Maximum cost in USD for this request | +| `role` | `string` | none | Task role hint: `coding`, `review`, `planning`, `analysis`, `debugging`, `documentation` | + +**Returns:** + +| Field | Description | +| ------------------------------ | --------------------------------------------------------- | +| `artifacts[].content` | The LLM response text | +| `metadata.routing_explanation` | Human-readable explanation of routing decision | +| `metadata.cost_envelope` | Estimated vs actual cost with currency | +| `metadata.resilience_trace` | Array of events (primary_selected, fallback_needed, etc.) | +| `metadata.policy_verdict` | Whether the request was allowed and why | + +### `quota-management` + +Answers natural-language queries about provider quotas. + +**Query types (inferred from message content):** + +| Query Pattern | Response Type | +| ---------------------------------------------- | -------------------------------------------------------- | +| Contains `"ranking"`, `"most quota"`, `"best"` | Providers ranked by remaining quota | +| Contains `"free"`, `"suggest"` | Lists free combos or suggests free-tier providers | +| Default | Full quota summary with warnings for low-quota providers | + +--- + +## Task Lifecycle + +``` +submitted โ”€โ”€โ†’ working โ”€โ”€โ†’ completed + โ”€โ”€โ†’ failed + โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ†’ cancelled +``` + +| State | Description | +| ----------- | ----------------------------------------------------- | +| `submitted` | Task created, queued for execution | +| `working` | Skill handler is executing | +| `completed` | Execution succeeded, artifacts available | +| `failed` | Execution failed or task expired (TTL: 5 min default) | +| `cancelled` | Cancelled by client via `tasks/cancel` | + +- Terminal states: `completed`, `failed`, `cancelled` (no further transitions) +- Expired tasks in `submitted` or `working` are auto-marked as `failed` +- Tasks are garbage-collected after 2ร— TTL + +--- + +## Client Examples + +### Python โ€” Orchestrator Agent + +```python +""" +A2A Client โ€” Python example. +Discovers OmniRoute agent, sends a task, and processes the result. +""" +import requests +import json + +BASE_URL = "http://localhost:20128" +API_KEY = "your-api-key" +HEADERS = { + "Content-Type": "application/json", + "Authorization": f"Bearer {API_KEY}", +} + +# 1. Discover agent capabilities +agent_card = requests.get(f"{BASE_URL}/.well-known/agent.json").json() +print(f"Agent: {agent_card['name']} v{agent_card['version']}") +print(f"Skills: {[s['id'] for s in agent_card['skills']]}") + +# 2. Send a smart-routing task +response = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python quicksort implementation"}], + "metadata": { + "model": "auto", + "combo": "fast-coding", + "budget": 0.10, + } + } +}) +result = response.json()["result"] +print(f"\n๐Ÿ“ Response: {result['artifacts'][0]['content'][:200]}...") +print(f"๐Ÿ”€ Routing: {result['metadata']['routing_explanation']}") +print(f"๐Ÿ’ฐ Cost: ${result['metadata']['cost_envelope']['actual']}") +print(f"๐Ÿ›ก๏ธ Policy: {result['metadata']['policy_verdict']['reason']}") + +# 3. Query quota status +quota_resp = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-2", + "method": "message/send", + "params": { + "skill": "quota-management", + "messages": [{"role": "user", "content": "Which provider has the most quota remaining?"}], + } +}) +quota_result = quota_resp.json()["result"] +print(f"\n๐Ÿ“Š Quota: {quota_result['artifacts'][0]['content']}") +``` + +### TypeScript โ€” Multi-Agent Orchestrator + +```typescript +/** + * A2A Client โ€” TypeScript example. + * Shows agent discovery, task delegation, and streaming. + */ + +const BASE_URL = "http://localhost:20128"; +const API_KEY = "your-api-key"; + +interface JsonRpcResponse { + jsonrpc: "2.0"; + id: string | number; + result?: T; + error?: { code: number; message: string }; +} + +async function a2aCall(method: string, params: Record): Promise { + const resp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: `${method}-${Date.now()}`, + method, + params, + }), + }); + const json: JsonRpcResponse = await resp.json(); + if (json.error) throw new Error(`[${json.error.code}] ${json.error.message}`); + return json.result!; +} + +// โ”€โ”€ Agent Discovery โ”€โ”€ +const agentCard = await fetch(`${BASE_URL}/.well-known/agent.json`).then((r) => r.json()); +console.log(`Connected to: ${agentCard.name} (${agentCard.skills.length} skills)`); + +// โ”€โ”€ Smart Routing: Send a coding task โ”€โ”€ +const routingResult = await a2aCall("message/send", { + skill: "smart-routing", + messages: [{ role: "user", content: "Implement a Redis cache wrapper in TypeScript" }], + metadata: { model: "claude-sonnet-4", role: "coding" }, +}); +console.log("Response:", routingResult.artifacts[0].content); +console.log("Provider:", routingResult.metadata.routing_explanation); + +// โ”€โ”€ Quota Management: Find free alternatives โ”€โ”€ +const quotaResult = await a2aCall("message/send", { + skill: "quota-management", + messages: [{ role: "user", content: "Suggest free combos for documentation" }], +}); +console.log("Free combos:", quotaResult.artifacts[0].content); + +// โ”€โ”€ Streaming: Real-time response โ”€โ”€ +const streamResp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "stream-1", + method: "message/stream", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Explain microservices architecture" }], + }, + }), +}); + +const reader = streamResp.body!.getReader(); +const decoder = new TextDecoder(); +while (true) { + const { done, value } = await reader.read(); + if (done) break; + const chunk = decoder.decode(value); + for (const line of chunk.split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + if (event.params.chunk) { + process.stdout.write(event.params.chunk.content); + } + if (event.params.task.state === "completed") { + console.log("\nโœ… Stream completed"); + } + } + } +} +``` + +### Python โ€” LangChain A2A Integration + +```python +""" +LangChain integration โ€” Use OmniRoute A2A as a custom LLM. +""" +from langchain.llms.base import BaseLLM +from langchain.schema import LLMResult, Generation +import requests +from typing import List, Optional + +class OmniRouteA2A(BaseLLM): + base_url: str = "http://localhost:20128" + api_key: str = "" + model: str = "auto" + combo: Optional[str] = None + + @property + def _llm_type(self) -> str: + return "omniroute-a2a" + + def _call(self, prompt: str, stop: Optional[List[str]] = None, **kwargs) -> str: + response = requests.post( + f"{self.base_url}/a2a", + headers={ + "Content-Type": "application/json", + "Authorization": f"Bearer {self.api_key}", + }, + json={ + "jsonrpc": "2.0", + "id": "langchain-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": prompt}], + "metadata": { + "model": self.model, + **({"combo": self.combo} if self.combo else {}), + }, + }, + }, + ) + result = response.json()["result"] + return result["artifacts"][0]["content"] + + def _generate(self, prompts: List[str], stop=None, **kwargs) -> LLMResult: + return LLMResult( + generations=[[Generation(text=self._call(p, stop))] for p in prompts] + ) + +# Usage +llm = OmniRouteA2A( + base_url="http://localhost:20128", + api_key="your-key", + model="auto", + combo="fast-coding", +) +result = llm("Write a Python function to merge two sorted lists") +print(result) +``` + +### Go โ€” A2A Client + +```go +package main + +import ( + "bytes" + "encoding/json" + "fmt" + "io" + "net/http" +) + +const baseURL = "http://localhost:20128" +const apiKey = "your-api-key" + +type JsonRpcRequest struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Method string `json:"method"` + Params interface{} `json:"params"` +} + +type JsonRpcResponse struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Result interface{} `json:"result"` + Error *struct { + Code int `json:"code"` + Message string `json:"message"` + } `json:"error"` +} + +func a2aCall(method string, params interface{}) (*JsonRpcResponse, error) { + body, _ := json.Marshal(JsonRpcRequest{ + Jsonrpc: "2.0", + ID: "go-1", + Method: method, + Params: params, + }) + + req, _ := http.NewRequest("POST", baseURL+"/a2a", bytes.NewReader(body)) + req.Header.Set("Content-Type", "application/json") + req.Header.Set("Authorization", "Bearer "+apiKey) + + resp, err := http.DefaultClient.Do(req) + if err != nil { + return nil, err + } + defer resp.Body.Close() + data, _ := io.ReadAll(resp.Body) + + var result JsonRpcResponse + json.Unmarshal(data, &result) + return &result, nil +} + +func main() { + // Discover agent + resp, _ := http.Get(baseURL + "/.well-known/agent.json") + defer resp.Body.Close() + body, _ := io.ReadAll(resp.Body) + fmt.Println("Agent Card:", string(body)) + + // Send smart-routing task + result, _ := a2aCall("message/send", map[string]interface{}{ + "skill": "smart-routing", + "messages": []map[string]string{{"role": "user", "content": "Hello from Go!"}}, + "metadata": map[string]interface{}{"model": "auto"}, + }) + out, _ := json.MarshalIndent(result.Result, "", " ") + fmt.Println("Result:", string(out)) +} +``` + +--- + +## Use Cases + +### ๐Ÿค– Use Case 1: Multi-Agent Coding Pipeline + +An orchestrator agent delegates code generation to OmniRoute, then passes the output to a review agent. + +```python +def coding_pipeline(task: str): + # Step 1: Generate code via OmniRoute A2A + code_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Write production-quality code: {task}"} + ], metadata={"model": "auto", "role": "coding"}) + code = code_result["artifacts"][0]["content"] + + # Step 2: Review the code via OmniRoute A2A (different model) + review_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Review this code for bugs and improvements:\n\n{code}"} + ], metadata={"model": "auto", "role": "review"}) + review = review_result["artifacts"][0]["content"] + + # Step 3: Check costs + print(f"Code cost: ${code_result['metadata']['cost_envelope']['actual']}") + print(f"Review cost: ${review_result['metadata']['cost_envelope']['actual']}") + + return {"code": code, "review": review} +``` + +### ๐Ÿ’ก Use Case 2: Quota-Aware Agent Swarm + +Multiple agents share quota through OmniRoute, using the quota skill to coordinate. + +```python +async def quota_aware_agent(agent_name: str, task: str): + # Check quota before starting + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Which provider has the most quota remaining?"} + ]) + print(f"[{agent_name}] {quota['artifacts'][0]['content']}") + + # Send request with budget constraint + result = a2a_send("smart-routing", [ + {"role": "user", "content": task} + ], metadata={"budget": 0.05}) + + policy = result["metadata"]["policy_verdict"] + if not policy["allowed"]: + print(f"[{agent_name}] โš ๏ธ Budget exceeded: {policy['reason']}") + # Fall back to free combo + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Suggest free combos"} + ]) + print(f"[{agent_name}] Free alternatives: {quota['artifacts'][0]['content']}") + + return result +``` + +### ๐Ÿ“Š Use Case 3: Real-Time Streaming Dashboard + +A monitoring agent streams responses and displays progress in real-time. + +```typescript +async function streamingDashboard(prompt: string) { + const response = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { "Content-Type": "application/json", Authorization: `Bearer ${API_KEY}` }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "dash-1", + method: "message/stream", + params: { skill: "smart-routing", messages: [{ role: "user", content: prompt }] }, + }), + }); + + let totalChunks = 0; + const reader = response.body!.getReader(); + const decoder = new TextDecoder(); + + while (true) { + const { done, value } = await reader.read(); + if (done) break; + + for (const line of decoder.decode(value).split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + const state = event.params.task.state; + + if (state === "working" && event.params.chunk) { + totalChunks++; + process.stdout.write( + `\r[Chunk ${totalChunks}] ${event.params.chunk.content.slice(0, 50)}...` + ); + } + if (state === "completed") { + const meta = event.params.metadata; + console.log( + `\nโœ… Done | Cost: $${meta?.cost_envelope?.actual || 0} | Route: ${meta?.routing_explanation || "N/A"}` + ); + } + if (state === "failed") { + console.error(`\nโŒ Failed: ${event.params.metadata?.error}`); + } + } + } + } +} +``` + +### ๐Ÿ” Use Case 4: Task Polling Pattern + +For long-running tasks, poll the task status instead of waiting synchronously. + +```python +import time + +def poll_task(task_id: str, timeout: int = 60): + """Poll task status until completion or timeout.""" + start = time.time() + while time.time() - start < timeout: + result = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "poll-1", + "method": "tasks/get", + "params": {"taskId": task_id}, + }).json() + + task = result["result"]["task"] + state = task["state"] + print(f" Task {task_id[:8]}... state={state}") + + if state in ("completed", "failed", "cancelled"): + return task + time.sleep(2) + + # Timeout โ€” cancel the task + requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "cancel-1", + "method": "tasks/cancel", + "params": {"taskId": task_id}, + }) + raise TimeoutError(f"Task {task_id} timed out after {timeout}s") +``` + +--- + +## Error Codes + +| Code | Constant | Meaning | +| ------ | ------------------------ | ---------------------------------------- | +| -32700 | โ€” | Parse error (invalid JSON) | +| -32600 | `INVALID_REQUEST` | Invalid JSON-RPC request or unauthorized | +| -32601 | `METHOD_NOT_FOUND` | Unknown method or skill | +| -32602 | `INVALID_PARAMS` | Missing or invalid parameters | +| -32603 | `INTERNAL_ERROR` | Skill execution failed | +| -32001 | `TASK_NOT_FOUND` | Task ID not found | +| -32002 | `TASK_ALREADY_COMPLETED` | Cannot modify a completed task | +| -32003 | `UNAUTHORIZED` | Invalid or missing API key | +| -32004 | `BUDGET_EXCEEDED` | Request exceeds configured budget | +| -32005 | `PROVIDER_UNAVAILABLE` | No available providers | + +--- + +## Authentication + +All `/a2a` requests require a Bearer token via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server (`OMNIROUTE_API_KEY` is empty), authentication is bypassed. + +--- + +## File Structure + +``` +src/lib/a2a/ +โ”œโ”€โ”€ taskManager.ts # Task lifecycle (create/update/cancel/list), TTL, cleanup +โ”œโ”€โ”€ taskExecution.ts # Generic task executor with state management +โ”œโ”€โ”€ streaming.ts # SSE stream formatting, heartbeat, chunk/completion events +โ”œโ”€โ”€ routingLogger.ts # Routing decision logger (stats, history, retention) +โ””โ”€โ”€ skills/ + โ”œโ”€โ”€ smartRouting.ts # Smart routing skill (routes via /v1/chat/completions) + โ””โ”€โ”€ quotaManagement.ts # Quota management skill (natural-language quota queries) + +src/app/a2a/ +โ””โ”€โ”€ route.ts # Next.js API route handler (JSON-RPC 2.0 dispatch) + +open-sse/mcp-server/ +โ””โ”€โ”€ schemas/a2a.ts # Zod schemas (AgentCard, Task, JSON-RPC, SSE events) +``` + +--- + +## Comparison: MCP vs A2A + +| Feature | MCP Server | A2A Server | +| ----------------- | ---------------------------- | ------------------------------------------------- | +| **Protocol** | Model Context Protocol | Agent-to-Agent Protocol v0.3 | +| **Transport** | stdio / HTTP | HTTP (JSON-RPC 2.0) | +| **Discovery** | Tool listing via MCP | `/.well-known/agent.json` | +| **Granularity** | 16 individual tools | 2 high-level skills | +| **Best for** | IDE agents (Cursor, VS Code) | Multi-agent systems (LangChain, CrewAI) | +| **Streaming** | Not supported | SSE via `message/stream` | +| **Task tracking** | No | Full lifecycle (submitted โ†’ completed) | +| **Observability** | Audit log per tool call | Cost envelope + resilience trace + policy verdict | + +--- + +## Lisenssi + +Part of [OmniRoute](https://github.com/diegosouzapw/OmniRoute) โ€” MIT License. diff --git a/docs/i18n/fr/A2A-SERVER.md b/docs/i18n/fr/A2A-SERVER.md deleted file mode 100644 index 01531ff482..0000000000 --- a/docs/i18n/fr/A2A-SERVER.md +++ /dev/null @@ -1,200 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/A2A-SERVER.md) - ---- - -# OmniRoute A2A Server Documentation - -> Agent-to-Agent Protocol v0.3 โ€” OmniRoute as an intelligent routing agent - -## Agent Discovery - -```bash -curl http://localhost:20128/.well-known/agent.json -``` - -Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements. - ---- - -## Authentication - -All `/a2a` requests require an API key via the `Authorization` header: - -``` -Authorization: Bearer YOUR_OMNIROUTE_API_KEY -``` - -If no API key is configured on the server, authentication is bypassed. - ---- - -## JSON-RPC 2.0 Methods - -### `message/send` โ€” Synchronous Execution - -Sends a message to a skill and waits for the complete response. - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{ - "jsonrpc": "2.0", - "id": "1", - "method": "message/send", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Write a hello world in Python"}], - "metadata": {"model": "auto", "combo": "fast-coding"} - } - }' -``` - -**Response:** - -```json -{ - "jsonrpc": "2.0", - "id": "1", - "result": { - "task": { "id": "uuid", "state": "completed" }, - "artifacts": [{ "type": "text", "content": "..." }], - "metadata": { - "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)", - "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, - "resilience_trace": [ - { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." } - ], - "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } - } - } -} -``` - -### `message/stream` โ€” SSE Streaming - -Same as `message/send` but returns Server-Sent Events for real-time streaming. - -```bash -curl -N -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{ - "jsonrpc": "2.0", - "id": "1", - "method": "message/stream", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Explain quantum computing"}] - } - }' -``` - -**SSE Events:** - -``` -data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}} - -: heartbeat 2026-03-03T17:00:00Z - -data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} -``` - -### `tasks/get` โ€” Query Task Status - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' -``` - -### `tasks/cancel` โ€” Cancel a Task - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' -``` - ---- - -## Available Skills - -| Skill | Description | -| :----------------- | :------------------------------------------------------------------------------------------------------------------------------ | -| `smart-routing` | Routes prompts through OmniRoute's intelligent pipeline. Returns response with routing explanation, cost, and resilience trace. | -| `quota-management` | Answers natural-language queries about provider quotas, suggests free combos, and provides quota rankings. | - ---- - -## Task Lifecycle - -``` -submitted โ†’ working โ†’ completed - โ†’ failed - โ†’ cancelled -``` - -- Tasks expire after 5 minutes (configurable) -- Terminal states: `completed`, `failed`, `cancelled` -- Event log tracks every state transition - ---- - -## Error Codes - -| Code | Meaning | -| :----- | :----------------------------- | -| -32700 | Parse error (invalid JSON) | -| -32600 | Invalid request / Unauthorized | -| -32601 | Method or skill not found | -| -32602 | Invalid params | -| -32603 | Internal error | - ---- - -## Integration Examples - -### Python (requests) - -```python -import requests - -resp = requests.post("http://localhost:20128/a2a", json={ - "jsonrpc": "2.0", "id": "1", - "method": "message/send", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Hello"}] - } -}, headers={"Authorization": "Bearer YOUR_KEY"}) - -result = resp.json()["result"] -print(result["artifacts"][0]["content"]) -print(result["metadata"]["routing_explanation"]) -``` - -### TypeScript (fetch) - -```typescript -const resp = await fetch("http://localhost:20128/a2a", { - method: "POST", - headers: { - "Content-Type": "application/json", - Authorization: "Bearer YOUR_KEY", - }, - body: JSON.stringify({ - jsonrpc: "2.0", - id: "1", - method: "message/send", - params: { - skill: "smart-routing", - messages: [{ role: "user", content: "Hello" }], - }, - }), -}); -const { result } = await resp.json(); -console.log(result.metadata.routing_explanation); -``` diff --git a/docs/i18n/fr/API_REFERENCE.md b/docs/i18n/fr/API_REFERENCE.md deleted file mode 100644 index b878605221..0000000000 --- a/docs/i18n/fr/API_REFERENCE.md +++ /dev/null @@ -1,455 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/API_REFERENCE.md) - ---- - -# API Reference - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/API_REFERENCE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/API_REFERENCE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/API_REFERENCE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/API_REFERENCE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/API_REFERENCE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/API_REFERENCE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/API_REFERENCE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/API_REFERENCE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/API_REFERENCE.md) - -Complete reference for all OmniRoute API endpoints. - ---- - -## Table of Contents - -- [Chat Completions](#chat-completions) -- [Embeddings](#embeddings) -- [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`. - -### ACP Agents - -| Endpoint | Method | Description | -| ----------------- | ------ | -------------------------------------------------------- | -| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | -| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | -| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | - -GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). - -### Resilience & Rate Limits - -| Endpoint | Method | Description | -| ----------------------- | ------- | ------------------------------- | -| `/api/resilience` | 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` diff --git a/docs/i18n/fr/ARCHITECTURE.md b/docs/i18n/fr/ARCHITECTURE.md deleted file mode 100644 index 4ea06a29f2..0000000000 --- a/docs/i18n/fr/ARCHITECTURE.md +++ /dev/null @@ -1,787 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/ARCHITECTURE.md) - ---- - -# OmniRoute Architecture - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/ARCHITECTURE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/ARCHITECTURE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/ARCHITECTURE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/ARCHITECTURE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/ARCHITECTURE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/ARCHITECTURE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/ARCHITECTURE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/ARCHITECTURE.md) - -_Last updated: 2026-03-04_ - -## 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 (`...`) for reasoning models -- Response sanitization for strict OpenAI SDK compatibility -- Role normalization (developerโ†’system, systemโ†’user) for cross-provider compatibility -- Structured output conversion (json_schema โ†’ Gemini responseSchema) -- Local persistence for providers, keys, aliases, combos, settings, pricing -- Usage/cost tracking and request logging -- Optional cloud sync for multi-device/state sync -- IP allowlist/blocklist for API access control -- Thinking budget management (passthrough/auto/custom/adaptive) -- Global system prompt injection -- Session tracking and fingerprinting -- Per-account enhanced rate limiting with provider-specific profiles -- Circuit breaker pattern for provider resilience -- Anti-thundering herd protection with mutex locking -- Signature-based request deduplication cache -- Domain layer: model availability, cost rules, fallback policy, lockout policy -- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) -- Policy engine for centralized request evaluation (lockout โ†’ budget โ†’ fallback) -- Request telemetry with p50/p95/p99 latency aggregation -- Correlation ID (X-Request-Id) for end-to-end tracing -- Compliance audit logging with opt-out per API key -- Eval framework for LLM quality assurance -- Resilience UI dashboard with real-time circuit breaker status -- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) - -Primary runtime model: - -- Next.js 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[(storage.sqlite)] - UDB[(usage tables + log artifacts)] - end - - subgraph Upstreams[Upstream Providers] - P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/Qoder/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/route.ts` (GET) -- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) -- OAuth: `src/app/api/oauth/*` -- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` -- Usage: `src/app/api/usage/*` -- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` -- CLI tooling helpers: `src/app/api/cli-tools/*` -- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) -- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) -- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) -- Sessions: `src/app/api/sessions` (GET) -- Rate limits: `src/app/api/rate-limits` (GET) -- Resilience: `src/app/api/resilience` (GET/PATCH) โ€” provider profiles, circuit breaker, rate limit state -- Resilience reset: `src/app/api/resilience/reset` (POST) โ€” reset breakers + cooldowns -- Cache stats: `src/app/api/cache/stats` (GET/DELETE) -- Model availability: `src/app/api/models/availability` (GET/POST) -- Telemetry: `src/app/api/telemetry/summary` (GET) -- Budget: `src/app/api/usage/budget` (GET/POST) -- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) -- Compliance audit: `src/app/api/compliance/audit-log` (GET) -- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) -- Policies: `src/app/api/policies` (GET/POST) - -## 2) SSE + 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` -- Response sanitization: `open-sse/handlers/responseSanitizer.ts` -- Role normalization: `open-sse/services/roleNormalizer.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`, `qoder.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 (SQLite): - -- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) -- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) -- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) -- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** - -Usage persistence: - -- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) -- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` -- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) -- legacy JSON files are migrated to SQLite by startup migrations when present - -Domain State DB (SQLite): - -- `src/lib/db/domainState.ts` โ€” CRUD operations 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: - -- primary runtime DB: `${DATA_DIR}/storage.sqlite` -- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) -- structured call payload archives: `${DATA_DIR}/call_logs/` -- optional translator/request debug sessions: `/logs/...` - -## Deployment Topology - -```mermaid -flowchart LR - 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[(storage.sqlite)] - UsageDB[(usage tables + log artifacts)] - end - - subgraph External[External Services] - Providers[AI Providers] - SyncCloud[Cloud Sync Service] - end - - CLI --> Next - Browser --> Next - Next --> Core - Next --> MainDB - Core --> MainDB - Core --> UsageDB - Core --> Providers - Next --> SyncCloud -``` - -## Module Mapping (Decision-Critical) - -### Route and API Modules - -- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs -- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) -- `src/app/api/providers*`: provider CRUD, validation, testing -- `src/app/api/provider-nodes*`: custom compatible node management -- `src/app/api/provider-models`: custom model management (CRUD) -- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) -- `src/app/api/oauth/*`: OAuth/device-code flows -- `src/app/api/keys*`: local API key lifecycle -- `src/app/api/models/alias`: alias management -- `src/app/api/combos*`: fallback combo management -- `src/app/api/pricing`: pricing overrides for cost calculation -- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) -- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) -- `src/app/api/usage/*`: usage and logs APIs -- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers -- `src/app/api/cli-tools/*`: local CLI config writers/checkers -- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) -- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) -- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) -- `src/app/api/sessions`: active session listing (GET) -- `src/app/api/rate-limits`: per-account rate limit status (GET) - -### Routing and Execution Core - -- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop -- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup -- `open-sse/executors/*`: provider-specific network and format behavior - -### Translation Registry and Format Converters - -- `open-sse/translator/index.ts`: translator registry and orchestration -- Request translators: `open-sse/translator/request/*` -- Response translators: `open-sse/translator/response/*` -- Format constants: `open-sse/translator/formats.ts` - -### Persistence - -- `src/lib/db/*`: persistent config/state and domain persistence on SQLite -- `src/lib/localDb.ts`: compatibility re-export for DB modules -- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables - -## Provider Executor Coverage (Strategy Pattern) - -Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. - -| Executor | Provider(s) | Special Handling | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | -| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, Qoder, 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 | -| Qoder | openai | OAuth (Basic) | โœ… | โœ… | โœ… | โš ๏ธ Per request | -| OpenRouter | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| GLM/Kimi/MiniMax | claude | API Key | โœ… | โœ… | โŒ | โŒ | -| DeepSeek | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Groq | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| xAI (Grok) | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Mistral | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Perplexity | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Together AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Fireworks AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Cerebras | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Cohere | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| NVIDIA NIM | openai | API Key | โœ… | โœ… | โŒ | โŒ | - -## Format Translation Coverage - -Detected source formats include: - -- `openai` -- `openai-responses` -- `claude` -- `gemini` - -Target formats include: - -- OpenAI chat/Responses -- Claude -- Gemini/Gemini-CLI/Antigravity envelope -- Kiro -- Cursor - -Translations use **OpenAI as the hub format** โ€” all conversions go through OpenAI as intermediate: - -``` -Source Format โ†’ OpenAI (hub) โ†’ Target Format -``` - -Translations are selected dynamically based on source payload shape and provider target format. - -Additional processing layers in the translation pipeline: - -- **Response sanitization** โ€” Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance -- **Role normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI targets; merges `system` โ†’ `user` for models that reject the system role (GLM, ERNIE) -- **Think tag extraction** โ€” Parses `...` blocks from content into `reasoning_content` field -- **Structured output** โ€” Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` - -## Supported API Endpoints - -| 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 `/logs//` 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 - -- SQLite schema migrations and auto-upgrade hooks at startup -- legacy JSON โ†’ SQLite migration compatibility path - -## Observability and Operational Signals - -Runtime visibility sources: - -- console logs from `src/sse/utils/logger.ts` -- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) -- textual request status log in `log.txt` (optional/compat) -- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` -- dashboard usage endpoints (`/api/usage/*`) for UI consumption - -## Security-Sensitive Boundaries - -- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing -- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning -- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format -- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level -- Cloud sync endpoints rely on API key auth + machine id semantics - -## Environment and Runtime Matrix - -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` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. -2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. -3. Request logger writes full headers/body when enabled; treat log directory as sensitive. -4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. -5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. -6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). -7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). -8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). - -## Operational Verification Checklist - -- Build from source: `npm run build` -- Build Docker image: `docker build -t omniroute .` -- Start service and verify: -- `GET /api/settings` -- `GET /api/v1/models` -- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/fr/AUTO-COMBO.md b/docs/i18n/fr/AUTO-COMBO.md deleted file mode 100644 index 2166e41dff..0000000000 --- a/docs/i18n/fr/AUTO-COMBO.md +++ /dev/null @@ -1,67 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/AUTO-COMBO.md) - ---- - -# OmniRoute Auto-Combo Engine - -> Self-managing model chains with adaptive scoring - -## How It Works - -The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**: - -| Factor | Weight | Description | -| :--------- | :----- | :---------------------------------------------- | -| Quota | 0.20 | Remaining capacity [0..1] | -| Health | 0.25 | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 | -| CostInv | 0.20 | Inverse cost (cheaper = higher score) | -| LatencyInv | 0.15 | Inverse p95 latency (faster = higher) | -| TaskFit | 0.10 | Model ร— task type fitness score | -| Stability | 0.10 | Low variance in latency/errors | - -## Mode Packs - -| Pack | Focus | Key Weight | -| :---------------------- | :----------- | :--------------- | -| ๐Ÿš€ **Ship Fast** | Speed | latencyInv: 0.35 | -| ๐Ÿ’ฐ **Cost Saver** | Economy | costInv: 0.40 | -| ๐ŸŽฏ **Quality First** | Best model | taskFit: 0.40 | -| ๐Ÿ“ก **Offline Friendly** | Availability | quota: 0.40 | - -## Self-Healing - -- **Temporary exclusion**: Score < 0.2 โ†’ excluded for 5 min (progressive backoff, max 30 min) -- **Circuit breaker awareness**: OPEN โ†’ auto-excluded; HALF_OPEN โ†’ probe requests -- **Incident mode**: >50% OPEN โ†’ disable exploration, maximize stability -- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout - -## Bandit Exploration - -5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode. - -## API - -```bash -# Create auto-combo -curl -X POST http://localhost:20128/api/combos/auto \ - -H "Content-Type: application/json" \ - -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}' - -# List auto-combos -curl http://localhost:20128/api/combos/auto -``` - -## Task Fitness - -30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` โ†’ high coding score). - -## Files - -| File | Purpose | -| :------------------------------------------- | :------------------------------------ | -| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization | -| `open-sse/services/autoCombo/taskFitness.ts` | Model ร— task fitness lookup | -| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap | -| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode | -| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles | -| `src/app/api/combos/auto/route.ts` | REST API | diff --git a/docs/i18n/fr/CHANGELOG.md b/docs/i18n/fr/CHANGELOG.md index 7391f28706..8c8c0cc9db 100644 --- a/docs/i18n/fr/CHANGELOG.md +++ b/docs/i18n/fr/CHANGELOG.md @@ -1,12 +1,92 @@ # Changelog (Franรงais) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CHANGELOG.md) --- - ## [Unreleased] +### ๐Ÿ› ๏ธ Maintenance + +- **AGENTS.md rewrite:** Condensed from 297โ†’153 lines. Added build/lint/test commands (including single-test execution), code style guidelines (Prettier, TypeScript, ESLint, naming, imports, error handling, security), and trimmed verbose architecture tables for AI agent consumption. + +## [3.4.2] - 2026-04-01 + +### ๐Ÿ› Bug Fixes + +- **CI Stabilization:** Fixed failing analytics/settings Playwright selectors and request assertions so GitHub Actions E2E runs pass reliably across localized UIs and switch-based controls. +- **Deterministic Tests:** Removed date-sensitive quota fixtures from Copilot usage tests and aligned idempotency/model catalog tests with the merged runtime behavior. +- **MCP Type Hardening:** Removed zero-budget explicit `any` regressions from the MCP server tool registration path, restoring the `check:any-budget:t11` workflow gate. + +### ๐Ÿ› ๏ธ Maintenance + +- **Release Branch Integration:** Consolidated the active feature branches into `release/v3.4.2` on top of current `main` and validated the branch with lint, unit, coverage, build, and CI-mode E2E runs. + +## [3.4.1] - 2026-03-31 + +> [!WARNING] +> **BREAKING CHANGE: request logging, retention, and logging environment variables have been redesigned.** +> On the first startup after upgrading, OmniRoute archives legacy request logs from `DATA_DIR/logs/`, legacy `DATA_DIR/call_logs/`, and `DATA_DIR/log.txt` into `DATA_DIR/log_archives/*.zip`, then removes the deprecated layout and switches to the new unified artifact format under `DATA_DIR/call_logs/`. + +### โœจ New Features + +- **.ENV Migration Utility:** Included `scripts/migrate-env.mjs` to seamlessly migrate ` Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` - ---- - -## Step 2 โ€” Install CLI Tools - -All npm-based tools require Node.js 18+: - -```bash -# Claude Code (Anthropic) -npm install -g @anthropic-ai/claude-code - -# OpenAI Codex -npm install -g @openai/codex - -# Gemini CLI (Google) -npm install -g @google/gemini-cli - -# OpenCode -npm install -g opencode-ai - -# Cline -npm install -g cline - -# KiloCode -npm install -g kilecode - -# Kiro CLI (Amazon โ€” requires curl + unzip) -apt-get install -y unzip # on Debian/Ubuntu -curl -fsSL https://cli.kiro.dev/install | bash -export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc -``` - -**Verify:** - -```bash -claude --version # 2.x.x -codex --version # 0.x.x -gemini --version # 0.x.x -opencode --version # x.x.x -cline --version # 2.x.x -kilocode --version # x.x.x (or: kilo --version) -kiro-cli --version # 1.x.x -``` - ---- - -## Step 3 โ€” Set Global Environment Variables - -Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`: - -```bash -# OmniRoute Universal Endpoint -export OPENAI_BASE_URL="http://localhost:20128/v1" -export OPENAI_API_KEY="sk-your-omniroute-key" -export ANTHROPIC_BASE_URL="http://localhost:20128/v1" -export ANTHROPIC_API_KEY="sk-your-omniroute-key" -export GEMINI_BASE_URL="http://localhost:20128/v1" -export GEMINI_API_KEY="sk-your-omniroute-key" -``` - -> For a **remote server** replace `localhost:20128` with the server IP or domain, -> e.g. `http://192.168.0.15:20128`. - ---- - -## Step 4 โ€” Configure Each Tool - -### Claude Code - -```bash -# Via CLI: -claude config set --global api-base-url http://localhost:20128/v1 - -# Or create ~/.claude/settings.json: -mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF -{ - "apiBaseUrl": "http://localhost:20128/v1", - "apiKey": "sk-your-omniroute-key" -} -EOF -``` - -**Test:** `claude "say hello"` - ---- - -### OpenAI Codex - -```bash -mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF -model: auto -apiKey: sk-your-omniroute-key -apiBaseUrl: http://localhost:20128/v1 -EOF -``` - -**Test:** `codex "what is 2+2?"` - ---- - -### Gemini CLI - -```bash -mkdir -p ~/.gemini && cat > ~/.gemini/settings.json << EOF -{ - "apiKey": "sk-your-omniroute-key", - "baseUrl": "http://localhost:20128/v1" -} -EOF -``` - -**Test:** `gemini "hello"` - ---- - -### OpenCode - -```bash -mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF -[provider.openai] -base_url = "http://localhost:20128/v1" -api_key = "sk-your-omniroute-key" -EOF -``` - -**Test:** `opencode` - ---- - -### Cline (CLI or VS Code) - -**CLI mode:** - -```bash -mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF -{ - "apiProvider": "openai", - "openAiBaseUrl": "http://localhost:20128/v1", - "openAiApiKey": "sk-your-omniroute-key" -} -EOF -``` - -**VS Code mode:** -Cline extension settings โ†’ API Provider: `OpenAI Compatible` โ†’ Base URL: `http://localhost:20128/v1` - -Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ Cline โ†’ Apply Config**. - ---- - -### KiloCode (CLI or VS Code) - -**CLI mode:** - -```bash -kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key -``` - -**VS Code settings:** - -```json -{ - "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", - "kilo-code.apiKey": "sk-your-omniroute-key" -} -``` - -Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ KiloCode โ†’ Apply Config**. - ---- - -### Continue (VS Code Extension) - -Edit `~/.continue/config.yaml`: - -```yaml -models: - - name: OmniRoute - provider: openai - model: auto - apiBase: http://localhost:20128/v1 - apiKey: sk-your-omniroute-key - default: true -``` - -Restart VS Code after editing. - ---- - -### Kiro CLI (Amazon) - -```bash -# Login to your AWS/Kiro account: -kiro-cli login - -# The CLI uses its own auth โ€” OmniRoute is not needed as backend for Kiro CLI itself. -# Use kiro-cli alongside OmniRoute for other tools. -kiro-cli status -``` - ---- - -### Cursor (Desktop App) - -> **Note:** Cursor routes requests through its cloud. For OmniRoute integration, -> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL. - -Via GUI: **Settings โ†’ Models โ†’ OpenAI API Key** - -- Base URL: `https://your-domain.com/v1` -- API Key: your OmniRoute key - ---- - -## Dashboard Auto-Configuration - -The OmniRoute dashboard automates configuration for most tools: - -1. Go to `http://localhost:20128/dashboard/cli-tools` -2. Expand any tool card -3. Select your API key from the dropdown -4. Click **Apply Config** (if tool is detected as installed) -5. Or copy the generated config snippet manually - ---- - -## Built-in Agents: Droid & OpenClaw - -**Droid** and **OpenClaw** are AI agents built directly into OmniRoute โ€” no installation needed. -They run as internal routes and use OmniRoute's model routing automatically. - -- Access: `http://localhost:20128/dashboard/agents` -- Configure: same combos and providers as all other tools -- No API key or CLI install required - ---- - -## Available API Endpoints - -| Endpoint | Description | Use For | -| -------------------------- | ----------------------------- | --------------------------- | -| `/v1/chat/completions` | Standard chat (all providers) | All modern tools | -| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows | -| `/v1/completions` | Legacy text completions | Older tools using `prompt:` | -| `/v1/embeddings` | Text embeddings | RAG, search | -| `/v1/images/generations` | Image generation | DALL-E, Flux, etc. | -| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS | -| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI | - ---- - -## Troubleshooting - -| Error | Cause | Fix | -| ------------------------- | ----------------------- | ------------------------------------------ | -| `Connection refused` | OmniRoute not running | `pm2 start omniroute` | -| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` | -| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` | -| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` | -| CLI shows "not installed" | Binary not in PATH | Check `which ` | -| `kiro-cli: not found` | Not in PATH | `export PATH="$HOME/.local/bin:$PATH"` | - ---- - -## Quick Setup Script (One Command) - -```bash -# Install all CLIs and configure for OmniRoute (replace with your key and server URL) -OMNIROUTE_URL="http://localhost:20128/v1" -OMNIROUTE_KEY="sk-your-omniroute-key" - -npm install -g @anthropic-ai/claude-code @openai/codex @google/gemini-cli opencode-ai cline kilecode - -# Kiro CLI -apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash - -# Write configs -mkdir -p ~/.claude ~/.codex ~/.gemini ~/.config/opencode ~/.continue - -cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" -cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" -cat > ~/.gemini/settings.json <<< "{\"apiKey\":\"$OMNIROUTE_KEY\",\"baseUrl\":\"$OMNIROUTE_URL\"}" -cat >> ~/.bashrc << EOF -export OPENAI_BASE_URL="$OMNIROUTE_URL" -export OPENAI_API_KEY="$OMNIROUTE_KEY" -export ANTHROPIC_BASE_URL="$OMNIROUTE_URL" -export ANTHROPIC_API_KEY="$OMNIROUTE_KEY" -EOF - -source ~/.bashrc -echo "โœ… All CLIs installed and configured for OmniRoute" -``` diff --git a/docs/i18n/fr/CODEBASE_DOCUMENTATION.md b/docs/i18n/fr/CODEBASE_DOCUMENTATION.md deleted file mode 100644 index e2d7950052..0000000000 --- a/docs/i18n/fr/CODEBASE_DOCUMENTATION.md +++ /dev/null @@ -1,593 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CODEBASE_DOCUMENTATION.md) - ---- - -# omniroute โ€” Codebase Documentation - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) - -> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. - ---- - -## 1. 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
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, Qoder, 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 | -| Qoder | 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"] -``` diff --git a/docs/i18n/fr/CONTRIBUTING.md b/docs/i18n/fr/CONTRIBUTING.md new file mode 100644 index 0000000000..3c1de7b148 --- /dev/null +++ b/docs/i18n/fr/CONTRIBUTING.md @@ -0,0 +1,299 @@ +# Contributing to OmniRoute (Franรงais) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CONTRIBUTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CONTRIBUTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CONTRIBUTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CONTRIBUTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CONTRIBUTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CONTRIBUTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CONTRIBUTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CONTRIBUTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CONTRIBUTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CONTRIBUTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CONTRIBUTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CONTRIBUTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CONTRIBUTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CONTRIBUTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CONTRIBUTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CONTRIBUTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CONTRIBUTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CONTRIBUTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CONTRIBUTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CONTRIBUTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CONTRIBUTING.md) + +--- + +Thank you for your interest in contributing! This guide covers everything you need to get started. + +--- + +## Development Setup + +### Prerequisites + +- **Node.js** >= 18 < 24 (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` | `20128` | Server port | +| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | Base URL for frontend | +| `JWT_SECRET` | (generate above) | JWT signing secret | +| `INITIAL_PASSWORD` | `CHANGEME` | First login password | +| `APP_LOG_LEVEL` | `info` | Log verbosity level | + +### Dashboard Settings + +The dashboard provides UI toggles for features that can also be configured via environment variables: + +| Setting Location | Toggle | Description | +| ------------------- | ------------------ | ------------------------------ | +| Settings โ†’ Advanced | Debug Mode | Enable debug request logs (UI) | +| Settings โ†’ General | Sidebar Visibility | Show/hide sidebar sections | + +These settings are stored in the database and persist across restarts, overriding env var defaults when set. + +### 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:20128/dashboard` +- **API**: `http://localhost:20128/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`, `mcp`, `a2a`, `memory`, `skills`. + +--- + +## Running Tests + +```bash +# All tests (unit + vitest + ecosystem + e2e) +npm run test:all + +# Single test file (Node.js native test runner โ€” most tests use this) +node --import tsx/esm --test tests/unit/your-file.test.mjs + +# Vitest (MCP server, autoCombo, cache) +npm run test:vitest + +# E2E tests (requires Playwright) +npm run test:e2e + +# Protocol clients E2E (MCP transports, A2A) +npm run test:protocols:e2e + +# Ecosystem compatibility tests +npm run test:ecosystem + +# Coverage (55% min statements/lines/functions; 60% branches) +npm run test:coverage +npm run coverage:report + +# Lint + format check +npm run lint +npm run check +``` + +Coverage notes: + +- `npm run test:coverage` measures source coverage for the main unit test suite, excludes `tests/**`, and includes `open-sse/**` +- `npm run coverage:report` prints the detailed file-by-file report from the latest coverage run +- `npm run test:coverage:legacy` preserves the older metric for historical comparison +- See `docs/COVERAGE_PLAN.md` for the phased coverage improvement roadmap + +Current test status: **122 unit test files** covering: + +- Provider translators and format conversion +- Rate limiting, circuit breaker, and resilience +- Semantic cache, idempotency, progress tracking +- Database operations and schema (21 DB modules) +- OAuth flows and authentication +- API endpoint validation (Zod v4) +- MCP server tools and scope enforcement +- Memory and Skills systems + +--- + +## Code Style + +- **ESLint** โ€” Run `npm run lint` before committing +- **Prettier** โ€” Auto-formatted via `lint-staged` on commit (2 spaces, semicolons, double quotes, 100 char width, es5 trailing commas) +- **TypeScript** โ€” All `src/` code uses `.ts`/`.tsx`; `open-sse/` uses `.ts`/`.js`; document with TSDoc (`@param`, `@returns`, `@throws`) +- **No `eval()`** โ€” ESLint enforces `no-eval`, `no-implied-eval`, `no-new-func` +- **Zod validation** โ€” Use Zod v4 schemas for all API input validation +- **Naming**: Files = camelCase/kebab-case, components = PascalCase, constants = UPPER_SNAKE + +--- + +## Project Structure + +``` +src/ # TypeScript (.ts / .tsx) +โ”œโ”€โ”€ app/ # Next.js 16 App Router +โ”‚ โ”œโ”€โ”€ (dashboard)/ # Dashboard pages (23 sections) +โ”‚ โ”œโ”€โ”€ api/ # API routes (51 directories) +โ”‚ โ””โ”€โ”€ login/ # Auth pages (.tsx) +โ”œโ”€โ”€ domain/ # Policy engine (policyEngine, comboResolver, costRules, etc.) +โ”œโ”€โ”€ lib/ # Core business logic (.ts) +โ”‚ โ”œโ”€โ”€ a2a/ # Agent-to-Agent v0.3 protocol server +โ”‚ โ”œโ”€โ”€ acp/ # Agent Communication Protocol registry +โ”‚ โ”œโ”€โ”€ compliance/ # Compliance policy engine +โ”‚ โ”œโ”€โ”€ db/ # SQLite database layer (21 modules + 16 migrations) +โ”‚ โ”œโ”€โ”€ memory/ # Persistent conversational memory +โ”‚ โ”œโ”€โ”€ oauth/ # OAuth providers, services, and utilities +โ”‚ โ”œโ”€โ”€ skills/ # Extensible skill framework +โ”‚ โ”œโ”€โ”€ usage/ # Usage tracking and cost calculation +โ”‚ โ””โ”€โ”€ localDb.ts # Re-export layer only โ€” never add logic here +โ”œโ”€โ”€ middleware/ # Request middleware (promptInjectionGuard) +โ”œโ”€โ”€ mitm/ # MITM proxy (cert, DNS, target routing) +โ”œโ”€โ”€ shared/ +โ”‚ โ”œโ”€โ”€ components/ # React components (.tsx) +โ”‚ โ”œโ”€โ”€ constants/ # Provider definitions (60+), MCP scopes, routing strategies +โ”‚ โ”œโ”€โ”€ utils/ # Circuit breaker, sanitizer, auth helpers +โ”‚ โ””โ”€โ”€ validation/ # Zod v4 schemas +โ””โ”€โ”€ sse/ # SSE proxy pipeline + +open-sse/ # @omniroute/open-sse workspace +โ”œโ”€โ”€ executors/ # 14 provider-specific request executors +โ”œโ”€โ”€ handlers/ # 11 request handlers (chat, responses, embeddings, images, etc.) +โ”œโ”€โ”€ mcp-server/ # MCP server (25 tools, 3 transports, 10 scopes) +โ”œโ”€โ”€ services/ # 36+ services (combo, autoCombo, rateLimitManager, etc.) +โ”œโ”€โ”€ translator/ # Format translators (OpenAI โ†” Claude โ†” Gemini โ†” Responses โ†” Ollama) +โ”œโ”€โ”€ transformer/ # Responses API transformer +โ””โ”€โ”€ utils/ # 22 utility modules (stream, TLS, proxy, logging) + +electron/ # Electron desktop app (cross-platform) + +tests/ +โ”œโ”€โ”€ unit/ # Node.js test runner (122 test files) +โ”œโ”€โ”€ integration/ # Integration tests +โ”œโ”€โ”€ e2e/ # Playwright tests +โ”œโ”€โ”€ security/ # Security tests +โ”œโ”€โ”€ translator/ # Translator-specific tests +โ””โ”€โ”€ load/ # Load tests + +docs/ # Documentation +โ”œโ”€โ”€ ARCHITECTURE.md # System architecture +โ”œโ”€โ”€ API_REFERENCE.md # All endpoints +โ”œโ”€โ”€ USER_GUIDE.md # Provider setup, CLI integration +โ”œโ”€โ”€ TROUBLESHOOTING.md # Common issues +โ”œโ”€โ”€ MCP-SERVER.md # MCP server (25 tools) +โ”œโ”€โ”€ A2A-SERVER.md # A2A agent protocol +โ”œโ”€โ”€ AUTO-COMBO.md # Auto-combo engine +โ”œโ”€โ”€ CLI-TOOLS.md # CLI tools integration +โ”œโ”€โ”€ COVERAGE_PLAN.md # Test coverage improvement plan +โ”œโ”€โ”€ openapi.yaml # OpenAPI specification +โ””โ”€โ”€ adr/ # Architecture Decision Records +``` + +--- + +## Adding a New Provider + +### Step 1: Register Provider Constants + +Add to `src/shared/constants/providers.ts` โ€” Zod-validated at module load. + +### Step 2: Add Executor (if custom logic needed) + +Create executor in `open-sse/executors/your-provider.ts` extending the base executor. + +### Step 3: Add Translator (if non-OpenAI format) + +Create request/response translators in `open-sse/translator/`. + +### Step 4: Add OAuth Config (if OAuth-based) + +Add OAuth credentials in `src/lib/oauth/constants/oauth.ts` and service in `src/lib/oauth/services/`. + +### Step 5: Register Models + +Add model definitions in `open-sse/config/providerRegistry.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 +- [ ] All inputs validated with Zod schemas +- [ ] CHANGELOG updated (if user-facing change) +- [ ] Documentation updated (if applicable) + +--- + +## Releasing + +Releases are managed via the `/generate-release` workflow. When a new GitHub Release is created, the package is **automatically published to npm** via GitHub Actions. + +--- + +## Getting Help + +- **Architecture**: See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) +- **API Reference**: See [`docs/API_REFERENCE.md`](docs/API_REFERENCE.md) +- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **ADRs**: See `docs/adr/` for architectural decision records diff --git a/docs/i18n/fr/FEATURES.md b/docs/i18n/fr/FEATURES.md deleted file mode 100644 index a65b5ba05c..0000000000 --- a/docs/i18n/fr/FEATURES.md +++ /dev/null @@ -1,147 +0,0 @@ -# OmniRoute โ€” Dashboard Features Gallery (Franรงais) - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) - -> ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../docs/FEATURES.md) - ---- - -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 (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. - -![Providers Dashboard](screenshots/01-providers.png) - ---- - -## ๐ŸŽจ Combos - -Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. - -![Combos Dashboard](screenshots/02-combos.png) - ---- - -## ๐Ÿ“Š Analytics - -Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. - -![Analytics Dashboard](screenshots/03-analytics.png) - ---- - -## ๐Ÿฅ System Health - -Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. - -![Health Dashboard](screenshots/04-health.png) - ---- - -## ๐Ÿ”ง Translator Playground - -Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). - -![Translator Playground](screenshots/05-translator.png) - ---- - -## ๐ŸŽฎ Model Playground _(v2.0.9+)_ - -Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. - ---- - -## ๐ŸŽจ Themes _(v2.0.5+)_ - -Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. - ---- - -## โš™๏ธ Settings - -Comprehensive settings panel with tabs: - -- **General** โ€” System storage, backup management (export/import database) -- **Appearance** โ€” Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls -- **Security** โ€” API endpoint protection, custom provider blocking, IP filtering, session info -- **Routing** โ€” Model aliases, background task degradation -- **Resilience** โ€” Rate limit persistence, circuit breaker tuning -- **Advanced** โ€” Configuration overrides - -![Settings Dashboard](screenshots/06-settings.png) - ---- - -## ๐Ÿ”ง CLI Tools - -One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. - -![CLI Tools Dashboard](screenshots/07-cli-tools.png) - ---- - -## ๐Ÿค– CLI Agents _(v2.0.11+)_ - -Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: - -- **Installation status** โ€” Installed / Not Found with version detection -- **Protocol badges** โ€” stdio, HTTP, etc. -- **Custom agents** โ€” Register any CLI tool via form (name, binary, version command, spawn args) -- **CLI Fingerprint Matching** โ€” Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP - ---- - -## ๐Ÿ–ผ๏ธ Media _(v2.0.3+)_ - -Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. - ---- - -## ๐Ÿ“ Request Logs - -Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. - -![Usage Logs](screenshots/08-usage.png) - ---- - -## ๐ŸŒ API Endpoint - -Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. - -![Endpoint Dashboard](screenshots/09-endpoint.png) - ---- - -## ๐Ÿ”‘ API Key Management - -Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. - ---- - -## ๐Ÿ“‹ Audit Log - -Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. - ---- - -## ๐Ÿ–ฅ๏ธ Desktop Application - -Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. - -Key features: - -- Server readiness polling (no blank screen on cold start) -- System tray with port management -- Content Security Policy -- Single-instance lock -- Auto-update on restart -- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) -- Hardened Electron build packaging โ€” symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+) - -๐Ÿ“– See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/fr/MCP-SERVER.md b/docs/i18n/fr/MCP-SERVER.md deleted file mode 100644 index 829acd30b1..0000000000 --- a/docs/i18n/fr/MCP-SERVER.md +++ /dev/null @@ -1,87 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/MCP-SERVER.md) - ---- - -# OmniRoute MCP Server Documentation - -> Model Context Protocol server with 16 intelligent tools - -## Installation - -OmniRoute MCP is built-in. Start it with: - -```bash -omniroute --mcp -``` - -Or via the open-sse transport: - -```bash -# HTTP streamable transport (port 20130) -omniroute --dev # MCP auto-starts on /mcp endpoint -``` - -## IDE Configuration - -See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup. - ---- - -## Essential Tools (8) - -| Tool | Description | -| :------------------------------ | :--------------------------------------- | -| `omniroute_get_health` | Gateway health, circuit breakers, uptime | -| `omniroute_list_combos` | All configured combos with models | -| `omniroute_get_combo_metrics` | Performance metrics for a specific combo | -| `omniroute_switch_combo` | Switch active combo by ID/name | -| `omniroute_check_quota` | Quota status per provider or all | -| `omniroute_route_request` | Send a chat completion through OmniRoute | -| `omniroute_cost_report` | Cost analytics for a time period | -| `omniroute_list_models_catalog` | Full model catalog with capabilities | - -## Advanced Tools (8) - -| Tool | Description | -| :--------------------------------- | :---------------------------------------------- | -| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | -| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | -| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | -| `omniroute_test_combo` | Live-test all models in a combo | -| `omniroute_get_provider_metrics` | Detailed metrics for one provider | -| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | -| `omniroute_explain_route` | Explain a past routing decision | -| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | - -## Authentication - -MCP tools are authenticated via API key scopes. Each tool requires specific scopes: - -| Scope | Tools | -| :------------- | :----------------------------------------------- | -| `read:health` | get_health, get_provider_metrics | -| `read:combos` | list_combos, get_combo_metrics | -| `write:combos` | switch_combo | -| `read:quota` | check_quota | -| `write:route` | route_request, simulate_route, test_combo | -| `read:usage` | cost_report, get_session_snapshot, explain_route | -| `write:config` | set_budget_guard, set_resilience_profile | -| `read:models` | list_models_catalog, best_combo_for_task | - -## Audit Logging - -Every tool call is logged to `mcp_tool_audit` with: - -- Tool name, arguments, result -- Duration (ms), success/failure -- API key hash, timestamp - -## Files - -| File | Purpose | -| :------------------------------------------- | :------------------------------------------ | -| `open-sse/mcp-server/server.ts` | MCP server creation + 16 tool registrations | -| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport | -| `open-sse/mcp-server/auth.ts` | API key + scope validation | -| `open-sse/mcp-server/audit.ts` | Tool call audit logging | -| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers | diff --git a/docs/i18n/fr/README.md b/docs/i18n/fr/README.md index 77c642a234..8d3d52f5fb 100644 --- a/docs/i18n/fr/README.md +++ b/docs/i18n/fr/README.md @@ -1,12 +1,12 @@ # ๐Ÿš€ OmniRoute โ€” The Free AI Gateway (Franรงais) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/README.md) --- ### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback. -_Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._ +_Your universal API proxy โ€” one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._ **Chat Completions โ€ข Embeddings โ€ข Image Generation โ€ข Video โ€ข Music โ€ข Audio โ€ข Reranking โ€ข **Web Search** โ€ข MCP Server โ€ข A2A Protocol โ€ข 100% TypeScript** @@ -46,15 +46,17 @@ _Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now wi > - `APP_LOG_FILE_PATH` > - `APP_LOG_MAX_FILE_SIZE` > - `APP_LOG_RETENTION_DAYS` +> - `APP_LOG_MAX_FILES` > - `APP_LOG_LEVEL` > - `APP_LOG_FORMAT` > - `CALL_LOG_RETENTION_DAYS` +> - `CALL_LOG_MAX_ENTRIES` > > For release details and upgrade notes, see the [CHANGELOG](CHANGELOG.md). --- -## ๐Ÿ†• What's New in v3.0.0 +## ๐Ÿ†• What's New > **Upgrading from v2.9.5?** โ€” See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes. @@ -274,7 +276,7 @@ Developers pay $20โ€“200/month for Claude Pro, Codex Pro, or GitHub Copilot. Eve - **Smart 4-Tier Fallback** โ€” If subscription quota runs out, automatically redirects to API Key โ†’ Cheap โ†’ Free with zero manual intervention - **Real-Time Quota Tracking** โ€” Shows token consumption in real-time with reset countdown (5h, daily, weekly) - **Multi-Account Support** โ€” Multiple accounts per provider with auto round-robin โ€” when one runs out, switches to the next -- **Custom Combos** โ€” Customizable fallback chains with 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Custom Combos** โ€” Customizable fallback chains with 9 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random) - **Codex Business Quotas** โ€” Business/Team workspace quota monitoring directly in the dashboard @@ -286,7 +288,7 @@ OpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If **How OmniRoute solves it:** -- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 67+ providers +- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 60+ providers - **Format Translation** โ€” Automatic and transparent: OpenAI โ†” Claude โ†” Gemini โ†” Responses API - **Response Sanitization** โ€” Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+ - **Role Normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI providers; `system` โ†’ `user` for GLM/ERNIE @@ -372,7 +374,7 @@ Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code.. - **CLI Tools Dashboard** โ€” Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline - **GitHub Copilot Config Generator** โ€” Generates `chatLanguageModels.json` for VS Code with bulk model selection - **Onboarding Wizard** โ€” Guided 4-step setup for first-time users -- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 67+ providers +- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 60+ providers @@ -419,7 +421,7 @@ When a call fails, the dev doesn't know if it was a rate limit, expired token, w - **SQLite Proxy Logs** โ€” Persistent logs that survive server restarts - **Translator Playground** โ€” 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time) - **Request Telemetry** โ€” p50/p95/p99 latency + X-Request-Id tracing -- **File-Based Logging with Rotation** โ€” Console interceptor captures everything to JSON log with size-based rotation +- **File-Based Logging with Rotation** โ€” App logs rotate by size, retention days, and archive count; call log artifacts rotate by retention days and file count - **System Info Report** โ€” `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage. @@ -514,7 +516,7 @@ Developers who want all responses in a specific language, with a specific tone, - **System Prompt Injection** โ€” Global prompt applied to all requests - **Thinking Budget Validation** โ€” Reasoning token allocation control per request (passthrough, auto, custom, adaptive) -- **6 Routing Strategies** โ€” Global strategies that determine how requests are distributed +- **9 Routing Strategies** โ€” Global strategies that determine how requests are distributed - **Wildcard Router** โ€” `provider/*` patterns route dynamically to any provider - **Combo Enable/Disable Toggle** โ€” Toggle combos directly from the dashboard - **Provider Toggle** โ€” Enable/disable all connections for a provider with one click @@ -581,7 +583,7 @@ Different clients should have least-privilege access to tool categories. **How OmniRoute solves it:** -- 9 granular MCP scopes for controlled tool access +- 10 granular MCP scopes for controlled tool access - Scope enforcement and visibility in MCP management UI - Safe default posture for operational tooling @@ -1325,19 +1327,19 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. ### ๐Ÿค– Agent & Protocol Operations (v2.0) -| Feature | What It Does | -| ------------------------------------- | -------------------------------------------------------------------------------------------------- | -| ๐Ÿ”ง **MCP Server (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) | -| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | -| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | -| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | -| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | -| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | -| ๐Ÿ” **MCP Scope Enforcement** | 9 granular scope permissions for controlled tool access | -| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | -| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | -| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | -| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | +| Feature | What It Does | +| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| ๐Ÿ”ง **MCP Server (25 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools | +| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | +| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | +| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | +| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | +| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | +| ๐Ÿ” **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access | +| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | +| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | +| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | +| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | ### ๐Ÿง  Routing & Intelligence @@ -1348,7 +1350,7 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. | ๐Ÿ”„ **Format Translation** | OpenAI โ†” Claude โ†” Gemini โ†” Responses with schema-safe conversions | | ๐Ÿ‘ฅ **Multi-Account Support** | Multiple accounts per provider with intelligent selection | | ๐Ÿ”„ **Auto Token Refresh** | OAuth tokens refresh automatically with retry | -| ๐ŸŽจ **Custom Combos** | 6 balancing strategies + fallback chain control | +| ๐ŸŽจ **Custom Combos** | 9 balancing strategies + fallback chain control | | ๐ŸŒ **Wildcard Router** | `provider/*` dynamic routing | | ๐Ÿง  **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits | | ๐Ÿ”€ **Model Aliases** | Built-in + custom model aliasing and migration safety | @@ -1949,6 +1951,7 @@ opencode - Request artifacts are written to `DATA_DIR/call_logs/` as one JSON file per request - Enable pipeline capture from Dashboard โ†’ Logs โ†’ Request Logs if you need detailed per-stage payloads - Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log` +- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed **Connection test shows "Invalid" for OpenAI-compatible providers** diff --git a/docs/i18n/fr/RELEASE_CHECKLIST.md b/docs/i18n/fr/RELEASE_CHECKLIST.md deleted file mode 100644 index 903e812c3f..0000000000 --- a/docs/i18n/fr/RELEASE_CHECKLIST.md +++ /dev/null @@ -1,37 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/RELEASE_CHECKLIST.md) - ---- - -# Release Checklist - -Use this checklist before tagging or publishing a new OmniRoute release. - -## Version and Changelog - -1. Bump `package.json` version (`x.y.z`) in the release branch. -2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: - - `## [x.y.z] โ€” YYYY-MM-DD` -3. Keep `## [Unreleased]` as the first changelog section for upcoming work. -4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. - -## API Docs - -1. Update `docs/openapi.yaml`: - - `info.version` must equal `package.json` version. -2. Validate endpoint examples if API contracts changed. - -## Runtime Docs - -1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. -2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. -3. Update localized docs if source docs changed significantly. - -## Automated Check - -Run the sync guard locally before opening PR: - -```bash -npm run check:docs-sync -``` - -CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/fr/SECURITY.md b/docs/i18n/fr/SECURITY.md new file mode 100644 index 0000000000..84f07f5ca3 --- /dev/null +++ b/docs/i18n/fr/SECURITY.md @@ -0,0 +1,179 @@ +# Security Policy (Franรงais) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../SECURITY.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/SECURITY.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/SECURITY.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/SECURITY.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/SECURITY.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/SECURITY.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/SECURITY.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/SECURITY.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/SECURITY.md) + +--- + +## 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 | +| ------- | -------------- | +| 3.4.x | โœ… Active | +| 3.0.x | โœ… Security | +| < 3.0.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 | +| **MCP Scopes** | 10 granular scopes for MCP tool access control | + +### ๐Ÿ›ก๏ธ 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:::` +- 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** | Allowlist/blocklist IP ranges in dashboard | +| **Rate Limiting** | Per-provider rate limits with automatic backoff | +| **Anti-Thundering Herd** | Mutex + per-connection locking prevents cascading 502s | +| **TLS Fingerprint** | Browser-like TLS fingerprint spoofing to reduce bot detection | +| **CLI Fingerprint** | Per-provider header/body ordering to match native CLI signatures | + +### ๐Ÿ”Œ Resilience & Availability + +| 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 `CALL_LOG_RETENTION_DAYS` | +| **No-Log Opt-out** | Per API key `noLog` flag disables request logging | +| **Audit Log** | Administrative actions tracked in `audit_log` table | +| **MCP Audit** | SQLite-backed audit logging for all MCP tool calls | +| **Zod Validation** | All API inputs validated with Zod v4 schemas at module load | + +--- + +## 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 +- Provider constants validated at module load via Zod (`src/shared/validation/providerSchema.ts`) diff --git a/docs/i18n/fr/TROUBLESHOOTING.md b/docs/i18n/fr/TROUBLESHOOTING.md deleted file mode 100644 index 63c148000a..0000000000 --- a/docs/i18n/fr/TROUBLESHOOTING.md +++ /dev/null @@ -1,258 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/TROUBLESHOOTING.md) - ---- - -# Troubleshooting - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/TROUBLESHOOTING.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/TROUBLESHOOTING.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/TROUBLESHOOTING.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/TROUBLESHOOTING.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/TROUBLESHOOTING.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/TROUBLESHOOTING.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/TROUBLESHOOTING.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/TROUBLESHOOTING.md) - -Common problems and solutions for OmniRoute. - ---- - -## Quick Fixes - -| Problem | Solution | -| ----------------------------- | ------------------------------------------------------------------ | -| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | -| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | -| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | -| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | -| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | - ---- - -## Provider Issues - -### "Language model did not provide messages" - -**Cause:** Provider quota exhausted. - -**Fix:** - -1. 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, Qoder) 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}/storage.sqlite` (providers, combos, aliases, keys, settings) -- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` -- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) - ---- - -## Circuit Breaker Issues - -### Provider stuck in OPEN state - -When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. - -**Fix:** - -1. 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 -- **SDK returns raw string instead of object** โ€” Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures -- **GLM/ERNIE rejects `system` role** โ€” Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models -- **`developer` role not recognized** โ€” Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers -- **`json_schema` not working with Gemini** โ€” Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` - ---- - -## Resilience Settings - -### Auto rate-limit not triggering - -- 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. - ---- - -## Optional RAG / LLM failure taxonomy (16 problems) - -Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. - -In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. - -If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: - -- retrieval drift and broken context boundaries -- empty or stale indexes and vector stores -- embedding versus semantic mismatch -- prompt assembly and context window issues -- logic collapse and overconfident answers -- long chain and agent coordination failures -- multi agent memory and role drift -- deployment and bootstrap ordering problems - -The idea is simple: - -1. When you investigate a bad response, capture: - - user task and request - - route or provider combo in OmniRoute - - any RAG context used downstream (retrieved documents, tool calls, etc) -2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` โ€ฆ `No.16`). -3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. -4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. - -Full text and concrete recipes live here (MIT license, text only): - -[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) - -You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. - ---- - -## Still Stuck? - -- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details -- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints -- **Health Dashboard**: Check **Dashboard โ†’ Health** for real-time system status -- **Translator**: Use **Dashboard โ†’ Translator** to debug format issues diff --git a/docs/i18n/fr/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/fr/VM_DEPLOYMENT_GUIDE.md deleted file mode 100644 index 3f95c0565e..0000000000 --- a/docs/i18n/fr/VM_DEPLOYMENT_GUIDE.md +++ /dev/null @@ -1,401 +0,0 @@ -# OmniRoute โ€” Guide de dรฉploiement sur VM avec Cloudflare - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](../pt-BR/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](../es/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](../fr/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](../it/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](../ru/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](../zh-CN/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](../de/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](../in/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](../th/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](../uk-UA/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](../ar/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](../ja/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](../vi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](../bg/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](../da/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](../fi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](../he/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](../hu/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](../id/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](../ko/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](../ms/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](../nl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](../no/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](../pt/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](../ro/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](../pl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](../sk/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](../sv/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](../phi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](../cs/VM_DEPLOYMENT_GUIDE.md) - -Guide complet pour installer et configurer OmniRoute sur une VM (VPS) avec domaine gรฉrรฉ via Cloudflare. - ---- - -## Prรฉrequis - -| Article | Minimum | Recommandรฉ | -| -------------- | ---------------------- | ---------------------- | -| **processeur** | 1 processeur virtuel | 2 processeurs virtuels | -| **RAM** | 1 Go | 2 Go | -| **Disque** | Disque SSD de 10 Go | Disque SSD de 25 Go | -| **OS** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS | -| **Domaine** | Inscrit sur Cloudflare | โ€” | -| **Docker** | Moteur Docker 24+ | Docker 27+ | - -**Fournisseurs testรฉs**ย : Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. - ---- - -## 1. Configurer la VM - -### 1.1 Crรฉer l'instance - -Sur votre fournisseur VPS prรฉfรฉrรฉย : - -- Choisissez Ubuntu 24.04 LTS -- Sรฉlectionnez le forfait minimum (1 vCPU / 1 Go de RAM) -- Dรฉfinissez un mot de passe root fort ou configurez la clรฉ SSH -- Notez l'**IP publique** (par exemple, `203.0.113.10`) - -### 1.2 Connectez-vous via SSH - -```bash -ssh root@203.0.113.10 -``` - -### 1.3 Mettre ร  jour le systรจme - -```bash -apt update && apt upgrade -y -``` - -### 1.4 Installer Docker - -```bash -# Install dependencies -apt install -y ca-certificates curl gnupg - -# Add official Docker repository -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 Installer nginx - -```bash -apt install -y nginx -``` - -### 1.6 Configurer le pare-feu (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 -``` - -> **Conseil**ย : Pour une sรฉcuritรฉ maximale, limitez les ports 80 et 443 aux IP Cloudflare uniquement. Voir la section [Advanced Security](#advanced-security). - ---- - -## 2. Installez OmniRoute - -### 2.1 Crรฉer un rรฉpertoire de configuration - -```bash -mkdir -p /opt/omniroute -``` - -### 2.2 Crรฉer un fichier de variables d'environnement - -```bash -cat > /opt/omniroute/.env << โ€˜EOFโ€™ -# === Security === -JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY -INITIAL_PASSWORD=YourSecurePassword123! -API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY -STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY -STORAGE_ENCRYPTION_KEY_VERSION=v1 -MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT - -# === 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 (change to your domain) === -BASE_URL=https://llms.seudominio.com -NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com - -# === Cloud Sync (optional) === -# CLOUD_URL=https://cloud.omniroute.online -# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online -EOF -``` - -> โš ๏ธ **IMPORTANT** : Gรฉnรฉrez des clรฉs secrรจtes uniques ! Utilisez `openssl rand -hex 32` pour chaque clรฉ. - -### 2.3 Dรฉmarrer le conteneur - -```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 Vรฉrifiez qu'il est en cours d'exรฉcution - -```bash -docker ps | grep omniroute -docker logs omniroute --tail 20 -``` - -Il doit afficherย : `[DB] SQLite database ready` et `listening on port 20128`. - ---- - -## 3. Configurer nginx (proxy inverse) - -### 3.1 Gรฉnรฉrer un certificat SSL (Cloudflare Origin) - -Dans le tableau de bord Cloudflareย : - -1. Accรฉdez ร  **SSL/TLS โ†’ Serveur d'origine** -2. Cliquez sur **Crรฉer un certificat** -3. Conservez les valeurs par dรฉfaut (15 ans, \*.votredomaine.com) -4. Copiez le **Certificat d'origine** et la **Clรฉ privรฉe** - -```bash -mkdir -p /etc/nginx/ssl - -# Paste the certificate -nano /etc/nginx/ssl/origin.crt - -# Paste the private key -nano /etc/nginx/ssl/origin.key - -chmod 600 /etc/nginx/ssl/origin.key -``` - -### 3.2 Configuration de Nginx - -```bash -cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ -# Default server โ€” blocks direct access via 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.yourdomain.com; # Change to your domain - - 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.yourdomain.com; - return 301 https://$server_name$request_uri; -} -NGINX -``` - -### 3.3 Activer et tester - -```bash -# Remove default configuration -rm -f /etc/nginx/sites-enabled/default - -# Enable OmniRoute -ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute - -# Test and reload -nginx -t && systemctl reload nginx -``` - ---- - -## 4. Configurer le DNS Cloudflare - -### 4.1 Ajouter un enregistrement DNS - -Dans le tableau de bord Cloudflare โ†’ DNSย : - -| Tapez | Nom | Contenu | Proxy | -| ----- | ------ | ------------------------------------------- | ------------- | -| Un | `llms` | `203.0.113.10` (IP de la machine virtuelle) | โœ… Mandataire | - -### 4.2 Configurer SSL - -Sous **SSL/TLS โ†’ Prรฉsentation**ย : - -- Modeย : **Complet (strict)** - -Sous **SSL/TLS โ†’ Certificats Edge**ย : - -- Utilisez toujours HTTPSย : โœ…ย Activรฉ - -Version TLS minimaleย :ย TLS 1.2 -- Rรฉรฉcritures HTTPS automatiquesย : โœ…ย Activรฉe - -### 4.3 Tests - -```bash -curl -sI https://llms.seudominio.com/health -# Should return HTTP/2 200 -``` - ---- - -## 5. Exploitation et maintenance - -### Mettre ร  niveau vers une nouvelle version - -```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 -``` - -### Afficher les journaux - -```bash -docker logs -f omniroute # Real-time stream -docker logs omniroute --tail 50 # Last 50 lines -``` - -### Sauvegarde manuelle de la base de donnรฉes - -```bash -# Copy data from the volume to the host -docker cp omniroute:/app/data ./backup-$(date +%F) - -# Or compress the entire volume -docker run --rm -v omniroute-data:/data -v $(pwd):/backup \ - alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data -``` - -### Restaurer ร  partir d'une sauvegarde - -```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. Sรฉcuritรฉ avancรฉe - -### Restreindre nginx aux IP Cloudflare - -```bash -cat > /etc/nginx/cloudflare-ips.conf << โ€˜CFโ€™ -# Cloudflare IPv4 ranges โ€” update periodically -# 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 -``` - -Ajoutez ce qui suit ร  `nginx.conf` ร  l'intรฉrieur du bloc `http {}`ย : - -```nginx -include /etc/nginx/cloudflare-ips.conf; -``` - -### Installer fail2ban - -```bash -apt install -y fail2ban -systemctl enable fail2ban -systemctl start fail2ban - -# Check status -fail2ban-client status sshd -``` - -### Bloquer l'accรจs direct au port Docker - -```bash -# Prevent direct external access to port 20128 -iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP -iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT - -# Persist the rules -apt install -y iptables-persistent -netfilter-persistent save -``` - ---- - -## 7. Dรฉployer sur Cloudflare Workers (facultatif) - -Pour un accรจs ร  distance via Cloudflare Workers (sans exposer directement la VM)ย : - -```bash -# In the local repository -cd omnirouteCloud -npm install -npx wrangler login -npx wrangler deploy -``` - -Consultez la documentation complรจte sur [omnirouteCloud/README.md](../omnirouteCloud/README.md). - ---- - -## Rรฉsumรฉ des ports - -| Port | Services | Accรจs | -| ----- | ----------- | -------------------------------- | -| 22 | SSH | Public (avec fail2ban) | -| 80 | nginx HTTP | Redirection โ†’ HTTPS | -| 443 | nginx HTTPS | Via le proxy Cloudflare | -| 20128 | OmniRoute | Localhost uniquement (via nginx) | diff --git a/docs/i18n/fr/docs/A2A-SERVER.md b/docs/i18n/fr/docs/A2A-SERVER.md new file mode 100644 index 0000000000..19b7711e41 --- /dev/null +++ b/docs/i18n/fr/docs/A2A-SERVER.md @@ -0,0 +1,200 @@ +# OmniRoute A2A Server Documentation (Franรงais) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/A2A-SERVER.md) + +--- + +> Agent-to-Agent Protocol v0.3 โ€” OmniRoute as an intelligent routing agent + +## Agent Discovery + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements. + +--- + +## Authentication + +All `/a2a` requests require an API key via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server, authentication is bypassed. + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Sends a message to a skill and waits for the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a hello world in Python"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "uuid", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "..." }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}} + +: heartbeat 2026-03-03T17:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Available Skills + +| Skill | Description | +| :----------------- | :------------------------------------------------------------------------------------------------------------------------------ | +| `smart-routing` | Routes prompts through OmniRoute's intelligent pipeline. Returns response with routing explanation, cost, and resilience trace. | +| `quota-management` | Answers natural-language queries about provider quotas, suggests free combos, and provides quota rankings. | + +--- + +## Task Lifecycle + +``` +submitted โ†’ working โ†’ completed + โ†’ failed + โ†’ cancelled +``` + +- Tasks expire after 5 minutes (configurable) +- Terminal states: `completed`, `failed`, `cancelled` +- Event log tracks every state transition + +--- + +## Error Codes + +| Code | Meaning | +| :----- | :----------------------------- | +| -32700 | Parse error (invalid JSON) | +| -32600 | Invalid request / Unauthorized | +| -32601 | Method or skill not found | +| -32602 | Invalid params | +| -32603 | Internal error | + +--- + +## Integration Examples + +### Python (requests) + +```python +import requests + +resp = requests.post("http://localhost:20128/a2a", json={ + "jsonrpc": "2.0", "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Hello"}] + } +}, headers={"Authorization": "Bearer YOUR_KEY"}) + +result = resp.json()["result"] +print(result["artifacts"][0]["content"]) +print(result["metadata"]["routing_explanation"]) +``` + +### TypeScript (fetch) + +```typescript +const resp = await fetch("http://localhost:20128/a2a", { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: "Bearer YOUR_KEY", + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "1", + method: "message/send", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Hello" }], + }, + }), +}); +const { result } = await resp.json(); +console.log(result.metadata.routing_explanation); +``` diff --git a/docs/i18n/fr/docs/API_REFERENCE.md b/docs/i18n/fr/docs/API_REFERENCE.md new file mode 100644 index 0000000000..9fe45fdc62 --- /dev/null +++ b/docs/i18n/fr/docs/API_REFERENCE.md @@ -0,0 +1,465 @@ +# API Reference (Franรงais) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/API_REFERENCE.md) + +--- + +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 | +| `X-Session-Id` | Request | Sticky session key for external session affinity | +| `x_session_id` | Request | Underscore variant also accepted (direct HTTP) | +| `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 | +| `X-OmniRoute-Session-Id` | Response | Effective session ID used by OmniRoute | + +> Nginx note: if you rely on underscore headers (for example `x_session_id`), enable `underscores_in_headers 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/stats + +# Clear all caches +DELETE /api/cache/stats +``` + +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/PATCH | 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 + provider summary (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`) | +| `/api/cache/stats` | 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 | + +### Tunnels + +| Endpoint | Method | Description | +| -------------------------- | ------ | ----------------------------------------------------------------------- | +| `/api/tunnels/cloudflared` | GET | Read Cloudflare Quick Tunnel install/runtime status for the dashboard | +| `/api/tunnels/cloudflared` | POST | Enable or disable the Cloudflare Quick Tunnel (`action=enable/disable`) | + +### 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`. + +### ACP Agents + +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | + +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). + +### Resilience & Rate Limits + +| Endpoint | Method | Description | +| ----------------------- | --------- | ------------------------------- | +| `/api/resilience` | GET/PATCH | 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` diff --git a/docs/i18n/fr/docs/ARCHITECTURE.md b/docs/i18n/fr/docs/ARCHITECTURE.md new file mode 100644 index 0000000000..aaa0200d38 --- /dev/null +++ b/docs/i18n/fr/docs/ARCHITECTURE.md @@ -0,0 +1,814 @@ +# OmniRoute Architecture (Franรงais) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/ARCHITECTURE.md) + +--- + +_Last updated: 2026-03-28_ + +## 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 (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developerโ†’system, systemโ†’user) for cross-provider compatibility +- Structured output conversion (json_schema โ†’ Gemini responseSchema) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) +- Global system prompt injection +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout โ†’ budget โ†’ fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) + +Primary runtime model: + +- Next.js 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.) + +## Dashboard Surface (Current) + +Main pages under `src/app/(dashboard)/dashboard/`: + +- `/dashboard` โ€” quick start + provider overview +- `/dashboard/endpoint` โ€” endpoint proxy + MCP + A2A + API endpoint tabs +- `/dashboard/providers` โ€” provider connections and credentials +- `/dashboard/combos` โ€” combo strategies, templates, model routing rules +- `/dashboard/costs` โ€” cost aggregation and pricing visibility +- `/dashboard/analytics` โ€” usage analytics and evaluations +- `/dashboard/limits` โ€” quota/rate controls +- `/dashboard/cli-tools` โ€” CLI onboarding, runtime detection, config generation +- `/dashboard/agents` โ€” detected ACP agents + custom agent registration +- `/dashboard/media` โ€” image/video/music playground +- `/dashboard/search-tools` โ€” search provider testing and history +- `/dashboard/health` โ€” uptime, circuit breakers, rate limits +- `/dashboard/logs` โ€” request/proxy/audit/console logs +- `/dashboard/settings` โ€” system settings tabs (general, routing, combo defaults, etc.) +- `/dashboard/api-manager` โ€” API key lifecycle and model permissions + +## 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[(storage.sqlite)] + UDB[(usage tables + log artifacts)] + end + + subgraph Upstreams[Upstream Providers] + P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/Qoder/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/route.ts` (GET) +- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- OAuth: `src/app/api/oauth/*` +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` +- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI tooling helpers: `src/app/api/cli-tools/*` +- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) +- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) โ€” provider profiles, circuit breaker, rate limit state +- Resilience reset: `src/app/api/resilience/reset` (POST) โ€” reset breakers + cooldowns +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) +- Telemetry: `src/app/api/telemetry/summary` (GET) +- Budget: `src/app/api/usage/budget` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Policies: `src/app/api/policies` (GET/POST) + +## 2) SSE + 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` +- Response sanitization: `open-sse/handlers/responseSanitizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.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`, `qoder.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 (SQLite): + +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** + +Usage persistence: + +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present + +Domain State DB (SQLite): + +- `src/lib/db/domainState.ts` โ€” CRUD operations 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`, `src/shared/services/modelSyncScheduler.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Periodic task: `src/shared/services/modelSyncScheduler.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. Combo routing adds one extra guard: provider-scoped 400s such as upstream content-block and role-validation failures are treated as model-local failures so later combo targets can still run. + +## 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: + +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` + +## Deployment Topology + +```mermaid +flowchart LR + 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[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] + end + + subgraph External[External Services] + Providers[AI Providers] + SyncCloud[Cloud Sync Service] + end + + CLI --> Next + Browser --> Next + Next --> Core + Next --> MainDB + Core --> MainDB + Core --> UsageDB + Core --> Providers + Next --> SyncCloud +``` + +## Module Mapping (Decision-Critical) + +### Route and API Modules + +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle +- `src/app/api/models/alias`: alias management +- `src/app/api/combos*`: fallback combo management +- `src/app/api/pricing`: pricing overrides for cost calculation +- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers +- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) +- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) +- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) +- `src/app/api/sessions`: active session listing (GET) +- `src/app/api/rate-limits`: per-account rate limit status (GET) + +### Routing and Execution Core + +- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior + +### Translation Registry and Format Converters + +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` +- Format constants: `open-sse/translator/formats.ts` + +### Persistence + +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables + +## Provider Executor Coverage (Strategy Pattern) + +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. + +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, Qoder, 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 | +| Qoder | openai | OAuth (Basic) | โœ… | โœ… | โœ… | โš ๏ธ Per request | +| OpenRouter | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| GLM/Kimi/MiniMax | claude | API Key | โœ… | โœ… | โŒ | โŒ | +| DeepSeek | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Groq | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| xAI (Grok) | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Mistral | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Perplexity | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Together AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Fireworks AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Cerebras | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Cohere | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| NVIDIA NIM | openai | API Key | โœ… | โœ… | โŒ | โŒ | + +## Format Translation Coverage + +Detected source formats include: + +- `openai` +- `openai-responses` +- `claude` +- `gemini` + +Target formats include: + +- OpenAI chat/Responses +- Claude +- Gemini/Gemini-CLI/Antigravity envelope +- Kiro +- Cursor + +Translations use **OpenAI as the hub format** โ€” all conversions go through OpenAI as intermediate: + +``` +Source Format โ†’ OpenAI (hub) โ†’ Target Format +``` + +Translations are selected dynamically based on source payload shape and provider target format. + +Additional processing layers in the translation pipeline: + +- **Response sanitization** โ€” Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI targets; merges `system` โ†’ `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** โ€” Parses `...` blocks from content into `reasoning_content` field +- **Structured output** โ€” Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` + +## Supported API Endpoints + +| 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` | Provider Models | Provider model metadata backing custom and managed available models | + +## 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 `/logs//` 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 + +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON โ†’ SQLite migration compatibility path + +## Observability and Operational Signals + +Runtime visibility sources: + +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- four-stage detailed payload captures in SQLite (`request_detail_logs`) when `settings.detailed_logs_enabled=true` +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption + +Detailed request payload capture stores up to four JSON payload stages per routed call: + +- raw request received from the client +- translated request actually sent upstream +- provider response reconstructed as JSON; streamed responses are compacted to the final summary plus stream metadata +- final client response returned by OmniRoute; streamed responses are stored in the same compact summary form + +## Security-Sensitive Boundaries + +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics + +## Environment and Runtime Matrix + +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` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). + +## Operational Verification Checklist + +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: +- `GET /api/settings` +- `GET /api/v1/models` +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/fr/docs/AUTO-COMBO.md b/docs/i18n/fr/docs/AUTO-COMBO.md new file mode 100644 index 0000000000..9cf0f6d606 --- /dev/null +++ b/docs/i18n/fr/docs/AUTO-COMBO.md @@ -0,0 +1,67 @@ +# OmniRoute Auto-Combo Engine (Franรงais) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/AUTO-COMBO.md) + +--- + +> Self-managing model chains with adaptive scoring + +## How It Works + +The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**: + +| Factor | Weight | Description | +| :--------- | :----- | :---------------------------------------------- | +| Quota | 0.20 | Remaining capacity [0..1] | +| Health | 0.25 | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 | +| CostInv | 0.20 | Inverse cost (cheaper = higher score) | +| LatencyInv | 0.15 | Inverse p95 latency (faster = higher) | +| TaskFit | 0.10 | Model ร— task type fitness score | +| Stability | 0.10 | Low variance in latency/errors | + +## Mode Packs + +| Pack | Focus | Key Weight | +| :---------------------- | :----------- | :--------------- | +| ๐Ÿš€ **Ship Fast** | Speed | latencyInv: 0.35 | +| ๐Ÿ’ฐ **Cost Saver** | Economy | costInv: 0.40 | +| ๐ŸŽฏ **Quality First** | Best model | taskFit: 0.40 | +| ๐Ÿ“ก **Offline Friendly** | Availability | quota: 0.40 | + +## Self-Healing + +- **Temporary exclusion**: Score < 0.2 โ†’ excluded for 5 min (progressive backoff, max 30 min) +- **Circuit breaker awareness**: OPEN โ†’ auto-excluded; HALF_OPEN โ†’ probe requests +- **Incident mode**: >50% OPEN โ†’ disable exploration, maximize stability +- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout + +## Bandit Exploration + +5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode. + +## API + +```bash +# Create auto-combo +curl -X POST http://localhost:20128/api/combos/auto \ + -H "Content-Type: application/json" \ + -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}' + +# List auto-combos +curl http://localhost:20128/api/combos/auto +``` + +## Task Fitness + +30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` โ†’ high coding score). + +## Files + +| File | Purpose | +| :------------------------------------------- | :------------------------------------ | +| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization | +| `open-sse/services/autoCombo/taskFitness.ts` | Model ร— task fitness lookup | +| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap | +| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode | +| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles | +| `src/app/api/combos/auto/route.ts` | REST API | diff --git a/docs/i18n/fr/docs/CLI-TOOLS.md b/docs/i18n/fr/docs/CLI-TOOLS.md new file mode 100644 index 0000000000..6cefebbbc1 --- /dev/null +++ b/docs/i18n/fr/docs/CLI-TOOLS.md @@ -0,0 +1,348 @@ +# CLI Tools Setup Guide โ€” OmniRoute (Franรงais) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CLI-TOOLS.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CLI-TOOLS.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CLI-TOOLS.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CLI-TOOLS.md) + +--- + +This guide explains how to install and configure all supported AI coding CLI tools +to use **OmniRoute** as the unified backend, giving you centralized key management, +cost tracking, model switching, and request logging across every tool. + +--- + +## How It Works + +``` +Claude / Codex / OpenCode / Cline / KiloCode / Continue / Kiro / Cursor / Copilot + โ”‚ + โ–ผ (all point to OmniRoute) + http://YOUR_SERVER:20128/v1 + โ”‚ + โ–ผ (OmniRoute routes to the right provider) + Anthropic / OpenAI / Gemini / DeepSeek / Groq / Mistral / ... +``` + +**Benefits:** + +- One API key to manage all tools +- Cost tracking across all CLIs in the dashboard +- Model switching without reconfiguring every tool +- Works locally and on remote servers (VPS) + +--- + +## Supported Tools (Dashboard Source of Truth) + +The dashboard cards in `/dashboard/cli-tools` are generated from `src/shared/constants/cliTools.ts`. +Current list (v3.0.0-rc.16): + +| Tool | ID | Command | Setup Mode | Install Method | +| ------------------ | ------------- | ---------- | ---------- | -------------- | +| **Claude Code** | `claude` | `claude` | env | npm | +| **OpenAI Codex** | `codex` | `codex` | custom | npm | +| **Factory Droid** | `droid` | `droid` | custom | bundled/CLI | +| **OpenClaw** | `openclaw` | `openclaw` | custom | bundled/CLI | +| **Cursor** | `cursor` | app | guide | desktop app | +| **Cline** | `cline` | `cline` | custom | npm | +| **Kilo Code** | `kilo` | `kilocode` | custom | npm | +| **Continue** | `continue` | extension | guide | VS Code | +| **Antigravity** | `antigravity` | internal | mitm | OmniRoute | +| **GitHub Copilot** | `copilot` | extension | custom | VS Code | +| **OpenCode** | `opencode` | `opencode` | guide | npm | +| **Kiro AI** | `kiro` | app/cli | mitm | desktop/CLI | + +### CLI fingerprint sync (Agents + Settings) + +`/dashboard/agents` and `Settings > CLI Fingerprint` use `src/shared/constants/cliCompatProviders.ts`. +This keeps provider IDs aligned with CLI cards and legacy IDs. + +| CLI ID | Fingerprint Provider ID | +| ---------------------------------------------------------------------------------------------------- | ----------------------- | +| `kilo` | `kilocode` | +| `copilot` | `github` | +| `claude` / `codex` / `antigravity` / `kiro` / `cursor` / `cline` / `opencode` / `droid` / `openclaw` | same ID | + +Legacy IDs still accepted for compatibility: `copilot`, `kimi-coding`, `qwen`. + +--- + +## Step 1 โ€” Get an OmniRoute API Key + +1. Open the OmniRoute dashboard โ†’ **API Manager** (`/dashboard/api-manager`) +2. Click **Create API Key** +3. Give it a name (e.g. `cli-tools`) and select all permissions +4. Copy the key โ€” you'll need it for every CLI below + +> Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` + +--- + +## Step 2 โ€” Install CLI Tools + +All npm-based tools require Node.js 18+: + +```bash +# Claude Code (Anthropic) +npm install -g @anthropic-ai/claude-code + +# OpenAI Codex +npm install -g @openai/codex + +# OpenCode +npm install -g opencode-ai + +# Cline +npm install -g cline + +# KiloCode +npm install -g kilocode + +# Kiro CLI (Amazon โ€” requires curl + unzip) +apt-get install -y unzip # on Debian/Ubuntu +curl -fsSL https://cli.kiro.dev/install | bash +export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc +``` + +**Verify:** + +```bash +claude --version # 2.x.x +codex --version # 0.x.x +opencode --version # x.x.x +cline --version # 2.x.x +kilocode --version # x.x.x (or: kilo --version) +kiro-cli --version # 1.x.x +``` + +--- + +## Step 3 โ€” Set Global Environment Variables + +Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`: + +```bash +# OmniRoute Universal Endpoint +export OPENAI_BASE_URL="http://localhost:20128/v1" +export OPENAI_API_KEY="sk-your-omniroute-key" +export ANTHROPIC_BASE_URL="http://localhost:20128/v1" +export ANTHROPIC_API_KEY="sk-your-omniroute-key" +export GEMINI_BASE_URL="http://localhost:20128/v1" +export GEMINI_API_KEY="sk-your-omniroute-key" +``` + +> For a **remote server** replace `localhost:20128` with the server IP or domain, +> e.g. `http://192.168.0.15:20128`. + +--- + +## Step 4 โ€” Configure Each Tool + +### Claude Code + +```bash +# Via CLI: +claude config set --global api-base-url http://localhost:20128/v1 + +# Or create ~/.claude/settings.json: +mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF +{ + "apiBaseUrl": "http://localhost:20128/v1", + "apiKey": "sk-your-omniroute-key" +} +EOF +``` + +**Test:** `claude "say hello"` + +--- + +### OpenAI Codex + +```bash +mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF +model: auto +apiKey: sk-your-omniroute-key +apiBaseUrl: http://localhost:20128/v1 +EOF +``` + +**Test:** `codex "what is 2+2?"` + +--- + +### OpenCode + +```bash +mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF +[provider.openai] +base_url = "http://localhost:20128/v1" +api_key = "sk-your-omniroute-key" +EOF +``` + +**Test:** `opencode` + +--- + +### Cline (CLI or VS Code) + +**CLI mode:** + +```bash +mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF +{ + "apiProvider": "openai", + "openAiBaseUrl": "http://localhost:20128/v1", + "openAiApiKey": "sk-your-omniroute-key" +} +EOF +``` + +**VS Code mode:** +Cline extension settings โ†’ API Provider: `OpenAI Compatible` โ†’ Base URL: `http://localhost:20128/v1` + +Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ Cline โ†’ Apply Config**. + +--- + +### KiloCode (CLI or VS Code) + +**CLI mode:** + +```bash +kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key +``` + +**VS Code settings:** + +```json +{ + "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", + "kilo-code.apiKey": "sk-your-omniroute-key" +} +``` + +Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ KiloCode โ†’ Apply Config**. + +--- + +### Continue (VS Code Extension) + +Edit `~/.continue/config.yaml`: + +```yaml +models: + - name: OmniRoute + provider: openai + model: auto + apiBase: http://localhost:20128/v1 + apiKey: sk-your-omniroute-key + default: true +``` + +Restart VS Code after editing. + +--- + +### Kiro CLI (Amazon) + +```bash +# Login to your AWS/Kiro account: +kiro-cli login + +# The CLI uses its own auth โ€” OmniRoute is not needed as backend for Kiro CLI itself. +# Use kiro-cli alongside OmniRoute for other tools. +kiro-cli status +``` + +--- + +### Cursor (Desktop App) + +> **Note:** Cursor routes requests through its cloud. For OmniRoute integration, +> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL. + +Via GUI: **Settings โ†’ Models โ†’ OpenAI API Key** + +- Base URL: `https://your-domain.com/v1` +- API Key: your OmniRoute key + +--- + +## Dashboard Auto-Configuration + +The OmniRoute dashboard automates configuration for most tools: + +1. Go to `http://localhost:20128/dashboard/cli-tools` +2. Expand any tool card +3. Select your API key from the dropdown +4. Click **Apply Config** (if tool is detected as installed) +5. Or copy the generated config snippet manually + +--- + +## Built-in Agents: Droid & OpenClaw + +**Droid** and **OpenClaw** are AI agents built directly into OmniRoute โ€” no installation needed. +They run as internal routes and use OmniRoute's model routing automatically. + +- Access: `http://localhost:20128/dashboard/agents` +- Configure: same combos and providers as all other tools +- No API key or CLI install required + +--- + +## Available API Endpoints + +| Endpoint | Description | Use For | +| -------------------------- | ----------------------------- | --------------------------- | +| `/v1/chat/completions` | Standard chat (all providers) | All modern tools | +| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows | +| `/v1/completions` | Legacy text completions | Older tools using `prompt:` | +| `/v1/embeddings` | Text embeddings | RAG, search | +| `/v1/images/generations` | Image generation | DALL-E, Flux, etc. | +| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS | +| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI | + +--- + +## Dรฉpannage + +| Error | Cause | Fix | +| ------------------------- | ----------------------- | ------------------------------------------ | +| `Connection refused` | OmniRoute not running | `pm2 start omniroute` | +| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` | +| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` | +| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` | +| CLI shows "not installed" | Binary not in PATH | Check `which ` | +| `kiro-cli: not found` | Not in PATH | `export PATH="$HOME/.local/bin:$PATH"` | + +--- + +## Quick Setup Script (One Command) + +```bash +# Install all CLIs and configure for OmniRoute (replace with your key and server URL) +OMNIROUTE_URL="http://localhost:20128/v1" +OMNIROUTE_KEY="sk-your-omniroute-key" + +npm install -g @anthropic-ai/claude-code @openai/codex opencode-ai cline kilocode + +# Kiro CLI +apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash + +# Write configs +mkdir -p ~/.claude ~/.codex ~/.config/opencode ~/.continue + +cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" +cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" +cat >> ~/.bashrc << EOF +export OPENAI_BASE_URL="$OMNIROUTE_URL" +export OPENAI_API_KEY="$OMNIROUTE_KEY" +export ANTHROPIC_BASE_URL="$OMNIROUTE_URL" +export ANTHROPIC_API_KEY="$OMNIROUTE_KEY" +EOF + +source ~/.bashrc +echo "โœ… All CLIs installed and configured for OmniRoute" +``` diff --git a/docs/i18n/da/CODEBASE_DOCUMENTATION.md b/docs/i18n/fr/docs/CODEBASE_DOCUMENTATION.md similarity index 91% rename from docs/i18n/da/CODEBASE_DOCUMENTATION.md rename to docs/i18n/fr/docs/CODEBASE_DOCUMENTATION.md index e2d7950052..3801796702 100644 --- a/docs/i18n/da/CODEBASE_DOCUMENTATION.md +++ b/docs/i18n/fr/docs/CODEBASE_DOCUMENTATION.md @@ -1,11 +1,9 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CODEBASE_DOCUMENTATION.md) +# omniroute โ€” Codebase Documentation (Franรงais) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CODEBASE_DOCUMENTATION.md) --- -# omniroute โ€” Codebase Documentation - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) - > A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. --- diff --git a/docs/i18n/fr/docs/COVERAGE_PLAN.md b/docs/i18n/fr/docs/COVERAGE_PLAN.md new file mode 100644 index 0000000000..9367c5fb6d --- /dev/null +++ b/docs/i18n/fr/docs/COVERAGE_PLAN.md @@ -0,0 +1,170 @@ +# Test Coverage Plan (Franรงais) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/COVERAGE_PLAN.md) + +--- + +Last updated: 2026-03-28 + +## Baseline + +There are multiple coverage numbers depending on how the report is computed. For planning, only one of them is useful. + +| Metric | Scope | Statements / Lines | Branches | Functions | Notes | +| -------------------- | ----------------------------------------------------- | -----------------: | -------: | --------: | --------------------------------------------------- | +| Legacy | Old `npm run test:coverage` | 79.42% | 75.15% | 67.94% | Inflated: counts test files and excludes `open-sse` | +| Diagnostic | Source-only, excluding tests and excluding `open-sse` | 68.16% | 63.55% | 64.06% | Useful only to isolate `src/**` | +| Recommended baseline | Source-only, excluding tests and including `open-sse` | 56.95% | 66.05% | 57.80% | This is the project-wide baseline to improve | + +The recommended baseline is the number to optimize against. + +## Rules + +- Coverage targets apply to source files, not to `tests/**`. +- `open-sse/**` is part of the product and must remain in scope. +- New code should not reduce coverage in touched areas. +- Prefer testing behavior and branch outcomes over implementation details. +- Prefer temp SQLite databases and small fixtures over broad mocks for `src/lib/db/**`. + +## Current command set + +- `npm run test:coverage` + - Main source coverage gate for the unit test suite + - Generates `text-summary`, `html`, `json-summary`, and `lcov` +- `npm run coverage:report` + - Detailed file-by-file report from the latest run +- `npm run test:coverage:legacy` + - Historical comparison only + +## Milestones + +| Phase | Target | Focus | +| ------- | ---------------------: | ------------------------------------------------- | +| Phase 1 | 60% statements / lines | Quick wins and low-risk utility coverage | +| Phase 2 | 65% statements / lines | DB and route foundations | +| Phase 3 | 70% statements / lines | Provider validation and usage analytics | +| Phase 4 | 75% statements / lines | `open-sse` translators and helpers | +| Phase 5 | 80% statements / lines | `open-sse` handlers and executor branches | +| Phase 6 | 85% statements / lines | Harder edge cases, branch debt, regression suites | +| Phase 7 | 90% statements / lines | Final sweep, gap closure, strict ratchet | + +Branches and functions should ratchet upward with each phase, but the primary hard target is statements / lines. + +## Priority hotspots + +These files or areas offer the best return for the next phases: + +1. `open-sse/handlers` + - `chatCore.ts` at 7.57% + - Overall directory at 29.07% +2. `open-sse/translator/request` + - Overall directory at 36.39% + - Many translators are still near single-digit coverage +3. `open-sse/translator/response` + - Overall directory at 8.07% +4. `open-sse/executors` + - Overall directory at 36.62% +5. `src/lib/db` + - `models.ts` at 20.66% + - `registeredKeys.ts` at 34.46% + - `modelComboMappings.ts` at 36.25% + - `settings.ts` at 46.40% + - `webhooks.ts` at 33.33% +6. `src/lib/usage` + - `usageHistory.ts` at 21.12% + - `usageStats.ts` at 9.56% + - `costCalculator.ts` at 30.00% +7. `src/lib/providers` + - `validation.ts` at 41.16% +8. Low-risk utility and API files for early gains + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/api/errorResponse.ts` + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +## Execution checklist + +### Phase 1: 56.95% -> 60% + +- [x] Fix coverage metric so it reflects source code instead of test files +- [x] Keep a legacy coverage script for comparison +- [x] Record the baseline and hotspots in-repo +- [ ] Add focused tests for low-risk utilities: + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/fetchTimeout.ts` + - `src/lib/api/errorResponse.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/display/names.ts` +- [ ] Add route tests for: + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +### Phase 2: 60% -> 65% + +- [ ] Add DB-backed tests for: + - `src/lib/db/modelComboMappings.ts` + - `src/lib/db/settings.ts` + - `src/lib/db/registeredKeys.ts` +- [ ] Cover branch behavior in: + - `src/lib/providers/validation.ts` + - `src/app/api/v1/embeddings/route.ts` + - `src/app/api/v1/moderations/route.ts` + +### Phase 3: 65% -> 70% + +- [ ] Add usage analytics tests for: + - `src/lib/usage/usageHistory.ts` + - `src/lib/usage/usageStats.ts` + - `src/lib/usage/costCalculator.ts` +- [ ] Expand route coverage for proxy management and settings branches + +### Phase 4: 70% -> 75% + +- [ ] Cover translator helpers and central translation paths: + - `open-sse/translator/index.ts` + - `open-sse/translator/helpers/*` + - `open-sse/translator/request/*` + - `open-sse/translator/response/*` + +### Phase 5: 75% -> 80% + +- [ ] Add handler-level tests for: + - `open-sse/handlers/chatCore.ts` + - `open-sse/handlers/responsesHandler.js` + - `open-sse/handlers/imageGeneration.js` + - `open-sse/handlers/embeddings.js` +- [ ] Add executor branch coverage for provider-specific auth, retries, and endpoint overrides + +### Phase 6: 80% -> 85% + +- [ ] Merge more edge-case suites into the main coverage path +- [ ] Increase function coverage for DB modules with weak constructor/helper coverage +- [ ] Close branch gaps in `settings.ts`, `registeredKeys.ts`, `validation.ts`, and translator helpers + +### Phase 7: 85% -> 90% + +- [ ] Treat the remaining low-coverage files as blockers +- [ ] Add regression tests for every uncovered production bug fixed during the push to 90% +- [ ] Raise the coverage gate in CI only after the local baseline is stable for at least two consecutive runs + +## Ratchet policy + +Update `npm run test:coverage` thresholds only after the project actually exceeds the next milestone with a comfortable buffer. + +Recommended ratchet sequence: + +1. 55/60/55 +2. 60/62/58 +3. 65/64/62 +4. 70/66/66 +5. 75/70/72 +6. 80/75/78 +7. 85/80/84 +8. 90/85/88 + +Order is `statements-lines / branches / functions`. + +## Known gap + +The current coverage command measures the main Node unit suite and includes source reached from it, including `open-sse`. It does not yet merge Vitest coverage into a single unified report. That merge is worth doing later, but it is not a blocker for starting the 60% -> 80% climb. diff --git a/docs/i18n/fr/docs/FEATURES.md b/docs/i18n/fr/docs/FEATURES.md index ede8e2c315..d5e1ca59d6 100644 --- a/docs/i18n/fr/docs/FEATURES.md +++ b/docs/i18n/fr/docs/FEATURES.md @@ -1,6 +1,6 @@ # OmniRoute โ€” Dashboard Features Gallery (Franรงais) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/FEATURES.md) --- @@ -10,7 +10,7 @@ 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). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. ![Providers Dashboard](screenshots/01-providers.png) diff --git a/docs/i18n/fr/docs/MCP-SERVER.md b/docs/i18n/fr/docs/MCP-SERVER.md new file mode 100644 index 0000000000..890f9830e8 --- /dev/null +++ b/docs/i18n/fr/docs/MCP-SERVER.md @@ -0,0 +1,87 @@ +# OmniRoute MCP Server Documentation (Franรงais) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/MCP-SERVER.md) + +--- + +> Model Context Protocol server with 16 intelligent tools + +## Installer + +OmniRoute MCP is built-in. Start it with: + +```bash +omniroute --mcp +``` + +Or via the open-sse transport: + +```bash +# HTTP streamable transport (port 20130) +omniroute --dev # MCP auto-starts on /mcp endpoint +``` + +## IDE Configuration + +See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup. + +--- + +## Essential Tools (8) + +| Tool | Description | +| :------------------------------ | :--------------------------------------- | +| `omniroute_get_health` | Gateway health, circuit breakers, uptime | +| `omniroute_list_combos` | All configured combos with models | +| `omniroute_get_combo_metrics` | Performance metrics for a specific combo | +| `omniroute_switch_combo` | Switch active combo by ID/name | +| `omniroute_check_quota` | Quota status per provider or all | +| `omniroute_route_request` | Send a chat completion through OmniRoute | +| `omniroute_cost_report` | Cost analytics for a time period | +| `omniroute_list_models_catalog` | Full model catalog with capabilities | + +## Advanced Tools (8) + +| Tool | Description | +| :--------------------------------- | :---------------------------------------------------------- | +| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | +| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | +| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | +| `omniroute_test_combo` | Live-test all models in a combo via a real upstream request | +| `omniroute_get_provider_metrics` | Detailed metrics for one provider | +| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | +| `omniroute_explain_route` | Explain a past routing decision | +| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | + +## Authentication + +MCP tools are authenticated via API key scopes. Each tool requires specific scopes: + +| Scope | Tools | +| :------------- | :----------------------------------------------- | +| `read:health` | get_health, get_provider_metrics | +| `read:combos` | list_combos, get_combo_metrics | +| `write:combos` | switch_combo | +| `read:quota` | check_quota | +| `write:route` | route_request, simulate_route, test_combo | +| `read:usage` | cost_report, get_session_snapshot, explain_route | +| `write:config` | set_budget_guard, set_resilience_profile | +| `read:models` | list_models_catalog, best_combo_for_task | + +## Audit Logging + +Every tool call is logged to `mcp_tool_audit` with: + +- Tool name, arguments, result +- Duration (ms), success/failure +- API key hash, timestamp + +## Files + +| File | Purpose | +| :------------------------------------------- | :------------------------------------------ | +| `open-sse/mcp-server/server.ts` | MCP server creation + 16 tool registrations | +| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport | +| `open-sse/mcp-server/auth.ts` | API key + scope validation | +| `open-sse/mcp-server/audit.ts` | Tool call audit logging | +| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers | diff --git a/docs/i18n/fr/docs/RELEASE_CHECKLIST.md b/docs/i18n/fr/docs/RELEASE_CHECKLIST.md new file mode 100644 index 0000000000..e75f6294a8 --- /dev/null +++ b/docs/i18n/fr/docs/RELEASE_CHECKLIST.md @@ -0,0 +1,37 @@ +# Release Checklist (Franรงais) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/RELEASE_CHECKLIST.md) + +--- + +Use this checklist before tagging or publishing a new OmniRoute release. + +## Version and Changelog + +1. Bump `package.json` version (`x.y.z`) in the release branch. +2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: + - `## [x.y.z] โ€” YYYY-MM-DD` +3. Keep `## [Unreleased]` as the first changelog section for upcoming work. +4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. + +## API Docs + +1. Update `docs/openapi.yaml`: + - `info.version` must equal `package.json` version. +2. Validate endpoint examples if API contracts changed. + +## Runtime Docs + +1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. +2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. +3. Update localized docs if source docs changed significantly. + +## Automated Check + +Run the sync guard locally before opening PR: + +```bash +npm run check:docs-sync +``` + +CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/fr/docs/TROUBLESHOOTING.md b/docs/i18n/fr/docs/TROUBLESHOOTING.md new file mode 100644 index 0000000000..aad399143b --- /dev/null +++ b/docs/i18n/fr/docs/TROUBLESHOOTING.md @@ -0,0 +1,256 @@ +# Troubleshooting (Franรงais) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/TROUBLESHOOTING.md) + +--- + +Common problems and solutions for OmniRoute. + +--- + +## Quick Fixes + +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | + +--- + +## Provider Issues + +### "Language model did not provide messages" + +**Cause:** Provider quota exhausted. + +**Fix:** + +1. 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, Qoder) 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}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) + +--- + +## Circuit Breaker Issues + +### Provider stuck in OPEN state + +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. + +**Fix:** + +1. 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 +- **SDK returns raw string instead of object** โ€” Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** โ€” Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** โ€” Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** โ€” Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` + +--- + +## Resilience Settings + +### Auto rate-limit not triggering + +- 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. + +--- + +## Optional RAG / LLM failure taxonomy (16 problems) + +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` โ€ฆ `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard โ†’ Health** for real-time system status +- **Translator**: Use **Dashboard โ†’ Translator** to debug format issues diff --git a/docs/i18n/fr/USER_GUIDE.md b/docs/i18n/fr/docs/USER_GUIDE.md similarity index 82% rename from docs/i18n/fr/USER_GUIDE.md rename to docs/i18n/fr/docs/USER_GUIDE.md index a2066296e3..653c9a9853 100644 --- a/docs/i18n/fr/USER_GUIDE.md +++ b/docs/i18n/fr/docs/USER_GUIDE.md @@ -1,8 +1,6 @@ # User Guide (Franรงais) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/USER_GUIDE.md) - -> ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/USER_GUIDE.md) --- @@ -320,7 +318,7 @@ Model: cc/claude-opus-4-6 --- -## ๐Ÿš€ Deployment +## Dรฉploiement ### Global npm install (Recommended) @@ -511,23 +509,26 @@ post_install() { ### Environment Variables -| Variable | Default | Description | -| ------------------------- | ------------------------------------ | ------------------------------------------------------- | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | -| `INITIAL_PASSWORD` | `123456` | First login password | -| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | -| `PORT` | framework default | Service port (`20128` in examples) | -| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | -| `NODE_ENV` | runtime default | Set `production` for deploy | -| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | -| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | -| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | -| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | -| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | -| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | -| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | -| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | +| 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/*` | +| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand | +| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | For the full environment variable reference, see the [README](../README.md). @@ -598,6 +599,11 @@ curl -X POST http://localhost:20128/api/provider-models \ Or use Dashboard: **Providers โ†’ [Provider] โ†’ Custom Models**. +Notes: + +- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers. +- The **Custom Models** section is intended for providers that do not expose managed available-model imports. + ### Dedicated Provider Routes Route requests directly to a specific provider with model validation: @@ -642,6 +648,14 @@ Returns models grouped by provider with types (`chat`, `embedding`, `image`). - Automatic background sync with timeout + fail-fast - Prefer server-side `BASE_URL`/`CLOUD_URL` in production +### Cloudflare Quick Tunnel + +- Available in **Dashboard โ†’ Endpoints** for Docker and other self-hosted deployments +- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint +- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary +- Tunnel URLs are ephemeral and change every time you stop/start the tunnel +- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download + ### LLM Gateway Intelligence (Phase 9) - **Semantic Cache** โ€” Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) @@ -757,11 +771,11 @@ OmniRoute implements provider-level resilience with four components: 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 | +| 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 unless `DISABLE_SQLITE_AUTO_BACKUP=true` | ```bash # API: Export database @@ -787,10 +801,11 @@ curl -X POST http://localhost:20128/api/db-backups/import \ ### Settings Dashboard -The settings page is organized into 5 tabs for easy navigation: +The settings page is organized into 6 tabs for easy navigation: | Tab | Contents | | -------------- | ---------------------------------------------------------------------------------------------- | +| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility | | **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | | **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | | **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | diff --git a/docs/i18n/fr/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/fr/docs/VM_DEPLOYMENT_GUIDE.md new file mode 100644 index 0000000000..9b8c6af5f9 --- /dev/null +++ b/docs/i18n/fr/docs/VM_DEPLOYMENT_GUIDE.md @@ -0,0 +1,403 @@ +# OmniRoute โ€” Deployment Guide on VM with Cloudflare (Franรงais) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/VM_DEPLOYMENT_GUIDE.md) + +--- + +Complete guide to install and configure OmniRoute on a VM (VPS) with domain managed via Cloudflare. + +--- + +## Prerequisites + +| Item | Minimum | Recommended | +| ---------- | ------------------------ | ---------------- | +| **CPU** | 1 vCPU | 2 vCPU | +| **RAM** | 1 GB | 2 GB | +| **Disk** | 10 GB SSD | 25 GB SSD | +| **OS** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS | +| **Domain** | Registered on Cloudflare | โ€” | +| **Docker** | Docker Engine 24+ | Docker 27+ | + +**Tested providers**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. + +--- + +## 1. Configure the VM + +### 1.1 Create the instance + +On your preferred VPS provider: + +- Choose Ubuntu 24.04 LTS +- Select the minimum plan (1 vCPU / 1 GB RAM) +- Set a strong root password or configure SSH key +- Note the **public IP** (e.g., `203.0.113.10`) + +### 1.2 Connect via SSH + +```bash +ssh root@203.0.113.10 +``` + +### 1.3 Update the system + +```bash +apt update && apt upgrade -y +``` + +### 1.4 Install Docker + +```bash +# Install dependencies +apt install -y ca-certificates curl gnupg + +# Add official Docker repository +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 Install nginx + +```bash +apt install -y nginx +``` + +### 1.6 Configure 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 +``` + +> **Tip**: For maximum security, restrict ports 80 and 443 to Cloudflare IPs only. See the [Advanced Security](#advanced-security) section. + +--- + +## 2. Install OmniRoute + +### 2.1 Create configuration directory + +```bash +mkdir -p /opt/omniroute +``` + +### 2.2 Create environment variables file + +```bash +cat > /opt/omniroute/.env << โ€˜EOFโ€™ +# === Security === +JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY +INITIAL_PASSWORD=YourSecurePassword123! +API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY +STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY +STORAGE_ENCRYPTION_KEY_VERSION=v1 +MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT + +# === 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 (change to your domain) === +BASE_URL=https://llms.seudominio.com +NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com + +# === Cloud Sync (optional) === +# CLOUD_URL=https://cloud.omniroute.online +# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online +EOF +``` + +> โš ๏ธ **IMPORTANT**: Generate unique secret keys! Use `openssl rand -hex 32` for each key. + +### 2.3 Start the 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 Verify that it is running + +```bash +docker ps | grep omniroute +docker logs omniroute --tail 20 +``` + +It should display: `[DB] SQLite database ready` and `listening on port 20128`. + +--- + +## 3. Configure nginx (Reverse Proxy) + +### 3.1 Generate SSL certificate (Cloudflare Origin) + +In the Cloudflare dashboard: + +1. Go to **SSL/TLS โ†’ Origin Server** +2. Click **Create Certificate** +3. Keep the defaults (15 years, \*.yourdomain.com) +4. Copy the **Origin Certificate** and the **Private Key** + +```bash +mkdir -p /etc/nginx/ssl + +# Paste the certificate +nano /etc/nginx/ssl/origin.crt + +# Paste the private key +nano /etc/nginx/ssl/origin.key + +chmod 600 /etc/nginx/ssl/origin.key +``` + +### 3.2 Nginx Configuration + +```bash +cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ +# Default server โ€” blocks direct access via 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.yourdomain.com; # Change to your domain + + 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.yourdomain.com; + return 301 https://$server_name$request_uri; +} +NGINX +``` + +### 3.3 Enable and Test + +```bash +# Remove default configuration +rm -f /etc/nginx/sites-enabled/default + +# Enable OmniRoute +ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute + +# Test and reload +nginx -t && systemctl reload nginx +``` + +--- + +## 4. Configure Cloudflare DNS + +### 4.1 Add DNS record + +In the Cloudflare dashboard โ†’ DNS: + +| Type | Name | Content | Proxy | +| ---- | ------ | ---------------------- | ---------- | +| A | `llms` | `203.0.113.10` (VM IP) | โœ… Proxied | + +### 4.2 Configure SSL + +Under **SSL/TLS โ†’ Overview**: + +- Mode: **Full (Strict)** + +Under **SSL/TLS โ†’ Edge Certificates**: + +- Always Use HTTPS: โœ… On +- Minimum TLS Version: TLS 1.2 +- Automatic HTTPS Rewrites: โœ… On + +### 4.3 Testing + +```bash +curl -sI https://llms.seudominio.com/health +# Should return HTTP/2 200 +``` + +--- + +## 5. Operations and Maintenance + +### Upgrade to a new version + +```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 +``` + +### View logs + +```bash +docker logs -f omniroute # Real-time stream +docker logs omniroute --tail 50 # Last 50 lines +``` + +### Manual database backup + +```bash +# Copy data from the volume to the host +docker cp omniroute:/app/data ./backup-$(date +%F) + +# Or compress the entire volume +docker run --rm -v omniroute-data:/data -v $(pwd):/backup \ + alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data +``` + +### Restore from 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. Advanced Security + +### Restrict nginx to Cloudflare IPs + +```bash +cat > /etc/nginx/cloudflare-ips.conf << โ€˜CFโ€™ +# Cloudflare IPv4 ranges โ€” update periodically +# 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 +``` + +Add the following to `nginx.conf` inside the `http {}` block: + +```nginx +include /etc/nginx/cloudflare-ips.conf; +``` + +### Install fail2ban + +```bash +apt install -y fail2ban +systemctl enable fail2ban +systemctl start fail2ban + +# Check status +fail2ban-client status sshd +``` + +### Block direct access to the Docker port + +```bash +# Prevent direct external access to port 20128 +iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP +iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT + +# Persist the rules +apt install -y iptables-persistent +netfilter-persistent save +``` + +--- + +## 7. Deploy to Cloudflare Workers (Optional) + +For remote access via Cloudflare Workers (without exposing the VM directly): + +```bash +# In the local repository +cd omnirouteCloud +npm install +npx wrangler login +npx wrangler deploy +``` + +See the full documentation at [omnirouteCloud/README.md](../omnirouteCloud/README.md). + +--- + +## Port Summary + +| Port | Service | Access | +| ----- | ----------- | -------------------------- | +| 22 | SSH | Public (with fail2ban) | +| 80 | nginx HTTP | Redirect โ†’ HTTPS | +| 443 | nginx HTTPS | Via Cloudflare Proxy | +| 20128 | OmniRoute | Localhost only (via nginx) | diff --git a/docs/i18n/fr/src/lib/a2a/README.md b/docs/i18n/fr/src/lib/a2a/README.md new file mode 100644 index 0000000000..1b83226b1a --- /dev/null +++ b/docs/i18n/fr/src/lib/a2a/README.md @@ -0,0 +1,752 @@ +# OmniRoute A2A Server (Franรงais) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../../../src/lib/a2a/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../../../es/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../../../fr/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../../../de/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../../../it/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../../../ru/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../../../zh-CN/src/lib/a2a/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../../../ja/src/lib/a2a/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../../../ko/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../../../ar/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../../../in/src/lib/a2a/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../../../th/src/lib/a2a/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../../../vi/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../../../id/src/lib/a2a/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../../../ms/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../../../nl/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../../../pl/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../../../sv/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../../../no/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../../../da/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../../../fi/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../../../pt/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../../../ro/src/lib/a2a/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../../../hu/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../../../bg/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../../../sk/src/lib/a2a/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../../../uk-UA/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../../../he/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../../../phi/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../../../pt-BR/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../../../cs/src/lib/a2a/README.md) + +--- + +> **Agent-to-Agent Protocol v0.3** โ€” Enables any AI agent to use OmniRoute as an intelligent routing agent via JSON-RPC 2.0. + +The A2A Server exposes OmniRoute as a **first-class agent** that other agents can discover, delegate tasks to, and collaborate with using the [A2A Protocol](https://google.github.io/A2A/). + +--- + +## Architecture + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Orchestrator Agent โ”‚ +โ”‚ (LangChain, CrewAI, AutoGen, Custom Agent) โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ 1. GET /.well-known/agent.json (discover) + โ”‚ 2. POST /a2a (JSON-RPC 2.0) + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ OmniRoute A2A Server โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Task Manager โ”‚ โ”‚ Skill Engine โ”‚ โ”‚ SSE Streaming โ”‚ โ”‚ +โ”‚ โ”‚ (lifecycle) โ”‚โ”€โ”€โ”‚ (registry) โ”‚โ”€โ”€โ”‚ (real-time) โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ +โ”‚ Skills: โ”‚ โ”‚ +โ”‚ โ”œโ”€ smart-routing โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ””โ”€ quota-management โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ Routing Decision Logger โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ OmniRoute Gateway (internal) + /v1/chat/completions, /api/combos, /api/usage/quota +``` + +--- + +## Dรฉmarrage Rapide + +### Agent Discovery + +Every A2A-compatible agent exposes an **Agent Card** at `/.well-known/agent.json`: + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +**Response:** + +```json +{ + "name": "OmniRoute", + "description": "Intelligent AI gateway with auto-routing across 50+ providers", + "url": "http://localhost:20128/a2a", + "version": "1.8.1", + "capabilities": { + "streaming": true, + "pushNotifications": false + }, + "skills": [ + { + "id": "smart-routing", + "name": "Smart Routing", + "description": "Routes prompts through OmniRoute intelligent pipeline", + "tags": ["routing", "llm", "multi-provider", "cost-optimization"], + "examples": [ + "Write a hello world in Python", + "Explain quantum computing using the cheapest provider" + ] + }, + { + "id": "quota-management", + "name": "Quota Management", + "description": "Natural-language queries about provider quotas", + "tags": ["quota", "analytics", "cost"], + "examples": [ + "Which provider has the most quota remaining?", + "Suggest a free combo for coding" + ] + } + ], + "authentication": { + "schemes": ["bearer"], + "apiKeyHeader": "Authorization" + } +} +``` + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Send a message to a skill and receive the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python hello world"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "a1b2c3d4-...", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "print('Hello, World!')" }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.0030)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "2026-03-04T..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"Quantum computing..."}}} + +: heartbeat 2026-03-04T21:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Running Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Skills Reference + +### `smart-routing` + +Routes prompts through OmniRoute's intelligent pipeline with full observability. + +**Parameters (in `metadata`):** + +| Parameter | Type | Default | Description | +| --------- | -------- | ------------ | ---------------------------------------------------------------------------------------- | +| `model` | `string` | `"auto"` | Target model (e.g., `claude-sonnet-4`, `gpt-4o`, `auto`) | +| `combo` | `string` | active combo | Specific combo to route through | +| `budget` | `number` | none | Maximum cost in USD for this request | +| `role` | `string` | none | Task role hint: `coding`, `review`, `planning`, `analysis`, `debugging`, `documentation` | + +**Returns:** + +| Field | Description | +| ------------------------------ | --------------------------------------------------------- | +| `artifacts[].content` | The LLM response text | +| `metadata.routing_explanation` | Human-readable explanation of routing decision | +| `metadata.cost_envelope` | Estimated vs actual cost with currency | +| `metadata.resilience_trace` | Array of events (primary_selected, fallback_needed, etc.) | +| `metadata.policy_verdict` | Whether the request was allowed and why | + +### `quota-management` + +Answers natural-language queries about provider quotas. + +**Query types (inferred from message content):** + +| Query Pattern | Response Type | +| ---------------------------------------------- | -------------------------------------------------------- | +| Contains `"ranking"`, `"most quota"`, `"best"` | Providers ranked by remaining quota | +| Contains `"free"`, `"suggest"` | Lists free combos or suggests free-tier providers | +| Default | Full quota summary with warnings for low-quota providers | + +--- + +## Task Lifecycle + +``` +submitted โ”€โ”€โ†’ working โ”€โ”€โ†’ completed + โ”€โ”€โ†’ failed + โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ†’ cancelled +``` + +| State | Description | +| ----------- | ----------------------------------------------------- | +| `submitted` | Task created, queued for execution | +| `working` | Skill handler is executing | +| `completed` | Execution succeeded, artifacts available | +| `failed` | Execution failed or task expired (TTL: 5 min default) | +| `cancelled` | Cancelled by client via `tasks/cancel` | + +- Terminal states: `completed`, `failed`, `cancelled` (no further transitions) +- Expired tasks in `submitted` or `working` are auto-marked as `failed` +- Tasks are garbage-collected after 2ร— TTL + +--- + +## Client Examples + +### Python โ€” Orchestrator Agent + +```python +""" +A2A Client โ€” Python example. +Discovers OmniRoute agent, sends a task, and processes the result. +""" +import requests +import json + +BASE_URL = "http://localhost:20128" +API_KEY = "your-api-key" +HEADERS = { + "Content-Type": "application/json", + "Authorization": f"Bearer {API_KEY}", +} + +# 1. Discover agent capabilities +agent_card = requests.get(f"{BASE_URL}/.well-known/agent.json").json() +print(f"Agent: {agent_card['name']} v{agent_card['version']}") +print(f"Skills: {[s['id'] for s in agent_card['skills']]}") + +# 2. Send a smart-routing task +response = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python quicksort implementation"}], + "metadata": { + "model": "auto", + "combo": "fast-coding", + "budget": 0.10, + } + } +}) +result = response.json()["result"] +print(f"\n๐Ÿ“ Response: {result['artifacts'][0]['content'][:200]}...") +print(f"๐Ÿ”€ Routing: {result['metadata']['routing_explanation']}") +print(f"๐Ÿ’ฐ Cost: ${result['metadata']['cost_envelope']['actual']}") +print(f"๐Ÿ›ก๏ธ Policy: {result['metadata']['policy_verdict']['reason']}") + +# 3. Query quota status +quota_resp = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-2", + "method": "message/send", + "params": { + "skill": "quota-management", + "messages": [{"role": "user", "content": "Which provider has the most quota remaining?"}], + } +}) +quota_result = quota_resp.json()["result"] +print(f"\n๐Ÿ“Š Quota: {quota_result['artifacts'][0]['content']}") +``` + +### TypeScript โ€” Multi-Agent Orchestrator + +```typescript +/** + * A2A Client โ€” TypeScript example. + * Shows agent discovery, task delegation, and streaming. + */ + +const BASE_URL = "http://localhost:20128"; +const API_KEY = "your-api-key"; + +interface JsonRpcResponse { + jsonrpc: "2.0"; + id: string | number; + result?: T; + error?: { code: number; message: string }; +} + +async function a2aCall(method: string, params: Record): Promise { + const resp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: `${method}-${Date.now()}`, + method, + params, + }), + }); + const json: JsonRpcResponse = await resp.json(); + if (json.error) throw new Error(`[${json.error.code}] ${json.error.message}`); + return json.result!; +} + +// โ”€โ”€ Agent Discovery โ”€โ”€ +const agentCard = await fetch(`${BASE_URL}/.well-known/agent.json`).then((r) => r.json()); +console.log(`Connected to: ${agentCard.name} (${agentCard.skills.length} skills)`); + +// โ”€โ”€ Smart Routing: Send a coding task โ”€โ”€ +const routingResult = await a2aCall("message/send", { + skill: "smart-routing", + messages: [{ role: "user", content: "Implement a Redis cache wrapper in TypeScript" }], + metadata: { model: "claude-sonnet-4", role: "coding" }, +}); +console.log("Response:", routingResult.artifacts[0].content); +console.log("Provider:", routingResult.metadata.routing_explanation); + +// โ”€โ”€ Quota Management: Find free alternatives โ”€โ”€ +const quotaResult = await a2aCall("message/send", { + skill: "quota-management", + messages: [{ role: "user", content: "Suggest free combos for documentation" }], +}); +console.log("Free combos:", quotaResult.artifacts[0].content); + +// โ”€โ”€ Streaming: Real-time response โ”€โ”€ +const streamResp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "stream-1", + method: "message/stream", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Explain microservices architecture" }], + }, + }), +}); + +const reader = streamResp.body!.getReader(); +const decoder = new TextDecoder(); +while (true) { + const { done, value } = await reader.read(); + if (done) break; + const chunk = decoder.decode(value); + for (const line of chunk.split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + if (event.params.chunk) { + process.stdout.write(event.params.chunk.content); + } + if (event.params.task.state === "completed") { + console.log("\nโœ… Stream completed"); + } + } + } +} +``` + +### Python โ€” LangChain A2A Integration + +```python +""" +LangChain integration โ€” Use OmniRoute A2A as a custom LLM. +""" +from langchain.llms.base import BaseLLM +from langchain.schema import LLMResult, Generation +import requests +from typing import List, Optional + +class OmniRouteA2A(BaseLLM): + base_url: str = "http://localhost:20128" + api_key: str = "" + model: str = "auto" + combo: Optional[str] = None + + @property + def _llm_type(self) -> str: + return "omniroute-a2a" + + def _call(self, prompt: str, stop: Optional[List[str]] = None, **kwargs) -> str: + response = requests.post( + f"{self.base_url}/a2a", + headers={ + "Content-Type": "application/json", + "Authorization": f"Bearer {self.api_key}", + }, + json={ + "jsonrpc": "2.0", + "id": "langchain-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": prompt}], + "metadata": { + "model": self.model, + **({"combo": self.combo} if self.combo else {}), + }, + }, + }, + ) + result = response.json()["result"] + return result["artifacts"][0]["content"] + + def _generate(self, prompts: List[str], stop=None, **kwargs) -> LLMResult: + return LLMResult( + generations=[[Generation(text=self._call(p, stop))] for p in prompts] + ) + +# Usage +llm = OmniRouteA2A( + base_url="http://localhost:20128", + api_key="your-key", + model="auto", + combo="fast-coding", +) +result = llm("Write a Python function to merge two sorted lists") +print(result) +``` + +### Go โ€” A2A Client + +```go +package main + +import ( + "bytes" + "encoding/json" + "fmt" + "io" + "net/http" +) + +const baseURL = "http://localhost:20128" +const apiKey = "your-api-key" + +type JsonRpcRequest struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Method string `json:"method"` + Params interface{} `json:"params"` +} + +type JsonRpcResponse struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Result interface{} `json:"result"` + Error *struct { + Code int `json:"code"` + Message string `json:"message"` + } `json:"error"` +} + +func a2aCall(method string, params interface{}) (*JsonRpcResponse, error) { + body, _ := json.Marshal(JsonRpcRequest{ + Jsonrpc: "2.0", + ID: "go-1", + Method: method, + Params: params, + }) + + req, _ := http.NewRequest("POST", baseURL+"/a2a", bytes.NewReader(body)) + req.Header.Set("Content-Type", "application/json") + req.Header.Set("Authorization", "Bearer "+apiKey) + + resp, err := http.DefaultClient.Do(req) + if err != nil { + return nil, err + } + defer resp.Body.Close() + data, _ := io.ReadAll(resp.Body) + + var result JsonRpcResponse + json.Unmarshal(data, &result) + return &result, nil +} + +func main() { + // Discover agent + resp, _ := http.Get(baseURL + "/.well-known/agent.json") + defer resp.Body.Close() + body, _ := io.ReadAll(resp.Body) + fmt.Println("Agent Card:", string(body)) + + // Send smart-routing task + result, _ := a2aCall("message/send", map[string]interface{}{ + "skill": "smart-routing", + "messages": []map[string]string{{"role": "user", "content": "Hello from Go!"}}, + "metadata": map[string]interface{}{"model": "auto"}, + }) + out, _ := json.MarshalIndent(result.Result, "", " ") + fmt.Println("Result:", string(out)) +} +``` + +--- + +## Use Cases + +### ๐Ÿค– Use Case 1: Multi-Agent Coding Pipeline + +An orchestrator agent delegates code generation to OmniRoute, then passes the output to a review agent. + +```python +def coding_pipeline(task: str): + # Step 1: Generate code via OmniRoute A2A + code_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Write production-quality code: {task}"} + ], metadata={"model": "auto", "role": "coding"}) + code = code_result["artifacts"][0]["content"] + + # Step 2: Review the code via OmniRoute A2A (different model) + review_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Review this code for bugs and improvements:\n\n{code}"} + ], metadata={"model": "auto", "role": "review"}) + review = review_result["artifacts"][0]["content"] + + # Step 3: Check costs + print(f"Code cost: ${code_result['metadata']['cost_envelope']['actual']}") + print(f"Review cost: ${review_result['metadata']['cost_envelope']['actual']}") + + return {"code": code, "review": review} +``` + +### ๐Ÿ’ก Use Case 2: Quota-Aware Agent Swarm + +Multiple agents share quota through OmniRoute, using the quota skill to coordinate. + +```python +async def quota_aware_agent(agent_name: str, task: str): + # Check quota before starting + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Which provider has the most quota remaining?"} + ]) + print(f"[{agent_name}] {quota['artifacts'][0]['content']}") + + # Send request with budget constraint + result = a2a_send("smart-routing", [ + {"role": "user", "content": task} + ], metadata={"budget": 0.05}) + + policy = result["metadata"]["policy_verdict"] + if not policy["allowed"]: + print(f"[{agent_name}] โš ๏ธ Budget exceeded: {policy['reason']}") + # Fall back to free combo + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Suggest free combos"} + ]) + print(f"[{agent_name}] Free alternatives: {quota['artifacts'][0]['content']}") + + return result +``` + +### ๐Ÿ“Š Use Case 3: Real-Time Streaming Dashboard + +A monitoring agent streams responses and displays progress in real-time. + +```typescript +async function streamingDashboard(prompt: string) { + const response = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { "Content-Type": "application/json", Authorization: `Bearer ${API_KEY}` }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "dash-1", + method: "message/stream", + params: { skill: "smart-routing", messages: [{ role: "user", content: prompt }] }, + }), + }); + + let totalChunks = 0; + const reader = response.body!.getReader(); + const decoder = new TextDecoder(); + + while (true) { + const { done, value } = await reader.read(); + if (done) break; + + for (const line of decoder.decode(value).split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + const state = event.params.task.state; + + if (state === "working" && event.params.chunk) { + totalChunks++; + process.stdout.write( + `\r[Chunk ${totalChunks}] ${event.params.chunk.content.slice(0, 50)}...` + ); + } + if (state === "completed") { + const meta = event.params.metadata; + console.log( + `\nโœ… Done | Cost: $${meta?.cost_envelope?.actual || 0} | Route: ${meta?.routing_explanation || "N/A"}` + ); + } + if (state === "failed") { + console.error(`\nโŒ Failed: ${event.params.metadata?.error}`); + } + } + } + } +} +``` + +### ๐Ÿ” Use Case 4: Task Polling Pattern + +For long-running tasks, poll the task status instead of waiting synchronously. + +```python +import time + +def poll_task(task_id: str, timeout: int = 60): + """Poll task status until completion or timeout.""" + start = time.time() + while time.time() - start < timeout: + result = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "poll-1", + "method": "tasks/get", + "params": {"taskId": task_id}, + }).json() + + task = result["result"]["task"] + state = task["state"] + print(f" Task {task_id[:8]}... state={state}") + + if state in ("completed", "failed", "cancelled"): + return task + time.sleep(2) + + # Timeout โ€” cancel the task + requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "cancel-1", + "method": "tasks/cancel", + "params": {"taskId": task_id}, + }) + raise TimeoutError(f"Task {task_id} timed out after {timeout}s") +``` + +--- + +## Error Codes + +| Code | Constant | Meaning | +| ------ | ------------------------ | ---------------------------------------- | +| -32700 | โ€” | Parse error (invalid JSON) | +| -32600 | `INVALID_REQUEST` | Invalid JSON-RPC request or unauthorized | +| -32601 | `METHOD_NOT_FOUND` | Unknown method or skill | +| -32602 | `INVALID_PARAMS` | Missing or invalid parameters | +| -32603 | `INTERNAL_ERROR` | Skill execution failed | +| -32001 | `TASK_NOT_FOUND` | Task ID not found | +| -32002 | `TASK_ALREADY_COMPLETED` | Cannot modify a completed task | +| -32003 | `UNAUTHORIZED` | Invalid or missing API key | +| -32004 | `BUDGET_EXCEEDED` | Request exceeds configured budget | +| -32005 | `PROVIDER_UNAVAILABLE` | No available providers | + +--- + +## Authentication + +All `/a2a` requests require a Bearer token via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server (`OMNIROUTE_API_KEY` is empty), authentication is bypassed. + +--- + +## File Structure + +``` +src/lib/a2a/ +โ”œโ”€โ”€ taskManager.ts # Task lifecycle (create/update/cancel/list), TTL, cleanup +โ”œโ”€โ”€ taskExecution.ts # Generic task executor with state management +โ”œโ”€โ”€ streaming.ts # SSE stream formatting, heartbeat, chunk/completion events +โ”œโ”€โ”€ routingLogger.ts # Routing decision logger (stats, history, retention) +โ””โ”€โ”€ skills/ + โ”œโ”€โ”€ smartRouting.ts # Smart routing skill (routes via /v1/chat/completions) + โ””โ”€โ”€ quotaManagement.ts # Quota management skill (natural-language quota queries) + +src/app/a2a/ +โ””โ”€โ”€ route.ts # Next.js API route handler (JSON-RPC 2.0 dispatch) + +open-sse/mcp-server/ +โ””โ”€โ”€ schemas/a2a.ts # Zod schemas (AgentCard, Task, JSON-RPC, SSE events) +``` + +--- + +## Comparison: MCP vs A2A + +| Feature | MCP Server | A2A Server | +| ----------------- | ---------------------------- | ------------------------------------------------- | +| **Protocol** | Model Context Protocol | Agent-to-Agent Protocol v0.3 | +| **Transport** | stdio / HTTP | HTTP (JSON-RPC 2.0) | +| **Discovery** | Tool listing via MCP | `/.well-known/agent.json` | +| **Granularity** | 16 individual tools | 2 high-level skills | +| **Best for** | IDE agents (Cursor, VS Code) | Multi-agent systems (LangChain, CrewAI) | +| **Streaming** | Not supported | SSE via `message/stream` | +| **Task tracking** | No | Full lifecycle (submitted โ†’ completed) | +| **Observability** | Audit log per tool call | Cost envelope + resilience trace + policy verdict | + +--- + +## Licence + +Part of [OmniRoute](https://github.com/diegosouzapw/OmniRoute) โ€” MIT License. diff --git a/docs/i18n/he/A2A-SERVER.md b/docs/i18n/he/A2A-SERVER.md deleted file mode 100644 index 01531ff482..0000000000 --- a/docs/i18n/he/A2A-SERVER.md +++ /dev/null @@ -1,200 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/A2A-SERVER.md) - ---- - -# OmniRoute A2A Server Documentation - -> Agent-to-Agent Protocol v0.3 โ€” OmniRoute as an intelligent routing agent - -## Agent Discovery - -```bash -curl http://localhost:20128/.well-known/agent.json -``` - -Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements. - ---- - -## Authentication - -All `/a2a` requests require an API key via the `Authorization` header: - -``` -Authorization: Bearer YOUR_OMNIROUTE_API_KEY -``` - -If no API key is configured on the server, authentication is bypassed. - ---- - -## JSON-RPC 2.0 Methods - -### `message/send` โ€” Synchronous Execution - -Sends a message to a skill and waits for the complete response. - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{ - "jsonrpc": "2.0", - "id": "1", - "method": "message/send", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Write a hello world in Python"}], - "metadata": {"model": "auto", "combo": "fast-coding"} - } - }' -``` - -**Response:** - -```json -{ - "jsonrpc": "2.0", - "id": "1", - "result": { - "task": { "id": "uuid", "state": "completed" }, - "artifacts": [{ "type": "text", "content": "..." }], - "metadata": { - "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)", - "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, - "resilience_trace": [ - { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." } - ], - "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } - } - } -} -``` - -### `message/stream` โ€” SSE Streaming - -Same as `message/send` but returns Server-Sent Events for real-time streaming. - -```bash -curl -N -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{ - "jsonrpc": "2.0", - "id": "1", - "method": "message/stream", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Explain quantum computing"}] - } - }' -``` - -**SSE Events:** - -``` -data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}} - -: heartbeat 2026-03-03T17:00:00Z - -data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} -``` - -### `tasks/get` โ€” Query Task Status - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' -``` - -### `tasks/cancel` โ€” Cancel a Task - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' -``` - ---- - -## Available Skills - -| Skill | Description | -| :----------------- | :------------------------------------------------------------------------------------------------------------------------------ | -| `smart-routing` | Routes prompts through OmniRoute's intelligent pipeline. Returns response with routing explanation, cost, and resilience trace. | -| `quota-management` | Answers natural-language queries about provider quotas, suggests free combos, and provides quota rankings. | - ---- - -## Task Lifecycle - -``` -submitted โ†’ working โ†’ completed - โ†’ failed - โ†’ cancelled -``` - -- Tasks expire after 5 minutes (configurable) -- Terminal states: `completed`, `failed`, `cancelled` -- Event log tracks every state transition - ---- - -## Error Codes - -| Code | Meaning | -| :----- | :----------------------------- | -| -32700 | Parse error (invalid JSON) | -| -32600 | Invalid request / Unauthorized | -| -32601 | Method or skill not found | -| -32602 | Invalid params | -| -32603 | Internal error | - ---- - -## Integration Examples - -### Python (requests) - -```python -import requests - -resp = requests.post("http://localhost:20128/a2a", json={ - "jsonrpc": "2.0", "id": "1", - "method": "message/send", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Hello"}] - } -}, headers={"Authorization": "Bearer YOUR_KEY"}) - -result = resp.json()["result"] -print(result["artifacts"][0]["content"]) -print(result["metadata"]["routing_explanation"]) -``` - -### TypeScript (fetch) - -```typescript -const resp = await fetch("http://localhost:20128/a2a", { - method: "POST", - headers: { - "Content-Type": "application/json", - Authorization: "Bearer YOUR_KEY", - }, - body: JSON.stringify({ - jsonrpc: "2.0", - id: "1", - method: "message/send", - params: { - skill: "smart-routing", - messages: [{ role: "user", content: "Hello" }], - }, - }), -}); -const { result } = await resp.json(); -console.log(result.metadata.routing_explanation); -``` diff --git a/docs/i18n/he/API_REFERENCE.md b/docs/i18n/he/API_REFERENCE.md deleted file mode 100644 index b878605221..0000000000 --- a/docs/i18n/he/API_REFERENCE.md +++ /dev/null @@ -1,455 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/API_REFERENCE.md) - ---- - -# API Reference - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/API_REFERENCE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/API_REFERENCE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/API_REFERENCE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/API_REFERENCE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/API_REFERENCE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/API_REFERENCE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/API_REFERENCE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/API_REFERENCE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/API_REFERENCE.md) - -Complete reference for all OmniRoute API endpoints. - ---- - -## Table of Contents - -- [Chat Completions](#chat-completions) -- [Embeddings](#embeddings) -- [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`. - -### ACP Agents - -| Endpoint | Method | Description | -| ----------------- | ------ | -------------------------------------------------------- | -| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | -| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | -| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | - -GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). - -### Resilience & Rate Limits - -| Endpoint | Method | Description | -| ----------------------- | ------- | ------------------------------- | -| `/api/resilience` | 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` diff --git a/docs/i18n/he/ARCHITECTURE.md b/docs/i18n/he/ARCHITECTURE.md deleted file mode 100644 index 4ea06a29f2..0000000000 --- a/docs/i18n/he/ARCHITECTURE.md +++ /dev/null @@ -1,787 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/ARCHITECTURE.md) - ---- - -# OmniRoute Architecture - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/ARCHITECTURE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/ARCHITECTURE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/ARCHITECTURE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/ARCHITECTURE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/ARCHITECTURE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/ARCHITECTURE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/ARCHITECTURE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/ARCHITECTURE.md) - -_Last updated: 2026-03-04_ - -## 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 (`...`) for reasoning models -- Response sanitization for strict OpenAI SDK compatibility -- Role normalization (developerโ†’system, systemโ†’user) for cross-provider compatibility -- Structured output conversion (json_schema โ†’ Gemini responseSchema) -- Local persistence for providers, keys, aliases, combos, settings, pricing -- Usage/cost tracking and request logging -- Optional cloud sync for multi-device/state sync -- IP allowlist/blocklist for API access control -- Thinking budget management (passthrough/auto/custom/adaptive) -- Global system prompt injection -- Session tracking and fingerprinting -- Per-account enhanced rate limiting with provider-specific profiles -- Circuit breaker pattern for provider resilience -- Anti-thundering herd protection with mutex locking -- Signature-based request deduplication cache -- Domain layer: model availability, cost rules, fallback policy, lockout policy -- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) -- Policy engine for centralized request evaluation (lockout โ†’ budget โ†’ fallback) -- Request telemetry with p50/p95/p99 latency aggregation -- Correlation ID (X-Request-Id) for end-to-end tracing -- Compliance audit logging with opt-out per API key -- Eval framework for LLM quality assurance -- Resilience UI dashboard with real-time circuit breaker status -- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) - -Primary runtime model: - -- Next.js 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[(storage.sqlite)] - UDB[(usage tables + log artifacts)] - end - - subgraph Upstreams[Upstream Providers] - P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/Qoder/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/route.ts` (GET) -- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) -- OAuth: `src/app/api/oauth/*` -- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` -- Usage: `src/app/api/usage/*` -- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` -- CLI tooling helpers: `src/app/api/cli-tools/*` -- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) -- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) -- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) -- Sessions: `src/app/api/sessions` (GET) -- Rate limits: `src/app/api/rate-limits` (GET) -- Resilience: `src/app/api/resilience` (GET/PATCH) โ€” provider profiles, circuit breaker, rate limit state -- Resilience reset: `src/app/api/resilience/reset` (POST) โ€” reset breakers + cooldowns -- Cache stats: `src/app/api/cache/stats` (GET/DELETE) -- Model availability: `src/app/api/models/availability` (GET/POST) -- Telemetry: `src/app/api/telemetry/summary` (GET) -- Budget: `src/app/api/usage/budget` (GET/POST) -- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) -- Compliance audit: `src/app/api/compliance/audit-log` (GET) -- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) -- Policies: `src/app/api/policies` (GET/POST) - -## 2) SSE + 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` -- Response sanitization: `open-sse/handlers/responseSanitizer.ts` -- Role normalization: `open-sse/services/roleNormalizer.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`, `qoder.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 (SQLite): - -- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) -- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) -- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) -- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** - -Usage persistence: - -- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) -- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` -- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) -- legacy JSON files are migrated to SQLite by startup migrations when present - -Domain State DB (SQLite): - -- `src/lib/db/domainState.ts` โ€” CRUD operations 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: - -- primary runtime DB: `${DATA_DIR}/storage.sqlite` -- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) -- structured call payload archives: `${DATA_DIR}/call_logs/` -- optional translator/request debug sessions: `/logs/...` - -## Deployment Topology - -```mermaid -flowchart LR - 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[(storage.sqlite)] - UsageDB[(usage tables + log artifacts)] - end - - subgraph External[External Services] - Providers[AI Providers] - SyncCloud[Cloud Sync Service] - end - - CLI --> Next - Browser --> Next - Next --> Core - Next --> MainDB - Core --> MainDB - Core --> UsageDB - Core --> Providers - Next --> SyncCloud -``` - -## Module Mapping (Decision-Critical) - -### Route and API Modules - -- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs -- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) -- `src/app/api/providers*`: provider CRUD, validation, testing -- `src/app/api/provider-nodes*`: custom compatible node management -- `src/app/api/provider-models`: custom model management (CRUD) -- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) -- `src/app/api/oauth/*`: OAuth/device-code flows -- `src/app/api/keys*`: local API key lifecycle -- `src/app/api/models/alias`: alias management -- `src/app/api/combos*`: fallback combo management -- `src/app/api/pricing`: pricing overrides for cost calculation -- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) -- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) -- `src/app/api/usage/*`: usage and logs APIs -- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers -- `src/app/api/cli-tools/*`: local CLI config writers/checkers -- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) -- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) -- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) -- `src/app/api/sessions`: active session listing (GET) -- `src/app/api/rate-limits`: per-account rate limit status (GET) - -### Routing and Execution Core - -- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop -- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup -- `open-sse/executors/*`: provider-specific network and format behavior - -### Translation Registry and Format Converters - -- `open-sse/translator/index.ts`: translator registry and orchestration -- Request translators: `open-sse/translator/request/*` -- Response translators: `open-sse/translator/response/*` -- Format constants: `open-sse/translator/formats.ts` - -### Persistence - -- `src/lib/db/*`: persistent config/state and domain persistence on SQLite -- `src/lib/localDb.ts`: compatibility re-export for DB modules -- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables - -## Provider Executor Coverage (Strategy Pattern) - -Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. - -| Executor | Provider(s) | Special Handling | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | -| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, Qoder, 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 | -| Qoder | openai | OAuth (Basic) | โœ… | โœ… | โœ… | โš ๏ธ Per request | -| OpenRouter | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| GLM/Kimi/MiniMax | claude | API Key | โœ… | โœ… | โŒ | โŒ | -| DeepSeek | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Groq | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| xAI (Grok) | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Mistral | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Perplexity | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Together AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Fireworks AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Cerebras | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Cohere | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| NVIDIA NIM | openai | API Key | โœ… | โœ… | โŒ | โŒ | - -## Format Translation Coverage - -Detected source formats include: - -- `openai` -- `openai-responses` -- `claude` -- `gemini` - -Target formats include: - -- OpenAI chat/Responses -- Claude -- Gemini/Gemini-CLI/Antigravity envelope -- Kiro -- Cursor - -Translations use **OpenAI as the hub format** โ€” all conversions go through OpenAI as intermediate: - -``` -Source Format โ†’ OpenAI (hub) โ†’ Target Format -``` - -Translations are selected dynamically based on source payload shape and provider target format. - -Additional processing layers in the translation pipeline: - -- **Response sanitization** โ€” Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance -- **Role normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI targets; merges `system` โ†’ `user` for models that reject the system role (GLM, ERNIE) -- **Think tag extraction** โ€” Parses `...` blocks from content into `reasoning_content` field -- **Structured output** โ€” Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` - -## Supported API Endpoints - -| 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 `/logs//` 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 - -- SQLite schema migrations and auto-upgrade hooks at startup -- legacy JSON โ†’ SQLite migration compatibility path - -## Observability and Operational Signals - -Runtime visibility sources: - -- console logs from `src/sse/utils/logger.ts` -- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) -- textual request status log in `log.txt` (optional/compat) -- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` -- dashboard usage endpoints (`/api/usage/*`) for UI consumption - -## Security-Sensitive Boundaries - -- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing -- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning -- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format -- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level -- Cloud sync endpoints rely on API key auth + machine id semantics - -## Environment and Runtime Matrix - -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` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. -2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. -3. Request logger writes full headers/body when enabled; treat log directory as sensitive. -4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. -5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. -6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). -7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). -8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). - -## Operational Verification Checklist - -- Build from source: `npm run build` -- Build Docker image: `docker build -t omniroute .` -- Start service and verify: -- `GET /api/settings` -- `GET /api/v1/models` -- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/he/AUTO-COMBO.md b/docs/i18n/he/AUTO-COMBO.md deleted file mode 100644 index 2166e41dff..0000000000 --- a/docs/i18n/he/AUTO-COMBO.md +++ /dev/null @@ -1,67 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/AUTO-COMBO.md) - ---- - -# OmniRoute Auto-Combo Engine - -> Self-managing model chains with adaptive scoring - -## How It Works - -The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**: - -| Factor | Weight | Description | -| :--------- | :----- | :---------------------------------------------- | -| Quota | 0.20 | Remaining capacity [0..1] | -| Health | 0.25 | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 | -| CostInv | 0.20 | Inverse cost (cheaper = higher score) | -| LatencyInv | 0.15 | Inverse p95 latency (faster = higher) | -| TaskFit | 0.10 | Model ร— task type fitness score | -| Stability | 0.10 | Low variance in latency/errors | - -## Mode Packs - -| Pack | Focus | Key Weight | -| :---------------------- | :----------- | :--------------- | -| ๐Ÿš€ **Ship Fast** | Speed | latencyInv: 0.35 | -| ๐Ÿ’ฐ **Cost Saver** | Economy | costInv: 0.40 | -| ๐ŸŽฏ **Quality First** | Best model | taskFit: 0.40 | -| ๐Ÿ“ก **Offline Friendly** | Availability | quota: 0.40 | - -## Self-Healing - -- **Temporary exclusion**: Score < 0.2 โ†’ excluded for 5 min (progressive backoff, max 30 min) -- **Circuit breaker awareness**: OPEN โ†’ auto-excluded; HALF_OPEN โ†’ probe requests -- **Incident mode**: >50% OPEN โ†’ disable exploration, maximize stability -- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout - -## Bandit Exploration - -5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode. - -## API - -```bash -# Create auto-combo -curl -X POST http://localhost:20128/api/combos/auto \ - -H "Content-Type: application/json" \ - -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}' - -# List auto-combos -curl http://localhost:20128/api/combos/auto -``` - -## Task Fitness - -30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` โ†’ high coding score). - -## Files - -| File | Purpose | -| :------------------------------------------- | :------------------------------------ | -| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization | -| `open-sse/services/autoCombo/taskFitness.ts` | Model ร— task fitness lookup | -| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap | -| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode | -| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles | -| `src/app/api/combos/auto/route.ts` | REST API | diff --git a/docs/i18n/he/CHANGELOG.md b/docs/i18n/he/CHANGELOG.md index 83a4241e34..eb36ed44ba 100644 --- a/docs/i18n/he/CHANGELOG.md +++ b/docs/i18n/he/CHANGELOG.md @@ -1,12 +1,92 @@ # Changelog (ืขื‘ืจื™ืช) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CHANGELOG.md) --- - ## [Unreleased] +### ๐Ÿ› ๏ธ Maintenance + +- **AGENTS.md rewrite:** Condensed from 297โ†’153 lines. Added build/lint/test commands (including single-test execution), code style guidelines (Prettier, TypeScript, ESLint, naming, imports, error handling, security), and trimmed verbose architecture tables for AI agent consumption. + +## [3.4.2] - 2026-04-01 + +### ๐Ÿ› Bug Fixes + +- **CI Stabilization:** Fixed failing analytics/settings Playwright selectors and request assertions so GitHub Actions E2E runs pass reliably across localized UIs and switch-based controls. +- **Deterministic Tests:** Removed date-sensitive quota fixtures from Copilot usage tests and aligned idempotency/model catalog tests with the merged runtime behavior. +- **MCP Type Hardening:** Removed zero-budget explicit `any` regressions from the MCP server tool registration path, restoring the `check:any-budget:t11` workflow gate. + +### ๐Ÿ› ๏ธ Maintenance + +- **Release Branch Integration:** Consolidated the active feature branches into `release/v3.4.2` on top of current `main` and validated the branch with lint, unit, coverage, build, and CI-mode E2E runs. + +## [3.4.1] - 2026-03-31 + +> [!WARNING] +> **BREAKING CHANGE: request logging, retention, and logging environment variables have been redesigned.** +> On the first startup after upgrading, OmniRoute archives legacy request logs from `DATA_DIR/logs/`, legacy `DATA_DIR/call_logs/`, and `DATA_DIR/log.txt` into `DATA_DIR/log_archives/*.zip`, then removes the deprecated layout and switches to the new unified artifact format under `DATA_DIR/call_logs/`. + +### โœจ New Features + +- **.ENV Migration Utility:** Included `scripts/migrate-env.mjs` to seamlessly migrate ` Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` - ---- - -## Step 2 โ€” Install CLI Tools - -All npm-based tools require Node.js 18+: - -```bash -# Claude Code (Anthropic) -npm install -g @anthropic-ai/claude-code - -# OpenAI Codex -npm install -g @openai/codex - -# Gemini CLI (Google) -npm install -g @google/gemini-cli - -# OpenCode -npm install -g opencode-ai - -# Cline -npm install -g cline - -# KiloCode -npm install -g kilecode - -# Kiro CLI (Amazon โ€” requires curl + unzip) -apt-get install -y unzip # on Debian/Ubuntu -curl -fsSL https://cli.kiro.dev/install | bash -export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc -``` - -**Verify:** - -```bash -claude --version # 2.x.x -codex --version # 0.x.x -gemini --version # 0.x.x -opencode --version # x.x.x -cline --version # 2.x.x -kilocode --version # x.x.x (or: kilo --version) -kiro-cli --version # 1.x.x -``` - ---- - -## Step 3 โ€” Set Global Environment Variables - -Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`: - -```bash -# OmniRoute Universal Endpoint -export OPENAI_BASE_URL="http://localhost:20128/v1" -export OPENAI_API_KEY="sk-your-omniroute-key" -export ANTHROPIC_BASE_URL="http://localhost:20128/v1" -export ANTHROPIC_API_KEY="sk-your-omniroute-key" -export GEMINI_BASE_URL="http://localhost:20128/v1" -export GEMINI_API_KEY="sk-your-omniroute-key" -``` - -> For a **remote server** replace `localhost:20128` with the server IP or domain, -> e.g. `http://192.168.0.15:20128`. - ---- - -## Step 4 โ€” Configure Each Tool - -### Claude Code - -```bash -# Via CLI: -claude config set --global api-base-url http://localhost:20128/v1 - -# Or create ~/.claude/settings.json: -mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF -{ - "apiBaseUrl": "http://localhost:20128/v1", - "apiKey": "sk-your-omniroute-key" -} -EOF -``` - -**Test:** `claude "say hello"` - ---- - -### OpenAI Codex - -```bash -mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF -model: auto -apiKey: sk-your-omniroute-key -apiBaseUrl: http://localhost:20128/v1 -EOF -``` - -**Test:** `codex "what is 2+2?"` - ---- - -### Gemini CLI - -```bash -mkdir -p ~/.gemini && cat > ~/.gemini/settings.json << EOF -{ - "apiKey": "sk-your-omniroute-key", - "baseUrl": "http://localhost:20128/v1" -} -EOF -``` - -**Test:** `gemini "hello"` - ---- - -### OpenCode - -```bash -mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF -[provider.openai] -base_url = "http://localhost:20128/v1" -api_key = "sk-your-omniroute-key" -EOF -``` - -**Test:** `opencode` - ---- - -### Cline (CLI or VS Code) - -**CLI mode:** - -```bash -mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF -{ - "apiProvider": "openai", - "openAiBaseUrl": "http://localhost:20128/v1", - "openAiApiKey": "sk-your-omniroute-key" -} -EOF -``` - -**VS Code mode:** -Cline extension settings โ†’ API Provider: `OpenAI Compatible` โ†’ Base URL: `http://localhost:20128/v1` - -Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ Cline โ†’ Apply Config**. - ---- - -### KiloCode (CLI or VS Code) - -**CLI mode:** - -```bash -kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key -``` - -**VS Code settings:** - -```json -{ - "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", - "kilo-code.apiKey": "sk-your-omniroute-key" -} -``` - -Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ KiloCode โ†’ Apply Config**. - ---- - -### Continue (VS Code Extension) - -Edit `~/.continue/config.yaml`: - -```yaml -models: - - name: OmniRoute - provider: openai - model: auto - apiBase: http://localhost:20128/v1 - apiKey: sk-your-omniroute-key - default: true -``` - -Restart VS Code after editing. - ---- - -### Kiro CLI (Amazon) - -```bash -# Login to your AWS/Kiro account: -kiro-cli login - -# The CLI uses its own auth โ€” OmniRoute is not needed as backend for Kiro CLI itself. -# Use kiro-cli alongside OmniRoute for other tools. -kiro-cli status -``` - ---- - -### Cursor (Desktop App) - -> **Note:** Cursor routes requests through its cloud. For OmniRoute integration, -> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL. - -Via GUI: **Settings โ†’ Models โ†’ OpenAI API Key** - -- Base URL: `https://your-domain.com/v1` -- API Key: your OmniRoute key - ---- - -## Dashboard Auto-Configuration - -The OmniRoute dashboard automates configuration for most tools: - -1. Go to `http://localhost:20128/dashboard/cli-tools` -2. Expand any tool card -3. Select your API key from the dropdown -4. Click **Apply Config** (if tool is detected as installed) -5. Or copy the generated config snippet manually - ---- - -## Built-in Agents: Droid & OpenClaw - -**Droid** and **OpenClaw** are AI agents built directly into OmniRoute โ€” no installation needed. -They run as internal routes and use OmniRoute's model routing automatically. - -- Access: `http://localhost:20128/dashboard/agents` -- Configure: same combos and providers as all other tools -- No API key or CLI install required - ---- - -## Available API Endpoints - -| Endpoint | Description | Use For | -| -------------------------- | ----------------------------- | --------------------------- | -| `/v1/chat/completions` | Standard chat (all providers) | All modern tools | -| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows | -| `/v1/completions` | Legacy text completions | Older tools using `prompt:` | -| `/v1/embeddings` | Text embeddings | RAG, search | -| `/v1/images/generations` | Image generation | DALL-E, Flux, etc. | -| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS | -| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI | - ---- - -## Troubleshooting - -| Error | Cause | Fix | -| ------------------------- | ----------------------- | ------------------------------------------ | -| `Connection refused` | OmniRoute not running | `pm2 start omniroute` | -| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` | -| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` | -| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` | -| CLI shows "not installed" | Binary not in PATH | Check `which ` | -| `kiro-cli: not found` | Not in PATH | `export PATH="$HOME/.local/bin:$PATH"` | - ---- - -## Quick Setup Script (One Command) - -```bash -# Install all CLIs and configure for OmniRoute (replace with your key and server URL) -OMNIROUTE_URL="http://localhost:20128/v1" -OMNIROUTE_KEY="sk-your-omniroute-key" - -npm install -g @anthropic-ai/claude-code @openai/codex @google/gemini-cli opencode-ai cline kilecode - -# Kiro CLI -apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash - -# Write configs -mkdir -p ~/.claude ~/.codex ~/.gemini ~/.config/opencode ~/.continue - -cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" -cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" -cat > ~/.gemini/settings.json <<< "{\"apiKey\":\"$OMNIROUTE_KEY\",\"baseUrl\":\"$OMNIROUTE_URL\"}" -cat >> ~/.bashrc << EOF -export OPENAI_BASE_URL="$OMNIROUTE_URL" -export OPENAI_API_KEY="$OMNIROUTE_KEY" -export ANTHROPIC_BASE_URL="$OMNIROUTE_URL" -export ANTHROPIC_API_KEY="$OMNIROUTE_KEY" -EOF - -source ~/.bashrc -echo "โœ… All CLIs installed and configured for OmniRoute" -``` diff --git a/docs/i18n/he/CODEBASE_DOCUMENTATION.md b/docs/i18n/he/CODEBASE_DOCUMENTATION.md deleted file mode 100644 index e2d7950052..0000000000 --- a/docs/i18n/he/CODEBASE_DOCUMENTATION.md +++ /dev/null @@ -1,593 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CODEBASE_DOCUMENTATION.md) - ---- - -# omniroute โ€” Codebase Documentation - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) - -> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. - ---- - -## 1. 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
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, Qoder, 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 | -| Qoder | 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"] -``` diff --git a/docs/i18n/he/CONTRIBUTING.md b/docs/i18n/he/CONTRIBUTING.md new file mode 100644 index 0000000000..7d8516e147 --- /dev/null +++ b/docs/i18n/he/CONTRIBUTING.md @@ -0,0 +1,299 @@ +# Contributing to OmniRoute (ืขื‘ืจื™ืช) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CONTRIBUTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CONTRIBUTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CONTRIBUTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CONTRIBUTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CONTRIBUTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CONTRIBUTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CONTRIBUTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CONTRIBUTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CONTRIBUTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CONTRIBUTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CONTRIBUTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CONTRIBUTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CONTRIBUTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CONTRIBUTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CONTRIBUTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CONTRIBUTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CONTRIBUTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CONTRIBUTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CONTRIBUTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CONTRIBUTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CONTRIBUTING.md) + +--- + +Thank you for your interest in contributing! This guide covers everything you need to get started. + +--- + +## Development Setup + +### Prerequisites + +- **Node.js** >= 18 < 24 (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` | `20128` | Server port | +| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | Base URL for frontend | +| `JWT_SECRET` | (generate above) | JWT signing secret | +| `INITIAL_PASSWORD` | `CHANGEME` | First login password | +| `APP_LOG_LEVEL` | `info` | Log verbosity level | + +### Dashboard Settings + +The dashboard provides UI toggles for features that can also be configured via environment variables: + +| Setting Location | Toggle | Description | +| ------------------- | ------------------ | ------------------------------ | +| Settings โ†’ Advanced | Debug Mode | Enable debug request logs (UI) | +| Settings โ†’ General | Sidebar Visibility | Show/hide sidebar sections | + +These settings are stored in the database and persist across restarts, overriding env var defaults when set. + +### 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:20128/dashboard` +- **API**: `http://localhost:20128/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`, `mcp`, `a2a`, `memory`, `skills`. + +--- + +## Running Tests + +```bash +# All tests (unit + vitest + ecosystem + e2e) +npm run test:all + +# Single test file (Node.js native test runner โ€” most tests use this) +node --import tsx/esm --test tests/unit/your-file.test.mjs + +# Vitest (MCP server, autoCombo, cache) +npm run test:vitest + +# E2E tests (requires Playwright) +npm run test:e2e + +# Protocol clients E2E (MCP transports, A2A) +npm run test:protocols:e2e + +# Ecosystem compatibility tests +npm run test:ecosystem + +# Coverage (55% min statements/lines/functions; 60% branches) +npm run test:coverage +npm run coverage:report + +# Lint + format check +npm run lint +npm run check +``` + +Coverage notes: + +- `npm run test:coverage` measures source coverage for the main unit test suite, excludes `tests/**`, and includes `open-sse/**` +- `npm run coverage:report` prints the detailed file-by-file report from the latest coverage run +- `npm run test:coverage:legacy` preserves the older metric for historical comparison +- See `docs/COVERAGE_PLAN.md` for the phased coverage improvement roadmap + +Current test status: **122 unit test files** covering: + +- Provider translators and format conversion +- Rate limiting, circuit breaker, and resilience +- Semantic cache, idempotency, progress tracking +- Database operations and schema (21 DB modules) +- OAuth flows and authentication +- API endpoint validation (Zod v4) +- MCP server tools and scope enforcement +- Memory and Skills systems + +--- + +## Code Style + +- **ESLint** โ€” Run `npm run lint` before committing +- **Prettier** โ€” Auto-formatted via `lint-staged` on commit (2 spaces, semicolons, double quotes, 100 char width, es5 trailing commas) +- **TypeScript** โ€” All `src/` code uses `.ts`/`.tsx`; `open-sse/` uses `.ts`/`.js`; document with TSDoc (`@param`, `@returns`, `@throws`) +- **No `eval()`** โ€” ESLint enforces `no-eval`, `no-implied-eval`, `no-new-func` +- **Zod validation** โ€” Use Zod v4 schemas for all API input validation +- **Naming**: Files = camelCase/kebab-case, components = PascalCase, constants = UPPER_SNAKE + +--- + +## Project Structure + +``` +src/ # TypeScript (.ts / .tsx) +โ”œโ”€โ”€ app/ # Next.js 16 App Router +โ”‚ โ”œโ”€โ”€ (dashboard)/ # Dashboard pages (23 sections) +โ”‚ โ”œโ”€โ”€ api/ # API routes (51 directories) +โ”‚ โ””โ”€โ”€ login/ # Auth pages (.tsx) +โ”œโ”€โ”€ domain/ # Policy engine (policyEngine, comboResolver, costRules, etc.) +โ”œโ”€โ”€ lib/ # Core business logic (.ts) +โ”‚ โ”œโ”€โ”€ a2a/ # Agent-to-Agent v0.3 protocol server +โ”‚ โ”œโ”€โ”€ acp/ # Agent Communication Protocol registry +โ”‚ โ”œโ”€โ”€ compliance/ # Compliance policy engine +โ”‚ โ”œโ”€โ”€ db/ # SQLite database layer (21 modules + 16 migrations) +โ”‚ โ”œโ”€โ”€ memory/ # Persistent conversational memory +โ”‚ โ”œโ”€โ”€ oauth/ # OAuth providers, services, and utilities +โ”‚ โ”œโ”€โ”€ skills/ # Extensible skill framework +โ”‚ โ”œโ”€โ”€ usage/ # Usage tracking and cost calculation +โ”‚ โ””โ”€โ”€ localDb.ts # Re-export layer only โ€” never add logic here +โ”œโ”€โ”€ middleware/ # Request middleware (promptInjectionGuard) +โ”œโ”€โ”€ mitm/ # MITM proxy (cert, DNS, target routing) +โ”œโ”€โ”€ shared/ +โ”‚ โ”œโ”€โ”€ components/ # React components (.tsx) +โ”‚ โ”œโ”€โ”€ constants/ # Provider definitions (60+), MCP scopes, routing strategies +โ”‚ โ”œโ”€โ”€ utils/ # Circuit breaker, sanitizer, auth helpers +โ”‚ โ””โ”€โ”€ validation/ # Zod v4 schemas +โ””โ”€โ”€ sse/ # SSE proxy pipeline + +open-sse/ # @omniroute/open-sse workspace +โ”œโ”€โ”€ executors/ # 14 provider-specific request executors +โ”œโ”€โ”€ handlers/ # 11 request handlers (chat, responses, embeddings, images, etc.) +โ”œโ”€โ”€ mcp-server/ # MCP server (25 tools, 3 transports, 10 scopes) +โ”œโ”€โ”€ services/ # 36+ services (combo, autoCombo, rateLimitManager, etc.) +โ”œโ”€โ”€ translator/ # Format translators (OpenAI โ†” Claude โ†” Gemini โ†” Responses โ†” Ollama) +โ”œโ”€โ”€ transformer/ # Responses API transformer +โ””โ”€โ”€ utils/ # 22 utility modules (stream, TLS, proxy, logging) + +electron/ # Electron desktop app (cross-platform) + +tests/ +โ”œโ”€โ”€ unit/ # Node.js test runner (122 test files) +โ”œโ”€โ”€ integration/ # Integration tests +โ”œโ”€โ”€ e2e/ # Playwright tests +โ”œโ”€โ”€ security/ # Security tests +โ”œโ”€โ”€ translator/ # Translator-specific tests +โ””โ”€โ”€ load/ # Load tests + +docs/ # Documentation +โ”œโ”€โ”€ ARCHITECTURE.md # System architecture +โ”œโ”€โ”€ API_REFERENCE.md # All endpoints +โ”œโ”€โ”€ USER_GUIDE.md # Provider setup, CLI integration +โ”œโ”€โ”€ TROUBLESHOOTING.md # Common issues +โ”œโ”€โ”€ MCP-SERVER.md # MCP server (25 tools) +โ”œโ”€โ”€ A2A-SERVER.md # A2A agent protocol +โ”œโ”€โ”€ AUTO-COMBO.md # Auto-combo engine +โ”œโ”€โ”€ CLI-TOOLS.md # CLI tools integration +โ”œโ”€โ”€ COVERAGE_PLAN.md # Test coverage improvement plan +โ”œโ”€โ”€ openapi.yaml # OpenAPI specification +โ””โ”€โ”€ adr/ # Architecture Decision Records +``` + +--- + +## Adding a New Provider + +### Step 1: Register Provider Constants + +Add to `src/shared/constants/providers.ts` โ€” Zod-validated at module load. + +### Step 2: Add Executor (if custom logic needed) + +Create executor in `open-sse/executors/your-provider.ts` extending the base executor. + +### Step 3: Add Translator (if non-OpenAI format) + +Create request/response translators in `open-sse/translator/`. + +### Step 4: Add OAuth Config (if OAuth-based) + +Add OAuth credentials in `src/lib/oauth/constants/oauth.ts` and service in `src/lib/oauth/services/`. + +### Step 5: Register Models + +Add model definitions in `open-sse/config/providerRegistry.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 +- [ ] All inputs validated with Zod schemas +- [ ] CHANGELOG updated (if user-facing change) +- [ ] Documentation updated (if applicable) + +--- + +## Releasing + +Releases are managed via the `/generate-release` workflow. When a new GitHub Release is created, the package is **automatically published to npm** via GitHub Actions. + +--- + +## Getting Help + +- **Architecture**: See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) +- **API Reference**: See [`docs/API_REFERENCE.md`](docs/API_REFERENCE.md) +- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **ADRs**: See `docs/adr/` for architectural decision records diff --git a/docs/i18n/he/FEATURES.md b/docs/i18n/he/FEATURES.md deleted file mode 100644 index 371ab6cc4f..0000000000 --- a/docs/i18n/he/FEATURES.md +++ /dev/null @@ -1,147 +0,0 @@ -# OmniRoute โ€” Dashboard Features Gallery (ืขื‘ืจื™ืช) - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) - -> ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../docs/FEATURES.md) - ---- - -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 (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. - -![Providers Dashboard](screenshots/01-providers.png) - ---- - -## ๐ŸŽจ Combos - -Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. - -![Combos Dashboard](screenshots/02-combos.png) - ---- - -## ๐Ÿ“Š Analytics - -Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. - -![Analytics Dashboard](screenshots/03-analytics.png) - ---- - -## ๐Ÿฅ System Health - -Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. - -![Health Dashboard](screenshots/04-health.png) - ---- - -## ๐Ÿ”ง Translator Playground - -Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). - -![Translator Playground](screenshots/05-translator.png) - ---- - -## ๐ŸŽฎ Model Playground _(v2.0.9+)_ - -Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. - ---- - -## ๐ŸŽจ Themes _(v2.0.5+)_ - -Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. - ---- - -## โš™๏ธ Settings - -Comprehensive settings panel with tabs: - -- **General** โ€” System storage, backup management (export/import database) -- **Appearance** โ€” Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls -- **Security** โ€” API endpoint protection, custom provider blocking, IP filtering, session info -- **Routing** โ€” Model aliases, background task degradation -- **Resilience** โ€” Rate limit persistence, circuit breaker tuning -- **Advanced** โ€” Configuration overrides - -![Settings Dashboard](screenshots/06-settings.png) - ---- - -## ๐Ÿ”ง CLI Tools - -One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. - -![CLI Tools Dashboard](screenshots/07-cli-tools.png) - ---- - -## ๐Ÿค– CLI Agents _(v2.0.11+)_ - -Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: - -- **Installation status** โ€” Installed / Not Found with version detection -- **Protocol badges** โ€” stdio, HTTP, etc. -- **Custom agents** โ€” Register any CLI tool via form (name, binary, version command, spawn args) -- **CLI Fingerprint Matching** โ€” Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP - ---- - -## ๐Ÿ–ผ๏ธ Media _(v2.0.3+)_ - -Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. - ---- - -## ๐Ÿ“ Request Logs - -Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. - -![Usage Logs](screenshots/08-usage.png) - ---- - -## ๐ŸŒ API Endpoint - -Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. - -![Endpoint Dashboard](screenshots/09-endpoint.png) - ---- - -## ๐Ÿ”‘ API Key Management - -Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. - ---- - -## ๐Ÿ“‹ Audit Log - -Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. - ---- - -## ๐Ÿ–ฅ๏ธ Desktop Application - -Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. - -Key features: - -- Server readiness polling (no blank screen on cold start) -- System tray with port management -- Content Security Policy -- Single-instance lock -- Auto-update on restart -- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) -- Hardened Electron build packaging โ€” symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+) - -๐Ÿ“– See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/he/MCP-SERVER.md b/docs/i18n/he/MCP-SERVER.md deleted file mode 100644 index 829acd30b1..0000000000 --- a/docs/i18n/he/MCP-SERVER.md +++ /dev/null @@ -1,87 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/MCP-SERVER.md) - ---- - -# OmniRoute MCP Server Documentation - -> Model Context Protocol server with 16 intelligent tools - -## Installation - -OmniRoute MCP is built-in. Start it with: - -```bash -omniroute --mcp -``` - -Or via the open-sse transport: - -```bash -# HTTP streamable transport (port 20130) -omniroute --dev # MCP auto-starts on /mcp endpoint -``` - -## IDE Configuration - -See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup. - ---- - -## Essential Tools (8) - -| Tool | Description | -| :------------------------------ | :--------------------------------------- | -| `omniroute_get_health` | Gateway health, circuit breakers, uptime | -| `omniroute_list_combos` | All configured combos with models | -| `omniroute_get_combo_metrics` | Performance metrics for a specific combo | -| `omniroute_switch_combo` | Switch active combo by ID/name | -| `omniroute_check_quota` | Quota status per provider or all | -| `omniroute_route_request` | Send a chat completion through OmniRoute | -| `omniroute_cost_report` | Cost analytics for a time period | -| `omniroute_list_models_catalog` | Full model catalog with capabilities | - -## Advanced Tools (8) - -| Tool | Description | -| :--------------------------------- | :---------------------------------------------- | -| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | -| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | -| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | -| `omniroute_test_combo` | Live-test all models in a combo | -| `omniroute_get_provider_metrics` | Detailed metrics for one provider | -| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | -| `omniroute_explain_route` | Explain a past routing decision | -| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | - -## Authentication - -MCP tools are authenticated via API key scopes. Each tool requires specific scopes: - -| Scope | Tools | -| :------------- | :----------------------------------------------- | -| `read:health` | get_health, get_provider_metrics | -| `read:combos` | list_combos, get_combo_metrics | -| `write:combos` | switch_combo | -| `read:quota` | check_quota | -| `write:route` | route_request, simulate_route, test_combo | -| `read:usage` | cost_report, get_session_snapshot, explain_route | -| `write:config` | set_budget_guard, set_resilience_profile | -| `read:models` | list_models_catalog, best_combo_for_task | - -## Audit Logging - -Every tool call is logged to `mcp_tool_audit` with: - -- Tool name, arguments, result -- Duration (ms), success/failure -- API key hash, timestamp - -## Files - -| File | Purpose | -| :------------------------------------------- | :------------------------------------------ | -| `open-sse/mcp-server/server.ts` | MCP server creation + 16 tool registrations | -| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport | -| `open-sse/mcp-server/auth.ts` | API key + scope validation | -| `open-sse/mcp-server/audit.ts` | Tool call audit logging | -| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers | diff --git a/docs/i18n/he/README.md b/docs/i18n/he/README.md index ed321c5417..3590dce8c9 100644 --- a/docs/i18n/he/README.md +++ b/docs/i18n/he/README.md @@ -1,12 +1,12 @@ # ๐Ÿš€ OmniRoute โ€” The Free AI Gateway (ืขื‘ืจื™ืช) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/README.md) --- ### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback. -_Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._ +_Your universal API proxy โ€” one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._ **Chat Completions โ€ข Embeddings โ€ข Image Generation โ€ข Video โ€ข Music โ€ข Audio โ€ข Reranking โ€ข **Web Search** โ€ข MCP Server โ€ข A2A Protocol โ€ข 100% TypeScript** @@ -46,15 +46,17 @@ _Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now wi > - `APP_LOG_FILE_PATH` > - `APP_LOG_MAX_FILE_SIZE` > - `APP_LOG_RETENTION_DAYS` +> - `APP_LOG_MAX_FILES` > - `APP_LOG_LEVEL` > - `APP_LOG_FORMAT` > - `CALL_LOG_RETENTION_DAYS` +> - `CALL_LOG_MAX_ENTRIES` > > For release details and upgrade notes, see the [CHANGELOG](CHANGELOG.md). --- -## ๐Ÿ†• What's New in v3.0.0 +## ๐Ÿ†• What's New > **Upgrading from v2.9.5?** โ€” See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes. @@ -274,7 +276,7 @@ Developers pay $20โ€“200/month for Claude Pro, Codex Pro, or GitHub Copilot. Eve - **Smart 4-Tier Fallback** โ€” If subscription quota runs out, automatically redirects to API Key โ†’ Cheap โ†’ Free with zero manual intervention - **Real-Time Quota Tracking** โ€” Shows token consumption in real-time with reset countdown (5h, daily, weekly) - **Multi-Account Support** โ€” Multiple accounts per provider with auto round-robin โ€” when one runs out, switches to the next -- **Custom Combos** โ€” Customizable fallback chains with 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Custom Combos** โ€” Customizable fallback chains with 9 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random) - **Codex Business Quotas** โ€” Business/Team workspace quota monitoring directly in the dashboard @@ -286,7 +288,7 @@ OpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If **How OmniRoute solves it:** -- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 67+ providers +- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 60+ providers - **Format Translation** โ€” Automatic and transparent: OpenAI โ†” Claude โ†” Gemini โ†” Responses API - **Response Sanitization** โ€” Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+ - **Role Normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI providers; `system` โ†’ `user` for GLM/ERNIE @@ -372,7 +374,7 @@ Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code.. - **CLI Tools Dashboard** โ€” Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline - **GitHub Copilot Config Generator** โ€” Generates `chatLanguageModels.json` for VS Code with bulk model selection - **Onboarding Wizard** โ€” Guided 4-step setup for first-time users -- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 67+ providers +- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 60+ providers @@ -419,7 +421,7 @@ When a call fails, the dev doesn't know if it was a rate limit, expired token, w - **SQLite Proxy Logs** โ€” Persistent logs that survive server restarts - **Translator Playground** โ€” 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time) - **Request Telemetry** โ€” p50/p95/p99 latency + X-Request-Id tracing -- **File-Based Logging with Rotation** โ€” Console interceptor captures everything to JSON log with size-based rotation +- **File-Based Logging with Rotation** โ€” App logs rotate by size, retention days, and archive count; call log artifacts rotate by retention days and file count - **System Info Report** โ€” `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage. @@ -514,7 +516,7 @@ Developers who want all responses in a specific language, with a specific tone, - **System Prompt Injection** โ€” Global prompt applied to all requests - **Thinking Budget Validation** โ€” Reasoning token allocation control per request (passthrough, auto, custom, adaptive) -- **6 Routing Strategies** โ€” Global strategies that determine how requests are distributed +- **9 Routing Strategies** โ€” Global strategies that determine how requests are distributed - **Wildcard Router** โ€” `provider/*` patterns route dynamically to any provider - **Combo Enable/Disable Toggle** โ€” Toggle combos directly from the dashboard - **Provider Toggle** โ€” Enable/disable all connections for a provider with one click @@ -581,7 +583,7 @@ Different clients should have least-privilege access to tool categories. **How OmniRoute solves it:** -- 9 granular MCP scopes for controlled tool access +- 10 granular MCP scopes for controlled tool access - Scope enforcement and visibility in MCP management UI - Safe default posture for operational tooling @@ -1325,19 +1327,19 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. ### ๐Ÿค– Agent & Protocol Operations (v2.0) -| Feature | What It Does | -| ------------------------------------- | -------------------------------------------------------------------------------------------------- | -| ๐Ÿ”ง **MCP Server (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) | -| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | -| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | -| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | -| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | -| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | -| ๐Ÿ” **MCP Scope Enforcement** | 9 granular scope permissions for controlled tool access | -| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | -| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | -| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | -| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | +| Feature | What It Does | +| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| ๐Ÿ”ง **MCP Server (25 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools | +| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | +| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | +| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | +| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | +| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | +| ๐Ÿ” **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access | +| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | +| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | +| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | +| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | ### ๐Ÿง  Routing & Intelligence @@ -1348,7 +1350,7 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. | ๐Ÿ”„ **Format Translation** | OpenAI โ†” Claude โ†” Gemini โ†” Responses with schema-safe conversions | | ๐Ÿ‘ฅ **Multi-Account Support** | Multiple accounts per provider with intelligent selection | | ๐Ÿ”„ **Auto Token Refresh** | OAuth tokens refresh automatically with retry | -| ๐ŸŽจ **Custom Combos** | 6 balancing strategies + fallback chain control | +| ๐ŸŽจ **Custom Combos** | 9 balancing strategies + fallback chain control | | ๐ŸŒ **Wildcard Router** | `provider/*` dynamic routing | | ๐Ÿง  **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits | | ๐Ÿ”€ **Model Aliases** | Built-in + custom model aliasing and migration safety | @@ -1949,6 +1951,7 @@ opencode - Request artifacts are written to `DATA_DIR/call_logs/` as one JSON file per request - Enable pipeline capture from Dashboard โ†’ Logs โ†’ Request Logs if you need detailed per-stage payloads - Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log` +- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed **Connection test shows "Invalid" for OpenAI-compatible providers** diff --git a/docs/i18n/he/RELEASE_CHECKLIST.md b/docs/i18n/he/RELEASE_CHECKLIST.md deleted file mode 100644 index 903e812c3f..0000000000 --- a/docs/i18n/he/RELEASE_CHECKLIST.md +++ /dev/null @@ -1,37 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/RELEASE_CHECKLIST.md) - ---- - -# Release Checklist - -Use this checklist before tagging or publishing a new OmniRoute release. - -## Version and Changelog - -1. Bump `package.json` version (`x.y.z`) in the release branch. -2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: - - `## [x.y.z] โ€” YYYY-MM-DD` -3. Keep `## [Unreleased]` as the first changelog section for upcoming work. -4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. - -## API Docs - -1. Update `docs/openapi.yaml`: - - `info.version` must equal `package.json` version. -2. Validate endpoint examples if API contracts changed. - -## Runtime Docs - -1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. -2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. -3. Update localized docs if source docs changed significantly. - -## Automated Check - -Run the sync guard locally before opening PR: - -```bash -npm run check:docs-sync -``` - -CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/he/SECURITY.md b/docs/i18n/he/SECURITY.md new file mode 100644 index 0000000000..a542414696 --- /dev/null +++ b/docs/i18n/he/SECURITY.md @@ -0,0 +1,179 @@ +# Security Policy (ืขื‘ืจื™ืช) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../SECURITY.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/SECURITY.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/SECURITY.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/SECURITY.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/SECURITY.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/SECURITY.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/SECURITY.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/SECURITY.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/SECURITY.md) + +--- + +## 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 | +| ------- | -------------- | +| 3.4.x | โœ… Active | +| 3.0.x | โœ… Security | +| < 3.0.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 | +| **MCP Scopes** | 10 granular scopes for MCP tool access control | + +### ๐Ÿ›ก๏ธ 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:::` +- 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** | Allowlist/blocklist IP ranges in dashboard | +| **Rate Limiting** | Per-provider rate limits with automatic backoff | +| **Anti-Thundering Herd** | Mutex + per-connection locking prevents cascading 502s | +| **TLS Fingerprint** | Browser-like TLS fingerprint spoofing to reduce bot detection | +| **CLI Fingerprint** | Per-provider header/body ordering to match native CLI signatures | + +### ๐Ÿ”Œ Resilience & Availability + +| 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 `CALL_LOG_RETENTION_DAYS` | +| **No-Log Opt-out** | Per API key `noLog` flag disables request logging | +| **Audit Log** | Administrative actions tracked in `audit_log` table | +| **MCP Audit** | SQLite-backed audit logging for all MCP tool calls | +| **Zod Validation** | All API inputs validated with Zod v4 schemas at module load | + +--- + +## 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 +- Provider constants validated at module load via Zod (`src/shared/validation/providerSchema.ts`) diff --git a/docs/i18n/he/TROUBLESHOOTING.md b/docs/i18n/he/TROUBLESHOOTING.md deleted file mode 100644 index 63c148000a..0000000000 --- a/docs/i18n/he/TROUBLESHOOTING.md +++ /dev/null @@ -1,258 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/TROUBLESHOOTING.md) - ---- - -# Troubleshooting - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/TROUBLESHOOTING.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/TROUBLESHOOTING.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/TROUBLESHOOTING.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/TROUBLESHOOTING.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/TROUBLESHOOTING.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/TROUBLESHOOTING.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/TROUBLESHOOTING.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/TROUBLESHOOTING.md) - -Common problems and solutions for OmniRoute. - ---- - -## Quick Fixes - -| Problem | Solution | -| ----------------------------- | ------------------------------------------------------------------ | -| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | -| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | -| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | -| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | -| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | - ---- - -## Provider Issues - -### "Language model did not provide messages" - -**Cause:** Provider quota exhausted. - -**Fix:** - -1. 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, Qoder) 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}/storage.sqlite` (providers, combos, aliases, keys, settings) -- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` -- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) - ---- - -## Circuit Breaker Issues - -### Provider stuck in OPEN state - -When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. - -**Fix:** - -1. 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 -- **SDK returns raw string instead of object** โ€” Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures -- **GLM/ERNIE rejects `system` role** โ€” Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models -- **`developer` role not recognized** โ€” Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers -- **`json_schema` not working with Gemini** โ€” Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` - ---- - -## Resilience Settings - -### Auto rate-limit not triggering - -- 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. - ---- - -## Optional RAG / LLM failure taxonomy (16 problems) - -Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. - -In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. - -If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: - -- retrieval drift and broken context boundaries -- empty or stale indexes and vector stores -- embedding versus semantic mismatch -- prompt assembly and context window issues -- logic collapse and overconfident answers -- long chain and agent coordination failures -- multi agent memory and role drift -- deployment and bootstrap ordering problems - -The idea is simple: - -1. When you investigate a bad response, capture: - - user task and request - - route or provider combo in OmniRoute - - any RAG context used downstream (retrieved documents, tool calls, etc) -2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` โ€ฆ `No.16`). -3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. -4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. - -Full text and concrete recipes live here (MIT license, text only): - -[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) - -You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. - ---- - -## Still Stuck? - -- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details -- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints -- **Health Dashboard**: Check **Dashboard โ†’ Health** for real-time system status -- **Translator**: Use **Dashboard โ†’ Translator** to debug format issues diff --git a/docs/i18n/he/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/he/VM_DEPLOYMENT_GUIDE.md deleted file mode 100644 index b00b99ddb9..0000000000 --- a/docs/i18n/he/VM_DEPLOYMENT_GUIDE.md +++ /dev/null @@ -1,401 +0,0 @@ -# OmniRoute โ€” ืžื“ืจื™ืš ืคืจื™ืกื” ื‘-VM ืขื Cloudflare - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](../pt-BR/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](../es/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](../fr/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](../it/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](../ru/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](../zh-CN/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](../de/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](../in/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](../th/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](../uk-UA/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](../ar/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](../ja/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](../vi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](../bg/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](../da/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](../fi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](../he/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](../hu/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](../id/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](../ko/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](../ms/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](../nl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](../no/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](../pt/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](../ro/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](../pl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](../sk/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](../sv/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](../phi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](../cs/VM_DEPLOYMENT_GUIDE.md) - -ืžื“ืจื™ืš ืฉืœื ืœื”ืชืงื ื” ื•ื”ื’ื“ืจื” ืฉืœ OmniRoute ื‘-VM (VPS) ืขื ื“ื•ืžื™ื™ืŸ ืžื ื•ื”ืœ ื‘ืืžืฆืขื•ืช Cloudflare. - ---- - -## ื“ืจื™ืฉื•ืช ืžื•ืงื“ืžื•ืช - -| ืคืจื™ื˜ | ืžื™ื ื™ืžื•ื | ืžื•ืžืœืฅ | -| ---------- | ----------------- | ----------------- | -| **ืžืขื‘ื“** | 1 vCPU | 2 vCPU | -| **RAM** | 1 GB | 2 GB | -| **ื“ื™ืกืง** | 10 GB SSD | SSD 25 GB | -| **OS** | ืื•ื‘ื•ื ื˜ื• 22.04 LTS | ืื•ื‘ื•ื ื˜ื• 24.04 LTS | -| **ื“ื•ืžื™ื™ืŸ** | ืจืฉื•ื ื‘-Cloudflare | โ€” | -| **ื“ื•ืงืจ** | Docker Engine 24+ | Docker 27+ | - -**ืกืคืงื™ื ืฉื ื‘ื“ืงื•**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. - ---- - -## 1. ื”ื’ื“ืจ ืืช ื”-VM - -### 1.1 ืฆื•ืจ ืืช ื”ืžื•ืคืข - -ื‘ืกืคืง ื”-VPS ื”ืžื•ืขื“ืฃ ืขืœื™ืš: - -- ื‘ื—ืจ ืื•ื‘ื•ื ื˜ื• 24.04 LTS -- ื‘ื—ืจ ืืช ื”ืชื•ื›ื ื™ืช ื”ืžื™ื ื™ืžืœื™ืช (1 vCPU / 1 GB RAM) -- ื”ื’ื“ืจ ืกื™ืกืžืช ืฉื•ืจืฉ ื—ื–ืงื” ืื• ื”ื’ื“ืจ ืืช ืžืคืชื— SSH -- ืฉื™ืžื• ืœื‘ ืœ-**IP ื”ืฆื™ื‘ื•ืจื™** (ืœืžืฉืœ, `203.0.113.10`) - -### 1.2 ื”ืชื—ื‘ืจ ื‘ืืžืฆืขื•ืช SSH - -```bash -ssh root@203.0.113.10 -``` - -### 1.3 ืขื“ื›ืŸ ืืช ื”ืžืขืจื›ืช - -```bash -apt update && apt upgrade -y -``` - -### 1.4 ื”ืชืงืŸ Docker - -```bash -# Install dependencies -apt install -y ca-certificates curl gnupg - -# Add official Docker repository -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 ื”ืชืงืŸ ืืช nginx - -```bash -apt install -y nginx -``` - -### 1.6 ื”ื’ื“ืจ ื—ื•ืžืช ืืฉ (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 -``` - -> **ื˜ื™ืค**: ืœืื‘ื˜ื—ื” ืžื™ืจื‘ื™ืช, ื”ื’ื‘ืœ ืืช ื”ื™ืฆื™ืื•ืช 80 ื•-443 ืœ-IP ืฉืœ Cloudflare ื‘ืœื‘ื“. ืขื™ื™ืŸ ื‘ืกืขื™ืฃ [Advanced Security](#advanced-security). - ---- - -## 2. ื”ืชืงืŸ ืืช OmniRoute - -### 2.1 ืฆื•ืจ ืกืคืจื™ื™ืช ืชืฆื•ืจื” - -```bash -mkdir -p /opt/omniroute -``` - -### 2.2 ืฆื•ืจ ืงื•ื‘ืฅ ืžืฉืชื ื™ ืกื‘ื™ื‘ื” - -```bash -cat > /opt/omniroute/.env << โ€˜EOFโ€™ -# === Security === -JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY -INITIAL_PASSWORD=YourSecurePassword123! -API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY -STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY -STORAGE_ENCRYPTION_KEY_VERSION=v1 -MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT - -# === 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 (change to your domain) === -BASE_URL=https://llms.seudominio.com -NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com - -# === Cloud Sync (optional) === -# CLOUD_URL=https://cloud.omniroute.online -# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online -EOF -``` - -> โš ๏ธ **ื—ืฉื•ื‘**: ืฆื•ืจ ืžืคืชื—ื•ืช ืกื•ื“ื™ื™ื ื™ื™ื—ื•ื“ื™ื™ื! ื”ืฉืชืžืฉ ื‘-`openssl rand -hex 32` ืขื‘ื•ืจ ื›ืœ ืžืคืชื—. - -### 2.3 ื”ืคืขืœ ืืช ื”ืžื™ื›ืœ - -```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 ื•ื“ื ืฉื”ื•ื ืคื•ืขืœ - -```bash -docker ps | grep omniroute -docker logs omniroute --tail 20 -``` - -ื–ื” ืืžื•ืจ ืœื”ืฆื™ื’: `[DB] SQLite database ready` ื•-`listening on port 20128`. - ---- - -## 3. ื”ื’ื“ืจ ืืช nginx (ืคืจื•ืงืกื™ ื”ืคื•ืš) - -### 3.1 ื™ืฆื™ืจืช ืื™ืฉื•ืจ SSL (ืžืงื•ืจ Cloudflare) - -ื‘ืœื•ื— ื”ืžื—ื•ื•ื ื™ื ืฉืœ Cloudflare: - -1. ืขื‘ื•ืจ ืืœ **SSL/TLS โ†’ ืฉืจืช ืžืงื•ืจ** -2. ืœื—ืฅ ืขืœ **ืฆื•ืจ ืื™ืฉื•ืจ** -3. ืฉืžื•ืจ ืขืœ ื‘ืจื™ืจืช ื”ืžื—ื“ืœ (15 ืฉื ื™ื, \*.yourdomain.com) -4. ื”ืขืชืง ืืช **ืชืขื•ื“ืช ื”ืžืงื•ืจ** ื•ืืช **ื”ืžืคืชื— ื”ืคืจื˜ื™** - -```bash -mkdir -p /etc/nginx/ssl - -# Paste the certificate -nano /etc/nginx/ssl/origin.crt - -# Paste the private key -nano /etc/nginx/ssl/origin.key - -chmod 600 /etc/nginx/ssl/origin.key -``` - -### 3.2 ืชืฆื•ืจืช Nginx - -```bash -cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ -# Default server โ€” blocks direct access via 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.yourdomain.com; # Change to your domain - - 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.yourdomain.com; - return 301 https://$server_name$request_uri; -} -NGINX -``` - -### 3.3 ื”ืคืขืœ ื•ื‘ื“ื•ืง - -```bash -# Remove default configuration -rm -f /etc/nginx/sites-enabled/default - -# Enable OmniRoute -ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute - -# Test and reload -nginx -t && systemctl reload nginx -``` - ---- - -## 4. ื”ื’ื“ืจ ืืช Cloudflare DNS - -### 4.1 ื”ื•ืกืฃ ืจืฉื•ืžืช DNS - -ื‘ืœื•ื— ื”ืžื—ื•ื•ื ื™ื ืฉืœ Cloudflare โ† DNS: - -| ื”ืงืœื“ | ืฉื | ืชื•ื›ืŸ | ืคืจื•ืงืกื™ | -| ---- | ------ | ---------------------- | --------- | -| ื | `llms` | `203.0.113.10` (VM IP) | โœ… ืคืจื•ืงืกื™ | - -### 4.2 ื”ื’ื“ืจ SSL - -ืชื—ืช **SSL/TLS โ† ืกืงื™ืจื” ื›ืœืœื™ืช**: - -- ืžืฆื‘: **ืžืœื (ืงืคื“ื ื™)** - -ืชื—ืช **SSL/TLS โ†’ Edge Certificates**: - -- ื”ืฉืชืžืฉ ืชืžื™ื“ ื‘-HTTPS: โœ… ืคื•ืขืœ -- ื’ืจืกืช TLS ืžื™ื ื™ืžืœื™ืช: TLS 1.2 -- ืฉื›ืชื•ื‘ื™ื ืื•ื˜ื•ืžื˜ื™ื™ื ืฉืœ HTTPS: โœ… ืคื•ืขืœ - -### 4.3 ื‘ื“ื™ืงื” - -```bash -curl -sI https://llms.seudominio.com/health -# Should return HTTP/2 200 -``` - ---- - -## 5. ืชืคืขื•ืœ ื•ืชื—ื–ื•ืงื” - -### ืฉื“ืจื’ ืœื’ืจืกื” ื—ื“ืฉื” - -```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 -``` - -### ื”ืฆื’ ื™ื•ืžื ื™ื - -```bash -docker logs -f omniroute # Real-time stream -docker logs omniroute --tail 50 # Last 50 lines -``` - -### ื’ื™ื‘ื•ื™ ื™ื“ื ื™ ืฉืœ ืžืกื“ ื”ื ืชื•ื ื™ื - -```bash -# Copy data from the volume to the host -docker cp omniroute:/app/data ./backup-$(date +%F) - -# Or compress the entire volume -docker run --rm -v omniroute-data:/data -v $(pwd):/backup \ - alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data -``` - -### ืฉื—ื–ืจ ืžื’ื™ื‘ื•ื™ - -```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. ืื‘ื˜ื—ื” ืžืชืงื“ืžืช - -### ื”ื’ื‘ืœ ืืช nginx ืœื›ืชื•ื‘ื•ืช IP ืฉืœ Cloudflare - -```bash -cat > /etc/nginx/cloudflare-ips.conf << โ€˜CFโ€™ -# Cloudflare IPv4 ranges โ€” update periodically -# 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 -``` - -ื”ื•ืกืฃ ืืช ื”ื“ื‘ืจื™ื ื”ื‘ืื™ื ืœ`nginx.conf` ื‘ืชื•ืš ื”ื‘ืœื•ืง `http {}`: - -```nginx -include /etc/nginx/cloudflare-ips.conf; -``` - -### ื”ืชืงืŸ fail2ban - -```bash -apt install -y fail2ban -systemctl enable fail2ban -systemctl start fail2ban - -# Check status -fail2ban-client status sshd -``` - -### ื—ืกื•ื ื’ื™ืฉื” ื™ืฉื™ืจื” ืœื™ืฆื™ืืช Docker - -```bash -# Prevent direct external access to port 20128 -iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP -iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT - -# Persist the rules -apt install -y iptables-persistent -netfilter-persistent save -``` - ---- - -## 7. ืคืจื™ืกื” ืœ-Cloudflare Workers (ืื•ืคืฆื™ื•ื ืœื™) - -ืœื’ื™ืฉื” ืžืจื—ื•ืง ื“ืจืš Cloudflare Workers (ืžื‘ืœื™ ืœื—ืฉื•ืฃ ื™ืฉื™ืจื•ืช ืืช ื”-VM): - -```bash -# In the local repository -cd omnirouteCloud -npm install -npx wrangler login -npx wrangler deploy -``` - -ืจืื” ืืช ื”ืชื™ืขื•ื“ ื”ืžืœื ื‘-[omnirouteCloud/README.md](../omnirouteCloud/README.md). - ---- - -## ืกื™ื›ื•ื ื™ืฆื™ืื” - -| ื ืžืœ | ืฉื™ืจื•ืช | ื’ื™ืฉื” | -| ----- | ----------- | -------------------------- | -| 22 | SSH | ืฆื™ื‘ื•ืจื™ (ืขื fail2ban) | -| 80 | nginx HTTP | ื”ืคื ื™ื” ืžื—ื“ืฉ โ†’ HTTPS | -| 443 | nginx HTTPS | ื“ืจืš Cloudflare Proxy | -| 20128 | OmniRoute | Localhost ื‘ืœื‘ื“ (ื“ืจืš nginx) | diff --git a/docs/i18n/he/docs/A2A-SERVER.md b/docs/i18n/he/docs/A2A-SERVER.md new file mode 100644 index 0000000000..883b221ebd --- /dev/null +++ b/docs/i18n/he/docs/A2A-SERVER.md @@ -0,0 +1,200 @@ +# OmniRoute A2A Server Documentation (ืขื‘ืจื™ืช) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/A2A-SERVER.md) + +--- + +> Agent-to-Agent Protocol v0.3 โ€” OmniRoute as an intelligent routing agent + +## Agent Discovery + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements. + +--- + +## Authentication + +All `/a2a` requests require an API key via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server, authentication is bypassed. + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Sends a message to a skill and waits for the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a hello world in Python"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "uuid", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "..." }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}} + +: heartbeat 2026-03-03T17:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Available Skills + +| Skill | Description | +| :----------------- | :------------------------------------------------------------------------------------------------------------------------------ | +| `smart-routing` | Routes prompts through OmniRoute's intelligent pipeline. Returns response with routing explanation, cost, and resilience trace. | +| `quota-management` | Answers natural-language queries about provider quotas, suggests free combos, and provides quota rankings. | + +--- + +## Task Lifecycle + +``` +submitted โ†’ working โ†’ completed + โ†’ failed + โ†’ cancelled +``` + +- Tasks expire after 5 minutes (configurable) +- Terminal states: `completed`, `failed`, `cancelled` +- Event log tracks every state transition + +--- + +## Error Codes + +| Code | Meaning | +| :----- | :----------------------------- | +| -32700 | Parse error (invalid JSON) | +| -32600 | Invalid request / Unauthorized | +| -32601 | Method or skill not found | +| -32602 | Invalid params | +| -32603 | Internal error | + +--- + +## Integration Examples + +### Python (requests) + +```python +import requests + +resp = requests.post("http://localhost:20128/a2a", json={ + "jsonrpc": "2.0", "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Hello"}] + } +}, headers={"Authorization": "Bearer YOUR_KEY"}) + +result = resp.json()["result"] +print(result["artifacts"][0]["content"]) +print(result["metadata"]["routing_explanation"]) +``` + +### TypeScript (fetch) + +```typescript +const resp = await fetch("http://localhost:20128/a2a", { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: "Bearer YOUR_KEY", + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "1", + method: "message/send", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Hello" }], + }, + }), +}); +const { result } = await resp.json(); +console.log(result.metadata.routing_explanation); +``` diff --git a/docs/i18n/he/docs/API_REFERENCE.md b/docs/i18n/he/docs/API_REFERENCE.md new file mode 100644 index 0000000000..347d8b6491 --- /dev/null +++ b/docs/i18n/he/docs/API_REFERENCE.md @@ -0,0 +1,465 @@ +# API Reference (ืขื‘ืจื™ืช) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/API_REFERENCE.md) + +--- + +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 | +| `X-Session-Id` | Request | Sticky session key for external session affinity | +| `x_session_id` | Request | Underscore variant also accepted (direct HTTP) | +| `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 | +| `X-OmniRoute-Session-Id` | Response | Effective session ID used by OmniRoute | + +> Nginx note: if you rely on underscore headers (for example `x_session_id`), enable `underscores_in_headers 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/stats + +# Clear all caches +DELETE /api/cache/stats +``` + +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/PATCH | 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 + provider summary (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`) | +| `/api/cache/stats` | 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 | + +### Tunnels + +| Endpoint | Method | Description | +| -------------------------- | ------ | ----------------------------------------------------------------------- | +| `/api/tunnels/cloudflared` | GET | Read Cloudflare Quick Tunnel install/runtime status for the dashboard | +| `/api/tunnels/cloudflared` | POST | Enable or disable the Cloudflare Quick Tunnel (`action=enable/disable`) | + +### 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`. + +### ACP Agents + +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | + +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). + +### Resilience & Rate Limits + +| Endpoint | Method | Description | +| ----------------------- | --------- | ------------------------------- | +| `/api/resilience` | GET/PATCH | 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` diff --git a/docs/i18n/he/docs/ARCHITECTURE.md b/docs/i18n/he/docs/ARCHITECTURE.md new file mode 100644 index 0000000000..06d2ace626 --- /dev/null +++ b/docs/i18n/he/docs/ARCHITECTURE.md @@ -0,0 +1,814 @@ +# OmniRoute Architecture (ืขื‘ืจื™ืช) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/ARCHITECTURE.md) + +--- + +_Last updated: 2026-03-28_ + +## 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 (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developerโ†’system, systemโ†’user) for cross-provider compatibility +- Structured output conversion (json_schema โ†’ Gemini responseSchema) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) +- Global system prompt injection +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout โ†’ budget โ†’ fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) + +Primary runtime model: + +- Next.js 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.) + +## Dashboard Surface (Current) + +Main pages under `src/app/(dashboard)/dashboard/`: + +- `/dashboard` โ€” quick start + provider overview +- `/dashboard/endpoint` โ€” endpoint proxy + MCP + A2A + API endpoint tabs +- `/dashboard/providers` โ€” provider connections and credentials +- `/dashboard/combos` โ€” combo strategies, templates, model routing rules +- `/dashboard/costs` โ€” cost aggregation and pricing visibility +- `/dashboard/analytics` โ€” usage analytics and evaluations +- `/dashboard/limits` โ€” quota/rate controls +- `/dashboard/cli-tools` โ€” CLI onboarding, runtime detection, config generation +- `/dashboard/agents` โ€” detected ACP agents + custom agent registration +- `/dashboard/media` โ€” image/video/music playground +- `/dashboard/search-tools` โ€” search provider testing and history +- `/dashboard/health` โ€” uptime, circuit breakers, rate limits +- `/dashboard/logs` โ€” request/proxy/audit/console logs +- `/dashboard/settings` โ€” system settings tabs (general, routing, combo defaults, etc.) +- `/dashboard/api-manager` โ€” API key lifecycle and model permissions + +## 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[(storage.sqlite)] + UDB[(usage tables + log artifacts)] + end + + subgraph Upstreams[Upstream Providers] + P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/Qoder/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/route.ts` (GET) +- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- OAuth: `src/app/api/oauth/*` +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` +- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI tooling helpers: `src/app/api/cli-tools/*` +- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) +- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) โ€” provider profiles, circuit breaker, rate limit state +- Resilience reset: `src/app/api/resilience/reset` (POST) โ€” reset breakers + cooldowns +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) +- Telemetry: `src/app/api/telemetry/summary` (GET) +- Budget: `src/app/api/usage/budget` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Policies: `src/app/api/policies` (GET/POST) + +## 2) SSE + 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` +- Response sanitization: `open-sse/handlers/responseSanitizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.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`, `qoder.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 (SQLite): + +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** + +Usage persistence: + +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present + +Domain State DB (SQLite): + +- `src/lib/db/domainState.ts` โ€” CRUD operations 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`, `src/shared/services/modelSyncScheduler.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Periodic task: `src/shared/services/modelSyncScheduler.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. Combo routing adds one extra guard: provider-scoped 400s such as upstream content-block and role-validation failures are treated as model-local failures so later combo targets can still run. + +## 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: + +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` + +## Deployment Topology + +```mermaid +flowchart LR + 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[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] + end + + subgraph External[External Services] + Providers[AI Providers] + SyncCloud[Cloud Sync Service] + end + + CLI --> Next + Browser --> Next + Next --> Core + Next --> MainDB + Core --> MainDB + Core --> UsageDB + Core --> Providers + Next --> SyncCloud +``` + +## Module Mapping (Decision-Critical) + +### Route and API Modules + +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle +- `src/app/api/models/alias`: alias management +- `src/app/api/combos*`: fallback combo management +- `src/app/api/pricing`: pricing overrides for cost calculation +- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers +- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) +- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) +- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) +- `src/app/api/sessions`: active session listing (GET) +- `src/app/api/rate-limits`: per-account rate limit status (GET) + +### Routing and Execution Core + +- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior + +### Translation Registry and Format Converters + +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` +- Format constants: `open-sse/translator/formats.ts` + +### Persistence + +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables + +## Provider Executor Coverage (Strategy Pattern) + +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. + +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, Qoder, 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 | +| Qoder | openai | OAuth (Basic) | โœ… | โœ… | โœ… | โš ๏ธ Per request | +| OpenRouter | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| GLM/Kimi/MiniMax | claude | API Key | โœ… | โœ… | โŒ | โŒ | +| DeepSeek | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Groq | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| xAI (Grok) | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Mistral | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Perplexity | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Together AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Fireworks AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Cerebras | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Cohere | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| NVIDIA NIM | openai | API Key | โœ… | โœ… | โŒ | โŒ | + +## Format Translation Coverage + +Detected source formats include: + +- `openai` +- `openai-responses` +- `claude` +- `gemini` + +Target formats include: + +- OpenAI chat/Responses +- Claude +- Gemini/Gemini-CLI/Antigravity envelope +- Kiro +- Cursor + +Translations use **OpenAI as the hub format** โ€” all conversions go through OpenAI as intermediate: + +``` +Source Format โ†’ OpenAI (hub) โ†’ Target Format +``` + +Translations are selected dynamically based on source payload shape and provider target format. + +Additional processing layers in the translation pipeline: + +- **Response sanitization** โ€” Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI targets; merges `system` โ†’ `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** โ€” Parses `...` blocks from content into `reasoning_content` field +- **Structured output** โ€” Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` + +## Supported API Endpoints + +| 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` | Provider Models | Provider model metadata backing custom and managed available models | + +## 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 `/logs//` 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 + +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON โ†’ SQLite migration compatibility path + +## Observability and Operational Signals + +Runtime visibility sources: + +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- four-stage detailed payload captures in SQLite (`request_detail_logs`) when `settings.detailed_logs_enabled=true` +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption + +Detailed request payload capture stores up to four JSON payload stages per routed call: + +- raw request received from the client +- translated request actually sent upstream +- provider response reconstructed as JSON; streamed responses are compacted to the final summary plus stream metadata +- final client response returned by OmniRoute; streamed responses are stored in the same compact summary form + +## Security-Sensitive Boundaries + +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics + +## Environment and Runtime Matrix + +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` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). + +## Operational Verification Checklist + +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: +- `GET /api/settings` +- `GET /api/v1/models` +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/he/docs/AUTO-COMBO.md b/docs/i18n/he/docs/AUTO-COMBO.md new file mode 100644 index 0000000000..d5979dc8db --- /dev/null +++ b/docs/i18n/he/docs/AUTO-COMBO.md @@ -0,0 +1,67 @@ +# OmniRoute Auto-Combo Engine (ืขื‘ืจื™ืช) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/AUTO-COMBO.md) + +--- + +> Self-managing model chains with adaptive scoring + +## How It Works + +The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**: + +| Factor | Weight | Description | +| :--------- | :----- | :---------------------------------------------- | +| Quota | 0.20 | Remaining capacity [0..1] | +| Health | 0.25 | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 | +| CostInv | 0.20 | Inverse cost (cheaper = higher score) | +| LatencyInv | 0.15 | Inverse p95 latency (faster = higher) | +| TaskFit | 0.10 | Model ร— task type fitness score | +| Stability | 0.10 | Low variance in latency/errors | + +## Mode Packs + +| Pack | Focus | Key Weight | +| :---------------------- | :----------- | :--------------- | +| ๐Ÿš€ **Ship Fast** | Speed | latencyInv: 0.35 | +| ๐Ÿ’ฐ **Cost Saver** | Economy | costInv: 0.40 | +| ๐ŸŽฏ **Quality First** | Best model | taskFit: 0.40 | +| ๐Ÿ“ก **Offline Friendly** | Availability | quota: 0.40 | + +## Self-Healing + +- **Temporary exclusion**: Score < 0.2 โ†’ excluded for 5 min (progressive backoff, max 30 min) +- **Circuit breaker awareness**: OPEN โ†’ auto-excluded; HALF_OPEN โ†’ probe requests +- **Incident mode**: >50% OPEN โ†’ disable exploration, maximize stability +- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout + +## Bandit Exploration + +5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode. + +## API + +```bash +# Create auto-combo +curl -X POST http://localhost:20128/api/combos/auto \ + -H "Content-Type: application/json" \ + -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}' + +# List auto-combos +curl http://localhost:20128/api/combos/auto +``` + +## Task Fitness + +30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` โ†’ high coding score). + +## Files + +| File | Purpose | +| :------------------------------------------- | :------------------------------------ | +| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization | +| `open-sse/services/autoCombo/taskFitness.ts` | Model ร— task fitness lookup | +| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap | +| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode | +| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles | +| `src/app/api/combos/auto/route.ts` | REST API | diff --git a/docs/i18n/he/docs/CLI-TOOLS.md b/docs/i18n/he/docs/CLI-TOOLS.md new file mode 100644 index 0000000000..b8416f0dbc --- /dev/null +++ b/docs/i18n/he/docs/CLI-TOOLS.md @@ -0,0 +1,348 @@ +# CLI Tools Setup Guide โ€” OmniRoute (ืขื‘ืจื™ืช) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CLI-TOOLS.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CLI-TOOLS.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CLI-TOOLS.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CLI-TOOLS.md) + +--- + +This guide explains how to install and configure all supported AI coding CLI tools +to use **OmniRoute** as the unified backend, giving you centralized key management, +cost tracking, model switching, and request logging across every tool. + +--- + +## How It Works + +``` +Claude / Codex / OpenCode / Cline / KiloCode / Continue / Kiro / Cursor / Copilot + โ”‚ + โ–ผ (all point to OmniRoute) + http://YOUR_SERVER:20128/v1 + โ”‚ + โ–ผ (OmniRoute routes to the right provider) + Anthropic / OpenAI / Gemini / DeepSeek / Groq / Mistral / ... +``` + +**Benefits:** + +- One API key to manage all tools +- Cost tracking across all CLIs in the dashboard +- Model switching without reconfiguring every tool +- Works locally and on remote servers (VPS) + +--- + +## Supported Tools (Dashboard Source of Truth) + +The dashboard cards in `/dashboard/cli-tools` are generated from `src/shared/constants/cliTools.ts`. +Current list (v3.0.0-rc.16): + +| Tool | ID | Command | Setup Mode | Install Method | +| ------------------ | ------------- | ---------- | ---------- | -------------- | +| **Claude Code** | `claude` | `claude` | env | npm | +| **OpenAI Codex** | `codex` | `codex` | custom | npm | +| **Factory Droid** | `droid` | `droid` | custom | bundled/CLI | +| **OpenClaw** | `openclaw` | `openclaw` | custom | bundled/CLI | +| **Cursor** | `cursor` | app | guide | desktop app | +| **Cline** | `cline` | `cline` | custom | npm | +| **Kilo Code** | `kilo` | `kilocode` | custom | npm | +| **Continue** | `continue` | extension | guide | VS Code | +| **Antigravity** | `antigravity` | internal | mitm | OmniRoute | +| **GitHub Copilot** | `copilot` | extension | custom | VS Code | +| **OpenCode** | `opencode` | `opencode` | guide | npm | +| **Kiro AI** | `kiro` | app/cli | mitm | desktop/CLI | + +### CLI fingerprint sync (Agents + Settings) + +`/dashboard/agents` and `Settings > CLI Fingerprint` use `src/shared/constants/cliCompatProviders.ts`. +This keeps provider IDs aligned with CLI cards and legacy IDs. + +| CLI ID | Fingerprint Provider ID | +| ---------------------------------------------------------------------------------------------------- | ----------------------- | +| `kilo` | `kilocode` | +| `copilot` | `github` | +| `claude` / `codex` / `antigravity` / `kiro` / `cursor` / `cline` / `opencode` / `droid` / `openclaw` | same ID | + +Legacy IDs still accepted for compatibility: `copilot`, `kimi-coding`, `qwen`. + +--- + +## Step 1 โ€” Get an OmniRoute API Key + +1. Open the OmniRoute dashboard โ†’ **API Manager** (`/dashboard/api-manager`) +2. Click **Create API Key** +3. Give it a name (e.g. `cli-tools`) and select all permissions +4. Copy the key โ€” you'll need it for every CLI below + +> Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` + +--- + +## Step 2 โ€” Install CLI Tools + +All npm-based tools require Node.js 18+: + +```bash +# Claude Code (Anthropic) +npm install -g @anthropic-ai/claude-code + +# OpenAI Codex +npm install -g @openai/codex + +# OpenCode +npm install -g opencode-ai + +# Cline +npm install -g cline + +# KiloCode +npm install -g kilocode + +# Kiro CLI (Amazon โ€” requires curl + unzip) +apt-get install -y unzip # on Debian/Ubuntu +curl -fsSL https://cli.kiro.dev/install | bash +export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc +``` + +**Verify:** + +```bash +claude --version # 2.x.x +codex --version # 0.x.x +opencode --version # x.x.x +cline --version # 2.x.x +kilocode --version # x.x.x (or: kilo --version) +kiro-cli --version # 1.x.x +``` + +--- + +## Step 3 โ€” Set Global Environment Variables + +Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`: + +```bash +# OmniRoute Universal Endpoint +export OPENAI_BASE_URL="http://localhost:20128/v1" +export OPENAI_API_KEY="sk-your-omniroute-key" +export ANTHROPIC_BASE_URL="http://localhost:20128/v1" +export ANTHROPIC_API_KEY="sk-your-omniroute-key" +export GEMINI_BASE_URL="http://localhost:20128/v1" +export GEMINI_API_KEY="sk-your-omniroute-key" +``` + +> For a **remote server** replace `localhost:20128` with the server IP or domain, +> e.g. `http://192.168.0.15:20128`. + +--- + +## Step 4 โ€” Configure Each Tool + +### Claude Code + +```bash +# Via CLI: +claude config set --global api-base-url http://localhost:20128/v1 + +# Or create ~/.claude/settings.json: +mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF +{ + "apiBaseUrl": "http://localhost:20128/v1", + "apiKey": "sk-your-omniroute-key" +} +EOF +``` + +**Test:** `claude "say hello"` + +--- + +### OpenAI Codex + +```bash +mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF +model: auto +apiKey: sk-your-omniroute-key +apiBaseUrl: http://localhost:20128/v1 +EOF +``` + +**Test:** `codex "what is 2+2?"` + +--- + +### OpenCode + +```bash +mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF +[provider.openai] +base_url = "http://localhost:20128/v1" +api_key = "sk-your-omniroute-key" +EOF +``` + +**Test:** `opencode` + +--- + +### Cline (CLI or VS Code) + +**CLI mode:** + +```bash +mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF +{ + "apiProvider": "openai", + "openAiBaseUrl": "http://localhost:20128/v1", + "openAiApiKey": "sk-your-omniroute-key" +} +EOF +``` + +**VS Code mode:** +Cline extension settings โ†’ API Provider: `OpenAI Compatible` โ†’ Base URL: `http://localhost:20128/v1` + +Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ Cline โ†’ Apply Config**. + +--- + +### KiloCode (CLI or VS Code) + +**CLI mode:** + +```bash +kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key +``` + +**VS Code settings:** + +```json +{ + "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", + "kilo-code.apiKey": "sk-your-omniroute-key" +} +``` + +Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ KiloCode โ†’ Apply Config**. + +--- + +### Continue (VS Code Extension) + +Edit `~/.continue/config.yaml`: + +```yaml +models: + - name: OmniRoute + provider: openai + model: auto + apiBase: http://localhost:20128/v1 + apiKey: sk-your-omniroute-key + default: true +``` + +Restart VS Code after editing. + +--- + +### Kiro CLI (Amazon) + +```bash +# Login to your AWS/Kiro account: +kiro-cli login + +# The CLI uses its own auth โ€” OmniRoute is not needed as backend for Kiro CLI itself. +# Use kiro-cli alongside OmniRoute for other tools. +kiro-cli status +``` + +--- + +### Cursor (Desktop App) + +> **Note:** Cursor routes requests through its cloud. For OmniRoute integration, +> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL. + +Via GUI: **Settings โ†’ Models โ†’ OpenAI API Key** + +- Base URL: `https://your-domain.com/v1` +- API Key: your OmniRoute key + +--- + +## Dashboard Auto-Configuration + +The OmniRoute dashboard automates configuration for most tools: + +1. Go to `http://localhost:20128/dashboard/cli-tools` +2. Expand any tool card +3. Select your API key from the dropdown +4. Click **Apply Config** (if tool is detected as installed) +5. Or copy the generated config snippet manually + +--- + +## Built-in Agents: Droid & OpenClaw + +**Droid** and **OpenClaw** are AI agents built directly into OmniRoute โ€” no installation needed. +They run as internal routes and use OmniRoute's model routing automatically. + +- Access: `http://localhost:20128/dashboard/agents` +- Configure: same combos and providers as all other tools +- No API key or CLI install required + +--- + +## Available API Endpoints + +| Endpoint | Description | Use For | +| -------------------------- | ----------------------------- | --------------------------- | +| `/v1/chat/completions` | Standard chat (all providers) | All modern tools | +| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows | +| `/v1/completions` | Legacy text completions | Older tools using `prompt:` | +| `/v1/embeddings` | Text embeddings | RAG, search | +| `/v1/images/generations` | Image generation | DALL-E, Flux, etc. | +| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS | +| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI | + +--- + +## ืคืชืจื•ืŸ ื‘ืขื™ื•ืช + +| Error | Cause | Fix | +| ------------------------- | ----------------------- | ------------------------------------------ | +| `Connection refused` | OmniRoute not running | `pm2 start omniroute` | +| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` | +| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` | +| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` | +| CLI shows "not installed" | Binary not in PATH | Check `which ` | +| `kiro-cli: not found` | Not in PATH | `export PATH="$HOME/.local/bin:$PATH"` | + +--- + +## Quick Setup Script (One Command) + +```bash +# Install all CLIs and configure for OmniRoute (replace with your key and server URL) +OMNIROUTE_URL="http://localhost:20128/v1" +OMNIROUTE_KEY="sk-your-omniroute-key" + +npm install -g @anthropic-ai/claude-code @openai/codex opencode-ai cline kilocode + +# Kiro CLI +apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash + +# Write configs +mkdir -p ~/.claude ~/.codex ~/.config/opencode ~/.continue + +cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" +cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" +cat >> ~/.bashrc << EOF +export OPENAI_BASE_URL="$OMNIROUTE_URL" +export OPENAI_API_KEY="$OMNIROUTE_KEY" +export ANTHROPIC_BASE_URL="$OMNIROUTE_URL" +export ANTHROPIC_API_KEY="$OMNIROUTE_KEY" +EOF + +source ~/.bashrc +echo "โœ… All CLIs installed and configured for OmniRoute" +``` diff --git a/docs/i18n/he/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/he/docs/CODEBASE_DOCUMENTATION.md new file mode 100644 index 0000000000..8d47892964 --- /dev/null +++ b/docs/i18n/he/docs/CODEBASE_DOCUMENTATION.md @@ -0,0 +1,591 @@ +# omniroute โ€” Codebase Documentation (ืขื‘ืจื™ืช) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CODEBASE_DOCUMENTATION.md) + +--- + +> 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
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, Qoder, 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. + +#### ืืจื›ื™ื˜ืงื˜ื•ืจื” + +```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 | +| Qoder | 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"] +``` diff --git a/docs/i18n/he/docs/COVERAGE_PLAN.md b/docs/i18n/he/docs/COVERAGE_PLAN.md new file mode 100644 index 0000000000..ae171638ef --- /dev/null +++ b/docs/i18n/he/docs/COVERAGE_PLAN.md @@ -0,0 +1,170 @@ +# Test Coverage Plan (ืขื‘ืจื™ืช) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/COVERAGE_PLAN.md) + +--- + +Last updated: 2026-03-28 + +## Baseline + +There are multiple coverage numbers depending on how the report is computed. For planning, only one of them is useful. + +| Metric | Scope | Statements / Lines | Branches | Functions | Notes | +| -------------------- | ----------------------------------------------------- | -----------------: | -------: | --------: | --------------------------------------------------- | +| Legacy | Old `npm run test:coverage` | 79.42% | 75.15% | 67.94% | Inflated: counts test files and excludes `open-sse` | +| Diagnostic | Source-only, excluding tests and excluding `open-sse` | 68.16% | 63.55% | 64.06% | Useful only to isolate `src/**` | +| Recommended baseline | Source-only, excluding tests and including `open-sse` | 56.95% | 66.05% | 57.80% | This is the project-wide baseline to improve | + +The recommended baseline is the number to optimize against. + +## Rules + +- Coverage targets apply to source files, not to `tests/**`. +- `open-sse/**` is part of the product and must remain in scope. +- New code should not reduce coverage in touched areas. +- Prefer testing behavior and branch outcomes over implementation details. +- Prefer temp SQLite databases and small fixtures over broad mocks for `src/lib/db/**`. + +## Current command set + +- `npm run test:coverage` + - Main source coverage gate for the unit test suite + - Generates `text-summary`, `html`, `json-summary`, and `lcov` +- `npm run coverage:report` + - Detailed file-by-file report from the latest run +- `npm run test:coverage:legacy` + - Historical comparison only + +## Milestones + +| Phase | Target | Focus | +| ------- | ---------------------: | ------------------------------------------------- | +| Phase 1 | 60% statements / lines | Quick wins and low-risk utility coverage | +| Phase 2 | 65% statements / lines | DB and route foundations | +| Phase 3 | 70% statements / lines | Provider validation and usage analytics | +| Phase 4 | 75% statements / lines | `open-sse` translators and helpers | +| Phase 5 | 80% statements / lines | `open-sse` handlers and executor branches | +| Phase 6 | 85% statements / lines | Harder edge cases, branch debt, regression suites | +| Phase 7 | 90% statements / lines | Final sweep, gap closure, strict ratchet | + +Branches and functions should ratchet upward with each phase, but the primary hard target is statements / lines. + +## Priority hotspots + +These files or areas offer the best return for the next phases: + +1. `open-sse/handlers` + - `chatCore.ts` at 7.57% + - Overall directory at 29.07% +2. `open-sse/translator/request` + - Overall directory at 36.39% + - Many translators are still near single-digit coverage +3. `open-sse/translator/response` + - Overall directory at 8.07% +4. `open-sse/executors` + - Overall directory at 36.62% +5. `src/lib/db` + - `models.ts` at 20.66% + - `registeredKeys.ts` at 34.46% + - `modelComboMappings.ts` at 36.25% + - `settings.ts` at 46.40% + - `webhooks.ts` at 33.33% +6. `src/lib/usage` + - `usageHistory.ts` at 21.12% + - `usageStats.ts` at 9.56% + - `costCalculator.ts` at 30.00% +7. `src/lib/providers` + - `validation.ts` at 41.16% +8. Low-risk utility and API files for early gains + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/api/errorResponse.ts` + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +## Execution checklist + +### Phase 1: 56.95% -> 60% + +- [x] Fix coverage metric so it reflects source code instead of test files +- [x] Keep a legacy coverage script for comparison +- [x] Record the baseline and hotspots in-repo +- [ ] Add focused tests for low-risk utilities: + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/fetchTimeout.ts` + - `src/lib/api/errorResponse.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/display/names.ts` +- [ ] Add route tests for: + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +### Phase 2: 60% -> 65% + +- [ ] Add DB-backed tests for: + - `src/lib/db/modelComboMappings.ts` + - `src/lib/db/settings.ts` + - `src/lib/db/registeredKeys.ts` +- [ ] Cover branch behavior in: + - `src/lib/providers/validation.ts` + - `src/app/api/v1/embeddings/route.ts` + - `src/app/api/v1/moderations/route.ts` + +### Phase 3: 65% -> 70% + +- [ ] Add usage analytics tests for: + - `src/lib/usage/usageHistory.ts` + - `src/lib/usage/usageStats.ts` + - `src/lib/usage/costCalculator.ts` +- [ ] Expand route coverage for proxy management and settings branches + +### Phase 4: 70% -> 75% + +- [ ] Cover translator helpers and central translation paths: + - `open-sse/translator/index.ts` + - `open-sse/translator/helpers/*` + - `open-sse/translator/request/*` + - `open-sse/translator/response/*` + +### Phase 5: 75% -> 80% + +- [ ] Add handler-level tests for: + - `open-sse/handlers/chatCore.ts` + - `open-sse/handlers/responsesHandler.js` + - `open-sse/handlers/imageGeneration.js` + - `open-sse/handlers/embeddings.js` +- [ ] Add executor branch coverage for provider-specific auth, retries, and endpoint overrides + +### Phase 6: 80% -> 85% + +- [ ] Merge more edge-case suites into the main coverage path +- [ ] Increase function coverage for DB modules with weak constructor/helper coverage +- [ ] Close branch gaps in `settings.ts`, `registeredKeys.ts`, `validation.ts`, and translator helpers + +### Phase 7: 85% -> 90% + +- [ ] Treat the remaining low-coverage files as blockers +- [ ] Add regression tests for every uncovered production bug fixed during the push to 90% +- [ ] Raise the coverage gate in CI only after the local baseline is stable for at least two consecutive runs + +## Ratchet policy + +Update `npm run test:coverage` thresholds only after the project actually exceeds the next milestone with a comfortable buffer. + +Recommended ratchet sequence: + +1. 55/60/55 +2. 60/62/58 +3. 65/64/62 +4. 70/66/66 +5. 75/70/72 +6. 80/75/78 +7. 85/80/84 +8. 90/85/88 + +Order is `statements-lines / branches / functions`. + +## Known gap + +The current coverage command measures the main Node unit suite and includes source reached from it, including `open-sse`. It does not yet merge Vitest coverage into a single unified report. That merge is worth doing later, but it is not a blocker for starting the 60% -> 80% climb. diff --git a/docs/i18n/he/docs/FEATURES.md b/docs/i18n/he/docs/FEATURES.md index 3eeee0d0b3..7049741023 100644 --- a/docs/i18n/he/docs/FEATURES.md +++ b/docs/i18n/he/docs/FEATURES.md @@ -1,6 +1,6 @@ # OmniRoute โ€” Dashboard Features Gallery (ืขื‘ืจื™ืช) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/FEATURES.md) --- @@ -10,7 +10,7 @@ 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). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. ![Providers Dashboard](screenshots/01-providers.png) diff --git a/docs/i18n/he/docs/MCP-SERVER.md b/docs/i18n/he/docs/MCP-SERVER.md new file mode 100644 index 0000000000..58c3b31c6a --- /dev/null +++ b/docs/i18n/he/docs/MCP-SERVER.md @@ -0,0 +1,87 @@ +# OmniRoute MCP Server Documentation (ืขื‘ืจื™ืช) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/MCP-SERVER.md) + +--- + +> Model Context Protocol server with 16 intelligent tools + +## ื”ืชืงื ื” + +OmniRoute MCP is built-in. Start it with: + +```bash +omniroute --mcp +``` + +Or via the open-sse transport: + +```bash +# HTTP streamable transport (port 20130) +omniroute --dev # MCP auto-starts on /mcp endpoint +``` + +## IDE Configuration + +See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup. + +--- + +## Essential Tools (8) + +| Tool | Description | +| :------------------------------ | :--------------------------------------- | +| `omniroute_get_health` | Gateway health, circuit breakers, uptime | +| `omniroute_list_combos` | All configured combos with models | +| `omniroute_get_combo_metrics` | Performance metrics for a specific combo | +| `omniroute_switch_combo` | Switch active combo by ID/name | +| `omniroute_check_quota` | Quota status per provider or all | +| `omniroute_route_request` | Send a chat completion through OmniRoute | +| `omniroute_cost_report` | Cost analytics for a time period | +| `omniroute_list_models_catalog` | Full model catalog with capabilities | + +## Advanced Tools (8) + +| Tool | Description | +| :--------------------------------- | :---------------------------------------------------------- | +| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | +| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | +| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | +| `omniroute_test_combo` | Live-test all models in a combo via a real upstream request | +| `omniroute_get_provider_metrics` | Detailed metrics for one provider | +| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | +| `omniroute_explain_route` | Explain a past routing decision | +| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | + +## Authentication + +MCP tools are authenticated via API key scopes. Each tool requires specific scopes: + +| Scope | Tools | +| :------------- | :----------------------------------------------- | +| `read:health` | get_health, get_provider_metrics | +| `read:combos` | list_combos, get_combo_metrics | +| `write:combos` | switch_combo | +| `read:quota` | check_quota | +| `write:route` | route_request, simulate_route, test_combo | +| `read:usage` | cost_report, get_session_snapshot, explain_route | +| `write:config` | set_budget_guard, set_resilience_profile | +| `read:models` | list_models_catalog, best_combo_for_task | + +## Audit Logging + +Every tool call is logged to `mcp_tool_audit` with: + +- Tool name, arguments, result +- Duration (ms), success/failure +- API key hash, timestamp + +## Files + +| File | Purpose | +| :------------------------------------------- | :------------------------------------------ | +| `open-sse/mcp-server/server.ts` | MCP server creation + 16 tool registrations | +| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport | +| `open-sse/mcp-server/auth.ts` | API key + scope validation | +| `open-sse/mcp-server/audit.ts` | Tool call audit logging | +| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers | diff --git a/docs/i18n/he/docs/RELEASE_CHECKLIST.md b/docs/i18n/he/docs/RELEASE_CHECKLIST.md new file mode 100644 index 0000000000..5c707d543c --- /dev/null +++ b/docs/i18n/he/docs/RELEASE_CHECKLIST.md @@ -0,0 +1,37 @@ +# Release Checklist (ืขื‘ืจื™ืช) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/RELEASE_CHECKLIST.md) + +--- + +Use this checklist before tagging or publishing a new OmniRoute release. + +## Version and Changelog + +1. Bump `package.json` version (`x.y.z`) in the release branch. +2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: + - `## [x.y.z] โ€” YYYY-MM-DD` +3. Keep `## [Unreleased]` as the first changelog section for upcoming work. +4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. + +## API Docs + +1. Update `docs/openapi.yaml`: + - `info.version` must equal `package.json` version. +2. Validate endpoint examples if API contracts changed. + +## Runtime Docs + +1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. +2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. +3. Update localized docs if source docs changed significantly. + +## Automated Check + +Run the sync guard locally before opening PR: + +```bash +npm run check:docs-sync +``` + +CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/he/docs/TROUBLESHOOTING.md b/docs/i18n/he/docs/TROUBLESHOOTING.md new file mode 100644 index 0000000000..2476cbfa84 --- /dev/null +++ b/docs/i18n/he/docs/TROUBLESHOOTING.md @@ -0,0 +1,256 @@ +# Troubleshooting (ืขื‘ืจื™ืช) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/TROUBLESHOOTING.md) + +--- + +Common problems and solutions for OmniRoute. + +--- + +## Quick Fixes + +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | + +--- + +## Provider Issues + +### "Language model did not provide messages" + +**Cause:** Provider quota exhausted. + +**Fix:** + +1. 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, Qoder) 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}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) + +--- + +## Circuit Breaker Issues + +### Provider stuck in OPEN state + +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. + +**Fix:** + +1. 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 +- **SDK returns raw string instead of object** โ€” Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** โ€” Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** โ€” Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** โ€” Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` + +--- + +## Resilience Settings + +### Auto rate-limit not triggering + +- 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. + +--- + +## Optional RAG / LLM failure taxonomy (16 problems) + +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` โ€ฆ `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard โ†’ Health** for real-time system status +- **Translator**: Use **Dashboard โ†’ Translator** to debug format issues diff --git a/docs/i18n/he/USER_GUIDE.md b/docs/i18n/he/docs/USER_GUIDE.md similarity index 82% rename from docs/i18n/he/USER_GUIDE.md rename to docs/i18n/he/docs/USER_GUIDE.md index ebe3d7f53f..7a8885006f 100644 --- a/docs/i18n/he/USER_GUIDE.md +++ b/docs/i18n/he/docs/USER_GUIDE.md @@ -1,8 +1,6 @@ # User Guide (ืขื‘ืจื™ืช) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/USER_GUIDE.md) - -> ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/USER_GUIDE.md) --- @@ -320,7 +318,7 @@ Model: cc/claude-opus-4-6 --- -## ๐Ÿš€ Deployment +## ืคืจื™ืกื” ### Global npm install (Recommended) @@ -511,23 +509,26 @@ post_install() { ### Environment Variables -| Variable | Default | Description | -| ------------------------- | ------------------------------------ | ------------------------------------------------------- | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | -| `INITIAL_PASSWORD` | `123456` | First login password | -| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | -| `PORT` | framework default | Service port (`20128` in examples) | -| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | -| `NODE_ENV` | runtime default | Set `production` for deploy | -| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | -| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | -| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | -| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | -| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | -| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | -| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | -| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | +| 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/*` | +| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand | +| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | For the full environment variable reference, see the [README](../README.md). @@ -598,6 +599,11 @@ curl -X POST http://localhost:20128/api/provider-models \ Or use Dashboard: **Providers โ†’ [Provider] โ†’ Custom Models**. +Notes: + +- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers. +- The **Custom Models** section is intended for providers that do not expose managed available-model imports. + ### Dedicated Provider Routes Route requests directly to a specific provider with model validation: @@ -642,6 +648,14 @@ Returns models grouped by provider with types (`chat`, `embedding`, `image`). - Automatic background sync with timeout + fail-fast - Prefer server-side `BASE_URL`/`CLOUD_URL` in production +### Cloudflare Quick Tunnel + +- Available in **Dashboard โ†’ Endpoints** for Docker and other self-hosted deployments +- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint +- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary +- Tunnel URLs are ephemeral and change every time you stop/start the tunnel +- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download + ### LLM Gateway Intelligence (Phase 9) - **Semantic Cache** โ€” Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) @@ -757,11 +771,11 @@ OmniRoute implements provider-level resilience with four components: 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 | +| 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 unless `DISABLE_SQLITE_AUTO_BACKUP=true` | ```bash # API: Export database @@ -787,10 +801,11 @@ curl -X POST http://localhost:20128/api/db-backups/import \ ### Settings Dashboard -The settings page is organized into 5 tabs for easy navigation: +The settings page is organized into 6 tabs for easy navigation: | Tab | Contents | | -------------- | ---------------------------------------------------------------------------------------------- | +| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility | | **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | | **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | | **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | diff --git a/docs/i18n/he/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/he/docs/VM_DEPLOYMENT_GUIDE.md new file mode 100644 index 0000000000..87d3746956 --- /dev/null +++ b/docs/i18n/he/docs/VM_DEPLOYMENT_GUIDE.md @@ -0,0 +1,403 @@ +# OmniRoute โ€” Deployment Guide on VM with Cloudflare (ืขื‘ืจื™ืช) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/VM_DEPLOYMENT_GUIDE.md) + +--- + +Complete guide to install and configure OmniRoute on a VM (VPS) with domain managed via Cloudflare. + +--- + +## Prerequisites + +| Item | Minimum | Recommended | +| ---------- | ------------------------ | ---------------- | +| **CPU** | 1 vCPU | 2 vCPU | +| **RAM** | 1 GB | 2 GB | +| **Disk** | 10 GB SSD | 25 GB SSD | +| **OS** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS | +| **Domain** | Registered on Cloudflare | โ€” | +| **Docker** | Docker Engine 24+ | Docker 27+ | + +**Tested providers**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. + +--- + +## 1. Configure the VM + +### 1.1 Create the instance + +On your preferred VPS provider: + +- Choose Ubuntu 24.04 LTS +- Select the minimum plan (1 vCPU / 1 GB RAM) +- Set a strong root password or configure SSH key +- Note the **public IP** (e.g., `203.0.113.10`) + +### 1.2 Connect via SSH + +```bash +ssh root@203.0.113.10 +``` + +### 1.3 Update the system + +```bash +apt update && apt upgrade -y +``` + +### 1.4 Install Docker + +```bash +# Install dependencies +apt install -y ca-certificates curl gnupg + +# Add official Docker repository +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 Install nginx + +```bash +apt install -y nginx +``` + +### 1.6 Configure 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 +``` + +> **Tip**: For maximum security, restrict ports 80 and 443 to Cloudflare IPs only. See the [Advanced Security](#advanced-security) section. + +--- + +## 2. Install OmniRoute + +### 2.1 Create configuration directory + +```bash +mkdir -p /opt/omniroute +``` + +### 2.2 Create environment variables file + +```bash +cat > /opt/omniroute/.env << โ€˜EOFโ€™ +# === Security === +JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY +INITIAL_PASSWORD=YourSecurePassword123! +API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY +STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY +STORAGE_ENCRYPTION_KEY_VERSION=v1 +MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT + +# === 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 (change to your domain) === +BASE_URL=https://llms.seudominio.com +NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com + +# === Cloud Sync (optional) === +# CLOUD_URL=https://cloud.omniroute.online +# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online +EOF +``` + +> โš ๏ธ **IMPORTANT**: Generate unique secret keys! Use `openssl rand -hex 32` for each key. + +### 2.3 Start the 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 Verify that it is running + +```bash +docker ps | grep omniroute +docker logs omniroute --tail 20 +``` + +It should display: `[DB] SQLite database ready` and `listening on port 20128`. + +--- + +## 3. Configure nginx (Reverse Proxy) + +### 3.1 Generate SSL certificate (Cloudflare Origin) + +In the Cloudflare dashboard: + +1. Go to **SSL/TLS โ†’ Origin Server** +2. Click **Create Certificate** +3. Keep the defaults (15 years, \*.yourdomain.com) +4. Copy the **Origin Certificate** and the **Private Key** + +```bash +mkdir -p /etc/nginx/ssl + +# Paste the certificate +nano /etc/nginx/ssl/origin.crt + +# Paste the private key +nano /etc/nginx/ssl/origin.key + +chmod 600 /etc/nginx/ssl/origin.key +``` + +### 3.2 Nginx Configuration + +```bash +cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ +# Default server โ€” blocks direct access via 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.yourdomain.com; # Change to your domain + + 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.yourdomain.com; + return 301 https://$server_name$request_uri; +} +NGINX +``` + +### 3.3 Enable and Test + +```bash +# Remove default configuration +rm -f /etc/nginx/sites-enabled/default + +# Enable OmniRoute +ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute + +# Test and reload +nginx -t && systemctl reload nginx +``` + +--- + +## 4. Configure Cloudflare DNS + +### 4.1 Add DNS record + +In the Cloudflare dashboard โ†’ DNS: + +| Type | Name | Content | Proxy | +| ---- | ------ | ---------------------- | ---------- | +| A | `llms` | `203.0.113.10` (VM IP) | โœ… Proxied | + +### 4.2 Configure SSL + +Under **SSL/TLS โ†’ Overview**: + +- Mode: **Full (Strict)** + +Under **SSL/TLS โ†’ Edge Certificates**: + +- Always Use HTTPS: โœ… On +- Minimum TLS Version: TLS 1.2 +- Automatic HTTPS Rewrites: โœ… On + +### 4.3 Testing + +```bash +curl -sI https://llms.seudominio.com/health +# Should return HTTP/2 200 +``` + +--- + +## 5. Operations and Maintenance + +### Upgrade to a new version + +```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 +``` + +### View logs + +```bash +docker logs -f omniroute # Real-time stream +docker logs omniroute --tail 50 # Last 50 lines +``` + +### Manual database backup + +```bash +# Copy data from the volume to the host +docker cp omniroute:/app/data ./backup-$(date +%F) + +# Or compress the entire volume +docker run --rm -v omniroute-data:/data -v $(pwd):/backup \ + alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data +``` + +### Restore from 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. Advanced Security + +### Restrict nginx to Cloudflare IPs + +```bash +cat > /etc/nginx/cloudflare-ips.conf << โ€˜CFโ€™ +# Cloudflare IPv4 ranges โ€” update periodically +# 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 +``` + +Add the following to `nginx.conf` inside the `http {}` block: + +```nginx +include /etc/nginx/cloudflare-ips.conf; +``` + +### Install fail2ban + +```bash +apt install -y fail2ban +systemctl enable fail2ban +systemctl start fail2ban + +# Check status +fail2ban-client status sshd +``` + +### Block direct access to the Docker port + +```bash +# Prevent direct external access to port 20128 +iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP +iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT + +# Persist the rules +apt install -y iptables-persistent +netfilter-persistent save +``` + +--- + +## 7. Deploy to Cloudflare Workers (Optional) + +For remote access via Cloudflare Workers (without exposing the VM directly): + +```bash +# In the local repository +cd omnirouteCloud +npm install +npx wrangler login +npx wrangler deploy +``` + +See the full documentation at [omnirouteCloud/README.md](../omnirouteCloud/README.md). + +--- + +## Port Summary + +| Port | Service | Access | +| ----- | ----------- | -------------------------- | +| 22 | SSH | Public (with fail2ban) | +| 80 | nginx HTTP | Redirect โ†’ HTTPS | +| 443 | nginx HTTPS | Via Cloudflare Proxy | +| 20128 | OmniRoute | Localhost only (via nginx) | diff --git a/docs/i18n/he/src/lib/a2a/README.md b/docs/i18n/he/src/lib/a2a/README.md new file mode 100644 index 0000000000..3d89bf85f6 --- /dev/null +++ b/docs/i18n/he/src/lib/a2a/README.md @@ -0,0 +1,752 @@ +# OmniRoute A2A Server (ืขื‘ืจื™ืช) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../../../src/lib/a2a/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../../../es/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../../../fr/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../../../de/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../../../it/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../../../ru/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../../../zh-CN/src/lib/a2a/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../../../ja/src/lib/a2a/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../../../ko/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../../../ar/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../../../in/src/lib/a2a/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../../../th/src/lib/a2a/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../../../vi/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../../../id/src/lib/a2a/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../../../ms/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../../../nl/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../../../pl/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../../../sv/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../../../no/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../../../da/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../../../fi/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../../../pt/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../../../ro/src/lib/a2a/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../../../hu/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../../../bg/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../../../sk/src/lib/a2a/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../../../uk-UA/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../../../he/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../../../phi/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../../../pt-BR/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../../../cs/src/lib/a2a/README.md) + +--- + +> **Agent-to-Agent Protocol v0.3** โ€” Enables any AI agent to use OmniRoute as an intelligent routing agent via JSON-RPC 2.0. + +The A2A Server exposes OmniRoute as a **first-class agent** that other agents can discover, delegate tasks to, and collaborate with using the [A2A Protocol](https://google.github.io/A2A/). + +--- + +## ืืจื›ื™ื˜ืงื˜ื•ืจื” + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Orchestrator Agent โ”‚ +โ”‚ (LangChain, CrewAI, AutoGen, Custom Agent) โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ 1. GET /.well-known/agent.json (discover) + โ”‚ 2. POST /a2a (JSON-RPC 2.0) + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ OmniRoute A2A Server โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Task Manager โ”‚ โ”‚ Skill Engine โ”‚ โ”‚ SSE Streaming โ”‚ โ”‚ +โ”‚ โ”‚ (lifecycle) โ”‚โ”€โ”€โ”‚ (registry) โ”‚โ”€โ”€โ”‚ (real-time) โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ +โ”‚ Skills: โ”‚ โ”‚ +โ”‚ โ”œโ”€ smart-routing โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ””โ”€ quota-management โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ Routing Decision Logger โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ OmniRoute Gateway (internal) + /v1/chat/completions, /api/combos, /api/usage/quota +``` + +--- + +## ื”ืชื—ืœื” ืžื”ื™ืจื” + +### Agent Discovery + +Every A2A-compatible agent exposes an **Agent Card** at `/.well-known/agent.json`: + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +**Response:** + +```json +{ + "name": "OmniRoute", + "description": "Intelligent AI gateway with auto-routing across 50+ providers", + "url": "http://localhost:20128/a2a", + "version": "1.8.1", + "capabilities": { + "streaming": true, + "pushNotifications": false + }, + "skills": [ + { + "id": "smart-routing", + "name": "Smart Routing", + "description": "Routes prompts through OmniRoute intelligent pipeline", + "tags": ["routing", "llm", "multi-provider", "cost-optimization"], + "examples": [ + "Write a hello world in Python", + "Explain quantum computing using the cheapest provider" + ] + }, + { + "id": "quota-management", + "name": "Quota Management", + "description": "Natural-language queries about provider quotas", + "tags": ["quota", "analytics", "cost"], + "examples": [ + "Which provider has the most quota remaining?", + "Suggest a free combo for coding" + ] + } + ], + "authentication": { + "schemes": ["bearer"], + "apiKeyHeader": "Authorization" + } +} +``` + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Send a message to a skill and receive the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python hello world"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "a1b2c3d4-...", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "print('Hello, World!')" }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.0030)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "2026-03-04T..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"Quantum computing..."}}} + +: heartbeat 2026-03-04T21:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Running Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Skills Reference + +### `smart-routing` + +Routes prompts through OmniRoute's intelligent pipeline with full observability. + +**Parameters (in `metadata`):** + +| Parameter | Type | Default | Description | +| --------- | -------- | ------------ | ---------------------------------------------------------------------------------------- | +| `model` | `string` | `"auto"` | Target model (e.g., `claude-sonnet-4`, `gpt-4o`, `auto`) | +| `combo` | `string` | active combo | Specific combo to route through | +| `budget` | `number` | none | Maximum cost in USD for this request | +| `role` | `string` | none | Task role hint: `coding`, `review`, `planning`, `analysis`, `debugging`, `documentation` | + +**Returns:** + +| Field | Description | +| ------------------------------ | --------------------------------------------------------- | +| `artifacts[].content` | The LLM response text | +| `metadata.routing_explanation` | Human-readable explanation of routing decision | +| `metadata.cost_envelope` | Estimated vs actual cost with currency | +| `metadata.resilience_trace` | Array of events (primary_selected, fallback_needed, etc.) | +| `metadata.policy_verdict` | Whether the request was allowed and why | + +### `quota-management` + +Answers natural-language queries about provider quotas. + +**Query types (inferred from message content):** + +| Query Pattern | Response Type | +| ---------------------------------------------- | -------------------------------------------------------- | +| Contains `"ranking"`, `"most quota"`, `"best"` | Providers ranked by remaining quota | +| Contains `"free"`, `"suggest"` | Lists free combos or suggests free-tier providers | +| Default | Full quota summary with warnings for low-quota providers | + +--- + +## Task Lifecycle + +``` +submitted โ”€โ”€โ†’ working โ”€โ”€โ†’ completed + โ”€โ”€โ†’ failed + โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ†’ cancelled +``` + +| State | Description | +| ----------- | ----------------------------------------------------- | +| `submitted` | Task created, queued for execution | +| `working` | Skill handler is executing | +| `completed` | Execution succeeded, artifacts available | +| `failed` | Execution failed or task expired (TTL: 5 min default) | +| `cancelled` | Cancelled by client via `tasks/cancel` | + +- Terminal states: `completed`, `failed`, `cancelled` (no further transitions) +- Expired tasks in `submitted` or `working` are auto-marked as `failed` +- Tasks are garbage-collected after 2ร— TTL + +--- + +## Client Examples + +### Python โ€” Orchestrator Agent + +```python +""" +A2A Client โ€” Python example. +Discovers OmniRoute agent, sends a task, and processes the result. +""" +import requests +import json + +BASE_URL = "http://localhost:20128" +API_KEY = "your-api-key" +HEADERS = { + "Content-Type": "application/json", + "Authorization": f"Bearer {API_KEY}", +} + +# 1. Discover agent capabilities +agent_card = requests.get(f"{BASE_URL}/.well-known/agent.json").json() +print(f"Agent: {agent_card['name']} v{agent_card['version']}") +print(f"Skills: {[s['id'] for s in agent_card['skills']]}") + +# 2. Send a smart-routing task +response = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python quicksort implementation"}], + "metadata": { + "model": "auto", + "combo": "fast-coding", + "budget": 0.10, + } + } +}) +result = response.json()["result"] +print(f"\n๐Ÿ“ Response: {result['artifacts'][0]['content'][:200]}...") +print(f"๐Ÿ”€ Routing: {result['metadata']['routing_explanation']}") +print(f"๐Ÿ’ฐ Cost: ${result['metadata']['cost_envelope']['actual']}") +print(f"๐Ÿ›ก๏ธ Policy: {result['metadata']['policy_verdict']['reason']}") + +# 3. Query quota status +quota_resp = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-2", + "method": "message/send", + "params": { + "skill": "quota-management", + "messages": [{"role": "user", "content": "Which provider has the most quota remaining?"}], + } +}) +quota_result = quota_resp.json()["result"] +print(f"\n๐Ÿ“Š Quota: {quota_result['artifacts'][0]['content']}") +``` + +### TypeScript โ€” Multi-Agent Orchestrator + +```typescript +/** + * A2A Client โ€” TypeScript example. + * Shows agent discovery, task delegation, and streaming. + */ + +const BASE_URL = "http://localhost:20128"; +const API_KEY = "your-api-key"; + +interface JsonRpcResponse { + jsonrpc: "2.0"; + id: string | number; + result?: T; + error?: { code: number; message: string }; +} + +async function a2aCall(method: string, params: Record): Promise { + const resp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: `${method}-${Date.now()}`, + method, + params, + }), + }); + const json: JsonRpcResponse = await resp.json(); + if (json.error) throw new Error(`[${json.error.code}] ${json.error.message}`); + return json.result!; +} + +// โ”€โ”€ Agent Discovery โ”€โ”€ +const agentCard = await fetch(`${BASE_URL}/.well-known/agent.json`).then((r) => r.json()); +console.log(`Connected to: ${agentCard.name} (${agentCard.skills.length} skills)`); + +// โ”€โ”€ Smart Routing: Send a coding task โ”€โ”€ +const routingResult = await a2aCall("message/send", { + skill: "smart-routing", + messages: [{ role: "user", content: "Implement a Redis cache wrapper in TypeScript" }], + metadata: { model: "claude-sonnet-4", role: "coding" }, +}); +console.log("Response:", routingResult.artifacts[0].content); +console.log("Provider:", routingResult.metadata.routing_explanation); + +// โ”€โ”€ Quota Management: Find free alternatives โ”€โ”€ +const quotaResult = await a2aCall("message/send", { + skill: "quota-management", + messages: [{ role: "user", content: "Suggest free combos for documentation" }], +}); +console.log("Free combos:", quotaResult.artifacts[0].content); + +// โ”€โ”€ Streaming: Real-time response โ”€โ”€ +const streamResp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "stream-1", + method: "message/stream", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Explain microservices architecture" }], + }, + }), +}); + +const reader = streamResp.body!.getReader(); +const decoder = new TextDecoder(); +while (true) { + const { done, value } = await reader.read(); + if (done) break; + const chunk = decoder.decode(value); + for (const line of chunk.split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + if (event.params.chunk) { + process.stdout.write(event.params.chunk.content); + } + if (event.params.task.state === "completed") { + console.log("\nโœ… Stream completed"); + } + } + } +} +``` + +### Python โ€” LangChain A2A Integration + +```python +""" +LangChain integration โ€” Use OmniRoute A2A as a custom LLM. +""" +from langchain.llms.base import BaseLLM +from langchain.schema import LLMResult, Generation +import requests +from typing import List, Optional + +class OmniRouteA2A(BaseLLM): + base_url: str = "http://localhost:20128" + api_key: str = "" + model: str = "auto" + combo: Optional[str] = None + + @property + def _llm_type(self) -> str: + return "omniroute-a2a" + + def _call(self, prompt: str, stop: Optional[List[str]] = None, **kwargs) -> str: + response = requests.post( + f"{self.base_url}/a2a", + headers={ + "Content-Type": "application/json", + "Authorization": f"Bearer {self.api_key}", + }, + json={ + "jsonrpc": "2.0", + "id": "langchain-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": prompt}], + "metadata": { + "model": self.model, + **({"combo": self.combo} if self.combo else {}), + }, + }, + }, + ) + result = response.json()["result"] + return result["artifacts"][0]["content"] + + def _generate(self, prompts: List[str], stop=None, **kwargs) -> LLMResult: + return LLMResult( + generations=[[Generation(text=self._call(p, stop))] for p in prompts] + ) + +# Usage +llm = OmniRouteA2A( + base_url="http://localhost:20128", + api_key="your-key", + model="auto", + combo="fast-coding", +) +result = llm("Write a Python function to merge two sorted lists") +print(result) +``` + +### Go โ€” A2A Client + +```go +package main + +import ( + "bytes" + "encoding/json" + "fmt" + "io" + "net/http" +) + +const baseURL = "http://localhost:20128" +const apiKey = "your-api-key" + +type JsonRpcRequest struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Method string `json:"method"` + Params interface{} `json:"params"` +} + +type JsonRpcResponse struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Result interface{} `json:"result"` + Error *struct { + Code int `json:"code"` + Message string `json:"message"` + } `json:"error"` +} + +func a2aCall(method string, params interface{}) (*JsonRpcResponse, error) { + body, _ := json.Marshal(JsonRpcRequest{ + Jsonrpc: "2.0", + ID: "go-1", + Method: method, + Params: params, + }) + + req, _ := http.NewRequest("POST", baseURL+"/a2a", bytes.NewReader(body)) + req.Header.Set("Content-Type", "application/json") + req.Header.Set("Authorization", "Bearer "+apiKey) + + resp, err := http.DefaultClient.Do(req) + if err != nil { + return nil, err + } + defer resp.Body.Close() + data, _ := io.ReadAll(resp.Body) + + var result JsonRpcResponse + json.Unmarshal(data, &result) + return &result, nil +} + +func main() { + // Discover agent + resp, _ := http.Get(baseURL + "/.well-known/agent.json") + defer resp.Body.Close() + body, _ := io.ReadAll(resp.Body) + fmt.Println("Agent Card:", string(body)) + + // Send smart-routing task + result, _ := a2aCall("message/send", map[string]interface{}{ + "skill": "smart-routing", + "messages": []map[string]string{{"role": "user", "content": "Hello from Go!"}}, + "metadata": map[string]interface{}{"model": "auto"}, + }) + out, _ := json.MarshalIndent(result.Result, "", " ") + fmt.Println("Result:", string(out)) +} +``` + +--- + +## Use Cases + +### ๐Ÿค– Use Case 1: Multi-Agent Coding Pipeline + +An orchestrator agent delegates code generation to OmniRoute, then passes the output to a review agent. + +```python +def coding_pipeline(task: str): + # Step 1: Generate code via OmniRoute A2A + code_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Write production-quality code: {task}"} + ], metadata={"model": "auto", "role": "coding"}) + code = code_result["artifacts"][0]["content"] + + # Step 2: Review the code via OmniRoute A2A (different model) + review_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Review this code for bugs and improvements:\n\n{code}"} + ], metadata={"model": "auto", "role": "review"}) + review = review_result["artifacts"][0]["content"] + + # Step 3: Check costs + print(f"Code cost: ${code_result['metadata']['cost_envelope']['actual']}") + print(f"Review cost: ${review_result['metadata']['cost_envelope']['actual']}") + + return {"code": code, "review": review} +``` + +### ๐Ÿ’ก Use Case 2: Quota-Aware Agent Swarm + +Multiple agents share quota through OmniRoute, using the quota skill to coordinate. + +```python +async def quota_aware_agent(agent_name: str, task: str): + # Check quota before starting + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Which provider has the most quota remaining?"} + ]) + print(f"[{agent_name}] {quota['artifacts'][0]['content']}") + + # Send request with budget constraint + result = a2a_send("smart-routing", [ + {"role": "user", "content": task} + ], metadata={"budget": 0.05}) + + policy = result["metadata"]["policy_verdict"] + if not policy["allowed"]: + print(f"[{agent_name}] โš ๏ธ Budget exceeded: {policy['reason']}") + # Fall back to free combo + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Suggest free combos"} + ]) + print(f"[{agent_name}] Free alternatives: {quota['artifacts'][0]['content']}") + + return result +``` + +### ๐Ÿ“Š Use Case 3: Real-Time Streaming Dashboard + +A monitoring agent streams responses and displays progress in real-time. + +```typescript +async function streamingDashboard(prompt: string) { + const response = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { "Content-Type": "application/json", Authorization: `Bearer ${API_KEY}` }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "dash-1", + method: "message/stream", + params: { skill: "smart-routing", messages: [{ role: "user", content: prompt }] }, + }), + }); + + let totalChunks = 0; + const reader = response.body!.getReader(); + const decoder = new TextDecoder(); + + while (true) { + const { done, value } = await reader.read(); + if (done) break; + + for (const line of decoder.decode(value).split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + const state = event.params.task.state; + + if (state === "working" && event.params.chunk) { + totalChunks++; + process.stdout.write( + `\r[Chunk ${totalChunks}] ${event.params.chunk.content.slice(0, 50)}...` + ); + } + if (state === "completed") { + const meta = event.params.metadata; + console.log( + `\nโœ… Done | Cost: $${meta?.cost_envelope?.actual || 0} | Route: ${meta?.routing_explanation || "N/A"}` + ); + } + if (state === "failed") { + console.error(`\nโŒ Failed: ${event.params.metadata?.error}`); + } + } + } + } +} +``` + +### ๐Ÿ” Use Case 4: Task Polling Pattern + +For long-running tasks, poll the task status instead of waiting synchronously. + +```python +import time + +def poll_task(task_id: str, timeout: int = 60): + """Poll task status until completion or timeout.""" + start = time.time() + while time.time() - start < timeout: + result = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "poll-1", + "method": "tasks/get", + "params": {"taskId": task_id}, + }).json() + + task = result["result"]["task"] + state = task["state"] + print(f" Task {task_id[:8]}... state={state}") + + if state in ("completed", "failed", "cancelled"): + return task + time.sleep(2) + + # Timeout โ€” cancel the task + requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "cancel-1", + "method": "tasks/cancel", + "params": {"taskId": task_id}, + }) + raise TimeoutError(f"Task {task_id} timed out after {timeout}s") +``` + +--- + +## Error Codes + +| Code | Constant | Meaning | +| ------ | ------------------------ | ---------------------------------------- | +| -32700 | โ€” | Parse error (invalid JSON) | +| -32600 | `INVALID_REQUEST` | Invalid JSON-RPC request or unauthorized | +| -32601 | `METHOD_NOT_FOUND` | Unknown method or skill | +| -32602 | `INVALID_PARAMS` | Missing or invalid parameters | +| -32603 | `INTERNAL_ERROR` | Skill execution failed | +| -32001 | `TASK_NOT_FOUND` | Task ID not found | +| -32002 | `TASK_ALREADY_COMPLETED` | Cannot modify a completed task | +| -32003 | `UNAUTHORIZED` | Invalid or missing API key | +| -32004 | `BUDGET_EXCEEDED` | Request exceeds configured budget | +| -32005 | `PROVIDER_UNAVAILABLE` | No available providers | + +--- + +## Authentication + +All `/a2a` requests require a Bearer token via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server (`OMNIROUTE_API_KEY` is empty), authentication is bypassed. + +--- + +## File Structure + +``` +src/lib/a2a/ +โ”œโ”€โ”€ taskManager.ts # Task lifecycle (create/update/cancel/list), TTL, cleanup +โ”œโ”€โ”€ taskExecution.ts # Generic task executor with state management +โ”œโ”€โ”€ streaming.ts # SSE stream formatting, heartbeat, chunk/completion events +โ”œโ”€โ”€ routingLogger.ts # Routing decision logger (stats, history, retention) +โ””โ”€โ”€ skills/ + โ”œโ”€โ”€ smartRouting.ts # Smart routing skill (routes via /v1/chat/completions) + โ””โ”€โ”€ quotaManagement.ts # Quota management skill (natural-language quota queries) + +src/app/a2a/ +โ””โ”€โ”€ route.ts # Next.js API route handler (JSON-RPC 2.0 dispatch) + +open-sse/mcp-server/ +โ””โ”€โ”€ schemas/a2a.ts # Zod schemas (AgentCard, Task, JSON-RPC, SSE events) +``` + +--- + +## Comparison: MCP vs A2A + +| Feature | MCP Server | A2A Server | +| ----------------- | ---------------------------- | ------------------------------------------------- | +| **Protocol** | Model Context Protocol | Agent-to-Agent Protocol v0.3 | +| **Transport** | stdio / HTTP | HTTP (JSON-RPC 2.0) | +| **Discovery** | Tool listing via MCP | `/.well-known/agent.json` | +| **Granularity** | 16 individual tools | 2 high-level skills | +| **Best for** | IDE agents (Cursor, VS Code) | Multi-agent systems (LangChain, CrewAI) | +| **Streaming** | Not supported | SSE via `message/stream` | +| **Task tracking** | No | Full lifecycle (submitted โ†’ completed) | +| **Observability** | Audit log per tool call | Cost envelope + resilience trace + policy verdict | + +--- + +## ืจื™ืฉื™ื•ืŸ + +Part of [OmniRoute](https://github.com/diegosouzapw/OmniRoute) โ€” MIT License. diff --git a/docs/i18n/hu/A2A-SERVER.md b/docs/i18n/hu/A2A-SERVER.md deleted file mode 100644 index 01531ff482..0000000000 --- a/docs/i18n/hu/A2A-SERVER.md +++ /dev/null @@ -1,200 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/A2A-SERVER.md) - ---- - -# OmniRoute A2A Server Documentation - -> Agent-to-Agent Protocol v0.3 โ€” OmniRoute as an intelligent routing agent - -## Agent Discovery - -```bash -curl http://localhost:20128/.well-known/agent.json -``` - -Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements. - ---- - -## Authentication - -All `/a2a` requests require an API key via the `Authorization` header: - -``` -Authorization: Bearer YOUR_OMNIROUTE_API_KEY -``` - -If no API key is configured on the server, authentication is bypassed. - ---- - -## JSON-RPC 2.0 Methods - -### `message/send` โ€” Synchronous Execution - -Sends a message to a skill and waits for the complete response. - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{ - "jsonrpc": "2.0", - "id": "1", - "method": "message/send", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Write a hello world in Python"}], - "metadata": {"model": "auto", "combo": "fast-coding"} - } - }' -``` - -**Response:** - -```json -{ - "jsonrpc": "2.0", - "id": "1", - "result": { - "task": { "id": "uuid", "state": "completed" }, - "artifacts": [{ "type": "text", "content": "..." }], - "metadata": { - "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)", - "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, - "resilience_trace": [ - { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." } - ], - "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } - } - } -} -``` - -### `message/stream` โ€” SSE Streaming - -Same as `message/send` but returns Server-Sent Events for real-time streaming. - -```bash -curl -N -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{ - "jsonrpc": "2.0", - "id": "1", - "method": "message/stream", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Explain quantum computing"}] - } - }' -``` - -**SSE Events:** - -``` -data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}} - -: heartbeat 2026-03-03T17:00:00Z - -data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} -``` - -### `tasks/get` โ€” Query Task Status - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' -``` - -### `tasks/cancel` โ€” Cancel a Task - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' -``` - ---- - -## Available Skills - -| Skill | Description | -| :----------------- | :------------------------------------------------------------------------------------------------------------------------------ | -| `smart-routing` | Routes prompts through OmniRoute's intelligent pipeline. Returns response with routing explanation, cost, and resilience trace. | -| `quota-management` | Answers natural-language queries about provider quotas, suggests free combos, and provides quota rankings. | - ---- - -## Task Lifecycle - -``` -submitted โ†’ working โ†’ completed - โ†’ failed - โ†’ cancelled -``` - -- Tasks expire after 5 minutes (configurable) -- Terminal states: `completed`, `failed`, `cancelled` -- Event log tracks every state transition - ---- - -## Error Codes - -| Code | Meaning | -| :----- | :----------------------------- | -| -32700 | Parse error (invalid JSON) | -| -32600 | Invalid request / Unauthorized | -| -32601 | Method or skill not found | -| -32602 | Invalid params | -| -32603 | Internal error | - ---- - -## Integration Examples - -### Python (requests) - -```python -import requests - -resp = requests.post("http://localhost:20128/a2a", json={ - "jsonrpc": "2.0", "id": "1", - "method": "message/send", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Hello"}] - } -}, headers={"Authorization": "Bearer YOUR_KEY"}) - -result = resp.json()["result"] -print(result["artifacts"][0]["content"]) -print(result["metadata"]["routing_explanation"]) -``` - -### TypeScript (fetch) - -```typescript -const resp = await fetch("http://localhost:20128/a2a", { - method: "POST", - headers: { - "Content-Type": "application/json", - Authorization: "Bearer YOUR_KEY", - }, - body: JSON.stringify({ - jsonrpc: "2.0", - id: "1", - method: "message/send", - params: { - skill: "smart-routing", - messages: [{ role: "user", content: "Hello" }], - }, - }), -}); -const { result } = await resp.json(); -console.log(result.metadata.routing_explanation); -``` diff --git a/docs/i18n/hu/API_REFERENCE.md b/docs/i18n/hu/API_REFERENCE.md deleted file mode 100644 index b878605221..0000000000 --- a/docs/i18n/hu/API_REFERENCE.md +++ /dev/null @@ -1,455 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/API_REFERENCE.md) - ---- - -# API Reference - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/API_REFERENCE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/API_REFERENCE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/API_REFERENCE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/API_REFERENCE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/API_REFERENCE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/API_REFERENCE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/API_REFERENCE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/API_REFERENCE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/API_REFERENCE.md) - -Complete reference for all OmniRoute API endpoints. - ---- - -## Table of Contents - -- [Chat Completions](#chat-completions) -- [Embeddings](#embeddings) -- [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`. - -### ACP Agents - -| Endpoint | Method | Description | -| ----------------- | ------ | -------------------------------------------------------- | -| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | -| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | -| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | - -GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). - -### Resilience & Rate Limits - -| Endpoint | Method | Description | -| ----------------------- | ------- | ------------------------------- | -| `/api/resilience` | 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` diff --git a/docs/i18n/hu/ARCHITECTURE.md b/docs/i18n/hu/ARCHITECTURE.md deleted file mode 100644 index 4ea06a29f2..0000000000 --- a/docs/i18n/hu/ARCHITECTURE.md +++ /dev/null @@ -1,787 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/ARCHITECTURE.md) - ---- - -# OmniRoute Architecture - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/ARCHITECTURE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/ARCHITECTURE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/ARCHITECTURE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/ARCHITECTURE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/ARCHITECTURE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/ARCHITECTURE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/ARCHITECTURE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/ARCHITECTURE.md) - -_Last updated: 2026-03-04_ - -## 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 (`...`) for reasoning models -- Response sanitization for strict OpenAI SDK compatibility -- Role normalization (developerโ†’system, systemโ†’user) for cross-provider compatibility -- Structured output conversion (json_schema โ†’ Gemini responseSchema) -- Local persistence for providers, keys, aliases, combos, settings, pricing -- Usage/cost tracking and request logging -- Optional cloud sync for multi-device/state sync -- IP allowlist/blocklist for API access control -- Thinking budget management (passthrough/auto/custom/adaptive) -- Global system prompt injection -- Session tracking and fingerprinting -- Per-account enhanced rate limiting with provider-specific profiles -- Circuit breaker pattern for provider resilience -- Anti-thundering herd protection with mutex locking -- Signature-based request deduplication cache -- Domain layer: model availability, cost rules, fallback policy, lockout policy -- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) -- Policy engine for centralized request evaluation (lockout โ†’ budget โ†’ fallback) -- Request telemetry with p50/p95/p99 latency aggregation -- Correlation ID (X-Request-Id) for end-to-end tracing -- Compliance audit logging with opt-out per API key -- Eval framework for LLM quality assurance -- Resilience UI dashboard with real-time circuit breaker status -- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) - -Primary runtime model: - -- Next.js 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[(storage.sqlite)] - UDB[(usage tables + log artifacts)] - end - - subgraph Upstreams[Upstream Providers] - P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/Qoder/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/route.ts` (GET) -- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) -- OAuth: `src/app/api/oauth/*` -- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` -- Usage: `src/app/api/usage/*` -- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` -- CLI tooling helpers: `src/app/api/cli-tools/*` -- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) -- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) -- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) -- Sessions: `src/app/api/sessions` (GET) -- Rate limits: `src/app/api/rate-limits` (GET) -- Resilience: `src/app/api/resilience` (GET/PATCH) โ€” provider profiles, circuit breaker, rate limit state -- Resilience reset: `src/app/api/resilience/reset` (POST) โ€” reset breakers + cooldowns -- Cache stats: `src/app/api/cache/stats` (GET/DELETE) -- Model availability: `src/app/api/models/availability` (GET/POST) -- Telemetry: `src/app/api/telemetry/summary` (GET) -- Budget: `src/app/api/usage/budget` (GET/POST) -- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) -- Compliance audit: `src/app/api/compliance/audit-log` (GET) -- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) -- Policies: `src/app/api/policies` (GET/POST) - -## 2) SSE + 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` -- Response sanitization: `open-sse/handlers/responseSanitizer.ts` -- Role normalization: `open-sse/services/roleNormalizer.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`, `qoder.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 (SQLite): - -- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) -- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) -- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) -- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** - -Usage persistence: - -- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) -- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` -- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) -- legacy JSON files are migrated to SQLite by startup migrations when present - -Domain State DB (SQLite): - -- `src/lib/db/domainState.ts` โ€” CRUD operations 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: - -- primary runtime DB: `${DATA_DIR}/storage.sqlite` -- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) -- structured call payload archives: `${DATA_DIR}/call_logs/` -- optional translator/request debug sessions: `/logs/...` - -## Deployment Topology - -```mermaid -flowchart LR - 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[(storage.sqlite)] - UsageDB[(usage tables + log artifacts)] - end - - subgraph External[External Services] - Providers[AI Providers] - SyncCloud[Cloud Sync Service] - end - - CLI --> Next - Browser --> Next - Next --> Core - Next --> MainDB - Core --> MainDB - Core --> UsageDB - Core --> Providers - Next --> SyncCloud -``` - -## Module Mapping (Decision-Critical) - -### Route and API Modules - -- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs -- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) -- `src/app/api/providers*`: provider CRUD, validation, testing -- `src/app/api/provider-nodes*`: custom compatible node management -- `src/app/api/provider-models`: custom model management (CRUD) -- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) -- `src/app/api/oauth/*`: OAuth/device-code flows -- `src/app/api/keys*`: local API key lifecycle -- `src/app/api/models/alias`: alias management -- `src/app/api/combos*`: fallback combo management -- `src/app/api/pricing`: pricing overrides for cost calculation -- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) -- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) -- `src/app/api/usage/*`: usage and logs APIs -- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers -- `src/app/api/cli-tools/*`: local CLI config writers/checkers -- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) -- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) -- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) -- `src/app/api/sessions`: active session listing (GET) -- `src/app/api/rate-limits`: per-account rate limit status (GET) - -### Routing and Execution Core - -- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop -- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup -- `open-sse/executors/*`: provider-specific network and format behavior - -### Translation Registry and Format Converters - -- `open-sse/translator/index.ts`: translator registry and orchestration -- Request translators: `open-sse/translator/request/*` -- Response translators: `open-sse/translator/response/*` -- Format constants: `open-sse/translator/formats.ts` - -### Persistence - -- `src/lib/db/*`: persistent config/state and domain persistence on SQLite -- `src/lib/localDb.ts`: compatibility re-export for DB modules -- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables - -## Provider Executor Coverage (Strategy Pattern) - -Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. - -| Executor | Provider(s) | Special Handling | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | -| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, Qoder, 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 | -| Qoder | openai | OAuth (Basic) | โœ… | โœ… | โœ… | โš ๏ธ Per request | -| OpenRouter | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| GLM/Kimi/MiniMax | claude | API Key | โœ… | โœ… | โŒ | โŒ | -| DeepSeek | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Groq | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| xAI (Grok) | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Mistral | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Perplexity | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Together AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Fireworks AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Cerebras | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Cohere | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| NVIDIA NIM | openai | API Key | โœ… | โœ… | โŒ | โŒ | - -## Format Translation Coverage - -Detected source formats include: - -- `openai` -- `openai-responses` -- `claude` -- `gemini` - -Target formats include: - -- OpenAI chat/Responses -- Claude -- Gemini/Gemini-CLI/Antigravity envelope -- Kiro -- Cursor - -Translations use **OpenAI as the hub format** โ€” all conversions go through OpenAI as intermediate: - -``` -Source Format โ†’ OpenAI (hub) โ†’ Target Format -``` - -Translations are selected dynamically based on source payload shape and provider target format. - -Additional processing layers in the translation pipeline: - -- **Response sanitization** โ€” Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance -- **Role normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI targets; merges `system` โ†’ `user` for models that reject the system role (GLM, ERNIE) -- **Think tag extraction** โ€” Parses `...` blocks from content into `reasoning_content` field -- **Structured output** โ€” Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` - -## Supported API Endpoints - -| 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 `/logs//` 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 - -- SQLite schema migrations and auto-upgrade hooks at startup -- legacy JSON โ†’ SQLite migration compatibility path - -## Observability and Operational Signals - -Runtime visibility sources: - -- console logs from `src/sse/utils/logger.ts` -- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) -- textual request status log in `log.txt` (optional/compat) -- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` -- dashboard usage endpoints (`/api/usage/*`) for UI consumption - -## Security-Sensitive Boundaries - -- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing -- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning -- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format -- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level -- Cloud sync endpoints rely on API key auth + machine id semantics - -## Environment and Runtime Matrix - -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` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. -2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. -3. Request logger writes full headers/body when enabled; treat log directory as sensitive. -4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. -5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. -6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). -7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). -8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). - -## Operational Verification Checklist - -- Build from source: `npm run build` -- Build Docker image: `docker build -t omniroute .` -- Start service and verify: -- `GET /api/settings` -- `GET /api/v1/models` -- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/hu/AUTO-COMBO.md b/docs/i18n/hu/AUTO-COMBO.md deleted file mode 100644 index 2166e41dff..0000000000 --- a/docs/i18n/hu/AUTO-COMBO.md +++ /dev/null @@ -1,67 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/AUTO-COMBO.md) - ---- - -# OmniRoute Auto-Combo Engine - -> Self-managing model chains with adaptive scoring - -## How It Works - -The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**: - -| Factor | Weight | Description | -| :--------- | :----- | :---------------------------------------------- | -| Quota | 0.20 | Remaining capacity [0..1] | -| Health | 0.25 | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 | -| CostInv | 0.20 | Inverse cost (cheaper = higher score) | -| LatencyInv | 0.15 | Inverse p95 latency (faster = higher) | -| TaskFit | 0.10 | Model ร— task type fitness score | -| Stability | 0.10 | Low variance in latency/errors | - -## Mode Packs - -| Pack | Focus | Key Weight | -| :---------------------- | :----------- | :--------------- | -| ๐Ÿš€ **Ship Fast** | Speed | latencyInv: 0.35 | -| ๐Ÿ’ฐ **Cost Saver** | Economy | costInv: 0.40 | -| ๐ŸŽฏ **Quality First** | Best model | taskFit: 0.40 | -| ๐Ÿ“ก **Offline Friendly** | Availability | quota: 0.40 | - -## Self-Healing - -- **Temporary exclusion**: Score < 0.2 โ†’ excluded for 5 min (progressive backoff, max 30 min) -- **Circuit breaker awareness**: OPEN โ†’ auto-excluded; HALF_OPEN โ†’ probe requests -- **Incident mode**: >50% OPEN โ†’ disable exploration, maximize stability -- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout - -## Bandit Exploration - -5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode. - -## API - -```bash -# Create auto-combo -curl -X POST http://localhost:20128/api/combos/auto \ - -H "Content-Type: application/json" \ - -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}' - -# List auto-combos -curl http://localhost:20128/api/combos/auto -``` - -## Task Fitness - -30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` โ†’ high coding score). - -## Files - -| File | Purpose | -| :------------------------------------------- | :------------------------------------ | -| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization | -| `open-sse/services/autoCombo/taskFitness.ts` | Model ร— task fitness lookup | -| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap | -| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode | -| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles | -| `src/app/api/combos/auto/route.ts` | REST API | diff --git a/docs/i18n/hu/CHANGELOG.md b/docs/i18n/hu/CHANGELOG.md index bf9bb34f88..31dff77cb5 100644 --- a/docs/i18n/hu/CHANGELOG.md +++ b/docs/i18n/hu/CHANGELOG.md @@ -1,12 +1,92 @@ # Changelog (Magyar) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CHANGELOG.md) --- - ## [Unreleased] +### ๐Ÿ› ๏ธ Maintenance + +- **AGENTS.md rewrite:** Condensed from 297โ†’153 lines. Added build/lint/test commands (including single-test execution), code style guidelines (Prettier, TypeScript, ESLint, naming, imports, error handling, security), and trimmed verbose architecture tables for AI agent consumption. + +## [3.4.2] - 2026-04-01 + +### ๐Ÿ› Bug Fixes + +- **CI Stabilization:** Fixed failing analytics/settings Playwright selectors and request assertions so GitHub Actions E2E runs pass reliably across localized UIs and switch-based controls. +- **Deterministic Tests:** Removed date-sensitive quota fixtures from Copilot usage tests and aligned idempotency/model catalog tests with the merged runtime behavior. +- **MCP Type Hardening:** Removed zero-budget explicit `any` regressions from the MCP server tool registration path, restoring the `check:any-budget:t11` workflow gate. + +### ๐Ÿ› ๏ธ Maintenance + +- **Release Branch Integration:** Consolidated the active feature branches into `release/v3.4.2` on top of current `main` and validated the branch with lint, unit, coverage, build, and CI-mode E2E runs. + +## [3.4.1] - 2026-03-31 + +> [!WARNING] +> **BREAKING CHANGE: request logging, retention, and logging environment variables have been redesigned.** +> On the first startup after upgrading, OmniRoute archives legacy request logs from `DATA_DIR/logs/`, legacy `DATA_DIR/call_logs/`, and `DATA_DIR/log.txt` into `DATA_DIR/log_archives/*.zip`, then removes the deprecated layout and switches to the new unified artifact format under `DATA_DIR/call_logs/`. + +### โœจ New Features + +- **.ENV Migration Utility:** Included `scripts/migrate-env.mjs` to seamlessly migrate ` Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` - ---- - -## Step 2 โ€” Install CLI Tools - -All npm-based tools require Node.js 18+: - -```bash -# Claude Code (Anthropic) -npm install -g @anthropic-ai/claude-code - -# OpenAI Codex -npm install -g @openai/codex - -# Gemini CLI (Google) -npm install -g @google/gemini-cli - -# OpenCode -npm install -g opencode-ai - -# Cline -npm install -g cline - -# KiloCode -npm install -g kilecode - -# Kiro CLI (Amazon โ€” requires curl + unzip) -apt-get install -y unzip # on Debian/Ubuntu -curl -fsSL https://cli.kiro.dev/install | bash -export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc -``` - -**Verify:** - -```bash -claude --version # 2.x.x -codex --version # 0.x.x -gemini --version # 0.x.x -opencode --version # x.x.x -cline --version # 2.x.x -kilocode --version # x.x.x (or: kilo --version) -kiro-cli --version # 1.x.x -``` - ---- - -## Step 3 โ€” Set Global Environment Variables - -Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`: - -```bash -# OmniRoute Universal Endpoint -export OPENAI_BASE_URL="http://localhost:20128/v1" -export OPENAI_API_KEY="sk-your-omniroute-key" -export ANTHROPIC_BASE_URL="http://localhost:20128/v1" -export ANTHROPIC_API_KEY="sk-your-omniroute-key" -export GEMINI_BASE_URL="http://localhost:20128/v1" -export GEMINI_API_KEY="sk-your-omniroute-key" -``` - -> For a **remote server** replace `localhost:20128` with the server IP or domain, -> e.g. `http://192.168.0.15:20128`. - ---- - -## Step 4 โ€” Configure Each Tool - -### Claude Code - -```bash -# Via CLI: -claude config set --global api-base-url http://localhost:20128/v1 - -# Or create ~/.claude/settings.json: -mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF -{ - "apiBaseUrl": "http://localhost:20128/v1", - "apiKey": "sk-your-omniroute-key" -} -EOF -``` - -**Test:** `claude "say hello"` - ---- - -### OpenAI Codex - -```bash -mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF -model: auto -apiKey: sk-your-omniroute-key -apiBaseUrl: http://localhost:20128/v1 -EOF -``` - -**Test:** `codex "what is 2+2?"` - ---- - -### Gemini CLI - -```bash -mkdir -p ~/.gemini && cat > ~/.gemini/settings.json << EOF -{ - "apiKey": "sk-your-omniroute-key", - "baseUrl": "http://localhost:20128/v1" -} -EOF -``` - -**Test:** `gemini "hello"` - ---- - -### OpenCode - -```bash -mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF -[provider.openai] -base_url = "http://localhost:20128/v1" -api_key = "sk-your-omniroute-key" -EOF -``` - -**Test:** `opencode` - ---- - -### Cline (CLI or VS Code) - -**CLI mode:** - -```bash -mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF -{ - "apiProvider": "openai", - "openAiBaseUrl": "http://localhost:20128/v1", - "openAiApiKey": "sk-your-omniroute-key" -} -EOF -``` - -**VS Code mode:** -Cline extension settings โ†’ API Provider: `OpenAI Compatible` โ†’ Base URL: `http://localhost:20128/v1` - -Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ Cline โ†’ Apply Config**. - ---- - -### KiloCode (CLI or VS Code) - -**CLI mode:** - -```bash -kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key -``` - -**VS Code settings:** - -```json -{ - "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", - "kilo-code.apiKey": "sk-your-omniroute-key" -} -``` - -Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ KiloCode โ†’ Apply Config**. - ---- - -### Continue (VS Code Extension) - -Edit `~/.continue/config.yaml`: - -```yaml -models: - - name: OmniRoute - provider: openai - model: auto - apiBase: http://localhost:20128/v1 - apiKey: sk-your-omniroute-key - default: true -``` - -Restart VS Code after editing. - ---- - -### Kiro CLI (Amazon) - -```bash -# Login to your AWS/Kiro account: -kiro-cli login - -# The CLI uses its own auth โ€” OmniRoute is not needed as backend for Kiro CLI itself. -# Use kiro-cli alongside OmniRoute for other tools. -kiro-cli status -``` - ---- - -### Cursor (Desktop App) - -> **Note:** Cursor routes requests through its cloud. For OmniRoute integration, -> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL. - -Via GUI: **Settings โ†’ Models โ†’ OpenAI API Key** - -- Base URL: `https://your-domain.com/v1` -- API Key: your OmniRoute key - ---- - -## Dashboard Auto-Configuration - -The OmniRoute dashboard automates configuration for most tools: - -1. Go to `http://localhost:20128/dashboard/cli-tools` -2. Expand any tool card -3. Select your API key from the dropdown -4. Click **Apply Config** (if tool is detected as installed) -5. Or copy the generated config snippet manually - ---- - -## Built-in Agents: Droid & OpenClaw - -**Droid** and **OpenClaw** are AI agents built directly into OmniRoute โ€” no installation needed. -They run as internal routes and use OmniRoute's model routing automatically. - -- Access: `http://localhost:20128/dashboard/agents` -- Configure: same combos and providers as all other tools -- No API key or CLI install required - ---- - -## Available API Endpoints - -| Endpoint | Description | Use For | -| -------------------------- | ----------------------------- | --------------------------- | -| `/v1/chat/completions` | Standard chat (all providers) | All modern tools | -| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows | -| `/v1/completions` | Legacy text completions | Older tools using `prompt:` | -| `/v1/embeddings` | Text embeddings | RAG, search | -| `/v1/images/generations` | Image generation | DALL-E, Flux, etc. | -| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS | -| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI | - ---- - -## Troubleshooting - -| Error | Cause | Fix | -| ------------------------- | ----------------------- | ------------------------------------------ | -| `Connection refused` | OmniRoute not running | `pm2 start omniroute` | -| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` | -| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` | -| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` | -| CLI shows "not installed" | Binary not in PATH | Check `which ` | -| `kiro-cli: not found` | Not in PATH | `export PATH="$HOME/.local/bin:$PATH"` | - ---- - -## Quick Setup Script (One Command) - -```bash -# Install all CLIs and configure for OmniRoute (replace with your key and server URL) -OMNIROUTE_URL="http://localhost:20128/v1" -OMNIROUTE_KEY="sk-your-omniroute-key" - -npm install -g @anthropic-ai/claude-code @openai/codex @google/gemini-cli opencode-ai cline kilecode - -# Kiro CLI -apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash - -# Write configs -mkdir -p ~/.claude ~/.codex ~/.gemini ~/.config/opencode ~/.continue - -cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" -cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" -cat > ~/.gemini/settings.json <<< "{\"apiKey\":\"$OMNIROUTE_KEY\",\"baseUrl\":\"$OMNIROUTE_URL\"}" -cat >> ~/.bashrc << EOF -export OPENAI_BASE_URL="$OMNIROUTE_URL" -export OPENAI_API_KEY="$OMNIROUTE_KEY" -export ANTHROPIC_BASE_URL="$OMNIROUTE_URL" -export ANTHROPIC_API_KEY="$OMNIROUTE_KEY" -EOF - -source ~/.bashrc -echo "โœ… All CLIs installed and configured for OmniRoute" -``` diff --git a/docs/i18n/hu/CODEBASE_DOCUMENTATION.md b/docs/i18n/hu/CODEBASE_DOCUMENTATION.md deleted file mode 100644 index e2d7950052..0000000000 --- a/docs/i18n/hu/CODEBASE_DOCUMENTATION.md +++ /dev/null @@ -1,593 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CODEBASE_DOCUMENTATION.md) - ---- - -# omniroute โ€” Codebase Documentation - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) - -> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. - ---- - -## 1. 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
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, Qoder, 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 | -| Qoder | 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"] -``` diff --git a/docs/i18n/hu/CONTRIBUTING.md b/docs/i18n/hu/CONTRIBUTING.md new file mode 100644 index 0000000000..ffc88278f7 --- /dev/null +++ b/docs/i18n/hu/CONTRIBUTING.md @@ -0,0 +1,299 @@ +# Contributing to OmniRoute (Magyar) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CONTRIBUTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CONTRIBUTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CONTRIBUTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CONTRIBUTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CONTRIBUTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CONTRIBUTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CONTRIBUTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CONTRIBUTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CONTRIBUTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CONTRIBUTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CONTRIBUTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CONTRIBUTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CONTRIBUTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CONTRIBUTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CONTRIBUTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CONTRIBUTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CONTRIBUTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CONTRIBUTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CONTRIBUTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CONTRIBUTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CONTRIBUTING.md) + +--- + +Thank you for your interest in contributing! This guide covers everything you need to get started. + +--- + +## Development Setup + +### Prerequisites + +- **Node.js** >= 18 < 24 (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` | `20128` | Server port | +| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | Base URL for frontend | +| `JWT_SECRET` | (generate above) | JWT signing secret | +| `INITIAL_PASSWORD` | `CHANGEME` | First login password | +| `APP_LOG_LEVEL` | `info` | Log verbosity level | + +### Dashboard Settings + +The dashboard provides UI toggles for features that can also be configured via environment variables: + +| Setting Location | Toggle | Description | +| ------------------- | ------------------ | ------------------------------ | +| Settings โ†’ Advanced | Debug Mode | Enable debug request logs (UI) | +| Settings โ†’ General | Sidebar Visibility | Show/hide sidebar sections | + +These settings are stored in the database and persist across restarts, overriding env var defaults when set. + +### 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:20128/dashboard` +- **API**: `http://localhost:20128/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`, `mcp`, `a2a`, `memory`, `skills`. + +--- + +## Running Tests + +```bash +# All tests (unit + vitest + ecosystem + e2e) +npm run test:all + +# Single test file (Node.js native test runner โ€” most tests use this) +node --import tsx/esm --test tests/unit/your-file.test.mjs + +# Vitest (MCP server, autoCombo, cache) +npm run test:vitest + +# E2E tests (requires Playwright) +npm run test:e2e + +# Protocol clients E2E (MCP transports, A2A) +npm run test:protocols:e2e + +# Ecosystem compatibility tests +npm run test:ecosystem + +# Coverage (55% min statements/lines/functions; 60% branches) +npm run test:coverage +npm run coverage:report + +# Lint + format check +npm run lint +npm run check +``` + +Coverage notes: + +- `npm run test:coverage` measures source coverage for the main unit test suite, excludes `tests/**`, and includes `open-sse/**` +- `npm run coverage:report` prints the detailed file-by-file report from the latest coverage run +- `npm run test:coverage:legacy` preserves the older metric for historical comparison +- See `docs/COVERAGE_PLAN.md` for the phased coverage improvement roadmap + +Current test status: **122 unit test files** covering: + +- Provider translators and format conversion +- Rate limiting, circuit breaker, and resilience +- Semantic cache, idempotency, progress tracking +- Database operations and schema (21 DB modules) +- OAuth flows and authentication +- API endpoint validation (Zod v4) +- MCP server tools and scope enforcement +- Memory and Skills systems + +--- + +## Code Style + +- **ESLint** โ€” Run `npm run lint` before committing +- **Prettier** โ€” Auto-formatted via `lint-staged` on commit (2 spaces, semicolons, double quotes, 100 char width, es5 trailing commas) +- **TypeScript** โ€” All `src/` code uses `.ts`/`.tsx`; `open-sse/` uses `.ts`/`.js`; document with TSDoc (`@param`, `@returns`, `@throws`) +- **No `eval()`** โ€” ESLint enforces `no-eval`, `no-implied-eval`, `no-new-func` +- **Zod validation** โ€” Use Zod v4 schemas for all API input validation +- **Naming**: Files = camelCase/kebab-case, components = PascalCase, constants = UPPER_SNAKE + +--- + +## Project Structure + +``` +src/ # TypeScript (.ts / .tsx) +โ”œโ”€โ”€ app/ # Next.js 16 App Router +โ”‚ โ”œโ”€โ”€ (dashboard)/ # Dashboard pages (23 sections) +โ”‚ โ”œโ”€โ”€ api/ # API routes (51 directories) +โ”‚ โ””โ”€โ”€ login/ # Auth pages (.tsx) +โ”œโ”€โ”€ domain/ # Policy engine (policyEngine, comboResolver, costRules, etc.) +โ”œโ”€โ”€ lib/ # Core business logic (.ts) +โ”‚ โ”œโ”€โ”€ a2a/ # Agent-to-Agent v0.3 protocol server +โ”‚ โ”œโ”€โ”€ acp/ # Agent Communication Protocol registry +โ”‚ โ”œโ”€โ”€ compliance/ # Compliance policy engine +โ”‚ โ”œโ”€โ”€ db/ # SQLite database layer (21 modules + 16 migrations) +โ”‚ โ”œโ”€โ”€ memory/ # Persistent conversational memory +โ”‚ โ”œโ”€โ”€ oauth/ # OAuth providers, services, and utilities +โ”‚ โ”œโ”€โ”€ skills/ # Extensible skill framework +โ”‚ โ”œโ”€โ”€ usage/ # Usage tracking and cost calculation +โ”‚ โ””โ”€โ”€ localDb.ts # Re-export layer only โ€” never add logic here +โ”œโ”€โ”€ middleware/ # Request middleware (promptInjectionGuard) +โ”œโ”€โ”€ mitm/ # MITM proxy (cert, DNS, target routing) +โ”œโ”€โ”€ shared/ +โ”‚ โ”œโ”€โ”€ components/ # React components (.tsx) +โ”‚ โ”œโ”€โ”€ constants/ # Provider definitions (60+), MCP scopes, routing strategies +โ”‚ โ”œโ”€โ”€ utils/ # Circuit breaker, sanitizer, auth helpers +โ”‚ โ””โ”€โ”€ validation/ # Zod v4 schemas +โ””โ”€โ”€ sse/ # SSE proxy pipeline + +open-sse/ # @omniroute/open-sse workspace +โ”œโ”€โ”€ executors/ # 14 provider-specific request executors +โ”œโ”€โ”€ handlers/ # 11 request handlers (chat, responses, embeddings, images, etc.) +โ”œโ”€โ”€ mcp-server/ # MCP server (25 tools, 3 transports, 10 scopes) +โ”œโ”€โ”€ services/ # 36+ services (combo, autoCombo, rateLimitManager, etc.) +โ”œโ”€โ”€ translator/ # Format translators (OpenAI โ†” Claude โ†” Gemini โ†” Responses โ†” Ollama) +โ”œโ”€โ”€ transformer/ # Responses API transformer +โ””โ”€โ”€ utils/ # 22 utility modules (stream, TLS, proxy, logging) + +electron/ # Electron desktop app (cross-platform) + +tests/ +โ”œโ”€โ”€ unit/ # Node.js test runner (122 test files) +โ”œโ”€โ”€ integration/ # Integration tests +โ”œโ”€โ”€ e2e/ # Playwright tests +โ”œโ”€โ”€ security/ # Security tests +โ”œโ”€โ”€ translator/ # Translator-specific tests +โ””โ”€โ”€ load/ # Load tests + +docs/ # Documentation +โ”œโ”€โ”€ ARCHITECTURE.md # System architecture +โ”œโ”€โ”€ API_REFERENCE.md # All endpoints +โ”œโ”€โ”€ USER_GUIDE.md # Provider setup, CLI integration +โ”œโ”€โ”€ TROUBLESHOOTING.md # Common issues +โ”œโ”€โ”€ MCP-SERVER.md # MCP server (25 tools) +โ”œโ”€โ”€ A2A-SERVER.md # A2A agent protocol +โ”œโ”€โ”€ AUTO-COMBO.md # Auto-combo engine +โ”œโ”€โ”€ CLI-TOOLS.md # CLI tools integration +โ”œโ”€โ”€ COVERAGE_PLAN.md # Test coverage improvement plan +โ”œโ”€โ”€ openapi.yaml # OpenAPI specification +โ””โ”€โ”€ adr/ # Architecture Decision Records +``` + +--- + +## Adding a New Provider + +### Step 1: Register Provider Constants + +Add to `src/shared/constants/providers.ts` โ€” Zod-validated at module load. + +### Step 2: Add Executor (if custom logic needed) + +Create executor in `open-sse/executors/your-provider.ts` extending the base executor. + +### Step 3: Add Translator (if non-OpenAI format) + +Create request/response translators in `open-sse/translator/`. + +### Step 4: Add OAuth Config (if OAuth-based) + +Add OAuth credentials in `src/lib/oauth/constants/oauth.ts` and service in `src/lib/oauth/services/`. + +### Step 5: Register Models + +Add model definitions in `open-sse/config/providerRegistry.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 +- [ ] All inputs validated with Zod schemas +- [ ] CHANGELOG updated (if user-facing change) +- [ ] Documentation updated (if applicable) + +--- + +## Releasing + +Releases are managed via the `/generate-release` workflow. When a new GitHub Release is created, the package is **automatically published to npm** via GitHub Actions. + +--- + +## Getting Help + +- **Architecture**: See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) +- **API Reference**: See [`docs/API_REFERENCE.md`](docs/API_REFERENCE.md) +- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **ADRs**: See `docs/adr/` for architectural decision records diff --git a/docs/i18n/hu/FEATURES.md b/docs/i18n/hu/FEATURES.md deleted file mode 100644 index 0185f3ba35..0000000000 --- a/docs/i18n/hu/FEATURES.md +++ /dev/null @@ -1,147 +0,0 @@ -# OmniRoute โ€” Dashboard Features Gallery (Magyar) - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) - -> ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../docs/FEATURES.md) - ---- - -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 (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. - -![Providers Dashboard](screenshots/01-providers.png) - ---- - -## ๐ŸŽจ Combos - -Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. - -![Combos Dashboard](screenshots/02-combos.png) - ---- - -## ๐Ÿ“Š Analytics - -Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. - -![Analytics Dashboard](screenshots/03-analytics.png) - ---- - -## ๐Ÿฅ System Health - -Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. - -![Health Dashboard](screenshots/04-health.png) - ---- - -## ๐Ÿ”ง Translator Playground - -Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). - -![Translator Playground](screenshots/05-translator.png) - ---- - -## ๐ŸŽฎ Model Playground _(v2.0.9+)_ - -Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. - ---- - -## ๐ŸŽจ Themes _(v2.0.5+)_ - -Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. - ---- - -## โš™๏ธ Settings - -Comprehensive settings panel with tabs: - -- **General** โ€” System storage, backup management (export/import database) -- **Appearance** โ€” Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls -- **Security** โ€” API endpoint protection, custom provider blocking, IP filtering, session info -- **Routing** โ€” Model aliases, background task degradation -- **Resilience** โ€” Rate limit persistence, circuit breaker tuning -- **Advanced** โ€” Configuration overrides - -![Settings Dashboard](screenshots/06-settings.png) - ---- - -## ๐Ÿ”ง CLI Tools - -One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. - -![CLI Tools Dashboard](screenshots/07-cli-tools.png) - ---- - -## ๐Ÿค– CLI Agents _(v2.0.11+)_ - -Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: - -- **Installation status** โ€” Installed / Not Found with version detection -- **Protocol badges** โ€” stdio, HTTP, etc. -- **Custom agents** โ€” Register any CLI tool via form (name, binary, version command, spawn args) -- **CLI Fingerprint Matching** โ€” Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP - ---- - -## ๐Ÿ–ผ๏ธ Media _(v2.0.3+)_ - -Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. - ---- - -## ๐Ÿ“ Request Logs - -Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. - -![Usage Logs](screenshots/08-usage.png) - ---- - -## ๐ŸŒ API Endpoint - -Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. - -![Endpoint Dashboard](screenshots/09-endpoint.png) - ---- - -## ๐Ÿ”‘ API Key Management - -Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. - ---- - -## ๐Ÿ“‹ Audit Log - -Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. - ---- - -## ๐Ÿ–ฅ๏ธ Desktop Application - -Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. - -Key features: - -- Server readiness polling (no blank screen on cold start) -- System tray with port management -- Content Security Policy -- Single-instance lock -- Auto-update on restart -- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) -- Hardened Electron build packaging โ€” symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+) - -๐Ÿ“– See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/hu/MCP-SERVER.md b/docs/i18n/hu/MCP-SERVER.md deleted file mode 100644 index 829acd30b1..0000000000 --- a/docs/i18n/hu/MCP-SERVER.md +++ /dev/null @@ -1,87 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/MCP-SERVER.md) - ---- - -# OmniRoute MCP Server Documentation - -> Model Context Protocol server with 16 intelligent tools - -## Installation - -OmniRoute MCP is built-in. Start it with: - -```bash -omniroute --mcp -``` - -Or via the open-sse transport: - -```bash -# HTTP streamable transport (port 20130) -omniroute --dev # MCP auto-starts on /mcp endpoint -``` - -## IDE Configuration - -See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup. - ---- - -## Essential Tools (8) - -| Tool | Description | -| :------------------------------ | :--------------------------------------- | -| `omniroute_get_health` | Gateway health, circuit breakers, uptime | -| `omniroute_list_combos` | All configured combos with models | -| `omniroute_get_combo_metrics` | Performance metrics for a specific combo | -| `omniroute_switch_combo` | Switch active combo by ID/name | -| `omniroute_check_quota` | Quota status per provider or all | -| `omniroute_route_request` | Send a chat completion through OmniRoute | -| `omniroute_cost_report` | Cost analytics for a time period | -| `omniroute_list_models_catalog` | Full model catalog with capabilities | - -## Advanced Tools (8) - -| Tool | Description | -| :--------------------------------- | :---------------------------------------------- | -| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | -| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | -| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | -| `omniroute_test_combo` | Live-test all models in a combo | -| `omniroute_get_provider_metrics` | Detailed metrics for one provider | -| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | -| `omniroute_explain_route` | Explain a past routing decision | -| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | - -## Authentication - -MCP tools are authenticated via API key scopes. Each tool requires specific scopes: - -| Scope | Tools | -| :------------- | :----------------------------------------------- | -| `read:health` | get_health, get_provider_metrics | -| `read:combos` | list_combos, get_combo_metrics | -| `write:combos` | switch_combo | -| `read:quota` | check_quota | -| `write:route` | route_request, simulate_route, test_combo | -| `read:usage` | cost_report, get_session_snapshot, explain_route | -| `write:config` | set_budget_guard, set_resilience_profile | -| `read:models` | list_models_catalog, best_combo_for_task | - -## Audit Logging - -Every tool call is logged to `mcp_tool_audit` with: - -- Tool name, arguments, result -- Duration (ms), success/failure -- API key hash, timestamp - -## Files - -| File | Purpose | -| :------------------------------------------- | :------------------------------------------ | -| `open-sse/mcp-server/server.ts` | MCP server creation + 16 tool registrations | -| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport | -| `open-sse/mcp-server/auth.ts` | API key + scope validation | -| `open-sse/mcp-server/audit.ts` | Tool call audit logging | -| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers | diff --git a/docs/i18n/hu/README.md b/docs/i18n/hu/README.md index 0f9895acd1..36d3a748cb 100644 --- a/docs/i18n/hu/README.md +++ b/docs/i18n/hu/README.md @@ -1,12 +1,12 @@ # ๐Ÿš€ OmniRoute โ€” The Free AI Gateway (Magyar) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/README.md) --- ### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback. -_Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._ +_Your universal API proxy โ€” one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._ **Chat Completions โ€ข Embeddings โ€ข Image Generation โ€ข Video โ€ข Music โ€ข Audio โ€ข Reranking โ€ข **Web Search** โ€ข MCP Server โ€ข A2A Protocol โ€ข 100% TypeScript** @@ -46,15 +46,17 @@ _Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now wi > - `APP_LOG_FILE_PATH` > - `APP_LOG_MAX_FILE_SIZE` > - `APP_LOG_RETENTION_DAYS` +> - `APP_LOG_MAX_FILES` > - `APP_LOG_LEVEL` > - `APP_LOG_FORMAT` > - `CALL_LOG_RETENTION_DAYS` +> - `CALL_LOG_MAX_ENTRIES` > > For release details and upgrade notes, see the [CHANGELOG](CHANGELOG.md). --- -## ๐Ÿ†• What's New in v3.0.0 +## ๐Ÿ†• What's New > **Upgrading from v2.9.5?** โ€” See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes. @@ -274,7 +276,7 @@ Developers pay $20โ€“200/month for Claude Pro, Codex Pro, or GitHub Copilot. Eve - **Smart 4-Tier Fallback** โ€” If subscription quota runs out, automatically redirects to API Key โ†’ Cheap โ†’ Free with zero manual intervention - **Real-Time Quota Tracking** โ€” Shows token consumption in real-time with reset countdown (5h, daily, weekly) - **Multi-Account Support** โ€” Multiple accounts per provider with auto round-robin โ€” when one runs out, switches to the next -- **Custom Combos** โ€” Customizable fallback chains with 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Custom Combos** โ€” Customizable fallback chains with 9 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random) - **Codex Business Quotas** โ€” Business/Team workspace quota monitoring directly in the dashboard @@ -286,7 +288,7 @@ OpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If **How OmniRoute solves it:** -- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 67+ providers +- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 60+ providers - **Format Translation** โ€” Automatic and transparent: OpenAI โ†” Claude โ†” Gemini โ†” Responses API - **Response Sanitization** โ€” Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+ - **Role Normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI providers; `system` โ†’ `user` for GLM/ERNIE @@ -372,7 +374,7 @@ Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code.. - **CLI Tools Dashboard** โ€” Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline - **GitHub Copilot Config Generator** โ€” Generates `chatLanguageModels.json` for VS Code with bulk model selection - **Onboarding Wizard** โ€” Guided 4-step setup for first-time users -- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 67+ providers +- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 60+ providers @@ -419,7 +421,7 @@ When a call fails, the dev doesn't know if it was a rate limit, expired token, w - **SQLite Proxy Logs** โ€” Persistent logs that survive server restarts - **Translator Playground** โ€” 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time) - **Request Telemetry** โ€” p50/p95/p99 latency + X-Request-Id tracing -- **File-Based Logging with Rotation** โ€” Console interceptor captures everything to JSON log with size-based rotation +- **File-Based Logging with Rotation** โ€” App logs rotate by size, retention days, and archive count; call log artifacts rotate by retention days and file count - **System Info Report** โ€” `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage. @@ -514,7 +516,7 @@ Developers who want all responses in a specific language, with a specific tone, - **System Prompt Injection** โ€” Global prompt applied to all requests - **Thinking Budget Validation** โ€” Reasoning token allocation control per request (passthrough, auto, custom, adaptive) -- **6 Routing Strategies** โ€” Global strategies that determine how requests are distributed +- **9 Routing Strategies** โ€” Global strategies that determine how requests are distributed - **Wildcard Router** โ€” `provider/*` patterns route dynamically to any provider - **Combo Enable/Disable Toggle** โ€” Toggle combos directly from the dashboard - **Provider Toggle** โ€” Enable/disable all connections for a provider with one click @@ -581,7 +583,7 @@ Different clients should have least-privilege access to tool categories. **How OmniRoute solves it:** -- 9 granular MCP scopes for controlled tool access +- 10 granular MCP scopes for controlled tool access - Scope enforcement and visibility in MCP management UI - Safe default posture for operational tooling @@ -1325,19 +1327,19 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. ### ๐Ÿค– Agent & Protocol Operations (v2.0) -| Feature | What It Does | -| ------------------------------------- | -------------------------------------------------------------------------------------------------- | -| ๐Ÿ”ง **MCP Server (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) | -| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | -| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | -| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | -| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | -| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | -| ๐Ÿ” **MCP Scope Enforcement** | 9 granular scope permissions for controlled tool access | -| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | -| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | -| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | -| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | +| Feature | What It Does | +| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| ๐Ÿ”ง **MCP Server (25 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools | +| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | +| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | +| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | +| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | +| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | +| ๐Ÿ” **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access | +| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | +| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | +| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | +| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | ### ๐Ÿง  Routing & Intelligence @@ -1348,7 +1350,7 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. | ๐Ÿ”„ **Format Translation** | OpenAI โ†” Claude โ†” Gemini โ†” Responses with schema-safe conversions | | ๐Ÿ‘ฅ **Multi-Account Support** | Multiple accounts per provider with intelligent selection | | ๐Ÿ”„ **Auto Token Refresh** | OAuth tokens refresh automatically with retry | -| ๐ŸŽจ **Custom Combos** | 6 balancing strategies + fallback chain control | +| ๐ŸŽจ **Custom Combos** | 9 balancing strategies + fallback chain control | | ๐ŸŒ **Wildcard Router** | `provider/*` dynamic routing | | ๐Ÿง  **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits | | ๐Ÿ”€ **Model Aliases** | Built-in + custom model aliasing and migration safety | @@ -1949,6 +1951,7 @@ opencode - Request artifacts are written to `DATA_DIR/call_logs/` as one JSON file per request - Enable pipeline capture from Dashboard โ†’ Logs โ†’ Request Logs if you need detailed per-stage payloads - Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log` +- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed **Connection test shows "Invalid" for OpenAI-compatible providers** diff --git a/docs/i18n/hu/RELEASE_CHECKLIST.md b/docs/i18n/hu/RELEASE_CHECKLIST.md deleted file mode 100644 index 903e812c3f..0000000000 --- a/docs/i18n/hu/RELEASE_CHECKLIST.md +++ /dev/null @@ -1,37 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/RELEASE_CHECKLIST.md) - ---- - -# Release Checklist - -Use this checklist before tagging or publishing a new OmniRoute release. - -## Version and Changelog - -1. Bump `package.json` version (`x.y.z`) in the release branch. -2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: - - `## [x.y.z] โ€” YYYY-MM-DD` -3. Keep `## [Unreleased]` as the first changelog section for upcoming work. -4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. - -## API Docs - -1. Update `docs/openapi.yaml`: - - `info.version` must equal `package.json` version. -2. Validate endpoint examples if API contracts changed. - -## Runtime Docs - -1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. -2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. -3. Update localized docs if source docs changed significantly. - -## Automated Check - -Run the sync guard locally before opening PR: - -```bash -npm run check:docs-sync -``` - -CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/hu/SECURITY.md b/docs/i18n/hu/SECURITY.md new file mode 100644 index 0000000000..5e6595fe56 --- /dev/null +++ b/docs/i18n/hu/SECURITY.md @@ -0,0 +1,179 @@ +# Security Policy (Magyar) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../SECURITY.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/SECURITY.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/SECURITY.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/SECURITY.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/SECURITY.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/SECURITY.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/SECURITY.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/SECURITY.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/SECURITY.md) + +--- + +## 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 | +| ------- | -------------- | +| 3.4.x | โœ… Active | +| 3.0.x | โœ… Security | +| < 3.0.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 | +| **MCP Scopes** | 10 granular scopes for MCP tool access control | + +### ๐Ÿ›ก๏ธ 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:::` +- 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** | Allowlist/blocklist IP ranges in dashboard | +| **Rate Limiting** | Per-provider rate limits with automatic backoff | +| **Anti-Thundering Herd** | Mutex + per-connection locking prevents cascading 502s | +| **TLS Fingerprint** | Browser-like TLS fingerprint spoofing to reduce bot detection | +| **CLI Fingerprint** | Per-provider header/body ordering to match native CLI signatures | + +### ๐Ÿ”Œ Resilience & Availability + +| 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 `CALL_LOG_RETENTION_DAYS` | +| **No-Log Opt-out** | Per API key `noLog` flag disables request logging | +| **Audit Log** | Administrative actions tracked in `audit_log` table | +| **MCP Audit** | SQLite-backed audit logging for all MCP tool calls | +| **Zod Validation** | All API inputs validated with Zod v4 schemas at module load | + +--- + +## 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 +- Provider constants validated at module load via Zod (`src/shared/validation/providerSchema.ts`) diff --git a/docs/i18n/hu/TROUBLESHOOTING.md b/docs/i18n/hu/TROUBLESHOOTING.md deleted file mode 100644 index 63c148000a..0000000000 --- a/docs/i18n/hu/TROUBLESHOOTING.md +++ /dev/null @@ -1,258 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/TROUBLESHOOTING.md) - ---- - -# Troubleshooting - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/TROUBLESHOOTING.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/TROUBLESHOOTING.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/TROUBLESHOOTING.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/TROUBLESHOOTING.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/TROUBLESHOOTING.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/TROUBLESHOOTING.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/TROUBLESHOOTING.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/TROUBLESHOOTING.md) - -Common problems and solutions for OmniRoute. - ---- - -## Quick Fixes - -| Problem | Solution | -| ----------------------------- | ------------------------------------------------------------------ | -| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | -| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | -| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | -| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | -| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | - ---- - -## Provider Issues - -### "Language model did not provide messages" - -**Cause:** Provider quota exhausted. - -**Fix:** - -1. 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, Qoder) 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}/storage.sqlite` (providers, combos, aliases, keys, settings) -- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` -- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) - ---- - -## Circuit Breaker Issues - -### Provider stuck in OPEN state - -When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. - -**Fix:** - -1. 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 -- **SDK returns raw string instead of object** โ€” Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures -- **GLM/ERNIE rejects `system` role** โ€” Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models -- **`developer` role not recognized** โ€” Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers -- **`json_schema` not working with Gemini** โ€” Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` - ---- - -## Resilience Settings - -### Auto rate-limit not triggering - -- 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. - ---- - -## Optional RAG / LLM failure taxonomy (16 problems) - -Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. - -In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. - -If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: - -- retrieval drift and broken context boundaries -- empty or stale indexes and vector stores -- embedding versus semantic mismatch -- prompt assembly and context window issues -- logic collapse and overconfident answers -- long chain and agent coordination failures -- multi agent memory and role drift -- deployment and bootstrap ordering problems - -The idea is simple: - -1. When you investigate a bad response, capture: - - user task and request - - route or provider combo in OmniRoute - - any RAG context used downstream (retrieved documents, tool calls, etc) -2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` โ€ฆ `No.16`). -3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. -4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. - -Full text and concrete recipes live here (MIT license, text only): - -[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) - -You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. - ---- - -## Still Stuck? - -- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details -- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints -- **Health Dashboard**: Check **Dashboard โ†’ Health** for real-time system status -- **Translator**: Use **Dashboard โ†’ Translator** to debug format issues diff --git a/docs/i18n/hu/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/hu/VM_DEPLOYMENT_GUIDE.md deleted file mode 100644 index 09d559e465..0000000000 --- a/docs/i18n/hu/VM_DEPLOYMENT_GUIDE.md +++ /dev/null @@ -1,401 +0,0 @@ -# OmniRoute โ€” Telepรญtรฉsi รบtmutatรณ a Cloudflare-rel rendelkezล‘ virtuรกlis gรฉpen - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](../pt-BR/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](../es/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](../fr/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](../it/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](../ru/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](../zh-CN/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](../de/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](../in/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](../th/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](../uk-UA/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](../ar/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](../ja/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](../vi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](../bg/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](../da/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](../fi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](../he/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](../hu/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](../id/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](../ko/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](../ms/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](../nl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](../no/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](../pt/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](../ro/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](../pl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](../sk/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](../sv/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](../phi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](../cs/VM_DEPLOYMENT_GUIDE.md) - -Teljes รบtmutatรณ az OmniRoute telepรญtรฉsรฉhez รฉs konfigurรกlรกsรกhoz Cloudflare-en keresztรผl kezelt tartomรกnyรบ virtuรกlis gรฉpen (VPS). - ---- - -## Elล‘feltรฉtelek - -| Tรฉtel | Minimum | Ajรกnlott | -| ----------- | ------------------------- | ---------------- | -| **CPU** | 1 vCPU | 2 vCPU | -| **RAM** | 1 GB | 2 GB | -| **Lemez** | 10 GB SSD | 25 GB SSD | -| **OS** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS | -| **Domain** | Regisztrรกlva a Cloudflare | โ€” | -| **Dokkolรณ** | Docker Engine 24+ | Docker 27+ | - -**Tesztelt szolgรกltatรณk**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. - ---- - -## 1. Konfigurรกlja a virtuรกlis gรฉpet - -### 1.1 Hozza lรฉtre a pรฉldรกnyt - -A vรกlasztott VPS-szolgรกltatรณnรกl: - -- Vรกlassza az Ubuntu 24.04 LTS-t -- Vรกlassza ki a minimรกlis csomagot (1 vCPU / 1 GB RAM) -- รllรญtson be erล‘s root jelszรณt vagy konfigurรกlja az SSH-kulcsot -- Jegyezze fel a **nyilvรกnos IP-cรญmet** (pl. `203.0.113.10`) - -### 1.2 Csatlakozรกs SSH-n keresztรผl - -```bash -ssh root@203.0.113.10 -``` - -### 1.3 Frissรญtse a rendszert - -```bash -apt update && apt upgrade -y -``` - -### 1.4 Telepรญtse a Dockert - -```bash -# Install dependencies -apt install -y ca-certificates curl gnupg - -# Add official Docker repository -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 Az nginx telepรญtรฉse - -```bash -apt install -y nginx -``` - -### 1.6 Tลฑzfal konfigurรกlรกsa (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 -``` - -> **Tipp**: A maximรกlis biztonsรกg รฉrdekรฉben korlรกtozza a 80-as รฉs 443-as portot csak a Cloudflare IP-cรญmekre. Lรกsd a [Advanced Security](#advanced-security) rรฉszt. - ---- - -## 2. Telepรญtse az OmniRoute programot - -### 2.1 Konfigurรกciรณs kรถnyvtรกr lรฉtrehozรกsa - -```bash -mkdir -p /opt/omniroute -``` - -### 2.2 Kรถrnyezeti vรกltozรณk fรกjl lรฉtrehozรกsa - -```bash -cat > /opt/omniroute/.env << โ€˜EOFโ€™ -# === Security === -JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY -INITIAL_PASSWORD=YourSecurePassword123! -API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY -STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY -STORAGE_ENCRYPTION_KEY_VERSION=v1 -MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT - -# === 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 (change to your domain) === -BASE_URL=https://llms.seudominio.com -NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com - -# === Cloud Sync (optional) === -# CLOUD_URL=https://cloud.omniroute.online -# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online -EOF -``` - -> โš ๏ธ **FONTOS**: Hozzon lรฉtre egyedi titkos kulcsokat! Minden kulcshoz hasznรกlja az `openssl rand -hex 32` รฉrtรฉket. - -### 2.3 Indรญtsa el a tรกrolรณt - -```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 Ellenล‘rizze, hogy fut-e - -```bash -docker ps | grep omniroute -docker logs omniroute --tail 20 -``` - -Meg kell jelennie: `[DB] SQLite database ready` รฉs `listening on port 20128`. - ---- - -## 3. Az nginx (fordรญtott proxy) konfigurรกlรกsa - -### 3.1 SSL-tanรบsรญtvรกny generรกlรกsa (Cloudflare Origin) - -A Cloudflare irรกnyรญtรณpulton: - -1. Nyissa meg az **SSL/TLS โ†’ Origin Server** lehetล‘sรฉget. -2. Kattintson a **Tanรบsรญtvรกny lรฉtrehozรกsa** lehetล‘sรฉgre. -3. Tartsa meg az alapรฉrtelmezett รฉrtรฉkeket (15 รฉv, \*.sajatdomain.com) -4. Mรกsolja ki az **Eredeti tanรบsรญtvรกnyt** รฉs a **Privรกt kulcsot** - -```bash -mkdir -p /etc/nginx/ssl - -# Paste the certificate -nano /etc/nginx/ssl/origin.crt - -# Paste the private key -nano /etc/nginx/ssl/origin.key - -chmod 600 /etc/nginx/ssl/origin.key -``` - -### 3.2 Nginx konfigurรกciรณ - -```bash -cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ -# Default server โ€” blocks direct access via 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.yourdomain.com; # Change to your domain - - 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.yourdomain.com; - return 301 https://$server_name$request_uri; -} -NGINX -``` - -### 3.3 Engedรฉlyezรฉs รฉs tesztelรฉs - -```bash -# Remove default configuration -rm -f /etc/nginx/sites-enabled/default - -# Enable OmniRoute -ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute - -# Test and reload -nginx -t && systemctl reload nginx -``` - ---- - -## 4. Konfigurรกlja a Cloudflare DNS-t - -### 4.1 DNS-rekord hozzรกadรกsa - -A Cloudflare irรกnyรญtรณpulton โ†’ DNS: - -| Tรญpus | Nรฉv | Tartalom | Proxy | -| ----- | ------ | ---------------------- | ----------------- | -| A | `llms` | `203.0.113.10` (VM IP) | โœ… Meghatalmazott | - -### 4.2 SSL konfigurรกlรกsa - -Az **SSL/TLS โ†’ รttekintรฉs** alatt: - -- Mรณd: **Teljes (szigorรบ)** - -**SSL/TLS โ†’ Edge Certificates** alatt: - -- Mindig hasznรกljon HTTPS-t: โœ… Be -- Minimรกlis TLS-verziรณ: TLS 1.2 -- Automatikus HTTPS-รบjraรญrรกsok: โœ… Be - -### 4.3 Tesztelรฉs - -```bash -curl -sI https://llms.seudominio.com/health -# Should return HTTP/2 200 -``` - ---- - -## 5. Mลฑveletek รฉs karbantartรกs - -### Frissรญtsen egy รบj verziรณra - -```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 -``` - -### Naplรณk megtekintรฉse - -```bash -docker logs -f omniroute # Real-time stream -docker logs omniroute --tail 50 # Last 50 lines -``` - -### Manuรกlis adatbรกzis-mentรฉs - -```bash -# Copy data from the volume to the host -docker cp omniroute:/app/data ./backup-$(date +%F) - -# Or compress the entire volume -docker run --rm -v omniroute-data:/data -v $(pwd):/backup \ - alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data -``` - -### Visszaรกllรญtรกs biztonsรกgi mรกsolatbรณl - -```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. Speciรกlis biztonsรกg - -### Az nginx korlรกtozรกsa a Cloudflare IP-cรญmekre - -```bash -cat > /etc/nginx/cloudflare-ips.conf << โ€˜CFโ€™ -# Cloudflare IPv4 ranges โ€” update periodically -# 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 -``` - -Adja hozzรก a kรถvetkezล‘ket a `nginx.conf` elemhez a `http {}` blokkon belรผl: - -```nginx -include /etc/nginx/cloudflare-ips.conf; -``` - -### Telepรญtse a fail2ban-t - -```bash -apt install -y fail2ban -systemctl enable fail2ban -systemctl start fail2ban - -# Check status -fail2ban-client status sshd -``` - -### A Docker-porthoz valรณ kรถzvetlen hozzรกfรฉrรฉs letiltรกsa - -```bash -# Prevent direct external access to port 20128 -iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP -iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT - -# Persist the rules -apt install -y iptables-persistent -netfilter-persistent save -``` - ---- - -## 7. Telepรญtรฉs a Cloudflare Workers szรกmรกra (opcionรกlis) - -A Cloudflare Workersen keresztรผli tรกvoli elรฉrรฉshez (a virtuรกlis gรฉp kรถzvetlen feltรกrรกsa nรฉlkรผl): - -```bash -# In the local repository -cd omnirouteCloud -npm install -npx wrangler login -npx wrangler deploy -``` - -Tekintse meg a teljes dokumentรกciรณt: [omnirouteCloud/README.md](../omnirouteCloud/README.md). - ---- - -## Port รถsszefoglalรณ - -| Kikรถtล‘ | Szolgรกltatรกs | Hozzรกfรฉrรฉs | -| ------ | ------------ | ----------------------------------- | -| 22 | SSH | Nyilvรกnos (fail2ban-nal) | -| 80 | nginx HTTP | รtirรกnyรญtรกs โ†’ HTTPS | -| 443 | nginx HTTPS | Cloudflare Proxy segรญtsรฉgรฉvel | -| 20128 | OmniRoute | Csak Localhost (nginx-en keresztรผl) | diff --git a/docs/i18n/da/A2A-SERVER.md b/docs/i18n/hu/docs/A2A-SERVER.md similarity index 77% rename from docs/i18n/da/A2A-SERVER.md rename to docs/i18n/hu/docs/A2A-SERVER.md index 01531ff482..14946eca62 100644 --- a/docs/i18n/da/A2A-SERVER.md +++ b/docs/i18n/hu/docs/A2A-SERVER.md @@ -1,9 +1,9 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/A2A-SERVER.md) +# OmniRoute A2A Server Documentation (Magyar) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/A2A-SERVER.md) --- -# OmniRoute A2A Server Documentation - > Agent-to-Agent Protocol v0.3 โ€” OmniRoute as an intelligent routing agent ## Agent Discovery diff --git a/docs/i18n/da/API_REFERENCE.md b/docs/i18n/hu/docs/API_REFERENCE.md similarity index 74% rename from docs/i18n/da/API_REFERENCE.md rename to docs/i18n/hu/docs/API_REFERENCE.md index b878605221..9702f795f7 100644 --- a/docs/i18n/da/API_REFERENCE.md +++ b/docs/i18n/hu/docs/API_REFERENCE.md @@ -1,11 +1,9 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/API_REFERENCE.md) +# API Reference (Magyar) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/API_REFERENCE.md) --- -# API Reference - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/API_REFERENCE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/API_REFERENCE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/API_REFERENCE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/API_REFERENCE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/API_REFERENCE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/API_REFERENCE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/API_REFERENCE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/API_REFERENCE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/API_REFERENCE.md) - Complete reference for all OmniRoute API endpoints. --- @@ -42,15 +40,20 @@ Content-Type: application/json ### 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 | +| Header | Direction | Description | +| ------------------------ | --------- | ------------------------------------------------ | +| `X-OmniRoute-No-Cache` | Request | Set to `true` to bypass cache | +| `X-OmniRoute-Progress` | Request | Set to `true` for progress events | +| `X-Session-Id` | Request | Sticky session key for external session affinity | +| `x_session_id` | Request | Underscore variant also accepted (direct HTTP) | +| `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 | +| `X-OmniRoute-Session-Id` | Response | Effective session ID used by OmniRoute | + +> Nginx note: if you rely on underscore headers (for example `x_session_id`), enable `underscores_in_headers on;`. --- @@ -141,10 +144,10 @@ The provider prefix is auto-added if missing. Mismatched models return `400`. ```bash # Get cache stats -GET /api/cache +GET /api/cache/stats # Clear all caches -DELETE /api/cache +DELETE /api/cache/stats ``` Response example: @@ -215,23 +218,23 @@ Response example: ### 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 | +| Endpoint | Method | Description | +| ------------------------------- | ------------- | ---------------------- | +| `/api/settings` | GET/PUT/PATCH | 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 | +| Endpoint | Method | Description | +| ------------------------ | ---------- | ---------------------------------------------------------------------------------------------------- | +| `/api/sessions` | GET | Active session tracking | +| `/api/rate-limits` | GET | Per-account rate limits | +| `/api/monitoring/health` | GET | Health check + provider summary (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`) | +| `/api/cache/stats` | GET/DELETE | Cache stats / clear | ### Backup & Export/Import @@ -252,6 +255,13 @@ Response example: | `/api/sync/initialize` | POST | Initialize sync | | `/api/cloud/*` | Various | Cloud management | +### Tunnels + +| Endpoint | Method | Description | +| -------------------------- | ------ | ----------------------------------------------------------------------- | +| `/api/tunnels/cloudflared` | GET | Read Cloudflare Quick Tunnel install/runtime status for the dashboard | +| `/api/tunnels/cloudflared` | POST | Enable or disable the Cloudflare Quick Tunnel (`action=enable/disable`) | + ### CLI Tools | Endpoint | Method | Description | @@ -276,12 +286,12 @@ GET response includes `agents[]` (id, name, binary, version, installed, protocol ### 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 | +| Endpoint | Method | Description | +| ----------------------- | --------- | ------------------------------- | +| `/api/resilience` | GET/PATCH | 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 diff --git a/docs/i18n/bg/ARCHITECTURE.md b/docs/i18n/hu/docs/ARCHITECTURE.md similarity index 89% rename from docs/i18n/bg/ARCHITECTURE.md rename to docs/i18n/hu/docs/ARCHITECTURE.md index 4ea06a29f2..530ba3dad8 100644 --- a/docs/i18n/bg/ARCHITECTURE.md +++ b/docs/i18n/hu/docs/ARCHITECTURE.md @@ -1,12 +1,10 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/ARCHITECTURE.md) +# OmniRoute Architecture (Magyar) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/ARCHITECTURE.md) --- -# OmniRoute Architecture - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/ARCHITECTURE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/ARCHITECTURE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/ARCHITECTURE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/ARCHITECTURE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/ARCHITECTURE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/ARCHITECTURE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/ARCHITECTURE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/ARCHITECTURE.md) - -_Last updated: 2026-03-04_ +_Last updated: 2026-03-28_ ## Executive Summary @@ -69,6 +67,26 @@ Primary runtime model: - Provider SLA/control plane outside local process - External CLI binaries themselves (Claude CLI, Codex CLI, etc.) +## Dashboard Surface (Current) + +Main pages under `src/app/(dashboard)/dashboard/`: + +- `/dashboard` โ€” quick start + provider overview +- `/dashboard/endpoint` โ€” endpoint proxy + MCP + A2A + API endpoint tabs +- `/dashboard/providers` โ€” provider connections and credentials +- `/dashboard/combos` โ€” combo strategies, templates, model routing rules +- `/dashboard/costs` โ€” cost aggregation and pricing visibility +- `/dashboard/analytics` โ€” usage analytics and evaluations +- `/dashboard/limits` โ€” quota/rate controls +- `/dashboard/cli-tools` โ€” CLI onboarding, runtime detection, config generation +- `/dashboard/agents` โ€” detected ACP agents + custom agent registration +- `/dashboard/media` โ€” image/video/music playground +- `/dashboard/search-tools` โ€” search provider testing and history +- `/dashboard/health` โ€” uptime, circuit breakers, rate limits +- `/dashboard/logs` โ€” request/proxy/audit/console logs +- `/dashboard/settings` โ€” system settings tabs (general, routing, combo defaults, etc.) +- `/dashboard/api-manager` โ€” API key lifecycle and model permissions + ## High-Level System Context ```mermaid @@ -258,8 +276,9 @@ Domain State DB (SQLite): ## 5) Cloud Sync -- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` +- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts`, `src/shared/services/modelSyncScheduler.ts` - Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Periodic task: `src/shared/services/modelSyncScheduler.ts` - Control route: `src/app/api/sync/cloud/route.ts` ## Request Lifecycle (`/v1/chat/completions`) @@ -339,7 +358,7 @@ flowchart TD Q -- No --> R[Return all unavailable] ``` -Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics. +Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics. Combo routing adds one extra guard: provider-scoped 400s such as upstream content-block and role-validation failures are treated as model-local failures so later combo targets can still run. ## OAuth Onboarding and Token Refresh Lifecycle @@ -669,25 +688,25 @@ Additional processing layers in the translation pipeline: ## 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 | +| 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` | Provider Models | Provider model metadata backing custom and managed available models | ## Bypass Handler @@ -739,10 +758,18 @@ Runtime visibility sources: - console logs from `src/sse/utils/logger.ts` - per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- four-stage detailed payload captures in SQLite (`request_detail_logs`) when `settings.detailed_logs_enabled=true` - textual request status log in `log.txt` (optional/compat) - optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` - dashboard usage endpoints (`/api/usage/*`) for UI consumption +Detailed request payload capture stores up to four JSON payload stages per routed call: + +- raw request received from the client +- translated request actually sent upstream +- provider response reconstructed as JSON; streamed responses are compacted to the final summary plus stream metadata +- final client response returned by OmniRoute; streamed responses are stored in the same compact summary form + ## Security-Sensitive Boundaries - JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing diff --git a/docs/i18n/da/AUTO-COMBO.md b/docs/i18n/hu/docs/AUTO-COMBO.md similarity index 65% rename from docs/i18n/da/AUTO-COMBO.md rename to docs/i18n/hu/docs/AUTO-COMBO.md index 2166e41dff..7d754b6027 100644 --- a/docs/i18n/da/AUTO-COMBO.md +++ b/docs/i18n/hu/docs/AUTO-COMBO.md @@ -1,9 +1,9 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/AUTO-COMBO.md) +# OmniRoute Auto-Combo Engine (Magyar) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/AUTO-COMBO.md) --- -# OmniRoute Auto-Combo Engine - > Self-managing model chains with adaptive scoring ## How It Works diff --git a/docs/i18n/hu/docs/CLI-TOOLS.md b/docs/i18n/hu/docs/CLI-TOOLS.md new file mode 100644 index 0000000000..de160b39ae --- /dev/null +++ b/docs/i18n/hu/docs/CLI-TOOLS.md @@ -0,0 +1,348 @@ +# CLI Tools Setup Guide โ€” OmniRoute (Magyar) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CLI-TOOLS.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CLI-TOOLS.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CLI-TOOLS.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CLI-TOOLS.md) + +--- + +This guide explains how to install and configure all supported AI coding CLI tools +to use **OmniRoute** as the unified backend, giving you centralized key management, +cost tracking, model switching, and request logging across every tool. + +--- + +## How It Works + +``` +Claude / Codex / OpenCode / Cline / KiloCode / Continue / Kiro / Cursor / Copilot + โ”‚ + โ–ผ (all point to OmniRoute) + http://YOUR_SERVER:20128/v1 + โ”‚ + โ–ผ (OmniRoute routes to the right provider) + Anthropic / OpenAI / Gemini / DeepSeek / Groq / Mistral / ... +``` + +**Benefits:** + +- One API key to manage all tools +- Cost tracking across all CLIs in the dashboard +- Model switching without reconfiguring every tool +- Works locally and on remote servers (VPS) + +--- + +## Supported Tools (Dashboard Source of Truth) + +The dashboard cards in `/dashboard/cli-tools` are generated from `src/shared/constants/cliTools.ts`. +Current list (v3.0.0-rc.16): + +| Tool | ID | Command | Setup Mode | Install Method | +| ------------------ | ------------- | ---------- | ---------- | -------------- | +| **Claude Code** | `claude` | `claude` | env | npm | +| **OpenAI Codex** | `codex` | `codex` | custom | npm | +| **Factory Droid** | `droid` | `droid` | custom | bundled/CLI | +| **OpenClaw** | `openclaw` | `openclaw` | custom | bundled/CLI | +| **Cursor** | `cursor` | app | guide | desktop app | +| **Cline** | `cline` | `cline` | custom | npm | +| **Kilo Code** | `kilo` | `kilocode` | custom | npm | +| **Continue** | `continue` | extension | guide | VS Code | +| **Antigravity** | `antigravity` | internal | mitm | OmniRoute | +| **GitHub Copilot** | `copilot` | extension | custom | VS Code | +| **OpenCode** | `opencode` | `opencode` | guide | npm | +| **Kiro AI** | `kiro` | app/cli | mitm | desktop/CLI | + +### CLI fingerprint sync (Agents + Settings) + +`/dashboard/agents` and `Settings > CLI Fingerprint` use `src/shared/constants/cliCompatProviders.ts`. +This keeps provider IDs aligned with CLI cards and legacy IDs. + +| CLI ID | Fingerprint Provider ID | +| ---------------------------------------------------------------------------------------------------- | ----------------------- | +| `kilo` | `kilocode` | +| `copilot` | `github` | +| `claude` / `codex` / `antigravity` / `kiro` / `cursor` / `cline` / `opencode` / `droid` / `openclaw` | same ID | + +Legacy IDs still accepted for compatibility: `copilot`, `kimi-coding`, `qwen`. + +--- + +## Step 1 โ€” Get an OmniRoute API Key + +1. Open the OmniRoute dashboard โ†’ **API Manager** (`/dashboard/api-manager`) +2. Click **Create API Key** +3. Give it a name (e.g. `cli-tools`) and select all permissions +4. Copy the key โ€” you'll need it for every CLI below + +> Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` + +--- + +## Step 2 โ€” Install CLI Tools + +All npm-based tools require Node.js 18+: + +```bash +# Claude Code (Anthropic) +npm install -g @anthropic-ai/claude-code + +# OpenAI Codex +npm install -g @openai/codex + +# OpenCode +npm install -g opencode-ai + +# Cline +npm install -g cline + +# KiloCode +npm install -g kilocode + +# Kiro CLI (Amazon โ€” requires curl + unzip) +apt-get install -y unzip # on Debian/Ubuntu +curl -fsSL https://cli.kiro.dev/install | bash +export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc +``` + +**Verify:** + +```bash +claude --version # 2.x.x +codex --version # 0.x.x +opencode --version # x.x.x +cline --version # 2.x.x +kilocode --version # x.x.x (or: kilo --version) +kiro-cli --version # 1.x.x +``` + +--- + +## Step 3 โ€” Set Global Environment Variables + +Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`: + +```bash +# OmniRoute Universal Endpoint +export OPENAI_BASE_URL="http://localhost:20128/v1" +export OPENAI_API_KEY="sk-your-omniroute-key" +export ANTHROPIC_BASE_URL="http://localhost:20128/v1" +export ANTHROPIC_API_KEY="sk-your-omniroute-key" +export GEMINI_BASE_URL="http://localhost:20128/v1" +export GEMINI_API_KEY="sk-your-omniroute-key" +``` + +> For a **remote server** replace `localhost:20128` with the server IP or domain, +> e.g. `http://192.168.0.15:20128`. + +--- + +## Step 4 โ€” Configure Each Tool + +### Claude Code + +```bash +# Via CLI: +claude config set --global api-base-url http://localhost:20128/v1 + +# Or create ~/.claude/settings.json: +mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF +{ + "apiBaseUrl": "http://localhost:20128/v1", + "apiKey": "sk-your-omniroute-key" +} +EOF +``` + +**Test:** `claude "say hello"` + +--- + +### OpenAI Codex + +```bash +mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF +model: auto +apiKey: sk-your-omniroute-key +apiBaseUrl: http://localhost:20128/v1 +EOF +``` + +**Test:** `codex "what is 2+2?"` + +--- + +### OpenCode + +```bash +mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF +[provider.openai] +base_url = "http://localhost:20128/v1" +api_key = "sk-your-omniroute-key" +EOF +``` + +**Test:** `opencode` + +--- + +### Cline (CLI or VS Code) + +**CLI mode:** + +```bash +mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF +{ + "apiProvider": "openai", + "openAiBaseUrl": "http://localhost:20128/v1", + "openAiApiKey": "sk-your-omniroute-key" +} +EOF +``` + +**VS Code mode:** +Cline extension settings โ†’ API Provider: `OpenAI Compatible` โ†’ Base URL: `http://localhost:20128/v1` + +Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ Cline โ†’ Apply Config**. + +--- + +### KiloCode (CLI or VS Code) + +**CLI mode:** + +```bash +kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key +``` + +**VS Code settings:** + +```json +{ + "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", + "kilo-code.apiKey": "sk-your-omniroute-key" +} +``` + +Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ KiloCode โ†’ Apply Config**. + +--- + +### Continue (VS Code Extension) + +Edit `~/.continue/config.yaml`: + +```yaml +models: + - name: OmniRoute + provider: openai + model: auto + apiBase: http://localhost:20128/v1 + apiKey: sk-your-omniroute-key + default: true +``` + +Restart VS Code after editing. + +--- + +### Kiro CLI (Amazon) + +```bash +# Login to your AWS/Kiro account: +kiro-cli login + +# The CLI uses its own auth โ€” OmniRoute is not needed as backend for Kiro CLI itself. +# Use kiro-cli alongside OmniRoute for other tools. +kiro-cli status +``` + +--- + +### Cursor (Desktop App) + +> **Note:** Cursor routes requests through its cloud. For OmniRoute integration, +> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL. + +Via GUI: **Settings โ†’ Models โ†’ OpenAI API Key** + +- Base URL: `https://your-domain.com/v1` +- API Key: your OmniRoute key + +--- + +## Dashboard Auto-Configuration + +The OmniRoute dashboard automates configuration for most tools: + +1. Go to `http://localhost:20128/dashboard/cli-tools` +2. Expand any tool card +3. Select your API key from the dropdown +4. Click **Apply Config** (if tool is detected as installed) +5. Or copy the generated config snippet manually + +--- + +## Built-in Agents: Droid & OpenClaw + +**Droid** and **OpenClaw** are AI agents built directly into OmniRoute โ€” no installation needed. +They run as internal routes and use OmniRoute's model routing automatically. + +- Access: `http://localhost:20128/dashboard/agents` +- Configure: same combos and providers as all other tools +- No API key or CLI install required + +--- + +## Available API Endpoints + +| Endpoint | Description | Use For | +| -------------------------- | ----------------------------- | --------------------------- | +| `/v1/chat/completions` | Standard chat (all providers) | All modern tools | +| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows | +| `/v1/completions` | Legacy text completions | Older tools using `prompt:` | +| `/v1/embeddings` | Text embeddings | RAG, search | +| `/v1/images/generations` | Image generation | DALL-E, Flux, etc. | +| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS | +| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI | + +--- + +## Hibaelhรกrรญtรกs + +| Error | Cause | Fix | +| ------------------------- | ----------------------- | ------------------------------------------ | +| `Connection refused` | OmniRoute not running | `pm2 start omniroute` | +| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` | +| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` | +| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` | +| CLI shows "not installed" | Binary not in PATH | Check `which ` | +| `kiro-cli: not found` | Not in PATH | `export PATH="$HOME/.local/bin:$PATH"` | + +--- + +## Quick Setup Script (One Command) + +```bash +# Install all CLIs and configure for OmniRoute (replace with your key and server URL) +OMNIROUTE_URL="http://localhost:20128/v1" +OMNIROUTE_KEY="sk-your-omniroute-key" + +npm install -g @anthropic-ai/claude-code @openai/codex opencode-ai cline kilocode + +# Kiro CLI +apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash + +# Write configs +mkdir -p ~/.claude ~/.codex ~/.config/opencode ~/.continue + +cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" +cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" +cat >> ~/.bashrc << EOF +export OPENAI_BASE_URL="$OMNIROUTE_URL" +export OPENAI_API_KEY="$OMNIROUTE_KEY" +export ANTHROPIC_BASE_URL="$OMNIROUTE_URL" +export ANTHROPIC_API_KEY="$OMNIROUTE_KEY" +EOF + +source ~/.bashrc +echo "โœ… All CLIs installed and configured for OmniRoute" +``` diff --git a/docs/i18n/hu/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/hu/docs/CODEBASE_DOCUMENTATION.md new file mode 100644 index 0000000000..ccb188ac92 --- /dev/null +++ b/docs/i18n/hu/docs/CODEBASE_DOCUMENTATION.md @@ -0,0 +1,591 @@ +# omniroute โ€” Codebase Documentation (Magyar) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CODEBASE_DOCUMENTATION.md) + +--- + +> 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
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, Qoder, 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. + +#### Architektรบra + +```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 | +| Qoder | 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"] +``` diff --git a/docs/i18n/hu/docs/COVERAGE_PLAN.md b/docs/i18n/hu/docs/COVERAGE_PLAN.md new file mode 100644 index 0000000000..617d5d6da1 --- /dev/null +++ b/docs/i18n/hu/docs/COVERAGE_PLAN.md @@ -0,0 +1,170 @@ +# Test Coverage Plan (Magyar) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/COVERAGE_PLAN.md) + +--- + +Last updated: 2026-03-28 + +## Baseline + +There are multiple coverage numbers depending on how the report is computed. For planning, only one of them is useful. + +| Metric | Scope | Statements / Lines | Branches | Functions | Notes | +| -------------------- | ----------------------------------------------------- | -----------------: | -------: | --------: | --------------------------------------------------- | +| Legacy | Old `npm run test:coverage` | 79.42% | 75.15% | 67.94% | Inflated: counts test files and excludes `open-sse` | +| Diagnostic | Source-only, excluding tests and excluding `open-sse` | 68.16% | 63.55% | 64.06% | Useful only to isolate `src/**` | +| Recommended baseline | Source-only, excluding tests and including `open-sse` | 56.95% | 66.05% | 57.80% | This is the project-wide baseline to improve | + +The recommended baseline is the number to optimize against. + +## Rules + +- Coverage targets apply to source files, not to `tests/**`. +- `open-sse/**` is part of the product and must remain in scope. +- New code should not reduce coverage in touched areas. +- Prefer testing behavior and branch outcomes over implementation details. +- Prefer temp SQLite databases and small fixtures over broad mocks for `src/lib/db/**`. + +## Current command set + +- `npm run test:coverage` + - Main source coverage gate for the unit test suite + - Generates `text-summary`, `html`, `json-summary`, and `lcov` +- `npm run coverage:report` + - Detailed file-by-file report from the latest run +- `npm run test:coverage:legacy` + - Historical comparison only + +## Milestones + +| Phase | Target | Focus | +| ------- | ---------------------: | ------------------------------------------------- | +| Phase 1 | 60% statements / lines | Quick wins and low-risk utility coverage | +| Phase 2 | 65% statements / lines | DB and route foundations | +| Phase 3 | 70% statements / lines | Provider validation and usage analytics | +| Phase 4 | 75% statements / lines | `open-sse` translators and helpers | +| Phase 5 | 80% statements / lines | `open-sse` handlers and executor branches | +| Phase 6 | 85% statements / lines | Harder edge cases, branch debt, regression suites | +| Phase 7 | 90% statements / lines | Final sweep, gap closure, strict ratchet | + +Branches and functions should ratchet upward with each phase, but the primary hard target is statements / lines. + +## Priority hotspots + +These files or areas offer the best return for the next phases: + +1. `open-sse/handlers` + - `chatCore.ts` at 7.57% + - Overall directory at 29.07% +2. `open-sse/translator/request` + - Overall directory at 36.39% + - Many translators are still near single-digit coverage +3. `open-sse/translator/response` + - Overall directory at 8.07% +4. `open-sse/executors` + - Overall directory at 36.62% +5. `src/lib/db` + - `models.ts` at 20.66% + - `registeredKeys.ts` at 34.46% + - `modelComboMappings.ts` at 36.25% + - `settings.ts` at 46.40% + - `webhooks.ts` at 33.33% +6. `src/lib/usage` + - `usageHistory.ts` at 21.12% + - `usageStats.ts` at 9.56% + - `costCalculator.ts` at 30.00% +7. `src/lib/providers` + - `validation.ts` at 41.16% +8. Low-risk utility and API files for early gains + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/api/errorResponse.ts` + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +## Execution checklist + +### Phase 1: 56.95% -> 60% + +- [x] Fix coverage metric so it reflects source code instead of test files +- [x] Keep a legacy coverage script for comparison +- [x] Record the baseline and hotspots in-repo +- [ ] Add focused tests for low-risk utilities: + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/fetchTimeout.ts` + - `src/lib/api/errorResponse.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/display/names.ts` +- [ ] Add route tests for: + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +### Phase 2: 60% -> 65% + +- [ ] Add DB-backed tests for: + - `src/lib/db/modelComboMappings.ts` + - `src/lib/db/settings.ts` + - `src/lib/db/registeredKeys.ts` +- [ ] Cover branch behavior in: + - `src/lib/providers/validation.ts` + - `src/app/api/v1/embeddings/route.ts` + - `src/app/api/v1/moderations/route.ts` + +### Phase 3: 65% -> 70% + +- [ ] Add usage analytics tests for: + - `src/lib/usage/usageHistory.ts` + - `src/lib/usage/usageStats.ts` + - `src/lib/usage/costCalculator.ts` +- [ ] Expand route coverage for proxy management and settings branches + +### Phase 4: 70% -> 75% + +- [ ] Cover translator helpers and central translation paths: + - `open-sse/translator/index.ts` + - `open-sse/translator/helpers/*` + - `open-sse/translator/request/*` + - `open-sse/translator/response/*` + +### Phase 5: 75% -> 80% + +- [ ] Add handler-level tests for: + - `open-sse/handlers/chatCore.ts` + - `open-sse/handlers/responsesHandler.js` + - `open-sse/handlers/imageGeneration.js` + - `open-sse/handlers/embeddings.js` +- [ ] Add executor branch coverage for provider-specific auth, retries, and endpoint overrides + +### Phase 6: 80% -> 85% + +- [ ] Merge more edge-case suites into the main coverage path +- [ ] Increase function coverage for DB modules with weak constructor/helper coverage +- [ ] Close branch gaps in `settings.ts`, `registeredKeys.ts`, `validation.ts`, and translator helpers + +### Phase 7: 85% -> 90% + +- [ ] Treat the remaining low-coverage files as blockers +- [ ] Add regression tests for every uncovered production bug fixed during the push to 90% +- [ ] Raise the coverage gate in CI only after the local baseline is stable for at least two consecutive runs + +## Ratchet policy + +Update `npm run test:coverage` thresholds only after the project actually exceeds the next milestone with a comfortable buffer. + +Recommended ratchet sequence: + +1. 55/60/55 +2. 60/62/58 +3. 65/64/62 +4. 70/66/66 +5. 75/70/72 +6. 80/75/78 +7. 85/80/84 +8. 90/85/88 + +Order is `statements-lines / branches / functions`. + +## Known gap + +The current coverage command measures the main Node unit suite and includes source reached from it, including `open-sse`. It does not yet merge Vitest coverage into a single unified report. That merge is worth doing later, but it is not a blocker for starting the 60% -> 80% climb. diff --git a/docs/i18n/hu/docs/FEATURES.md b/docs/i18n/hu/docs/FEATURES.md index 61e2886ecf..cafb95d55f 100644 --- a/docs/i18n/hu/docs/FEATURES.md +++ b/docs/i18n/hu/docs/FEATURES.md @@ -1,6 +1,6 @@ # OmniRoute โ€” Dashboard Features Gallery (Magyar) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/FEATURES.md) --- @@ -10,7 +10,7 @@ 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). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. ![Providers Dashboard](screenshots/01-providers.png) diff --git a/docs/i18n/hu/docs/MCP-SERVER.md b/docs/i18n/hu/docs/MCP-SERVER.md new file mode 100644 index 0000000000..56eb669855 --- /dev/null +++ b/docs/i18n/hu/docs/MCP-SERVER.md @@ -0,0 +1,87 @@ +# OmniRoute MCP Server Documentation (Magyar) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/MCP-SERVER.md) + +--- + +> Model Context Protocol server with 16 intelligent tools + +## Telepรญtรฉs + +OmniRoute MCP is built-in. Start it with: + +```bash +omniroute --mcp +``` + +Or via the open-sse transport: + +```bash +# HTTP streamable transport (port 20130) +omniroute --dev # MCP auto-starts on /mcp endpoint +``` + +## IDE Configuration + +See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup. + +--- + +## Essential Tools (8) + +| Tool | Description | +| :------------------------------ | :--------------------------------------- | +| `omniroute_get_health` | Gateway health, circuit breakers, uptime | +| `omniroute_list_combos` | All configured combos with models | +| `omniroute_get_combo_metrics` | Performance metrics for a specific combo | +| `omniroute_switch_combo` | Switch active combo by ID/name | +| `omniroute_check_quota` | Quota status per provider or all | +| `omniroute_route_request` | Send a chat completion through OmniRoute | +| `omniroute_cost_report` | Cost analytics for a time period | +| `omniroute_list_models_catalog` | Full model catalog with capabilities | + +## Advanced Tools (8) + +| Tool | Description | +| :--------------------------------- | :---------------------------------------------------------- | +| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | +| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | +| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | +| `omniroute_test_combo` | Live-test all models in a combo via a real upstream request | +| `omniroute_get_provider_metrics` | Detailed metrics for one provider | +| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | +| `omniroute_explain_route` | Explain a past routing decision | +| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | + +## Authentication + +MCP tools are authenticated via API key scopes. Each tool requires specific scopes: + +| Scope | Tools | +| :------------- | :----------------------------------------------- | +| `read:health` | get_health, get_provider_metrics | +| `read:combos` | list_combos, get_combo_metrics | +| `write:combos` | switch_combo | +| `read:quota` | check_quota | +| `write:route` | route_request, simulate_route, test_combo | +| `read:usage` | cost_report, get_session_snapshot, explain_route | +| `write:config` | set_budget_guard, set_resilience_profile | +| `read:models` | list_models_catalog, best_combo_for_task | + +## Audit Logging + +Every tool call is logged to `mcp_tool_audit` with: + +- Tool name, arguments, result +- Duration (ms), success/failure +- API key hash, timestamp + +## Files + +| File | Purpose | +| :------------------------------------------- | :------------------------------------------ | +| `open-sse/mcp-server/server.ts` | MCP server creation + 16 tool registrations | +| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport | +| `open-sse/mcp-server/auth.ts` | API key + scope validation | +| `open-sse/mcp-server/audit.ts` | Tool call audit logging | +| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers | diff --git a/docs/i18n/hu/docs/RELEASE_CHECKLIST.md b/docs/i18n/hu/docs/RELEASE_CHECKLIST.md new file mode 100644 index 0000000000..63d257c74a --- /dev/null +++ b/docs/i18n/hu/docs/RELEASE_CHECKLIST.md @@ -0,0 +1,37 @@ +# Release Checklist (Magyar) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/RELEASE_CHECKLIST.md) + +--- + +Use this checklist before tagging or publishing a new OmniRoute release. + +## Version and Changelog + +1. Bump `package.json` version (`x.y.z`) in the release branch. +2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: + - `## [x.y.z] โ€” YYYY-MM-DD` +3. Keep `## [Unreleased]` as the first changelog section for upcoming work. +4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. + +## API Docs + +1. Update `docs/openapi.yaml`: + - `info.version` must equal `package.json` version. +2. Validate endpoint examples if API contracts changed. + +## Runtime Docs + +1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. +2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. +3. Update localized docs if source docs changed significantly. + +## Automated Check + +Run the sync guard locally before opening PR: + +```bash +npm run check:docs-sync +``` + +CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/hu/docs/TROUBLESHOOTING.md b/docs/i18n/hu/docs/TROUBLESHOOTING.md new file mode 100644 index 0000000000..28bc2c7fc5 --- /dev/null +++ b/docs/i18n/hu/docs/TROUBLESHOOTING.md @@ -0,0 +1,256 @@ +# Troubleshooting (Magyar) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/TROUBLESHOOTING.md) + +--- + +Common problems and solutions for OmniRoute. + +--- + +## Quick Fixes + +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | + +--- + +## Provider Issues + +### "Language model did not provide messages" + +**Cause:** Provider quota exhausted. + +**Fix:** + +1. 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, Qoder) 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}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) + +--- + +## Circuit Breaker Issues + +### Provider stuck in OPEN state + +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. + +**Fix:** + +1. 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 +- **SDK returns raw string instead of object** โ€” Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** โ€” Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** โ€” Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** โ€” Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` + +--- + +## Resilience Settings + +### Auto rate-limit not triggering + +- 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. + +--- + +## Optional RAG / LLM failure taxonomy (16 problems) + +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` โ€ฆ `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard โ†’ Health** for real-time system status +- **Translator**: Use **Dashboard โ†’ Translator** to debug format issues diff --git a/docs/i18n/hu/USER_GUIDE.md b/docs/i18n/hu/docs/USER_GUIDE.md similarity index 82% rename from docs/i18n/hu/USER_GUIDE.md rename to docs/i18n/hu/docs/USER_GUIDE.md index ca10bd9a28..5fc65fdc4f 100644 --- a/docs/i18n/hu/USER_GUIDE.md +++ b/docs/i18n/hu/docs/USER_GUIDE.md @@ -1,8 +1,6 @@ # User Guide (Magyar) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/USER_GUIDE.md) - -> ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/USER_GUIDE.md) --- @@ -320,7 +318,7 @@ Model: cc/claude-opus-4-6 --- -## ๐Ÿš€ Deployment +## Telepรญtรฉs ### Global npm install (Recommended) @@ -511,23 +509,26 @@ post_install() { ### Environment Variables -| Variable | Default | Description | -| ------------------------- | ------------------------------------ | ------------------------------------------------------- | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | -| `INITIAL_PASSWORD` | `123456` | First login password | -| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | -| `PORT` | framework default | Service port (`20128` in examples) | -| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | -| `NODE_ENV` | runtime default | Set `production` for deploy | -| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | -| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | -| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | -| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | -| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | -| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | -| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | -| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | +| 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/*` | +| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand | +| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | For the full environment variable reference, see the [README](../README.md). @@ -598,6 +599,11 @@ curl -X POST http://localhost:20128/api/provider-models \ Or use Dashboard: **Providers โ†’ [Provider] โ†’ Custom Models**. +Notes: + +- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers. +- The **Custom Models** section is intended for providers that do not expose managed available-model imports. + ### Dedicated Provider Routes Route requests directly to a specific provider with model validation: @@ -642,6 +648,14 @@ Returns models grouped by provider with types (`chat`, `embedding`, `image`). - Automatic background sync with timeout + fail-fast - Prefer server-side `BASE_URL`/`CLOUD_URL` in production +### Cloudflare Quick Tunnel + +- Available in **Dashboard โ†’ Endpoints** for Docker and other self-hosted deployments +- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint +- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary +- Tunnel URLs are ephemeral and change every time you stop/start the tunnel +- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download + ### LLM Gateway Intelligence (Phase 9) - **Semantic Cache** โ€” Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) @@ -757,11 +771,11 @@ OmniRoute implements provider-level resilience with four components: 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 | +| 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 unless `DISABLE_SQLITE_AUTO_BACKUP=true` | ```bash # API: Export database @@ -787,10 +801,11 @@ curl -X POST http://localhost:20128/api/db-backups/import \ ### Settings Dashboard -The settings page is organized into 5 tabs for easy navigation: +The settings page is organized into 6 tabs for easy navigation: | Tab | Contents | | -------------- | ---------------------------------------------------------------------------------------------- | +| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility | | **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | | **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | | **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | diff --git a/docs/i18n/hu/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/hu/docs/VM_DEPLOYMENT_GUIDE.md new file mode 100644 index 0000000000..fbce85463c --- /dev/null +++ b/docs/i18n/hu/docs/VM_DEPLOYMENT_GUIDE.md @@ -0,0 +1,403 @@ +# OmniRoute โ€” Deployment Guide on VM with Cloudflare (Magyar) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/VM_DEPLOYMENT_GUIDE.md) + +--- + +Complete guide to install and configure OmniRoute on a VM (VPS) with domain managed via Cloudflare. + +--- + +## Prerequisites + +| Item | Minimum | Recommended | +| ---------- | ------------------------ | ---------------- | +| **CPU** | 1 vCPU | 2 vCPU | +| **RAM** | 1 GB | 2 GB | +| **Disk** | 10 GB SSD | 25 GB SSD | +| **OS** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS | +| **Domain** | Registered on Cloudflare | โ€” | +| **Docker** | Docker Engine 24+ | Docker 27+ | + +**Tested providers**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. + +--- + +## 1. Configure the VM + +### 1.1 Create the instance + +On your preferred VPS provider: + +- Choose Ubuntu 24.04 LTS +- Select the minimum plan (1 vCPU / 1 GB RAM) +- Set a strong root password or configure SSH key +- Note the **public IP** (e.g., `203.0.113.10`) + +### 1.2 Connect via SSH + +```bash +ssh root@203.0.113.10 +``` + +### 1.3 Update the system + +```bash +apt update && apt upgrade -y +``` + +### 1.4 Install Docker + +```bash +# Install dependencies +apt install -y ca-certificates curl gnupg + +# Add official Docker repository +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 Install nginx + +```bash +apt install -y nginx +``` + +### 1.6 Configure 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 +``` + +> **Tip**: For maximum security, restrict ports 80 and 443 to Cloudflare IPs only. See the [Advanced Security](#advanced-security) section. + +--- + +## 2. Install OmniRoute + +### 2.1 Create configuration directory + +```bash +mkdir -p /opt/omniroute +``` + +### 2.2 Create environment variables file + +```bash +cat > /opt/omniroute/.env << โ€˜EOFโ€™ +# === Security === +JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY +INITIAL_PASSWORD=YourSecurePassword123! +API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY +STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY +STORAGE_ENCRYPTION_KEY_VERSION=v1 +MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT + +# === 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 (change to your domain) === +BASE_URL=https://llms.seudominio.com +NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com + +# === Cloud Sync (optional) === +# CLOUD_URL=https://cloud.omniroute.online +# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online +EOF +``` + +> โš ๏ธ **IMPORTANT**: Generate unique secret keys! Use `openssl rand -hex 32` for each key. + +### 2.3 Start the 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 Verify that it is running + +```bash +docker ps | grep omniroute +docker logs omniroute --tail 20 +``` + +It should display: `[DB] SQLite database ready` and `listening on port 20128`. + +--- + +## 3. Configure nginx (Reverse Proxy) + +### 3.1 Generate SSL certificate (Cloudflare Origin) + +In the Cloudflare dashboard: + +1. Go to **SSL/TLS โ†’ Origin Server** +2. Click **Create Certificate** +3. Keep the defaults (15 years, \*.yourdomain.com) +4. Copy the **Origin Certificate** and the **Private Key** + +```bash +mkdir -p /etc/nginx/ssl + +# Paste the certificate +nano /etc/nginx/ssl/origin.crt + +# Paste the private key +nano /etc/nginx/ssl/origin.key + +chmod 600 /etc/nginx/ssl/origin.key +``` + +### 3.2 Nginx Configuration + +```bash +cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ +# Default server โ€” blocks direct access via 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.yourdomain.com; # Change to your domain + + 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.yourdomain.com; + return 301 https://$server_name$request_uri; +} +NGINX +``` + +### 3.3 Enable and Test + +```bash +# Remove default configuration +rm -f /etc/nginx/sites-enabled/default + +# Enable OmniRoute +ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute + +# Test and reload +nginx -t && systemctl reload nginx +``` + +--- + +## 4. Configure Cloudflare DNS + +### 4.1 Add DNS record + +In the Cloudflare dashboard โ†’ DNS: + +| Type | Name | Content | Proxy | +| ---- | ------ | ---------------------- | ---------- | +| A | `llms` | `203.0.113.10` (VM IP) | โœ… Proxied | + +### 4.2 Configure SSL + +Under **SSL/TLS โ†’ Overview**: + +- Mode: **Full (Strict)** + +Under **SSL/TLS โ†’ Edge Certificates**: + +- Always Use HTTPS: โœ… On +- Minimum TLS Version: TLS 1.2 +- Automatic HTTPS Rewrites: โœ… On + +### 4.3 Testing + +```bash +curl -sI https://llms.seudominio.com/health +# Should return HTTP/2 200 +``` + +--- + +## 5. Operations and Maintenance + +### Upgrade to a new version + +```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 +``` + +### View logs + +```bash +docker logs -f omniroute # Real-time stream +docker logs omniroute --tail 50 # Last 50 lines +``` + +### Manual database backup + +```bash +# Copy data from the volume to the host +docker cp omniroute:/app/data ./backup-$(date +%F) + +# Or compress the entire volume +docker run --rm -v omniroute-data:/data -v $(pwd):/backup \ + alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data +``` + +### Restore from 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. Advanced Security + +### Restrict nginx to Cloudflare IPs + +```bash +cat > /etc/nginx/cloudflare-ips.conf << โ€˜CFโ€™ +# Cloudflare IPv4 ranges โ€” update periodically +# 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 +``` + +Add the following to `nginx.conf` inside the `http {}` block: + +```nginx +include /etc/nginx/cloudflare-ips.conf; +``` + +### Install fail2ban + +```bash +apt install -y fail2ban +systemctl enable fail2ban +systemctl start fail2ban + +# Check status +fail2ban-client status sshd +``` + +### Block direct access to the Docker port + +```bash +# Prevent direct external access to port 20128 +iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP +iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT + +# Persist the rules +apt install -y iptables-persistent +netfilter-persistent save +``` + +--- + +## 7. Deploy to Cloudflare Workers (Optional) + +For remote access via Cloudflare Workers (without exposing the VM directly): + +```bash +# In the local repository +cd omnirouteCloud +npm install +npx wrangler login +npx wrangler deploy +``` + +See the full documentation at [omnirouteCloud/README.md](../omnirouteCloud/README.md). + +--- + +## Port Summary + +| Port | Service | Access | +| ----- | ----------- | -------------------------- | +| 22 | SSH | Public (with fail2ban) | +| 80 | nginx HTTP | Redirect โ†’ HTTPS | +| 443 | nginx HTTPS | Via Cloudflare Proxy | +| 20128 | OmniRoute | Localhost only (via nginx) | diff --git a/docs/i18n/hu/src/lib/a2a/README.md b/docs/i18n/hu/src/lib/a2a/README.md new file mode 100644 index 0000000000..cc1863ddd5 --- /dev/null +++ b/docs/i18n/hu/src/lib/a2a/README.md @@ -0,0 +1,752 @@ +# OmniRoute A2A Server (Magyar) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../../../src/lib/a2a/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../../../es/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../../../fr/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../../../de/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../../../it/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../../../ru/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../../../zh-CN/src/lib/a2a/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../../../ja/src/lib/a2a/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../../../ko/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../../../ar/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../../../in/src/lib/a2a/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../../../th/src/lib/a2a/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../../../vi/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../../../id/src/lib/a2a/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../../../ms/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../../../nl/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../../../pl/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../../../sv/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../../../no/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../../../da/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../../../fi/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../../../pt/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../../../ro/src/lib/a2a/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../../../hu/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../../../bg/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../../../sk/src/lib/a2a/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../../../uk-UA/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../../../he/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../../../phi/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../../../pt-BR/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../../../cs/src/lib/a2a/README.md) + +--- + +> **Agent-to-Agent Protocol v0.3** โ€” Enables any AI agent to use OmniRoute as an intelligent routing agent via JSON-RPC 2.0. + +The A2A Server exposes OmniRoute as a **first-class agent** that other agents can discover, delegate tasks to, and collaborate with using the [A2A Protocol](https://google.github.io/A2A/). + +--- + +## Architektรบra + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Orchestrator Agent โ”‚ +โ”‚ (LangChain, CrewAI, AutoGen, Custom Agent) โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ 1. GET /.well-known/agent.json (discover) + โ”‚ 2. POST /a2a (JSON-RPC 2.0) + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ OmniRoute A2A Server โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Task Manager โ”‚ โ”‚ Skill Engine โ”‚ โ”‚ SSE Streaming โ”‚ โ”‚ +โ”‚ โ”‚ (lifecycle) โ”‚โ”€โ”€โ”‚ (registry) โ”‚โ”€โ”€โ”‚ (real-time) โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ +โ”‚ Skills: โ”‚ โ”‚ +โ”‚ โ”œโ”€ smart-routing โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ””โ”€ quota-management โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ Routing Decision Logger โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ OmniRoute Gateway (internal) + /v1/chat/completions, /api/combos, /api/usage/quota +``` + +--- + +## Gyors kezdรฉs + +### Agent Discovery + +Every A2A-compatible agent exposes an **Agent Card** at `/.well-known/agent.json`: + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +**Response:** + +```json +{ + "name": "OmniRoute", + "description": "Intelligent AI gateway with auto-routing across 50+ providers", + "url": "http://localhost:20128/a2a", + "version": "1.8.1", + "capabilities": { + "streaming": true, + "pushNotifications": false + }, + "skills": [ + { + "id": "smart-routing", + "name": "Smart Routing", + "description": "Routes prompts through OmniRoute intelligent pipeline", + "tags": ["routing", "llm", "multi-provider", "cost-optimization"], + "examples": [ + "Write a hello world in Python", + "Explain quantum computing using the cheapest provider" + ] + }, + { + "id": "quota-management", + "name": "Quota Management", + "description": "Natural-language queries about provider quotas", + "tags": ["quota", "analytics", "cost"], + "examples": [ + "Which provider has the most quota remaining?", + "Suggest a free combo for coding" + ] + } + ], + "authentication": { + "schemes": ["bearer"], + "apiKeyHeader": "Authorization" + } +} +``` + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Send a message to a skill and receive the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python hello world"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "a1b2c3d4-...", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "print('Hello, World!')" }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.0030)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "2026-03-04T..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"Quantum computing..."}}} + +: heartbeat 2026-03-04T21:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Running Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Skills Reference + +### `smart-routing` + +Routes prompts through OmniRoute's intelligent pipeline with full observability. + +**Parameters (in `metadata`):** + +| Parameter | Type | Default | Description | +| --------- | -------- | ------------ | ---------------------------------------------------------------------------------------- | +| `model` | `string` | `"auto"` | Target model (e.g., `claude-sonnet-4`, `gpt-4o`, `auto`) | +| `combo` | `string` | active combo | Specific combo to route through | +| `budget` | `number` | none | Maximum cost in USD for this request | +| `role` | `string` | none | Task role hint: `coding`, `review`, `planning`, `analysis`, `debugging`, `documentation` | + +**Returns:** + +| Field | Description | +| ------------------------------ | --------------------------------------------------------- | +| `artifacts[].content` | The LLM response text | +| `metadata.routing_explanation` | Human-readable explanation of routing decision | +| `metadata.cost_envelope` | Estimated vs actual cost with currency | +| `metadata.resilience_trace` | Array of events (primary_selected, fallback_needed, etc.) | +| `metadata.policy_verdict` | Whether the request was allowed and why | + +### `quota-management` + +Answers natural-language queries about provider quotas. + +**Query types (inferred from message content):** + +| Query Pattern | Response Type | +| ---------------------------------------------- | -------------------------------------------------------- | +| Contains `"ranking"`, `"most quota"`, `"best"` | Providers ranked by remaining quota | +| Contains `"free"`, `"suggest"` | Lists free combos or suggests free-tier providers | +| Default | Full quota summary with warnings for low-quota providers | + +--- + +## Task Lifecycle + +``` +submitted โ”€โ”€โ†’ working โ”€โ”€โ†’ completed + โ”€โ”€โ†’ failed + โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ†’ cancelled +``` + +| State | Description | +| ----------- | ----------------------------------------------------- | +| `submitted` | Task created, queued for execution | +| `working` | Skill handler is executing | +| `completed` | Execution succeeded, artifacts available | +| `failed` | Execution failed or task expired (TTL: 5 min default) | +| `cancelled` | Cancelled by client via `tasks/cancel` | + +- Terminal states: `completed`, `failed`, `cancelled` (no further transitions) +- Expired tasks in `submitted` or `working` are auto-marked as `failed` +- Tasks are garbage-collected after 2ร— TTL + +--- + +## Client Examples + +### Python โ€” Orchestrator Agent + +```python +""" +A2A Client โ€” Python example. +Discovers OmniRoute agent, sends a task, and processes the result. +""" +import requests +import json + +BASE_URL = "http://localhost:20128" +API_KEY = "your-api-key" +HEADERS = { + "Content-Type": "application/json", + "Authorization": f"Bearer {API_KEY}", +} + +# 1. Discover agent capabilities +agent_card = requests.get(f"{BASE_URL}/.well-known/agent.json").json() +print(f"Agent: {agent_card['name']} v{agent_card['version']}") +print(f"Skills: {[s['id'] for s in agent_card['skills']]}") + +# 2. Send a smart-routing task +response = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python quicksort implementation"}], + "metadata": { + "model": "auto", + "combo": "fast-coding", + "budget": 0.10, + } + } +}) +result = response.json()["result"] +print(f"\n๐Ÿ“ Response: {result['artifacts'][0]['content'][:200]}...") +print(f"๐Ÿ”€ Routing: {result['metadata']['routing_explanation']}") +print(f"๐Ÿ’ฐ Cost: ${result['metadata']['cost_envelope']['actual']}") +print(f"๐Ÿ›ก๏ธ Policy: {result['metadata']['policy_verdict']['reason']}") + +# 3. Query quota status +quota_resp = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-2", + "method": "message/send", + "params": { + "skill": "quota-management", + "messages": [{"role": "user", "content": "Which provider has the most quota remaining?"}], + } +}) +quota_result = quota_resp.json()["result"] +print(f"\n๐Ÿ“Š Quota: {quota_result['artifacts'][0]['content']}") +``` + +### TypeScript โ€” Multi-Agent Orchestrator + +```typescript +/** + * A2A Client โ€” TypeScript example. + * Shows agent discovery, task delegation, and streaming. + */ + +const BASE_URL = "http://localhost:20128"; +const API_KEY = "your-api-key"; + +interface JsonRpcResponse { + jsonrpc: "2.0"; + id: string | number; + result?: T; + error?: { code: number; message: string }; +} + +async function a2aCall(method: string, params: Record): Promise { + const resp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: `${method}-${Date.now()}`, + method, + params, + }), + }); + const json: JsonRpcResponse = await resp.json(); + if (json.error) throw new Error(`[${json.error.code}] ${json.error.message}`); + return json.result!; +} + +// โ”€โ”€ Agent Discovery โ”€โ”€ +const agentCard = await fetch(`${BASE_URL}/.well-known/agent.json`).then((r) => r.json()); +console.log(`Connected to: ${agentCard.name} (${agentCard.skills.length} skills)`); + +// โ”€โ”€ Smart Routing: Send a coding task โ”€โ”€ +const routingResult = await a2aCall("message/send", { + skill: "smart-routing", + messages: [{ role: "user", content: "Implement a Redis cache wrapper in TypeScript" }], + metadata: { model: "claude-sonnet-4", role: "coding" }, +}); +console.log("Response:", routingResult.artifacts[0].content); +console.log("Provider:", routingResult.metadata.routing_explanation); + +// โ”€โ”€ Quota Management: Find free alternatives โ”€โ”€ +const quotaResult = await a2aCall("message/send", { + skill: "quota-management", + messages: [{ role: "user", content: "Suggest free combos for documentation" }], +}); +console.log("Free combos:", quotaResult.artifacts[0].content); + +// โ”€โ”€ Streaming: Real-time response โ”€โ”€ +const streamResp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "stream-1", + method: "message/stream", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Explain microservices architecture" }], + }, + }), +}); + +const reader = streamResp.body!.getReader(); +const decoder = new TextDecoder(); +while (true) { + const { done, value } = await reader.read(); + if (done) break; + const chunk = decoder.decode(value); + for (const line of chunk.split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + if (event.params.chunk) { + process.stdout.write(event.params.chunk.content); + } + if (event.params.task.state === "completed") { + console.log("\nโœ… Stream completed"); + } + } + } +} +``` + +### Python โ€” LangChain A2A Integration + +```python +""" +LangChain integration โ€” Use OmniRoute A2A as a custom LLM. +""" +from langchain.llms.base import BaseLLM +from langchain.schema import LLMResult, Generation +import requests +from typing import List, Optional + +class OmniRouteA2A(BaseLLM): + base_url: str = "http://localhost:20128" + api_key: str = "" + model: str = "auto" + combo: Optional[str] = None + + @property + def _llm_type(self) -> str: + return "omniroute-a2a" + + def _call(self, prompt: str, stop: Optional[List[str]] = None, **kwargs) -> str: + response = requests.post( + f"{self.base_url}/a2a", + headers={ + "Content-Type": "application/json", + "Authorization": f"Bearer {self.api_key}", + }, + json={ + "jsonrpc": "2.0", + "id": "langchain-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": prompt}], + "metadata": { + "model": self.model, + **({"combo": self.combo} if self.combo else {}), + }, + }, + }, + ) + result = response.json()["result"] + return result["artifacts"][0]["content"] + + def _generate(self, prompts: List[str], stop=None, **kwargs) -> LLMResult: + return LLMResult( + generations=[[Generation(text=self._call(p, stop))] for p in prompts] + ) + +# Usage +llm = OmniRouteA2A( + base_url="http://localhost:20128", + api_key="your-key", + model="auto", + combo="fast-coding", +) +result = llm("Write a Python function to merge two sorted lists") +print(result) +``` + +### Go โ€” A2A Client + +```go +package main + +import ( + "bytes" + "encoding/json" + "fmt" + "io" + "net/http" +) + +const baseURL = "http://localhost:20128" +const apiKey = "your-api-key" + +type JsonRpcRequest struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Method string `json:"method"` + Params interface{} `json:"params"` +} + +type JsonRpcResponse struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Result interface{} `json:"result"` + Error *struct { + Code int `json:"code"` + Message string `json:"message"` + } `json:"error"` +} + +func a2aCall(method string, params interface{}) (*JsonRpcResponse, error) { + body, _ := json.Marshal(JsonRpcRequest{ + Jsonrpc: "2.0", + ID: "go-1", + Method: method, + Params: params, + }) + + req, _ := http.NewRequest("POST", baseURL+"/a2a", bytes.NewReader(body)) + req.Header.Set("Content-Type", "application/json") + req.Header.Set("Authorization", "Bearer "+apiKey) + + resp, err := http.DefaultClient.Do(req) + if err != nil { + return nil, err + } + defer resp.Body.Close() + data, _ := io.ReadAll(resp.Body) + + var result JsonRpcResponse + json.Unmarshal(data, &result) + return &result, nil +} + +func main() { + // Discover agent + resp, _ := http.Get(baseURL + "/.well-known/agent.json") + defer resp.Body.Close() + body, _ := io.ReadAll(resp.Body) + fmt.Println("Agent Card:", string(body)) + + // Send smart-routing task + result, _ := a2aCall("message/send", map[string]interface{}{ + "skill": "smart-routing", + "messages": []map[string]string{{"role": "user", "content": "Hello from Go!"}}, + "metadata": map[string]interface{}{"model": "auto"}, + }) + out, _ := json.MarshalIndent(result.Result, "", " ") + fmt.Println("Result:", string(out)) +} +``` + +--- + +## Use Cases + +### ๐Ÿค– Use Case 1: Multi-Agent Coding Pipeline + +An orchestrator agent delegates code generation to OmniRoute, then passes the output to a review agent. + +```python +def coding_pipeline(task: str): + # Step 1: Generate code via OmniRoute A2A + code_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Write production-quality code: {task}"} + ], metadata={"model": "auto", "role": "coding"}) + code = code_result["artifacts"][0]["content"] + + # Step 2: Review the code via OmniRoute A2A (different model) + review_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Review this code for bugs and improvements:\n\n{code}"} + ], metadata={"model": "auto", "role": "review"}) + review = review_result["artifacts"][0]["content"] + + # Step 3: Check costs + print(f"Code cost: ${code_result['metadata']['cost_envelope']['actual']}") + print(f"Review cost: ${review_result['metadata']['cost_envelope']['actual']}") + + return {"code": code, "review": review} +``` + +### ๐Ÿ’ก Use Case 2: Quota-Aware Agent Swarm + +Multiple agents share quota through OmniRoute, using the quota skill to coordinate. + +```python +async def quota_aware_agent(agent_name: str, task: str): + # Check quota before starting + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Which provider has the most quota remaining?"} + ]) + print(f"[{agent_name}] {quota['artifacts'][0]['content']}") + + # Send request with budget constraint + result = a2a_send("smart-routing", [ + {"role": "user", "content": task} + ], metadata={"budget": 0.05}) + + policy = result["metadata"]["policy_verdict"] + if not policy["allowed"]: + print(f"[{agent_name}] โš ๏ธ Budget exceeded: {policy['reason']}") + # Fall back to free combo + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Suggest free combos"} + ]) + print(f"[{agent_name}] Free alternatives: {quota['artifacts'][0]['content']}") + + return result +``` + +### ๐Ÿ“Š Use Case 3: Real-Time Streaming Dashboard + +A monitoring agent streams responses and displays progress in real-time. + +```typescript +async function streamingDashboard(prompt: string) { + const response = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { "Content-Type": "application/json", Authorization: `Bearer ${API_KEY}` }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "dash-1", + method: "message/stream", + params: { skill: "smart-routing", messages: [{ role: "user", content: prompt }] }, + }), + }); + + let totalChunks = 0; + const reader = response.body!.getReader(); + const decoder = new TextDecoder(); + + while (true) { + const { done, value } = await reader.read(); + if (done) break; + + for (const line of decoder.decode(value).split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + const state = event.params.task.state; + + if (state === "working" && event.params.chunk) { + totalChunks++; + process.stdout.write( + `\r[Chunk ${totalChunks}] ${event.params.chunk.content.slice(0, 50)}...` + ); + } + if (state === "completed") { + const meta = event.params.metadata; + console.log( + `\nโœ… Done | Cost: $${meta?.cost_envelope?.actual || 0} | Route: ${meta?.routing_explanation || "N/A"}` + ); + } + if (state === "failed") { + console.error(`\nโŒ Failed: ${event.params.metadata?.error}`); + } + } + } + } +} +``` + +### ๐Ÿ” Use Case 4: Task Polling Pattern + +For long-running tasks, poll the task status instead of waiting synchronously. + +```python +import time + +def poll_task(task_id: str, timeout: int = 60): + """Poll task status until completion or timeout.""" + start = time.time() + while time.time() - start < timeout: + result = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "poll-1", + "method": "tasks/get", + "params": {"taskId": task_id}, + }).json() + + task = result["result"]["task"] + state = task["state"] + print(f" Task {task_id[:8]}... state={state}") + + if state in ("completed", "failed", "cancelled"): + return task + time.sleep(2) + + # Timeout โ€” cancel the task + requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "cancel-1", + "method": "tasks/cancel", + "params": {"taskId": task_id}, + }) + raise TimeoutError(f"Task {task_id} timed out after {timeout}s") +``` + +--- + +## Error Codes + +| Code | Constant | Meaning | +| ------ | ------------------------ | ---------------------------------------- | +| -32700 | โ€” | Parse error (invalid JSON) | +| -32600 | `INVALID_REQUEST` | Invalid JSON-RPC request or unauthorized | +| -32601 | `METHOD_NOT_FOUND` | Unknown method or skill | +| -32602 | `INVALID_PARAMS` | Missing or invalid parameters | +| -32603 | `INTERNAL_ERROR` | Skill execution failed | +| -32001 | `TASK_NOT_FOUND` | Task ID not found | +| -32002 | `TASK_ALREADY_COMPLETED` | Cannot modify a completed task | +| -32003 | `UNAUTHORIZED` | Invalid or missing API key | +| -32004 | `BUDGET_EXCEEDED` | Request exceeds configured budget | +| -32005 | `PROVIDER_UNAVAILABLE` | No available providers | + +--- + +## Authentication + +All `/a2a` requests require a Bearer token via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server (`OMNIROUTE_API_KEY` is empty), authentication is bypassed. + +--- + +## File Structure + +``` +src/lib/a2a/ +โ”œโ”€โ”€ taskManager.ts # Task lifecycle (create/update/cancel/list), TTL, cleanup +โ”œโ”€โ”€ taskExecution.ts # Generic task executor with state management +โ”œโ”€โ”€ streaming.ts # SSE stream formatting, heartbeat, chunk/completion events +โ”œโ”€โ”€ routingLogger.ts # Routing decision logger (stats, history, retention) +โ””โ”€โ”€ skills/ + โ”œโ”€โ”€ smartRouting.ts # Smart routing skill (routes via /v1/chat/completions) + โ””โ”€โ”€ quotaManagement.ts # Quota management skill (natural-language quota queries) + +src/app/a2a/ +โ””โ”€โ”€ route.ts # Next.js API route handler (JSON-RPC 2.0 dispatch) + +open-sse/mcp-server/ +โ””โ”€โ”€ schemas/a2a.ts # Zod schemas (AgentCard, Task, JSON-RPC, SSE events) +``` + +--- + +## Comparison: MCP vs A2A + +| Feature | MCP Server | A2A Server | +| ----------------- | ---------------------------- | ------------------------------------------------- | +| **Protocol** | Model Context Protocol | Agent-to-Agent Protocol v0.3 | +| **Transport** | stdio / HTTP | HTTP (JSON-RPC 2.0) | +| **Discovery** | Tool listing via MCP | `/.well-known/agent.json` | +| **Granularity** | 16 individual tools | 2 high-level skills | +| **Best for** | IDE agents (Cursor, VS Code) | Multi-agent systems (LangChain, CrewAI) | +| **Streaming** | Not supported | SSE via `message/stream` | +| **Task tracking** | No | Full lifecycle (submitted โ†’ completed) | +| **Observability** | Audit log per tool call | Cost envelope + resilience trace + policy verdict | + +--- + +## Licenc + +Part of [OmniRoute](https://github.com/diegosouzapw/OmniRoute) โ€” MIT License. diff --git a/docs/i18n/id/A2A-SERVER.md b/docs/i18n/id/A2A-SERVER.md deleted file mode 100644 index 01531ff482..0000000000 --- a/docs/i18n/id/A2A-SERVER.md +++ /dev/null @@ -1,200 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/A2A-SERVER.md) - ---- - -# OmniRoute A2A Server Documentation - -> Agent-to-Agent Protocol v0.3 โ€” OmniRoute as an intelligent routing agent - -## Agent Discovery - -```bash -curl http://localhost:20128/.well-known/agent.json -``` - -Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements. - ---- - -## Authentication - -All `/a2a` requests require an API key via the `Authorization` header: - -``` -Authorization: Bearer YOUR_OMNIROUTE_API_KEY -``` - -If no API key is configured on the server, authentication is bypassed. - ---- - -## JSON-RPC 2.0 Methods - -### `message/send` โ€” Synchronous Execution - -Sends a message to a skill and waits for the complete response. - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{ - "jsonrpc": "2.0", - "id": "1", - "method": "message/send", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Write a hello world in Python"}], - "metadata": {"model": "auto", "combo": "fast-coding"} - } - }' -``` - -**Response:** - -```json -{ - "jsonrpc": "2.0", - "id": "1", - "result": { - "task": { "id": "uuid", "state": "completed" }, - "artifacts": [{ "type": "text", "content": "..." }], - "metadata": { - "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)", - "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, - "resilience_trace": [ - { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." } - ], - "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } - } - } -} -``` - -### `message/stream` โ€” SSE Streaming - -Same as `message/send` but returns Server-Sent Events for real-time streaming. - -```bash -curl -N -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{ - "jsonrpc": "2.0", - "id": "1", - "method": "message/stream", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Explain quantum computing"}] - } - }' -``` - -**SSE Events:** - -``` -data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}} - -: heartbeat 2026-03-03T17:00:00Z - -data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} -``` - -### `tasks/get` โ€” Query Task Status - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' -``` - -### `tasks/cancel` โ€” Cancel a Task - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' -``` - ---- - -## Available Skills - -| Skill | Description | -| :----------------- | :------------------------------------------------------------------------------------------------------------------------------ | -| `smart-routing` | Routes prompts through OmniRoute's intelligent pipeline. Returns response with routing explanation, cost, and resilience trace. | -| `quota-management` | Answers natural-language queries about provider quotas, suggests free combos, and provides quota rankings. | - ---- - -## Task Lifecycle - -``` -submitted โ†’ working โ†’ completed - โ†’ failed - โ†’ cancelled -``` - -- Tasks expire after 5 minutes (configurable) -- Terminal states: `completed`, `failed`, `cancelled` -- Event log tracks every state transition - ---- - -## Error Codes - -| Code | Meaning | -| :----- | :----------------------------- | -| -32700 | Parse error (invalid JSON) | -| -32600 | Invalid request / Unauthorized | -| -32601 | Method or skill not found | -| -32602 | Invalid params | -| -32603 | Internal error | - ---- - -## Integration Examples - -### Python (requests) - -```python -import requests - -resp = requests.post("http://localhost:20128/a2a", json={ - "jsonrpc": "2.0", "id": "1", - "method": "message/send", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Hello"}] - } -}, headers={"Authorization": "Bearer YOUR_KEY"}) - -result = resp.json()["result"] -print(result["artifacts"][0]["content"]) -print(result["metadata"]["routing_explanation"]) -``` - -### TypeScript (fetch) - -```typescript -const resp = await fetch("http://localhost:20128/a2a", { - method: "POST", - headers: { - "Content-Type": "application/json", - Authorization: "Bearer YOUR_KEY", - }, - body: JSON.stringify({ - jsonrpc: "2.0", - id: "1", - method: "message/send", - params: { - skill: "smart-routing", - messages: [{ role: "user", content: "Hello" }], - }, - }), -}); -const { result } = await resp.json(); -console.log(result.metadata.routing_explanation); -``` diff --git a/docs/i18n/id/API_REFERENCE.md b/docs/i18n/id/API_REFERENCE.md deleted file mode 100644 index b878605221..0000000000 --- a/docs/i18n/id/API_REFERENCE.md +++ /dev/null @@ -1,455 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/API_REFERENCE.md) - ---- - -# API Reference - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/API_REFERENCE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/API_REFERENCE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/API_REFERENCE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/API_REFERENCE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/API_REFERENCE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/API_REFERENCE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/API_REFERENCE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/API_REFERENCE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/API_REFERENCE.md) - -Complete reference for all OmniRoute API endpoints. - ---- - -## Table of Contents - -- [Chat Completions](#chat-completions) -- [Embeddings](#embeddings) -- [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`. - -### ACP Agents - -| Endpoint | Method | Description | -| ----------------- | ------ | -------------------------------------------------------- | -| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | -| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | -| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | - -GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). - -### Resilience & Rate Limits - -| Endpoint | Method | Description | -| ----------------------- | ------- | ------------------------------- | -| `/api/resilience` | 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` diff --git a/docs/i18n/id/ARCHITECTURE.md b/docs/i18n/id/ARCHITECTURE.md deleted file mode 100644 index 4ea06a29f2..0000000000 --- a/docs/i18n/id/ARCHITECTURE.md +++ /dev/null @@ -1,787 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/ARCHITECTURE.md) - ---- - -# OmniRoute Architecture - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/ARCHITECTURE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/ARCHITECTURE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/ARCHITECTURE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/ARCHITECTURE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/ARCHITECTURE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/ARCHITECTURE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/ARCHITECTURE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/ARCHITECTURE.md) - -_Last updated: 2026-03-04_ - -## 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 (`...`) for reasoning models -- Response sanitization for strict OpenAI SDK compatibility -- Role normalization (developerโ†’system, systemโ†’user) for cross-provider compatibility -- Structured output conversion (json_schema โ†’ Gemini responseSchema) -- Local persistence for providers, keys, aliases, combos, settings, pricing -- Usage/cost tracking and request logging -- Optional cloud sync for multi-device/state sync -- IP allowlist/blocklist for API access control -- Thinking budget management (passthrough/auto/custom/adaptive) -- Global system prompt injection -- Session tracking and fingerprinting -- Per-account enhanced rate limiting with provider-specific profiles -- Circuit breaker pattern for provider resilience -- Anti-thundering herd protection with mutex locking -- Signature-based request deduplication cache -- Domain layer: model availability, cost rules, fallback policy, lockout policy -- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) -- Policy engine for centralized request evaluation (lockout โ†’ budget โ†’ fallback) -- Request telemetry with p50/p95/p99 latency aggregation -- Correlation ID (X-Request-Id) for end-to-end tracing -- Compliance audit logging with opt-out per API key -- Eval framework for LLM quality assurance -- Resilience UI dashboard with real-time circuit breaker status -- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) - -Primary runtime model: - -- Next.js 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[(storage.sqlite)] - UDB[(usage tables + log artifacts)] - end - - subgraph Upstreams[Upstream Providers] - P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/Qoder/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/route.ts` (GET) -- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) -- OAuth: `src/app/api/oauth/*` -- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` -- Usage: `src/app/api/usage/*` -- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` -- CLI tooling helpers: `src/app/api/cli-tools/*` -- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) -- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) -- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) -- Sessions: `src/app/api/sessions` (GET) -- Rate limits: `src/app/api/rate-limits` (GET) -- Resilience: `src/app/api/resilience` (GET/PATCH) โ€” provider profiles, circuit breaker, rate limit state -- Resilience reset: `src/app/api/resilience/reset` (POST) โ€” reset breakers + cooldowns -- Cache stats: `src/app/api/cache/stats` (GET/DELETE) -- Model availability: `src/app/api/models/availability` (GET/POST) -- Telemetry: `src/app/api/telemetry/summary` (GET) -- Budget: `src/app/api/usage/budget` (GET/POST) -- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) -- Compliance audit: `src/app/api/compliance/audit-log` (GET) -- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) -- Policies: `src/app/api/policies` (GET/POST) - -## 2) SSE + 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` -- Response sanitization: `open-sse/handlers/responseSanitizer.ts` -- Role normalization: `open-sse/services/roleNormalizer.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`, `qoder.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 (SQLite): - -- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) -- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) -- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) -- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** - -Usage persistence: - -- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) -- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` -- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) -- legacy JSON files are migrated to SQLite by startup migrations when present - -Domain State DB (SQLite): - -- `src/lib/db/domainState.ts` โ€” CRUD operations 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: - -- primary runtime DB: `${DATA_DIR}/storage.sqlite` -- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) -- structured call payload archives: `${DATA_DIR}/call_logs/` -- optional translator/request debug sessions: `/logs/...` - -## Deployment Topology - -```mermaid -flowchart LR - 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[(storage.sqlite)] - UsageDB[(usage tables + log artifacts)] - end - - subgraph External[External Services] - Providers[AI Providers] - SyncCloud[Cloud Sync Service] - end - - CLI --> Next - Browser --> Next - Next --> Core - Next --> MainDB - Core --> MainDB - Core --> UsageDB - Core --> Providers - Next --> SyncCloud -``` - -## Module Mapping (Decision-Critical) - -### Route and API Modules - -- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs -- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) -- `src/app/api/providers*`: provider CRUD, validation, testing -- `src/app/api/provider-nodes*`: custom compatible node management -- `src/app/api/provider-models`: custom model management (CRUD) -- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) -- `src/app/api/oauth/*`: OAuth/device-code flows -- `src/app/api/keys*`: local API key lifecycle -- `src/app/api/models/alias`: alias management -- `src/app/api/combos*`: fallback combo management -- `src/app/api/pricing`: pricing overrides for cost calculation -- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) -- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) -- `src/app/api/usage/*`: usage and logs APIs -- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers -- `src/app/api/cli-tools/*`: local CLI config writers/checkers -- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) -- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) -- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) -- `src/app/api/sessions`: active session listing (GET) -- `src/app/api/rate-limits`: per-account rate limit status (GET) - -### Routing and Execution Core - -- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop -- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup -- `open-sse/executors/*`: provider-specific network and format behavior - -### Translation Registry and Format Converters - -- `open-sse/translator/index.ts`: translator registry and orchestration -- Request translators: `open-sse/translator/request/*` -- Response translators: `open-sse/translator/response/*` -- Format constants: `open-sse/translator/formats.ts` - -### Persistence - -- `src/lib/db/*`: persistent config/state and domain persistence on SQLite -- `src/lib/localDb.ts`: compatibility re-export for DB modules -- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables - -## Provider Executor Coverage (Strategy Pattern) - -Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. - -| Executor | Provider(s) | Special Handling | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | -| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, Qoder, 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 | -| Qoder | openai | OAuth (Basic) | โœ… | โœ… | โœ… | โš ๏ธ Per request | -| OpenRouter | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| GLM/Kimi/MiniMax | claude | API Key | โœ… | โœ… | โŒ | โŒ | -| DeepSeek | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Groq | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| xAI (Grok) | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Mistral | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Perplexity | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Together AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Fireworks AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Cerebras | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Cohere | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| NVIDIA NIM | openai | API Key | โœ… | โœ… | โŒ | โŒ | - -## Format Translation Coverage - -Detected source formats include: - -- `openai` -- `openai-responses` -- `claude` -- `gemini` - -Target formats include: - -- OpenAI chat/Responses -- Claude -- Gemini/Gemini-CLI/Antigravity envelope -- Kiro -- Cursor - -Translations use **OpenAI as the hub format** โ€” all conversions go through OpenAI as intermediate: - -``` -Source Format โ†’ OpenAI (hub) โ†’ Target Format -``` - -Translations are selected dynamically based on source payload shape and provider target format. - -Additional processing layers in the translation pipeline: - -- **Response sanitization** โ€” Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance -- **Role normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI targets; merges `system` โ†’ `user` for models that reject the system role (GLM, ERNIE) -- **Think tag extraction** โ€” Parses `...` blocks from content into `reasoning_content` field -- **Structured output** โ€” Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` - -## Supported API Endpoints - -| 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 `/logs//` 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 - -- SQLite schema migrations and auto-upgrade hooks at startup -- legacy JSON โ†’ SQLite migration compatibility path - -## Observability and Operational Signals - -Runtime visibility sources: - -- console logs from `src/sse/utils/logger.ts` -- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) -- textual request status log in `log.txt` (optional/compat) -- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` -- dashboard usage endpoints (`/api/usage/*`) for UI consumption - -## Security-Sensitive Boundaries - -- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing -- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning -- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format -- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level -- Cloud sync endpoints rely on API key auth + machine id semantics - -## Environment and Runtime Matrix - -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` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. -2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. -3. Request logger writes full headers/body when enabled; treat log directory as sensitive. -4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. -5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. -6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). -7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). -8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). - -## Operational Verification Checklist - -- Build from source: `npm run build` -- Build Docker image: `docker build -t omniroute .` -- Start service and verify: -- `GET /api/settings` -- `GET /api/v1/models` -- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/id/AUTO-COMBO.md b/docs/i18n/id/AUTO-COMBO.md deleted file mode 100644 index 2166e41dff..0000000000 --- a/docs/i18n/id/AUTO-COMBO.md +++ /dev/null @@ -1,67 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/AUTO-COMBO.md) - ---- - -# OmniRoute Auto-Combo Engine - -> Self-managing model chains with adaptive scoring - -## How It Works - -The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**: - -| Factor | Weight | Description | -| :--------- | :----- | :---------------------------------------------- | -| Quota | 0.20 | Remaining capacity [0..1] | -| Health | 0.25 | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 | -| CostInv | 0.20 | Inverse cost (cheaper = higher score) | -| LatencyInv | 0.15 | Inverse p95 latency (faster = higher) | -| TaskFit | 0.10 | Model ร— task type fitness score | -| Stability | 0.10 | Low variance in latency/errors | - -## Mode Packs - -| Pack | Focus | Key Weight | -| :---------------------- | :----------- | :--------------- | -| ๐Ÿš€ **Ship Fast** | Speed | latencyInv: 0.35 | -| ๐Ÿ’ฐ **Cost Saver** | Economy | costInv: 0.40 | -| ๐ŸŽฏ **Quality First** | Best model | taskFit: 0.40 | -| ๐Ÿ“ก **Offline Friendly** | Availability | quota: 0.40 | - -## Self-Healing - -- **Temporary exclusion**: Score < 0.2 โ†’ excluded for 5 min (progressive backoff, max 30 min) -- **Circuit breaker awareness**: OPEN โ†’ auto-excluded; HALF_OPEN โ†’ probe requests -- **Incident mode**: >50% OPEN โ†’ disable exploration, maximize stability -- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout - -## Bandit Exploration - -5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode. - -## API - -```bash -# Create auto-combo -curl -X POST http://localhost:20128/api/combos/auto \ - -H "Content-Type: application/json" \ - -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}' - -# List auto-combos -curl http://localhost:20128/api/combos/auto -``` - -## Task Fitness - -30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` โ†’ high coding score). - -## Files - -| File | Purpose | -| :------------------------------------------- | :------------------------------------ | -| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization | -| `open-sse/services/autoCombo/taskFitness.ts` | Model ร— task fitness lookup | -| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap | -| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode | -| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles | -| `src/app/api/combos/auto/route.ts` | REST API | diff --git a/docs/i18n/id/CHANGELOG.md b/docs/i18n/id/CHANGELOG.md index ef6f4a3bb1..df974ced96 100644 --- a/docs/i18n/id/CHANGELOG.md +++ b/docs/i18n/id/CHANGELOG.md @@ -1,12 +1,92 @@ # Changelog (Bahasa Indonesia) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CHANGELOG.md) --- - ## [Unreleased] +### ๐Ÿ› ๏ธ Maintenance + +- **AGENTS.md rewrite:** Condensed from 297โ†’153 lines. Added build/lint/test commands (including single-test execution), code style guidelines (Prettier, TypeScript, ESLint, naming, imports, error handling, security), and trimmed verbose architecture tables for AI agent consumption. + +## [3.4.2] - 2026-04-01 + +### ๐Ÿ› Bug Fixes + +- **CI Stabilization:** Fixed failing analytics/settings Playwright selectors and request assertions so GitHub Actions E2E runs pass reliably across localized UIs and switch-based controls. +- **Deterministic Tests:** Removed date-sensitive quota fixtures from Copilot usage tests and aligned idempotency/model catalog tests with the merged runtime behavior. +- **MCP Type Hardening:** Removed zero-budget explicit `any` regressions from the MCP server tool registration path, restoring the `check:any-budget:t11` workflow gate. + +### ๐Ÿ› ๏ธ Maintenance + +- **Release Branch Integration:** Consolidated the active feature branches into `release/v3.4.2` on top of current `main` and validated the branch with lint, unit, coverage, build, and CI-mode E2E runs. + +## [3.4.1] - 2026-03-31 + +> [!WARNING] +> **BREAKING CHANGE: request logging, retention, and logging environment variables have been redesigned.** +> On the first startup after upgrading, OmniRoute archives legacy request logs from `DATA_DIR/logs/`, legacy `DATA_DIR/call_logs/`, and `DATA_DIR/log.txt` into `DATA_DIR/log_archives/*.zip`, then removes the deprecated layout and switches to the new unified artifact format under `DATA_DIR/call_logs/`. + +### โœจ New Features + +- **.ENV Migration Utility:** Included `scripts/migrate-env.mjs` to seamlessly migrate ` Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` - ---- - -## Step 2 โ€” Install CLI Tools - -All npm-based tools require Node.js 18+: - -```bash -# Claude Code (Anthropic) -npm install -g @anthropic-ai/claude-code - -# OpenAI Codex -npm install -g @openai/codex - -# Gemini CLI (Google) -npm install -g @google/gemini-cli - -# OpenCode -npm install -g opencode-ai - -# Cline -npm install -g cline - -# KiloCode -npm install -g kilecode - -# Kiro CLI (Amazon โ€” requires curl + unzip) -apt-get install -y unzip # on Debian/Ubuntu -curl -fsSL https://cli.kiro.dev/install | bash -export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc -``` - -**Verify:** - -```bash -claude --version # 2.x.x -codex --version # 0.x.x -gemini --version # 0.x.x -opencode --version # x.x.x -cline --version # 2.x.x -kilocode --version # x.x.x (or: kilo --version) -kiro-cli --version # 1.x.x -``` - ---- - -## Step 3 โ€” Set Global Environment Variables - -Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`: - -```bash -# OmniRoute Universal Endpoint -export OPENAI_BASE_URL="http://localhost:20128/v1" -export OPENAI_API_KEY="sk-your-omniroute-key" -export ANTHROPIC_BASE_URL="http://localhost:20128/v1" -export ANTHROPIC_API_KEY="sk-your-omniroute-key" -export GEMINI_BASE_URL="http://localhost:20128/v1" -export GEMINI_API_KEY="sk-your-omniroute-key" -``` - -> For a **remote server** replace `localhost:20128` with the server IP or domain, -> e.g. `http://192.168.0.15:20128`. - ---- - -## Step 4 โ€” Configure Each Tool - -### Claude Code - -```bash -# Via CLI: -claude config set --global api-base-url http://localhost:20128/v1 - -# Or create ~/.claude/settings.json: -mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF -{ - "apiBaseUrl": "http://localhost:20128/v1", - "apiKey": "sk-your-omniroute-key" -} -EOF -``` - -**Test:** `claude "say hello"` - ---- - -### OpenAI Codex - -```bash -mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF -model: auto -apiKey: sk-your-omniroute-key -apiBaseUrl: http://localhost:20128/v1 -EOF -``` - -**Test:** `codex "what is 2+2?"` - ---- - -### Gemini CLI - -```bash -mkdir -p ~/.gemini && cat > ~/.gemini/settings.json << EOF -{ - "apiKey": "sk-your-omniroute-key", - "baseUrl": "http://localhost:20128/v1" -} -EOF -``` - -**Test:** `gemini "hello"` - ---- - -### OpenCode - -```bash -mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF -[provider.openai] -base_url = "http://localhost:20128/v1" -api_key = "sk-your-omniroute-key" -EOF -``` - -**Test:** `opencode` - ---- - -### Cline (CLI or VS Code) - -**CLI mode:** - -```bash -mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF -{ - "apiProvider": "openai", - "openAiBaseUrl": "http://localhost:20128/v1", - "openAiApiKey": "sk-your-omniroute-key" -} -EOF -``` - -**VS Code mode:** -Cline extension settings โ†’ API Provider: `OpenAI Compatible` โ†’ Base URL: `http://localhost:20128/v1` - -Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ Cline โ†’ Apply Config**. - ---- - -### KiloCode (CLI or VS Code) - -**CLI mode:** - -```bash -kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key -``` - -**VS Code settings:** - -```json -{ - "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", - "kilo-code.apiKey": "sk-your-omniroute-key" -} -``` - -Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ KiloCode โ†’ Apply Config**. - ---- - -### Continue (VS Code Extension) - -Edit `~/.continue/config.yaml`: - -```yaml -models: - - name: OmniRoute - provider: openai - model: auto - apiBase: http://localhost:20128/v1 - apiKey: sk-your-omniroute-key - default: true -``` - -Restart VS Code after editing. - ---- - -### Kiro CLI (Amazon) - -```bash -# Login to your AWS/Kiro account: -kiro-cli login - -# The CLI uses its own auth โ€” OmniRoute is not needed as backend for Kiro CLI itself. -# Use kiro-cli alongside OmniRoute for other tools. -kiro-cli status -``` - ---- - -### Cursor (Desktop App) - -> **Note:** Cursor routes requests through its cloud. For OmniRoute integration, -> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL. - -Via GUI: **Settings โ†’ Models โ†’ OpenAI API Key** - -- Base URL: `https://your-domain.com/v1` -- API Key: your OmniRoute key - ---- - -## Dashboard Auto-Configuration - -The OmniRoute dashboard automates configuration for most tools: - -1. Go to `http://localhost:20128/dashboard/cli-tools` -2. Expand any tool card -3. Select your API key from the dropdown -4. Click **Apply Config** (if tool is detected as installed) -5. Or copy the generated config snippet manually - ---- - -## Built-in Agents: Droid & OpenClaw - -**Droid** and **OpenClaw** are AI agents built directly into OmniRoute โ€” no installation needed. -They run as internal routes and use OmniRoute's model routing automatically. - -- Access: `http://localhost:20128/dashboard/agents` -- Configure: same combos and providers as all other tools -- No API key or CLI install required - ---- - -## Available API Endpoints - -| Endpoint | Description | Use For | -| -------------------------- | ----------------------------- | --------------------------- | -| `/v1/chat/completions` | Standard chat (all providers) | All modern tools | -| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows | -| `/v1/completions` | Legacy text completions | Older tools using `prompt:` | -| `/v1/embeddings` | Text embeddings | RAG, search | -| `/v1/images/generations` | Image generation | DALL-E, Flux, etc. | -| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS | -| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI | - ---- - -## Troubleshooting - -| Error | Cause | Fix | -| ------------------------- | ----------------------- | ------------------------------------------ | -| `Connection refused` | OmniRoute not running | `pm2 start omniroute` | -| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` | -| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` | -| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` | -| CLI shows "not installed" | Binary not in PATH | Check `which ` | -| `kiro-cli: not found` | Not in PATH | `export PATH="$HOME/.local/bin:$PATH"` | - ---- - -## Quick Setup Script (One Command) - -```bash -# Install all CLIs and configure for OmniRoute (replace with your key and server URL) -OMNIROUTE_URL="http://localhost:20128/v1" -OMNIROUTE_KEY="sk-your-omniroute-key" - -npm install -g @anthropic-ai/claude-code @openai/codex @google/gemini-cli opencode-ai cline kilecode - -# Kiro CLI -apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash - -# Write configs -mkdir -p ~/.claude ~/.codex ~/.gemini ~/.config/opencode ~/.continue - -cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" -cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" -cat > ~/.gemini/settings.json <<< "{\"apiKey\":\"$OMNIROUTE_KEY\",\"baseUrl\":\"$OMNIROUTE_URL\"}" -cat >> ~/.bashrc << EOF -export OPENAI_BASE_URL="$OMNIROUTE_URL" -export OPENAI_API_KEY="$OMNIROUTE_KEY" -export ANTHROPIC_BASE_URL="$OMNIROUTE_URL" -export ANTHROPIC_API_KEY="$OMNIROUTE_KEY" -EOF - -source ~/.bashrc -echo "โœ… All CLIs installed and configured for OmniRoute" -``` diff --git a/docs/i18n/id/CODEBASE_DOCUMENTATION.md b/docs/i18n/id/CODEBASE_DOCUMENTATION.md deleted file mode 100644 index e2d7950052..0000000000 --- a/docs/i18n/id/CODEBASE_DOCUMENTATION.md +++ /dev/null @@ -1,593 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CODEBASE_DOCUMENTATION.md) - ---- - -# omniroute โ€” Codebase Documentation - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) - -> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. - ---- - -## 1. 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
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, Qoder, 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 | -| Qoder | 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"] -``` diff --git a/docs/i18n/id/CONTRIBUTING.md b/docs/i18n/id/CONTRIBUTING.md new file mode 100644 index 0000000000..97ec4be241 --- /dev/null +++ b/docs/i18n/id/CONTRIBUTING.md @@ -0,0 +1,299 @@ +# Contributing to OmniRoute (Bahasa Indonesia) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CONTRIBUTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CONTRIBUTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CONTRIBUTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CONTRIBUTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CONTRIBUTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CONTRIBUTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CONTRIBUTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CONTRIBUTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CONTRIBUTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CONTRIBUTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CONTRIBUTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CONTRIBUTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CONTRIBUTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CONTRIBUTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CONTRIBUTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CONTRIBUTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CONTRIBUTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CONTRIBUTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CONTRIBUTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CONTRIBUTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CONTRIBUTING.md) + +--- + +Thank you for your interest in contributing! This guide covers everything you need to get started. + +--- + +## Development Setup + +### Prerequisites + +- **Node.js** >= 18 < 24 (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` | `20128` | Server port | +| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | Base URL for frontend | +| `JWT_SECRET` | (generate above) | JWT signing secret | +| `INITIAL_PASSWORD` | `CHANGEME` | First login password | +| `APP_LOG_LEVEL` | `info` | Log verbosity level | + +### Dashboard Settings + +The dashboard provides UI toggles for features that can also be configured via environment variables: + +| Setting Location | Toggle | Description | +| ------------------- | ------------------ | ------------------------------ | +| Settings โ†’ Advanced | Debug Mode | Enable debug request logs (UI) | +| Settings โ†’ General | Sidebar Visibility | Show/hide sidebar sections | + +These settings are stored in the database and persist across restarts, overriding env var defaults when set. + +### 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:20128/dashboard` +- **API**: `http://localhost:20128/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`, `mcp`, `a2a`, `memory`, `skills`. + +--- + +## Running Tests + +```bash +# All tests (unit + vitest + ecosystem + e2e) +npm run test:all + +# Single test file (Node.js native test runner โ€” most tests use this) +node --import tsx/esm --test tests/unit/your-file.test.mjs + +# Vitest (MCP server, autoCombo, cache) +npm run test:vitest + +# E2E tests (requires Playwright) +npm run test:e2e + +# Protocol clients E2E (MCP transports, A2A) +npm run test:protocols:e2e + +# Ecosystem compatibility tests +npm run test:ecosystem + +# Coverage (55% min statements/lines/functions; 60% branches) +npm run test:coverage +npm run coverage:report + +# Lint + format check +npm run lint +npm run check +``` + +Coverage notes: + +- `npm run test:coverage` measures source coverage for the main unit test suite, excludes `tests/**`, and includes `open-sse/**` +- `npm run coverage:report` prints the detailed file-by-file report from the latest coverage run +- `npm run test:coverage:legacy` preserves the older metric for historical comparison +- See `docs/COVERAGE_PLAN.md` for the phased coverage improvement roadmap + +Current test status: **122 unit test files** covering: + +- Provider translators and format conversion +- Rate limiting, circuit breaker, and resilience +- Semantic cache, idempotency, progress tracking +- Database operations and schema (21 DB modules) +- OAuth flows and authentication +- API endpoint validation (Zod v4) +- MCP server tools and scope enforcement +- Memory and Skills systems + +--- + +## Code Style + +- **ESLint** โ€” Run `npm run lint` before committing +- **Prettier** โ€” Auto-formatted via `lint-staged` on commit (2 spaces, semicolons, double quotes, 100 char width, es5 trailing commas) +- **TypeScript** โ€” All `src/` code uses `.ts`/`.tsx`; `open-sse/` uses `.ts`/`.js`; document with TSDoc (`@param`, `@returns`, `@throws`) +- **No `eval()`** โ€” ESLint enforces `no-eval`, `no-implied-eval`, `no-new-func` +- **Zod validation** โ€” Use Zod v4 schemas for all API input validation +- **Naming**: Files = camelCase/kebab-case, components = PascalCase, constants = UPPER_SNAKE + +--- + +## Project Structure + +``` +src/ # TypeScript (.ts / .tsx) +โ”œโ”€โ”€ app/ # Next.js 16 App Router +โ”‚ โ”œโ”€โ”€ (dashboard)/ # Dashboard pages (23 sections) +โ”‚ โ”œโ”€โ”€ api/ # API routes (51 directories) +โ”‚ โ””โ”€โ”€ login/ # Auth pages (.tsx) +โ”œโ”€โ”€ domain/ # Policy engine (policyEngine, comboResolver, costRules, etc.) +โ”œโ”€โ”€ lib/ # Core business logic (.ts) +โ”‚ โ”œโ”€โ”€ a2a/ # Agent-to-Agent v0.3 protocol server +โ”‚ โ”œโ”€โ”€ acp/ # Agent Communication Protocol registry +โ”‚ โ”œโ”€โ”€ compliance/ # Compliance policy engine +โ”‚ โ”œโ”€โ”€ db/ # SQLite database layer (21 modules + 16 migrations) +โ”‚ โ”œโ”€โ”€ memory/ # Persistent conversational memory +โ”‚ โ”œโ”€โ”€ oauth/ # OAuth providers, services, and utilities +โ”‚ โ”œโ”€โ”€ skills/ # Extensible skill framework +โ”‚ โ”œโ”€โ”€ usage/ # Usage tracking and cost calculation +โ”‚ โ””โ”€โ”€ localDb.ts # Re-export layer only โ€” never add logic here +โ”œโ”€โ”€ middleware/ # Request middleware (promptInjectionGuard) +โ”œโ”€โ”€ mitm/ # MITM proxy (cert, DNS, target routing) +โ”œโ”€โ”€ shared/ +โ”‚ โ”œโ”€โ”€ components/ # React components (.tsx) +โ”‚ โ”œโ”€โ”€ constants/ # Provider definitions (60+), MCP scopes, routing strategies +โ”‚ โ”œโ”€โ”€ utils/ # Circuit breaker, sanitizer, auth helpers +โ”‚ โ””โ”€โ”€ validation/ # Zod v4 schemas +โ””โ”€โ”€ sse/ # SSE proxy pipeline + +open-sse/ # @omniroute/open-sse workspace +โ”œโ”€โ”€ executors/ # 14 provider-specific request executors +โ”œโ”€โ”€ handlers/ # 11 request handlers (chat, responses, embeddings, images, etc.) +โ”œโ”€โ”€ mcp-server/ # MCP server (25 tools, 3 transports, 10 scopes) +โ”œโ”€โ”€ services/ # 36+ services (combo, autoCombo, rateLimitManager, etc.) +โ”œโ”€โ”€ translator/ # Format translators (OpenAI โ†” Claude โ†” Gemini โ†” Responses โ†” Ollama) +โ”œโ”€โ”€ transformer/ # Responses API transformer +โ””โ”€โ”€ utils/ # 22 utility modules (stream, TLS, proxy, logging) + +electron/ # Electron desktop app (cross-platform) + +tests/ +โ”œโ”€โ”€ unit/ # Node.js test runner (122 test files) +โ”œโ”€โ”€ integration/ # Integration tests +โ”œโ”€โ”€ e2e/ # Playwright tests +โ”œโ”€โ”€ security/ # Security tests +โ”œโ”€โ”€ translator/ # Translator-specific tests +โ””โ”€โ”€ load/ # Load tests + +docs/ # Documentation +โ”œโ”€โ”€ ARCHITECTURE.md # System architecture +โ”œโ”€โ”€ API_REFERENCE.md # All endpoints +โ”œโ”€โ”€ USER_GUIDE.md # Provider setup, CLI integration +โ”œโ”€โ”€ TROUBLESHOOTING.md # Common issues +โ”œโ”€โ”€ MCP-SERVER.md # MCP server (25 tools) +โ”œโ”€โ”€ A2A-SERVER.md # A2A agent protocol +โ”œโ”€โ”€ AUTO-COMBO.md # Auto-combo engine +โ”œโ”€โ”€ CLI-TOOLS.md # CLI tools integration +โ”œโ”€โ”€ COVERAGE_PLAN.md # Test coverage improvement plan +โ”œโ”€โ”€ openapi.yaml # OpenAPI specification +โ””โ”€โ”€ adr/ # Architecture Decision Records +``` + +--- + +## Adding a New Provider + +### Step 1: Register Provider Constants + +Add to `src/shared/constants/providers.ts` โ€” Zod-validated at module load. + +### Step 2: Add Executor (if custom logic needed) + +Create executor in `open-sse/executors/your-provider.ts` extending the base executor. + +### Step 3: Add Translator (if non-OpenAI format) + +Create request/response translators in `open-sse/translator/`. + +### Step 4: Add OAuth Config (if OAuth-based) + +Add OAuth credentials in `src/lib/oauth/constants/oauth.ts` and service in `src/lib/oauth/services/`. + +### Step 5: Register Models + +Add model definitions in `open-sse/config/providerRegistry.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 +- [ ] All inputs validated with Zod schemas +- [ ] CHANGELOG updated (if user-facing change) +- [ ] Documentation updated (if applicable) + +--- + +## Releasing + +Releases are managed via the `/generate-release` workflow. When a new GitHub Release is created, the package is **automatically published to npm** via GitHub Actions. + +--- + +## Getting Help + +- **Architecture**: See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) +- **API Reference**: See [`docs/API_REFERENCE.md`](docs/API_REFERENCE.md) +- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **ADRs**: See `docs/adr/` for architectural decision records diff --git a/docs/i18n/id/FEATURES.md b/docs/i18n/id/FEATURES.md deleted file mode 100644 index 1993515728..0000000000 --- a/docs/i18n/id/FEATURES.md +++ /dev/null @@ -1,147 +0,0 @@ -# OmniRoute โ€” Dashboard Features Gallery (Bahasa Indonesia) - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) - -> ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../docs/FEATURES.md) - ---- - -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 (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. - -![Providers Dashboard](screenshots/01-providers.png) - ---- - -## ๐ŸŽจ Combos - -Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. - -![Combos Dashboard](screenshots/02-combos.png) - ---- - -## ๐Ÿ“Š Analytics - -Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. - -![Analytics Dashboard](screenshots/03-analytics.png) - ---- - -## ๐Ÿฅ System Health - -Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. - -![Health Dashboard](screenshots/04-health.png) - ---- - -## ๐Ÿ”ง Translator Playground - -Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). - -![Translator Playground](screenshots/05-translator.png) - ---- - -## ๐ŸŽฎ Model Playground _(v2.0.9+)_ - -Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. - ---- - -## ๐ŸŽจ Themes _(v2.0.5+)_ - -Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. - ---- - -## โš™๏ธ Settings - -Comprehensive settings panel with tabs: - -- **General** โ€” System storage, backup management (export/import database) -- **Appearance** โ€” Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls -- **Security** โ€” API endpoint protection, custom provider blocking, IP filtering, session info -- **Routing** โ€” Model aliases, background task degradation -- **Resilience** โ€” Rate limit persistence, circuit breaker tuning -- **Advanced** โ€” Configuration overrides - -![Settings Dashboard](screenshots/06-settings.png) - ---- - -## ๐Ÿ”ง CLI Tools - -One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. - -![CLI Tools Dashboard](screenshots/07-cli-tools.png) - ---- - -## ๐Ÿค– CLI Agents _(v2.0.11+)_ - -Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: - -- **Installation status** โ€” Installed / Not Found with version detection -- **Protocol badges** โ€” stdio, HTTP, etc. -- **Custom agents** โ€” Register any CLI tool via form (name, binary, version command, spawn args) -- **CLI Fingerprint Matching** โ€” Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP - ---- - -## ๐Ÿ–ผ๏ธ Media _(v2.0.3+)_ - -Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. - ---- - -## ๐Ÿ“ Request Logs - -Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. - -![Usage Logs](screenshots/08-usage.png) - ---- - -## ๐ŸŒ API Endpoint - -Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. - -![Endpoint Dashboard](screenshots/09-endpoint.png) - ---- - -## ๐Ÿ”‘ API Key Management - -Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. - ---- - -## ๐Ÿ“‹ Audit Log - -Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. - ---- - -## ๐Ÿ–ฅ๏ธ Desktop Application - -Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. - -Key features: - -- Server readiness polling (no blank screen on cold start) -- System tray with port management -- Content Security Policy -- Single-instance lock -- Auto-update on restart -- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) -- Hardened Electron build packaging โ€” symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+) - -๐Ÿ“– See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/id/MCP-SERVER.md b/docs/i18n/id/MCP-SERVER.md deleted file mode 100644 index 829acd30b1..0000000000 --- a/docs/i18n/id/MCP-SERVER.md +++ /dev/null @@ -1,87 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/MCP-SERVER.md) - ---- - -# OmniRoute MCP Server Documentation - -> Model Context Protocol server with 16 intelligent tools - -## Installation - -OmniRoute MCP is built-in. Start it with: - -```bash -omniroute --mcp -``` - -Or via the open-sse transport: - -```bash -# HTTP streamable transport (port 20130) -omniroute --dev # MCP auto-starts on /mcp endpoint -``` - -## IDE Configuration - -See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup. - ---- - -## Essential Tools (8) - -| Tool | Description | -| :------------------------------ | :--------------------------------------- | -| `omniroute_get_health` | Gateway health, circuit breakers, uptime | -| `omniroute_list_combos` | All configured combos with models | -| `omniroute_get_combo_metrics` | Performance metrics for a specific combo | -| `omniroute_switch_combo` | Switch active combo by ID/name | -| `omniroute_check_quota` | Quota status per provider or all | -| `omniroute_route_request` | Send a chat completion through OmniRoute | -| `omniroute_cost_report` | Cost analytics for a time period | -| `omniroute_list_models_catalog` | Full model catalog with capabilities | - -## Advanced Tools (8) - -| Tool | Description | -| :--------------------------------- | :---------------------------------------------- | -| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | -| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | -| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | -| `omniroute_test_combo` | Live-test all models in a combo | -| `omniroute_get_provider_metrics` | Detailed metrics for one provider | -| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | -| `omniroute_explain_route` | Explain a past routing decision | -| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | - -## Authentication - -MCP tools are authenticated via API key scopes. Each tool requires specific scopes: - -| Scope | Tools | -| :------------- | :----------------------------------------------- | -| `read:health` | get_health, get_provider_metrics | -| `read:combos` | list_combos, get_combo_metrics | -| `write:combos` | switch_combo | -| `read:quota` | check_quota | -| `write:route` | route_request, simulate_route, test_combo | -| `read:usage` | cost_report, get_session_snapshot, explain_route | -| `write:config` | set_budget_guard, set_resilience_profile | -| `read:models` | list_models_catalog, best_combo_for_task | - -## Audit Logging - -Every tool call is logged to `mcp_tool_audit` with: - -- Tool name, arguments, result -- Duration (ms), success/failure -- API key hash, timestamp - -## Files - -| File | Purpose | -| :------------------------------------------- | :------------------------------------------ | -| `open-sse/mcp-server/server.ts` | MCP server creation + 16 tool registrations | -| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport | -| `open-sse/mcp-server/auth.ts` | API key + scope validation | -| `open-sse/mcp-server/audit.ts` | Tool call audit logging | -| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers | diff --git a/docs/i18n/id/README.md b/docs/i18n/id/README.md index 4a3b90fab0..e6b86b8748 100644 --- a/docs/i18n/id/README.md +++ b/docs/i18n/id/README.md @@ -1,12 +1,12 @@ # ๐Ÿš€ OmniRoute โ€” The Free AI Gateway (Bahasa Indonesia) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/README.md) --- ### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback. -_Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._ +_Your universal API proxy โ€” one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._ **Chat Completions โ€ข Embeddings โ€ข Image Generation โ€ข Video โ€ข Music โ€ข Audio โ€ข Reranking โ€ข **Web Search** โ€ข MCP Server โ€ข A2A Protocol โ€ข 100% TypeScript** @@ -46,15 +46,17 @@ _Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now wi > - `APP_LOG_FILE_PATH` > - `APP_LOG_MAX_FILE_SIZE` > - `APP_LOG_RETENTION_DAYS` +> - `APP_LOG_MAX_FILES` > - `APP_LOG_LEVEL` > - `APP_LOG_FORMAT` > - `CALL_LOG_RETENTION_DAYS` +> - `CALL_LOG_MAX_ENTRIES` > > For release details and upgrade notes, see the [CHANGELOG](CHANGELOG.md). --- -## ๐Ÿ†• What's New in v3.0.0 +## ๐Ÿ†• What's New > **Upgrading from v2.9.5?** โ€” See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes. @@ -274,7 +276,7 @@ Developers pay $20โ€“200/month for Claude Pro, Codex Pro, or GitHub Copilot. Eve - **Smart 4-Tier Fallback** โ€” If subscription quota runs out, automatically redirects to API Key โ†’ Cheap โ†’ Free with zero manual intervention - **Real-Time Quota Tracking** โ€” Shows token consumption in real-time with reset countdown (5h, daily, weekly) - **Multi-Account Support** โ€” Multiple accounts per provider with auto round-robin โ€” when one runs out, switches to the next -- **Custom Combos** โ€” Customizable fallback chains with 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Custom Combos** โ€” Customizable fallback chains with 9 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random) - **Codex Business Quotas** โ€” Business/Team workspace quota monitoring directly in the dashboard @@ -286,7 +288,7 @@ OpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If **How OmniRoute solves it:** -- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 67+ providers +- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 60+ providers - **Format Translation** โ€” Automatic and transparent: OpenAI โ†” Claude โ†” Gemini โ†” Responses API - **Response Sanitization** โ€” Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+ - **Role Normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI providers; `system` โ†’ `user` for GLM/ERNIE @@ -372,7 +374,7 @@ Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code.. - **CLI Tools Dashboard** โ€” Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline - **GitHub Copilot Config Generator** โ€” Generates `chatLanguageModels.json` for VS Code with bulk model selection - **Onboarding Wizard** โ€” Guided 4-step setup for first-time users -- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 67+ providers +- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 60+ providers @@ -419,7 +421,7 @@ When a call fails, the dev doesn't know if it was a rate limit, expired token, w - **SQLite Proxy Logs** โ€” Persistent logs that survive server restarts - **Translator Playground** โ€” 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time) - **Request Telemetry** โ€” p50/p95/p99 latency + X-Request-Id tracing -- **File-Based Logging with Rotation** โ€” Console interceptor captures everything to JSON log with size-based rotation +- **File-Based Logging with Rotation** โ€” App logs rotate by size, retention days, and archive count; call log artifacts rotate by retention days and file count - **System Info Report** โ€” `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage. @@ -514,7 +516,7 @@ Developers who want all responses in a specific language, with a specific tone, - **System Prompt Injection** โ€” Global prompt applied to all requests - **Thinking Budget Validation** โ€” Reasoning token allocation control per request (passthrough, auto, custom, adaptive) -- **6 Routing Strategies** โ€” Global strategies that determine how requests are distributed +- **9 Routing Strategies** โ€” Global strategies that determine how requests are distributed - **Wildcard Router** โ€” `provider/*` patterns route dynamically to any provider - **Combo Enable/Disable Toggle** โ€” Toggle combos directly from the dashboard - **Provider Toggle** โ€” Enable/disable all connections for a provider with one click @@ -581,7 +583,7 @@ Different clients should have least-privilege access to tool categories. **How OmniRoute solves it:** -- 9 granular MCP scopes for controlled tool access +- 10 granular MCP scopes for controlled tool access - Scope enforcement and visibility in MCP management UI - Safe default posture for operational tooling @@ -1325,19 +1327,19 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. ### ๐Ÿค– Agent & Protocol Operations (v2.0) -| Feature | What It Does | -| ------------------------------------- | -------------------------------------------------------------------------------------------------- | -| ๐Ÿ”ง **MCP Server (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) | -| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | -| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | -| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | -| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | -| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | -| ๐Ÿ” **MCP Scope Enforcement** | 9 granular scope permissions for controlled tool access | -| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | -| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | -| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | -| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | +| Feature | What It Does | +| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| ๐Ÿ”ง **MCP Server (25 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools | +| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | +| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | +| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | +| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | +| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | +| ๐Ÿ” **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access | +| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | +| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | +| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | +| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | ### ๐Ÿง  Routing & Intelligence @@ -1348,7 +1350,7 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. | ๐Ÿ”„ **Format Translation** | OpenAI โ†” Claude โ†” Gemini โ†” Responses with schema-safe conversions | | ๐Ÿ‘ฅ **Multi-Account Support** | Multiple accounts per provider with intelligent selection | | ๐Ÿ”„ **Auto Token Refresh** | OAuth tokens refresh automatically with retry | -| ๐ŸŽจ **Custom Combos** | 6 balancing strategies + fallback chain control | +| ๐ŸŽจ **Custom Combos** | 9 balancing strategies + fallback chain control | | ๐ŸŒ **Wildcard Router** | `provider/*` dynamic routing | | ๐Ÿง  **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits | | ๐Ÿ”€ **Model Aliases** | Built-in + custom model aliasing and migration safety | @@ -1949,6 +1951,7 @@ opencode - Request artifacts are written to `DATA_DIR/call_logs/` as one JSON file per request - Enable pipeline capture from Dashboard โ†’ Logs โ†’ Request Logs if you need detailed per-stage payloads - Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log` +- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed **Connection test shows "Invalid" for OpenAI-compatible providers** diff --git a/docs/i18n/id/RELEASE_CHECKLIST.md b/docs/i18n/id/RELEASE_CHECKLIST.md deleted file mode 100644 index 903e812c3f..0000000000 --- a/docs/i18n/id/RELEASE_CHECKLIST.md +++ /dev/null @@ -1,37 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/RELEASE_CHECKLIST.md) - ---- - -# Release Checklist - -Use this checklist before tagging or publishing a new OmniRoute release. - -## Version and Changelog - -1. Bump `package.json` version (`x.y.z`) in the release branch. -2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: - - `## [x.y.z] โ€” YYYY-MM-DD` -3. Keep `## [Unreleased]` as the first changelog section for upcoming work. -4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. - -## API Docs - -1. Update `docs/openapi.yaml`: - - `info.version` must equal `package.json` version. -2. Validate endpoint examples if API contracts changed. - -## Runtime Docs - -1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. -2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. -3. Update localized docs if source docs changed significantly. - -## Automated Check - -Run the sync guard locally before opening PR: - -```bash -npm run check:docs-sync -``` - -CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/id/SECURITY.md b/docs/i18n/id/SECURITY.md new file mode 100644 index 0000000000..6085c0e84a --- /dev/null +++ b/docs/i18n/id/SECURITY.md @@ -0,0 +1,179 @@ +# Security Policy (Bahasa Indonesia) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../SECURITY.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/SECURITY.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/SECURITY.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/SECURITY.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/SECURITY.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/SECURITY.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/SECURITY.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/SECURITY.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/SECURITY.md) + +--- + +## 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 | +| ------- | -------------- | +| 3.4.x | โœ… Active | +| 3.0.x | โœ… Security | +| < 3.0.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 | +| **MCP Scopes** | 10 granular scopes for MCP tool access control | + +### ๐Ÿ›ก๏ธ 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:::` +- 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** | Allowlist/blocklist IP ranges in dashboard | +| **Rate Limiting** | Per-provider rate limits with automatic backoff | +| **Anti-Thundering Herd** | Mutex + per-connection locking prevents cascading 502s | +| **TLS Fingerprint** | Browser-like TLS fingerprint spoofing to reduce bot detection | +| **CLI Fingerprint** | Per-provider header/body ordering to match native CLI signatures | + +### ๐Ÿ”Œ Resilience & Availability + +| 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 `CALL_LOG_RETENTION_DAYS` | +| **No-Log Opt-out** | Per API key `noLog` flag disables request logging | +| **Audit Log** | Administrative actions tracked in `audit_log` table | +| **MCP Audit** | SQLite-backed audit logging for all MCP tool calls | +| **Zod Validation** | All API inputs validated with Zod v4 schemas at module load | + +--- + +## 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 +- Provider constants validated at module load via Zod (`src/shared/validation/providerSchema.ts`) diff --git a/docs/i18n/id/TROUBLESHOOTING.md b/docs/i18n/id/TROUBLESHOOTING.md deleted file mode 100644 index 63c148000a..0000000000 --- a/docs/i18n/id/TROUBLESHOOTING.md +++ /dev/null @@ -1,258 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/TROUBLESHOOTING.md) - ---- - -# Troubleshooting - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/TROUBLESHOOTING.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/TROUBLESHOOTING.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/TROUBLESHOOTING.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/TROUBLESHOOTING.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/TROUBLESHOOTING.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/TROUBLESHOOTING.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/TROUBLESHOOTING.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/TROUBLESHOOTING.md) - -Common problems and solutions for OmniRoute. - ---- - -## Quick Fixes - -| Problem | Solution | -| ----------------------------- | ------------------------------------------------------------------ | -| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | -| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | -| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | -| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | -| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | - ---- - -## Provider Issues - -### "Language model did not provide messages" - -**Cause:** Provider quota exhausted. - -**Fix:** - -1. 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, Qoder) 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}/storage.sqlite` (providers, combos, aliases, keys, settings) -- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` -- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) - ---- - -## Circuit Breaker Issues - -### Provider stuck in OPEN state - -When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. - -**Fix:** - -1. 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 -- **SDK returns raw string instead of object** โ€” Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures -- **GLM/ERNIE rejects `system` role** โ€” Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models -- **`developer` role not recognized** โ€” Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers -- **`json_schema` not working with Gemini** โ€” Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` - ---- - -## Resilience Settings - -### Auto rate-limit not triggering - -- 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. - ---- - -## Optional RAG / LLM failure taxonomy (16 problems) - -Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. - -In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. - -If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: - -- retrieval drift and broken context boundaries -- empty or stale indexes and vector stores -- embedding versus semantic mismatch -- prompt assembly and context window issues -- logic collapse and overconfident answers -- long chain and agent coordination failures -- multi agent memory and role drift -- deployment and bootstrap ordering problems - -The idea is simple: - -1. When you investigate a bad response, capture: - - user task and request - - route or provider combo in OmniRoute - - any RAG context used downstream (retrieved documents, tool calls, etc) -2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` โ€ฆ `No.16`). -3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. -4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. - -Full text and concrete recipes live here (MIT license, text only): - -[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) - -You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. - ---- - -## Still Stuck? - -- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details -- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints -- **Health Dashboard**: Check **Dashboard โ†’ Health** for real-time system status -- **Translator**: Use **Dashboard โ†’ Translator** to debug format issues diff --git a/docs/i18n/id/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/id/VM_DEPLOYMENT_GUIDE.md deleted file mode 100644 index ff32516444..0000000000 --- a/docs/i18n/id/VM_DEPLOYMENT_GUIDE.md +++ /dev/null @@ -1,401 +0,0 @@ -# OmniRoute โ€” Panduan Penerapan pada VM dengan Cloudflare - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](../pt-BR/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](../es/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](../fr/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](../it/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](../ru/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](../zh-CN/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](../de/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](../in/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](../th/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](../uk-UA/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](../ar/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](../ja/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](../vi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](../bg/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](../da/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](../fi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](../he/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](../hu/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](../id/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](../ko/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](../ms/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](../nl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](../no/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](../pt/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](../ro/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](../pl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](../sk/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](../sv/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](../phi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](../cs/VM_DEPLOYMENT_GUIDE.md) - -Panduan lengkap untuk menginstal dan mengkonfigurasi OmniRoute pada VM (VPS) dengan domain yang dikelola melalui Cloudflare. - ---- - -## Prasyarat - -| Barang | Minimal | Direkomendasikan | -| ------------------- | ----------------------- | ------------------- | -| **CPU** | 1vCPU | 2vCPU | -| **RAM** | 1 GB | 2 GB | -| **Disk** | SSD 10 GB | SSD 25GB | -| **OS** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS | -| **Domain** | Terdaftar di Cloudflare | โ€” | -| **Buruh pelabuhan** | Mesin Docker 24+ | buruh pelabuhan 27+ | - -**Penyedia teruji**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. - ---- - -## 1. Konfigurasikan VM - -### 1.1 Membuat instance - -Pada penyedia VPS pilihan Anda: - -- Pilih Ubuntu 24.04 LTS -- Pilih paket minimum (1 vCPU / 1 GB RAM) -- Tetapkan kata sandi root yang kuat atau konfigurasikan kunci SSH -- Catat **IP publik** (mis., `203.0.113.10`) - -### 1.2 Terhubung melalui SSH - -```bash -ssh root@203.0.113.10 -``` - -### 1.3 Perbarui sistem - -```bash -apt update && apt upgrade -y -``` - -### 1.4 Instal Docker - -```bash -# Install dependencies -apt install -y ca-certificates curl gnupg - -# Add official Docker repository -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 Instal nginx - -```bash -apt install -y nginx -``` - -### 1.6 Konfigurasi 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 -``` - -> **Tips**: Untuk keamanan maksimum, batasi port 80 dan 443 hanya untuk IP Cloudflare. Lihat bagian [Advanced Security](#advanced-security). - ---- - -## 2. Instal OmniRoute - -### 2.1 Membuat direktori konfigurasi - -```bash -mkdir -p /opt/omniroute -``` - -### 2.2 Membuat file variabel lingkungan - -```bash -cat > /opt/omniroute/.env << โ€˜EOFโ€™ -# === Security === -JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY -INITIAL_PASSWORD=YourSecurePassword123! -API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY -STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY -STORAGE_ENCRYPTION_KEY_VERSION=v1 -MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT - -# === 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 (change to your domain) === -BASE_URL=https://llms.seudominio.com -NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com - -# === Cloud Sync (optional) === -# CLOUD_URL=https://cloud.omniroute.online -# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online -EOF -``` - -> โš ๏ธ **PENTING**: Hasilkan kunci rahasia unik! Gunakan `openssl rand -hex 32` untuk setiap kunci. - -### 2.3 Mulai penampung - -```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 Pastikan itu sedang berjalan - -```bash -docker ps | grep omniroute -docker logs omniroute --tail 20 -``` - -Seharusnya menampilkan: `[DB] SQLite database ready` dan `listening on port 20128`. - ---- - -## 3. Konfigurasikan nginx (Proxy Terbalik) - -### 3.1 Menghasilkan sertifikat SSL (Cloudflare Origin) - -Di dasbor Cloudflare: - -1. Buka **SSL/TLS โ†’ Server Asal** -2. Klik **Buat Sertifikat** -3. Pertahankan default (15 tahun, \*.domainanda.com) -4. Salin **Sertifikat Asal** dan **Kunci Pribadi** - -```bash -mkdir -p /etc/nginx/ssl - -# Paste the certificate -nano /etc/nginx/ssl/origin.crt - -# Paste the private key -nano /etc/nginx/ssl/origin.key - -chmod 600 /etc/nginx/ssl/origin.key -``` - -### 3.2 Konfigurasi Nginx - -```bash -cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ -# Default server โ€” blocks direct access via 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.yourdomain.com; # Change to your domain - - 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.yourdomain.com; - return 301 https://$server_name$request_uri; -} -NGINX -``` - -### 3.3 Aktifkan dan Uji - -```bash -# Remove default configuration -rm -f /etc/nginx/sites-enabled/default - -# Enable OmniRoute -ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute - -# Test and reload -nginx -t && systemctl reload nginx -``` - ---- - -## 4. Konfigurasikan DNS Cloudflare - -### 4.1 Tambahkan data DNS - -Di dasbor Cloudflare โ†’ DNS: - -| Ketik | Nama | Konten | Proksi | -| ------ | ------ | ---------------------- | ----------- | -| SEBUAH | `llms` | `203.0.113.10` (IP VM) | โœ… Diproksi | - -### 4.2 Konfigurasikan SSL - -Di bawah **SSL/TLS โ†’ Ikhtisar**: - -- Mode: **Penuh (Ketat)** - -Di bawah **SSL/TLS โ†’ Sertifikat Edge**: - -- Selalu Gunakan HTTPS: โœ… Aktif -- Versi TLS Minimum: TLS 1.2 -- Penulisan Ulang HTTPS Otomatis: โœ… Aktif - -### 4.3 Pengujian - -```bash -curl -sI https://llms.seudominio.com/health -# Should return HTTP/2 200 -``` - ---- - -## 5. Pengoperasian dan Pemeliharaan - -### Tingkatkan ke versi baru - -```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 -``` - -### Lihat log - -```bash -docker logs -f omniroute # Real-time stream -docker logs omniroute --tail 50 # Last 50 lines -``` - -### Pencadangan basis data manual - -```bash -# Copy data from the volume to the host -docker cp omniroute:/app/data ./backup-$(date +%F) - -# Or compress the entire volume -docker run --rm -v omniroute-data:/data -v $(pwd):/backup \ - alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data -``` - -### Pulihkan dari cadangan - -```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. Keamanan Tingkat Lanjut - -### Batasi nginx ke IP Cloudflare - -```bash -cat > /etc/nginx/cloudflare-ips.conf << โ€˜CFโ€™ -# Cloudflare IPv4 ranges โ€” update periodically -# 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 -``` - -Tambahkan yang berikut ini ke `nginx.conf` di dalam blok `http {}`: - -```nginx -include /etc/nginx/cloudflare-ips.conf; -``` - -### Instal fail2ban - -```bash -apt install -y fail2ban -systemctl enable fail2ban -systemctl start fail2ban - -# Check status -fail2ban-client status sshd -``` - -### Blokir akses langsung ke port Docker - -```bash -# Prevent direct external access to port 20128 -iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP -iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT - -# Persist the rules -apt install -y iptables-persistent -netfilter-persistent save -``` - ---- - -## 7. Deploy ke Cloudflare Worker (Opsional) - -Untuk akses jarak jauh melalui Cloudflare Workers (tanpa mengekspos VM secara langsung): - -```bash -# In the local repository -cd omnirouteCloud -npm install -npx wrangler login -npx wrangler deploy -``` - -Lihat dokumentasi selengkapnya di [omnirouteCloud/README.md](../omnirouteCloud/README.md). - ---- - -## Ringkasan Pelabuhan - -| Pelabuhan | Layanan | Akses | -| --------- | ----------- | ------------------------------- | -| 22 | SSH | Publik (dengan fail2ban) | -| 80 | nginx HTTP | Pengalihan โ†’ HTTPS | -| 443 | nginx HTTPS | Melalui Proksi Cloudflare | -| 20128 | OmniRoute | Hanya localhost (melalui nginx) | diff --git a/docs/i18n/id/docs/A2A-SERVER.md b/docs/i18n/id/docs/A2A-SERVER.md new file mode 100644 index 0000000000..a0b8279ad9 --- /dev/null +++ b/docs/i18n/id/docs/A2A-SERVER.md @@ -0,0 +1,200 @@ +# OmniRoute A2A Server Documentation (Bahasa Indonesia) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/A2A-SERVER.md) + +--- + +> Agent-to-Agent Protocol v0.3 โ€” OmniRoute as an intelligent routing agent + +## Agent Discovery + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements. + +--- + +## Authentication + +All `/a2a` requests require an API key via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server, authentication is bypassed. + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Sends a message to a skill and waits for the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a hello world in Python"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "uuid", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "..." }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}} + +: heartbeat 2026-03-03T17:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Available Skills + +| Skill | Description | +| :----------------- | :------------------------------------------------------------------------------------------------------------------------------ | +| `smart-routing` | Routes prompts through OmniRoute's intelligent pipeline. Returns response with routing explanation, cost, and resilience trace. | +| `quota-management` | Answers natural-language queries about provider quotas, suggests free combos, and provides quota rankings. | + +--- + +## Task Lifecycle + +``` +submitted โ†’ working โ†’ completed + โ†’ failed + โ†’ cancelled +``` + +- Tasks expire after 5 minutes (configurable) +- Terminal states: `completed`, `failed`, `cancelled` +- Event log tracks every state transition + +--- + +## Error Codes + +| Code | Meaning | +| :----- | :----------------------------- | +| -32700 | Parse error (invalid JSON) | +| -32600 | Invalid request / Unauthorized | +| -32601 | Method or skill not found | +| -32602 | Invalid params | +| -32603 | Internal error | + +--- + +## Integration Examples + +### Python (requests) + +```python +import requests + +resp = requests.post("http://localhost:20128/a2a", json={ + "jsonrpc": "2.0", "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Hello"}] + } +}, headers={"Authorization": "Bearer YOUR_KEY"}) + +result = resp.json()["result"] +print(result["artifacts"][0]["content"]) +print(result["metadata"]["routing_explanation"]) +``` + +### TypeScript (fetch) + +```typescript +const resp = await fetch("http://localhost:20128/a2a", { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: "Bearer YOUR_KEY", + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "1", + method: "message/send", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Hello" }], + }, + }), +}); +const { result } = await resp.json(); +console.log(result.metadata.routing_explanation); +``` diff --git a/docs/i18n/id/docs/API_REFERENCE.md b/docs/i18n/id/docs/API_REFERENCE.md new file mode 100644 index 0000000000..46432baedc --- /dev/null +++ b/docs/i18n/id/docs/API_REFERENCE.md @@ -0,0 +1,465 @@ +# API Reference (Bahasa Indonesia) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/API_REFERENCE.md) + +--- + +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 | +| `X-Session-Id` | Request | Sticky session key for external session affinity | +| `x_session_id` | Request | Underscore variant also accepted (direct HTTP) | +| `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 | +| `X-OmniRoute-Session-Id` | Response | Effective session ID used by OmniRoute | + +> Nginx note: if you rely on underscore headers (for example `x_session_id`), enable `underscores_in_headers 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/stats + +# Clear all caches +DELETE /api/cache/stats +``` + +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/PATCH | 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 + provider summary (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`) | +| `/api/cache/stats` | 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 | + +### Tunnels + +| Endpoint | Method | Description | +| -------------------------- | ------ | ----------------------------------------------------------------------- | +| `/api/tunnels/cloudflared` | GET | Read Cloudflare Quick Tunnel install/runtime status for the dashboard | +| `/api/tunnels/cloudflared` | POST | Enable or disable the Cloudflare Quick Tunnel (`action=enable/disable`) | + +### 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`. + +### ACP Agents + +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | + +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). + +### Resilience & Rate Limits + +| Endpoint | Method | Description | +| ----------------------- | --------- | ------------------------------- | +| `/api/resilience` | GET/PATCH | 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` diff --git a/docs/i18n/id/docs/ARCHITECTURE.md b/docs/i18n/id/docs/ARCHITECTURE.md new file mode 100644 index 0000000000..f8d0862c0c --- /dev/null +++ b/docs/i18n/id/docs/ARCHITECTURE.md @@ -0,0 +1,814 @@ +# OmniRoute Architecture (Bahasa Indonesia) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/ARCHITECTURE.md) + +--- + +_Last updated: 2026-03-28_ + +## 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 (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developerโ†’system, systemโ†’user) for cross-provider compatibility +- Structured output conversion (json_schema โ†’ Gemini responseSchema) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) +- Global system prompt injection +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout โ†’ budget โ†’ fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) + +Primary runtime model: + +- Next.js 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.) + +## Dashboard Surface (Current) + +Main pages under `src/app/(dashboard)/dashboard/`: + +- `/dashboard` โ€” quick start + provider overview +- `/dashboard/endpoint` โ€” endpoint proxy + MCP + A2A + API endpoint tabs +- `/dashboard/providers` โ€” provider connections and credentials +- `/dashboard/combos` โ€” combo strategies, templates, model routing rules +- `/dashboard/costs` โ€” cost aggregation and pricing visibility +- `/dashboard/analytics` โ€” usage analytics and evaluations +- `/dashboard/limits` โ€” quota/rate controls +- `/dashboard/cli-tools` โ€” CLI onboarding, runtime detection, config generation +- `/dashboard/agents` โ€” detected ACP agents + custom agent registration +- `/dashboard/media` โ€” image/video/music playground +- `/dashboard/search-tools` โ€” search provider testing and history +- `/dashboard/health` โ€” uptime, circuit breakers, rate limits +- `/dashboard/logs` โ€” request/proxy/audit/console logs +- `/dashboard/settings` โ€” system settings tabs (general, routing, combo defaults, etc.) +- `/dashboard/api-manager` โ€” API key lifecycle and model permissions + +## 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[(storage.sqlite)] + UDB[(usage tables + log artifacts)] + end + + subgraph Upstreams[Upstream Providers] + P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/Qoder/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/route.ts` (GET) +- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- OAuth: `src/app/api/oauth/*` +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` +- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI tooling helpers: `src/app/api/cli-tools/*` +- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) +- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) โ€” provider profiles, circuit breaker, rate limit state +- Resilience reset: `src/app/api/resilience/reset` (POST) โ€” reset breakers + cooldowns +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) +- Telemetry: `src/app/api/telemetry/summary` (GET) +- Budget: `src/app/api/usage/budget` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Policies: `src/app/api/policies` (GET/POST) + +## 2) SSE + 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` +- Response sanitization: `open-sse/handlers/responseSanitizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.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`, `qoder.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 (SQLite): + +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** + +Usage persistence: + +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present + +Domain State DB (SQLite): + +- `src/lib/db/domainState.ts` โ€” CRUD operations 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`, `src/shared/services/modelSyncScheduler.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Periodic task: `src/shared/services/modelSyncScheduler.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. Combo routing adds one extra guard: provider-scoped 400s such as upstream content-block and role-validation failures are treated as model-local failures so later combo targets can still run. + +## 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: + +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` + +## Deployment Topology + +```mermaid +flowchart LR + 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[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] + end + + subgraph External[External Services] + Providers[AI Providers] + SyncCloud[Cloud Sync Service] + end + + CLI --> Next + Browser --> Next + Next --> Core + Next --> MainDB + Core --> MainDB + Core --> UsageDB + Core --> Providers + Next --> SyncCloud +``` + +## Module Mapping (Decision-Critical) + +### Route and API Modules + +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle +- `src/app/api/models/alias`: alias management +- `src/app/api/combos*`: fallback combo management +- `src/app/api/pricing`: pricing overrides for cost calculation +- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers +- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) +- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) +- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) +- `src/app/api/sessions`: active session listing (GET) +- `src/app/api/rate-limits`: per-account rate limit status (GET) + +### Routing and Execution Core + +- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior + +### Translation Registry and Format Converters + +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` +- Format constants: `open-sse/translator/formats.ts` + +### Persistence + +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables + +## Provider Executor Coverage (Strategy Pattern) + +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. + +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, Qoder, 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 | +| Qoder | openai | OAuth (Basic) | โœ… | โœ… | โœ… | โš ๏ธ Per request | +| OpenRouter | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| GLM/Kimi/MiniMax | claude | API Key | โœ… | โœ… | โŒ | โŒ | +| DeepSeek | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Groq | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| xAI (Grok) | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Mistral | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Perplexity | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Together AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Fireworks AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Cerebras | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Cohere | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| NVIDIA NIM | openai | API Key | โœ… | โœ… | โŒ | โŒ | + +## Format Translation Coverage + +Detected source formats include: + +- `openai` +- `openai-responses` +- `claude` +- `gemini` + +Target formats include: + +- OpenAI chat/Responses +- Claude +- Gemini/Gemini-CLI/Antigravity envelope +- Kiro +- Cursor + +Translations use **OpenAI as the hub format** โ€” all conversions go through OpenAI as intermediate: + +``` +Source Format โ†’ OpenAI (hub) โ†’ Target Format +``` + +Translations are selected dynamically based on source payload shape and provider target format. + +Additional processing layers in the translation pipeline: + +- **Response sanitization** โ€” Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI targets; merges `system` โ†’ `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** โ€” Parses `...` blocks from content into `reasoning_content` field +- **Structured output** โ€” Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` + +## Supported API Endpoints + +| 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` | Provider Models | Provider model metadata backing custom and managed available models | + +## 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 `/logs//` 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 + +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON โ†’ SQLite migration compatibility path + +## Observability and Operational Signals + +Runtime visibility sources: + +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- four-stage detailed payload captures in SQLite (`request_detail_logs`) when `settings.detailed_logs_enabled=true` +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption + +Detailed request payload capture stores up to four JSON payload stages per routed call: + +- raw request received from the client +- translated request actually sent upstream +- provider response reconstructed as JSON; streamed responses are compacted to the final summary plus stream metadata +- final client response returned by OmniRoute; streamed responses are stored in the same compact summary form + +## Security-Sensitive Boundaries + +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics + +## Environment and Runtime Matrix + +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` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). + +## Operational Verification Checklist + +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: +- `GET /api/settings` +- `GET /api/v1/models` +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/id/docs/AUTO-COMBO.md b/docs/i18n/id/docs/AUTO-COMBO.md new file mode 100644 index 0000000000..93ab4073c9 --- /dev/null +++ b/docs/i18n/id/docs/AUTO-COMBO.md @@ -0,0 +1,67 @@ +# OmniRoute Auto-Combo Engine (Bahasa Indonesia) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/AUTO-COMBO.md) + +--- + +> Self-managing model chains with adaptive scoring + +## How It Works + +The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**: + +| Factor | Weight | Description | +| :--------- | :----- | :---------------------------------------------- | +| Quota | 0.20 | Remaining capacity [0..1] | +| Health | 0.25 | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 | +| CostInv | 0.20 | Inverse cost (cheaper = higher score) | +| LatencyInv | 0.15 | Inverse p95 latency (faster = higher) | +| TaskFit | 0.10 | Model ร— task type fitness score | +| Stability | 0.10 | Low variance in latency/errors | + +## Mode Packs + +| Pack | Focus | Key Weight | +| :---------------------- | :----------- | :--------------- | +| ๐Ÿš€ **Ship Fast** | Speed | latencyInv: 0.35 | +| ๐Ÿ’ฐ **Cost Saver** | Economy | costInv: 0.40 | +| ๐ŸŽฏ **Quality First** | Best model | taskFit: 0.40 | +| ๐Ÿ“ก **Offline Friendly** | Availability | quota: 0.40 | + +## Self-Healing + +- **Temporary exclusion**: Score < 0.2 โ†’ excluded for 5 min (progressive backoff, max 30 min) +- **Circuit breaker awareness**: OPEN โ†’ auto-excluded; HALF_OPEN โ†’ probe requests +- **Incident mode**: >50% OPEN โ†’ disable exploration, maximize stability +- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout + +## Bandit Exploration + +5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode. + +## API + +```bash +# Create auto-combo +curl -X POST http://localhost:20128/api/combos/auto \ + -H "Content-Type: application/json" \ + -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}' + +# List auto-combos +curl http://localhost:20128/api/combos/auto +``` + +## Task Fitness + +30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` โ†’ high coding score). + +## Files + +| File | Purpose | +| :------------------------------------------- | :------------------------------------ | +| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization | +| `open-sse/services/autoCombo/taskFitness.ts` | Model ร— task fitness lookup | +| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap | +| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode | +| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles | +| `src/app/api/combos/auto/route.ts` | REST API | diff --git a/docs/i18n/id/docs/CLI-TOOLS.md b/docs/i18n/id/docs/CLI-TOOLS.md new file mode 100644 index 0000000000..b5bc640f08 --- /dev/null +++ b/docs/i18n/id/docs/CLI-TOOLS.md @@ -0,0 +1,348 @@ +# CLI Tools Setup Guide โ€” OmniRoute (Bahasa Indonesia) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CLI-TOOLS.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CLI-TOOLS.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CLI-TOOLS.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CLI-TOOLS.md) + +--- + +This guide explains how to install and configure all supported AI coding CLI tools +to use **OmniRoute** as the unified backend, giving you centralized key management, +cost tracking, model switching, and request logging across every tool. + +--- + +## How It Works + +``` +Claude / Codex / OpenCode / Cline / KiloCode / Continue / Kiro / Cursor / Copilot + โ”‚ + โ–ผ (all point to OmniRoute) + http://YOUR_SERVER:20128/v1 + โ”‚ + โ–ผ (OmniRoute routes to the right provider) + Anthropic / OpenAI / Gemini / DeepSeek / Groq / Mistral / ... +``` + +**Benefits:** + +- One API key to manage all tools +- Cost tracking across all CLIs in the dashboard +- Model switching without reconfiguring every tool +- Works locally and on remote servers (VPS) + +--- + +## Supported Tools (Dashboard Source of Truth) + +The dashboard cards in `/dashboard/cli-tools` are generated from `src/shared/constants/cliTools.ts`. +Current list (v3.0.0-rc.16): + +| Tool | ID | Command | Setup Mode | Install Method | +| ------------------ | ------------- | ---------- | ---------- | -------------- | +| **Claude Code** | `claude` | `claude` | env | npm | +| **OpenAI Codex** | `codex` | `codex` | custom | npm | +| **Factory Droid** | `droid` | `droid` | custom | bundled/CLI | +| **OpenClaw** | `openclaw` | `openclaw` | custom | bundled/CLI | +| **Cursor** | `cursor` | app | guide | desktop app | +| **Cline** | `cline` | `cline` | custom | npm | +| **Kilo Code** | `kilo` | `kilocode` | custom | npm | +| **Continue** | `continue` | extension | guide | VS Code | +| **Antigravity** | `antigravity` | internal | mitm | OmniRoute | +| **GitHub Copilot** | `copilot` | extension | custom | VS Code | +| **OpenCode** | `opencode` | `opencode` | guide | npm | +| **Kiro AI** | `kiro` | app/cli | mitm | desktop/CLI | + +### CLI fingerprint sync (Agents + Settings) + +`/dashboard/agents` and `Settings > CLI Fingerprint` use `src/shared/constants/cliCompatProviders.ts`. +This keeps provider IDs aligned with CLI cards and legacy IDs. + +| CLI ID | Fingerprint Provider ID | +| ---------------------------------------------------------------------------------------------------- | ----------------------- | +| `kilo` | `kilocode` | +| `copilot` | `github` | +| `claude` / `codex` / `antigravity` / `kiro` / `cursor` / `cline` / `opencode` / `droid` / `openclaw` | same ID | + +Legacy IDs still accepted for compatibility: `copilot`, `kimi-coding`, `qwen`. + +--- + +## Step 1 โ€” Get an OmniRoute API Key + +1. Open the OmniRoute dashboard โ†’ **API Manager** (`/dashboard/api-manager`) +2. Click **Create API Key** +3. Give it a name (e.g. `cli-tools`) and select all permissions +4. Copy the key โ€” you'll need it for every CLI below + +> Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` + +--- + +## Step 2 โ€” Install CLI Tools + +All npm-based tools require Node.js 18+: + +```bash +# Claude Code (Anthropic) +npm install -g @anthropic-ai/claude-code + +# OpenAI Codex +npm install -g @openai/codex + +# OpenCode +npm install -g opencode-ai + +# Cline +npm install -g cline + +# KiloCode +npm install -g kilocode + +# Kiro CLI (Amazon โ€” requires curl + unzip) +apt-get install -y unzip # on Debian/Ubuntu +curl -fsSL https://cli.kiro.dev/install | bash +export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc +``` + +**Verify:** + +```bash +claude --version # 2.x.x +codex --version # 0.x.x +opencode --version # x.x.x +cline --version # 2.x.x +kilocode --version # x.x.x (or: kilo --version) +kiro-cli --version # 1.x.x +``` + +--- + +## Step 3 โ€” Set Global Environment Variables + +Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`: + +```bash +# OmniRoute Universal Endpoint +export OPENAI_BASE_URL="http://localhost:20128/v1" +export OPENAI_API_KEY="sk-your-omniroute-key" +export ANTHROPIC_BASE_URL="http://localhost:20128/v1" +export ANTHROPIC_API_KEY="sk-your-omniroute-key" +export GEMINI_BASE_URL="http://localhost:20128/v1" +export GEMINI_API_KEY="sk-your-omniroute-key" +``` + +> For a **remote server** replace `localhost:20128` with the server IP or domain, +> e.g. `http://192.168.0.15:20128`. + +--- + +## Step 4 โ€” Configure Each Tool + +### Claude Code + +```bash +# Via CLI: +claude config set --global api-base-url http://localhost:20128/v1 + +# Or create ~/.claude/settings.json: +mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF +{ + "apiBaseUrl": "http://localhost:20128/v1", + "apiKey": "sk-your-omniroute-key" +} +EOF +``` + +**Test:** `claude "say hello"` + +--- + +### OpenAI Codex + +```bash +mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF +model: auto +apiKey: sk-your-omniroute-key +apiBaseUrl: http://localhost:20128/v1 +EOF +``` + +**Test:** `codex "what is 2+2?"` + +--- + +### OpenCode + +```bash +mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF +[provider.openai] +base_url = "http://localhost:20128/v1" +api_key = "sk-your-omniroute-key" +EOF +``` + +**Test:** `opencode` + +--- + +### Cline (CLI or VS Code) + +**CLI mode:** + +```bash +mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF +{ + "apiProvider": "openai", + "openAiBaseUrl": "http://localhost:20128/v1", + "openAiApiKey": "sk-your-omniroute-key" +} +EOF +``` + +**VS Code mode:** +Cline extension settings โ†’ API Provider: `OpenAI Compatible` โ†’ Base URL: `http://localhost:20128/v1` + +Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ Cline โ†’ Apply Config**. + +--- + +### KiloCode (CLI or VS Code) + +**CLI mode:** + +```bash +kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key +``` + +**VS Code settings:** + +```json +{ + "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", + "kilo-code.apiKey": "sk-your-omniroute-key" +} +``` + +Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ KiloCode โ†’ Apply Config**. + +--- + +### Continue (VS Code Extension) + +Edit `~/.continue/config.yaml`: + +```yaml +models: + - name: OmniRoute + provider: openai + model: auto + apiBase: http://localhost:20128/v1 + apiKey: sk-your-omniroute-key + default: true +``` + +Restart VS Code after editing. + +--- + +### Kiro CLI (Amazon) + +```bash +# Login to your AWS/Kiro account: +kiro-cli login + +# The CLI uses its own auth โ€” OmniRoute is not needed as backend for Kiro CLI itself. +# Use kiro-cli alongside OmniRoute for other tools. +kiro-cli status +``` + +--- + +### Cursor (Desktop App) + +> **Note:** Cursor routes requests through its cloud. For OmniRoute integration, +> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL. + +Via GUI: **Settings โ†’ Models โ†’ OpenAI API Key** + +- Base URL: `https://your-domain.com/v1` +- API Key: your OmniRoute key + +--- + +## Dashboard Auto-Configuration + +The OmniRoute dashboard automates configuration for most tools: + +1. Go to `http://localhost:20128/dashboard/cli-tools` +2. Expand any tool card +3. Select your API key from the dropdown +4. Click **Apply Config** (if tool is detected as installed) +5. Or copy the generated config snippet manually + +--- + +## Built-in Agents: Droid & OpenClaw + +**Droid** and **OpenClaw** are AI agents built directly into OmniRoute โ€” no installation needed. +They run as internal routes and use OmniRoute's model routing automatically. + +- Access: `http://localhost:20128/dashboard/agents` +- Configure: same combos and providers as all other tools +- No API key or CLI install required + +--- + +## Available API Endpoints + +| Endpoint | Description | Use For | +| -------------------------- | ----------------------------- | --------------------------- | +| `/v1/chat/completions` | Standard chat (all providers) | All modern tools | +| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows | +| `/v1/completions` | Legacy text completions | Older tools using `prompt:` | +| `/v1/embeddings` | Text embeddings | RAG, search | +| `/v1/images/generations` | Image generation | DALL-E, Flux, etc. | +| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS | +| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI | + +--- + +## Pemecahan Masalah + +| Error | Cause | Fix | +| ------------------------- | ----------------------- | ------------------------------------------ | +| `Connection refused` | OmniRoute not running | `pm2 start omniroute` | +| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` | +| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` | +| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` | +| CLI shows "not installed" | Binary not in PATH | Check `which ` | +| `kiro-cli: not found` | Not in PATH | `export PATH="$HOME/.local/bin:$PATH"` | + +--- + +## Quick Setup Script (One Command) + +```bash +# Install all CLIs and configure for OmniRoute (replace with your key and server URL) +OMNIROUTE_URL="http://localhost:20128/v1" +OMNIROUTE_KEY="sk-your-omniroute-key" + +npm install -g @anthropic-ai/claude-code @openai/codex opencode-ai cline kilocode + +# Kiro CLI +apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash + +# Write configs +mkdir -p ~/.claude ~/.codex ~/.config/opencode ~/.continue + +cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" +cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" +cat >> ~/.bashrc << EOF +export OPENAI_BASE_URL="$OMNIROUTE_URL" +export OPENAI_API_KEY="$OMNIROUTE_KEY" +export ANTHROPIC_BASE_URL="$OMNIROUTE_URL" +export ANTHROPIC_API_KEY="$OMNIROUTE_KEY" +EOF + +source ~/.bashrc +echo "โœ… All CLIs installed and configured for OmniRoute" +``` diff --git a/docs/i18n/id/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/id/docs/CODEBASE_DOCUMENTATION.md new file mode 100644 index 0000000000..5520de1fbf --- /dev/null +++ b/docs/i18n/id/docs/CODEBASE_DOCUMENTATION.md @@ -0,0 +1,591 @@ +# omniroute โ€” Codebase Documentation (Bahasa Indonesia) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CODEBASE_DOCUMENTATION.md) + +--- + +> 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
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, Qoder, 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. + +#### Arsitektur + +```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 | +| Qoder | 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"] +``` diff --git a/docs/i18n/id/docs/COVERAGE_PLAN.md b/docs/i18n/id/docs/COVERAGE_PLAN.md new file mode 100644 index 0000000000..bf1879e447 --- /dev/null +++ b/docs/i18n/id/docs/COVERAGE_PLAN.md @@ -0,0 +1,170 @@ +# Test Coverage Plan (Bahasa Indonesia) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/COVERAGE_PLAN.md) + +--- + +Last updated: 2026-03-28 + +## Baseline + +There are multiple coverage numbers depending on how the report is computed. For planning, only one of them is useful. + +| Metric | Scope | Statements / Lines | Branches | Functions | Notes | +| -------------------- | ----------------------------------------------------- | -----------------: | -------: | --------: | --------------------------------------------------- | +| Legacy | Old `npm run test:coverage` | 79.42% | 75.15% | 67.94% | Inflated: counts test files and excludes `open-sse` | +| Diagnostic | Source-only, excluding tests and excluding `open-sse` | 68.16% | 63.55% | 64.06% | Useful only to isolate `src/**` | +| Recommended baseline | Source-only, excluding tests and including `open-sse` | 56.95% | 66.05% | 57.80% | This is the project-wide baseline to improve | + +The recommended baseline is the number to optimize against. + +## Rules + +- Coverage targets apply to source files, not to `tests/**`. +- `open-sse/**` is part of the product and must remain in scope. +- New code should not reduce coverage in touched areas. +- Prefer testing behavior and branch outcomes over implementation details. +- Prefer temp SQLite databases and small fixtures over broad mocks for `src/lib/db/**`. + +## Current command set + +- `npm run test:coverage` + - Main source coverage gate for the unit test suite + - Generates `text-summary`, `html`, `json-summary`, and `lcov` +- `npm run coverage:report` + - Detailed file-by-file report from the latest run +- `npm run test:coverage:legacy` + - Historical comparison only + +## Milestones + +| Phase | Target | Focus | +| ------- | ---------------------: | ------------------------------------------------- | +| Phase 1 | 60% statements / lines | Quick wins and low-risk utility coverage | +| Phase 2 | 65% statements / lines | DB and route foundations | +| Phase 3 | 70% statements / lines | Provider validation and usage analytics | +| Phase 4 | 75% statements / lines | `open-sse` translators and helpers | +| Phase 5 | 80% statements / lines | `open-sse` handlers and executor branches | +| Phase 6 | 85% statements / lines | Harder edge cases, branch debt, regression suites | +| Phase 7 | 90% statements / lines | Final sweep, gap closure, strict ratchet | + +Branches and functions should ratchet upward with each phase, but the primary hard target is statements / lines. + +## Priority hotspots + +These files or areas offer the best return for the next phases: + +1. `open-sse/handlers` + - `chatCore.ts` at 7.57% + - Overall directory at 29.07% +2. `open-sse/translator/request` + - Overall directory at 36.39% + - Many translators are still near single-digit coverage +3. `open-sse/translator/response` + - Overall directory at 8.07% +4. `open-sse/executors` + - Overall directory at 36.62% +5. `src/lib/db` + - `models.ts` at 20.66% + - `registeredKeys.ts` at 34.46% + - `modelComboMappings.ts` at 36.25% + - `settings.ts` at 46.40% + - `webhooks.ts` at 33.33% +6. `src/lib/usage` + - `usageHistory.ts` at 21.12% + - `usageStats.ts` at 9.56% + - `costCalculator.ts` at 30.00% +7. `src/lib/providers` + - `validation.ts` at 41.16% +8. Low-risk utility and API files for early gains + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/api/errorResponse.ts` + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +## Execution checklist + +### Phase 1: 56.95% -> 60% + +- [x] Fix coverage metric so it reflects source code instead of test files +- [x] Keep a legacy coverage script for comparison +- [x] Record the baseline and hotspots in-repo +- [ ] Add focused tests for low-risk utilities: + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/fetchTimeout.ts` + - `src/lib/api/errorResponse.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/display/names.ts` +- [ ] Add route tests for: + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +### Phase 2: 60% -> 65% + +- [ ] Add DB-backed tests for: + - `src/lib/db/modelComboMappings.ts` + - `src/lib/db/settings.ts` + - `src/lib/db/registeredKeys.ts` +- [ ] Cover branch behavior in: + - `src/lib/providers/validation.ts` + - `src/app/api/v1/embeddings/route.ts` + - `src/app/api/v1/moderations/route.ts` + +### Phase 3: 65% -> 70% + +- [ ] Add usage analytics tests for: + - `src/lib/usage/usageHistory.ts` + - `src/lib/usage/usageStats.ts` + - `src/lib/usage/costCalculator.ts` +- [ ] Expand route coverage for proxy management and settings branches + +### Phase 4: 70% -> 75% + +- [ ] Cover translator helpers and central translation paths: + - `open-sse/translator/index.ts` + - `open-sse/translator/helpers/*` + - `open-sse/translator/request/*` + - `open-sse/translator/response/*` + +### Phase 5: 75% -> 80% + +- [ ] Add handler-level tests for: + - `open-sse/handlers/chatCore.ts` + - `open-sse/handlers/responsesHandler.js` + - `open-sse/handlers/imageGeneration.js` + - `open-sse/handlers/embeddings.js` +- [ ] Add executor branch coverage for provider-specific auth, retries, and endpoint overrides + +### Phase 6: 80% -> 85% + +- [ ] Merge more edge-case suites into the main coverage path +- [ ] Increase function coverage for DB modules with weak constructor/helper coverage +- [ ] Close branch gaps in `settings.ts`, `registeredKeys.ts`, `validation.ts`, and translator helpers + +### Phase 7: 85% -> 90% + +- [ ] Treat the remaining low-coverage files as blockers +- [ ] Add regression tests for every uncovered production bug fixed during the push to 90% +- [ ] Raise the coverage gate in CI only after the local baseline is stable for at least two consecutive runs + +## Ratchet policy + +Update `npm run test:coverage` thresholds only after the project actually exceeds the next milestone with a comfortable buffer. + +Recommended ratchet sequence: + +1. 55/60/55 +2. 60/62/58 +3. 65/64/62 +4. 70/66/66 +5. 75/70/72 +6. 80/75/78 +7. 85/80/84 +8. 90/85/88 + +Order is `statements-lines / branches / functions`. + +## Known gap + +The current coverage command measures the main Node unit suite and includes source reached from it, including `open-sse`. It does not yet merge Vitest coverage into a single unified report. That merge is worth doing later, but it is not a blocker for starting the 60% -> 80% climb. diff --git a/docs/i18n/id/docs/FEATURES.md b/docs/i18n/id/docs/FEATURES.md index e8d75290d9..a64cb87fa3 100644 --- a/docs/i18n/id/docs/FEATURES.md +++ b/docs/i18n/id/docs/FEATURES.md @@ -1,6 +1,6 @@ # OmniRoute โ€” Dashboard Features Gallery (Bahasa Indonesia) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/FEATURES.md) --- @@ -10,7 +10,7 @@ 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). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. ![Providers Dashboard](screenshots/01-providers.png) diff --git a/docs/i18n/id/docs/MCP-SERVER.md b/docs/i18n/id/docs/MCP-SERVER.md new file mode 100644 index 0000000000..e4f6380858 --- /dev/null +++ b/docs/i18n/id/docs/MCP-SERVER.md @@ -0,0 +1,87 @@ +# OmniRoute MCP Server Documentation (Bahasa Indonesia) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/MCP-SERVER.md) + +--- + +> Model Context Protocol server with 16 intelligent tools + +## Instal + +OmniRoute MCP is built-in. Start it with: + +```bash +omniroute --mcp +``` + +Or via the open-sse transport: + +```bash +# HTTP streamable transport (port 20130) +omniroute --dev # MCP auto-starts on /mcp endpoint +``` + +## IDE Configuration + +See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup. + +--- + +## Essential Tools (8) + +| Tool | Description | +| :------------------------------ | :--------------------------------------- | +| `omniroute_get_health` | Gateway health, circuit breakers, uptime | +| `omniroute_list_combos` | All configured combos with models | +| `omniroute_get_combo_metrics` | Performance metrics for a specific combo | +| `omniroute_switch_combo` | Switch active combo by ID/name | +| `omniroute_check_quota` | Quota status per provider or all | +| `omniroute_route_request` | Send a chat completion through OmniRoute | +| `omniroute_cost_report` | Cost analytics for a time period | +| `omniroute_list_models_catalog` | Full model catalog with capabilities | + +## Advanced Tools (8) + +| Tool | Description | +| :--------------------------------- | :---------------------------------------------------------- | +| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | +| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | +| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | +| `omniroute_test_combo` | Live-test all models in a combo via a real upstream request | +| `omniroute_get_provider_metrics` | Detailed metrics for one provider | +| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | +| `omniroute_explain_route` | Explain a past routing decision | +| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | + +## Authentication + +MCP tools are authenticated via API key scopes. Each tool requires specific scopes: + +| Scope | Tools | +| :------------- | :----------------------------------------------- | +| `read:health` | get_health, get_provider_metrics | +| `read:combos` | list_combos, get_combo_metrics | +| `write:combos` | switch_combo | +| `read:quota` | check_quota | +| `write:route` | route_request, simulate_route, test_combo | +| `read:usage` | cost_report, get_session_snapshot, explain_route | +| `write:config` | set_budget_guard, set_resilience_profile | +| `read:models` | list_models_catalog, best_combo_for_task | + +## Audit Logging + +Every tool call is logged to `mcp_tool_audit` with: + +- Tool name, arguments, result +- Duration (ms), success/failure +- API key hash, timestamp + +## Files + +| File | Purpose | +| :------------------------------------------- | :------------------------------------------ | +| `open-sse/mcp-server/server.ts` | MCP server creation + 16 tool registrations | +| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport | +| `open-sse/mcp-server/auth.ts` | API key + scope validation | +| `open-sse/mcp-server/audit.ts` | Tool call audit logging | +| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers | diff --git a/docs/i18n/id/docs/RELEASE_CHECKLIST.md b/docs/i18n/id/docs/RELEASE_CHECKLIST.md new file mode 100644 index 0000000000..93b8734624 --- /dev/null +++ b/docs/i18n/id/docs/RELEASE_CHECKLIST.md @@ -0,0 +1,37 @@ +# Release Checklist (Bahasa Indonesia) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/RELEASE_CHECKLIST.md) + +--- + +Use this checklist before tagging or publishing a new OmniRoute release. + +## Version and Changelog + +1. Bump `package.json` version (`x.y.z`) in the release branch. +2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: + - `## [x.y.z] โ€” YYYY-MM-DD` +3. Keep `## [Unreleased]` as the first changelog section for upcoming work. +4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. + +## API Docs + +1. Update `docs/openapi.yaml`: + - `info.version` must equal `package.json` version. +2. Validate endpoint examples if API contracts changed. + +## Runtime Docs + +1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. +2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. +3. Update localized docs if source docs changed significantly. + +## Automated Check + +Run the sync guard locally before opening PR: + +```bash +npm run check:docs-sync +``` + +CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/id/docs/TROUBLESHOOTING.md b/docs/i18n/id/docs/TROUBLESHOOTING.md new file mode 100644 index 0000000000..9589c02040 --- /dev/null +++ b/docs/i18n/id/docs/TROUBLESHOOTING.md @@ -0,0 +1,256 @@ +# Troubleshooting (Bahasa Indonesia) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/TROUBLESHOOTING.md) + +--- + +Common problems and solutions for OmniRoute. + +--- + +## Quick Fixes + +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | + +--- + +## Provider Issues + +### "Language model did not provide messages" + +**Cause:** Provider quota exhausted. + +**Fix:** + +1. 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, Qoder) 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}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) + +--- + +## Circuit Breaker Issues + +### Provider stuck in OPEN state + +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. + +**Fix:** + +1. 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 +- **SDK returns raw string instead of object** โ€” Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** โ€” Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** โ€” Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** โ€” Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` + +--- + +## Resilience Settings + +### Auto rate-limit not triggering + +- 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. + +--- + +## Optional RAG / LLM failure taxonomy (16 problems) + +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` โ€ฆ `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard โ†’ Health** for real-time system status +- **Translator**: Use **Dashboard โ†’ Translator** to debug format issues diff --git a/docs/i18n/id/USER_GUIDE.md b/docs/i18n/id/docs/USER_GUIDE.md similarity index 82% rename from docs/i18n/id/USER_GUIDE.md rename to docs/i18n/id/docs/USER_GUIDE.md index 0814b5ba82..c30d2ac6ed 100644 --- a/docs/i18n/id/USER_GUIDE.md +++ b/docs/i18n/id/docs/USER_GUIDE.md @@ -1,8 +1,6 @@ # User Guide (Bahasa Indonesia) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/USER_GUIDE.md) - -> ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/USER_GUIDE.md) --- @@ -320,7 +318,7 @@ Model: cc/claude-opus-4-6 --- -## ๐Ÿš€ Deployment +## Penerapan ### Global npm install (Recommended) @@ -511,23 +509,26 @@ post_install() { ### Environment Variables -| Variable | Default | Description | -| ------------------------- | ------------------------------------ | ------------------------------------------------------- | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | -| `INITIAL_PASSWORD` | `123456` | First login password | -| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | -| `PORT` | framework default | Service port (`20128` in examples) | -| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | -| `NODE_ENV` | runtime default | Set `production` for deploy | -| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | -| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | -| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | -| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | -| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | -| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | -| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | -| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | +| 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/*` | +| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand | +| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | For the full environment variable reference, see the [README](../README.md). @@ -598,6 +599,11 @@ curl -X POST http://localhost:20128/api/provider-models \ Or use Dashboard: **Providers โ†’ [Provider] โ†’ Custom Models**. +Notes: + +- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers. +- The **Custom Models** section is intended for providers that do not expose managed available-model imports. + ### Dedicated Provider Routes Route requests directly to a specific provider with model validation: @@ -642,6 +648,14 @@ Returns models grouped by provider with types (`chat`, `embedding`, `image`). - Automatic background sync with timeout + fail-fast - Prefer server-side `BASE_URL`/`CLOUD_URL` in production +### Cloudflare Quick Tunnel + +- Available in **Dashboard โ†’ Endpoints** for Docker and other self-hosted deployments +- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint +- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary +- Tunnel URLs are ephemeral and change every time you stop/start the tunnel +- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download + ### LLM Gateway Intelligence (Phase 9) - **Semantic Cache** โ€” Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) @@ -757,11 +771,11 @@ OmniRoute implements provider-level resilience with four components: 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 | +| 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 unless `DISABLE_SQLITE_AUTO_BACKUP=true` | ```bash # API: Export database @@ -787,10 +801,11 @@ curl -X POST http://localhost:20128/api/db-backups/import \ ### Settings Dashboard -The settings page is organized into 5 tabs for easy navigation: +The settings page is organized into 6 tabs for easy navigation: | Tab | Contents | | -------------- | ---------------------------------------------------------------------------------------------- | +| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility | | **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | | **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | | **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | diff --git a/docs/i18n/id/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/id/docs/VM_DEPLOYMENT_GUIDE.md new file mode 100644 index 0000000000..0a649b4978 --- /dev/null +++ b/docs/i18n/id/docs/VM_DEPLOYMENT_GUIDE.md @@ -0,0 +1,403 @@ +# OmniRoute โ€” Deployment Guide on VM with Cloudflare (Bahasa Indonesia) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/VM_DEPLOYMENT_GUIDE.md) + +--- + +Complete guide to install and configure OmniRoute on a VM (VPS) with domain managed via Cloudflare. + +--- + +## Prerequisites + +| Item | Minimum | Recommended | +| ---------- | ------------------------ | ---------------- | +| **CPU** | 1 vCPU | 2 vCPU | +| **RAM** | 1 GB | 2 GB | +| **Disk** | 10 GB SSD | 25 GB SSD | +| **OS** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS | +| **Domain** | Registered on Cloudflare | โ€” | +| **Docker** | Docker Engine 24+ | Docker 27+ | + +**Tested providers**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. + +--- + +## 1. Configure the VM + +### 1.1 Create the instance + +On your preferred VPS provider: + +- Choose Ubuntu 24.04 LTS +- Select the minimum plan (1 vCPU / 1 GB RAM) +- Set a strong root password or configure SSH key +- Note the **public IP** (e.g., `203.0.113.10`) + +### 1.2 Connect via SSH + +```bash +ssh root@203.0.113.10 +``` + +### 1.3 Update the system + +```bash +apt update && apt upgrade -y +``` + +### 1.4 Install Docker + +```bash +# Install dependencies +apt install -y ca-certificates curl gnupg + +# Add official Docker repository +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 Install nginx + +```bash +apt install -y nginx +``` + +### 1.6 Configure 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 +``` + +> **Tip**: For maximum security, restrict ports 80 and 443 to Cloudflare IPs only. See the [Advanced Security](#advanced-security) section. + +--- + +## 2. Install OmniRoute + +### 2.1 Create configuration directory + +```bash +mkdir -p /opt/omniroute +``` + +### 2.2 Create environment variables file + +```bash +cat > /opt/omniroute/.env << โ€˜EOFโ€™ +# === Security === +JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY +INITIAL_PASSWORD=YourSecurePassword123! +API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY +STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY +STORAGE_ENCRYPTION_KEY_VERSION=v1 +MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT + +# === 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 (change to your domain) === +BASE_URL=https://llms.seudominio.com +NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com + +# === Cloud Sync (optional) === +# CLOUD_URL=https://cloud.omniroute.online +# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online +EOF +``` + +> โš ๏ธ **IMPORTANT**: Generate unique secret keys! Use `openssl rand -hex 32` for each key. + +### 2.3 Start the 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 Verify that it is running + +```bash +docker ps | grep omniroute +docker logs omniroute --tail 20 +``` + +It should display: `[DB] SQLite database ready` and `listening on port 20128`. + +--- + +## 3. Configure nginx (Reverse Proxy) + +### 3.1 Generate SSL certificate (Cloudflare Origin) + +In the Cloudflare dashboard: + +1. Go to **SSL/TLS โ†’ Origin Server** +2. Click **Create Certificate** +3. Keep the defaults (15 years, \*.yourdomain.com) +4. Copy the **Origin Certificate** and the **Private Key** + +```bash +mkdir -p /etc/nginx/ssl + +# Paste the certificate +nano /etc/nginx/ssl/origin.crt + +# Paste the private key +nano /etc/nginx/ssl/origin.key + +chmod 600 /etc/nginx/ssl/origin.key +``` + +### 3.2 Nginx Configuration + +```bash +cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ +# Default server โ€” blocks direct access via 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.yourdomain.com; # Change to your domain + + 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.yourdomain.com; + return 301 https://$server_name$request_uri; +} +NGINX +``` + +### 3.3 Enable and Test + +```bash +# Remove default configuration +rm -f /etc/nginx/sites-enabled/default + +# Enable OmniRoute +ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute + +# Test and reload +nginx -t && systemctl reload nginx +``` + +--- + +## 4. Configure Cloudflare DNS + +### 4.1 Add DNS record + +In the Cloudflare dashboard โ†’ DNS: + +| Type | Name | Content | Proxy | +| ---- | ------ | ---------------------- | ---------- | +| A | `llms` | `203.0.113.10` (VM IP) | โœ… Proxied | + +### 4.2 Configure SSL + +Under **SSL/TLS โ†’ Overview**: + +- Mode: **Full (Strict)** + +Under **SSL/TLS โ†’ Edge Certificates**: + +- Always Use HTTPS: โœ… On +- Minimum TLS Version: TLS 1.2 +- Automatic HTTPS Rewrites: โœ… On + +### 4.3 Testing + +```bash +curl -sI https://llms.seudominio.com/health +# Should return HTTP/2 200 +``` + +--- + +## 5. Operations and Maintenance + +### Upgrade to a new version + +```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 +``` + +### View logs + +```bash +docker logs -f omniroute # Real-time stream +docker logs omniroute --tail 50 # Last 50 lines +``` + +### Manual database backup + +```bash +# Copy data from the volume to the host +docker cp omniroute:/app/data ./backup-$(date +%F) + +# Or compress the entire volume +docker run --rm -v omniroute-data:/data -v $(pwd):/backup \ + alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data +``` + +### Restore from 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. Advanced Security + +### Restrict nginx to Cloudflare IPs + +```bash +cat > /etc/nginx/cloudflare-ips.conf << โ€˜CFโ€™ +# Cloudflare IPv4 ranges โ€” update periodically +# 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 +``` + +Add the following to `nginx.conf` inside the `http {}` block: + +```nginx +include /etc/nginx/cloudflare-ips.conf; +``` + +### Install fail2ban + +```bash +apt install -y fail2ban +systemctl enable fail2ban +systemctl start fail2ban + +# Check status +fail2ban-client status sshd +``` + +### Block direct access to the Docker port + +```bash +# Prevent direct external access to port 20128 +iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP +iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT + +# Persist the rules +apt install -y iptables-persistent +netfilter-persistent save +``` + +--- + +## 7. Deploy to Cloudflare Workers (Optional) + +For remote access via Cloudflare Workers (without exposing the VM directly): + +```bash +# In the local repository +cd omnirouteCloud +npm install +npx wrangler login +npx wrangler deploy +``` + +See the full documentation at [omnirouteCloud/README.md](../omnirouteCloud/README.md). + +--- + +## Port Summary + +| Port | Service | Access | +| ----- | ----------- | -------------------------- | +| 22 | SSH | Public (with fail2ban) | +| 80 | nginx HTTP | Redirect โ†’ HTTPS | +| 443 | nginx HTTPS | Via Cloudflare Proxy | +| 20128 | OmniRoute | Localhost only (via nginx) | diff --git a/docs/i18n/id/src/lib/a2a/README.md b/docs/i18n/id/src/lib/a2a/README.md new file mode 100644 index 0000000000..54f6d52556 --- /dev/null +++ b/docs/i18n/id/src/lib/a2a/README.md @@ -0,0 +1,752 @@ +# OmniRoute A2A Server (Bahasa Indonesia) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../../../src/lib/a2a/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../../../es/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../../../fr/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../../../de/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../../../it/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../../../ru/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../../../zh-CN/src/lib/a2a/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../../../ja/src/lib/a2a/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../../../ko/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../../../ar/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../../../in/src/lib/a2a/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../../../th/src/lib/a2a/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../../../vi/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../../../id/src/lib/a2a/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../../../ms/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../../../nl/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../../../pl/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../../../sv/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../../../no/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../../../da/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../../../fi/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../../../pt/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../../../ro/src/lib/a2a/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../../../hu/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../../../bg/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../../../sk/src/lib/a2a/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../../../uk-UA/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../../../he/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../../../phi/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../../../pt-BR/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../../../cs/src/lib/a2a/README.md) + +--- + +> **Agent-to-Agent Protocol v0.3** โ€” Enables any AI agent to use OmniRoute as an intelligent routing agent via JSON-RPC 2.0. + +The A2A Server exposes OmniRoute as a **first-class agent** that other agents can discover, delegate tasks to, and collaborate with using the [A2A Protocol](https://google.github.io/A2A/). + +--- + +## Arsitektur + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Orchestrator Agent โ”‚ +โ”‚ (LangChain, CrewAI, AutoGen, Custom Agent) โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ 1. GET /.well-known/agent.json (discover) + โ”‚ 2. POST /a2a (JSON-RPC 2.0) + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ OmniRoute A2A Server โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Task Manager โ”‚ โ”‚ Skill Engine โ”‚ โ”‚ SSE Streaming โ”‚ โ”‚ +โ”‚ โ”‚ (lifecycle) โ”‚โ”€โ”€โ”‚ (registry) โ”‚โ”€โ”€โ”‚ (real-time) โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ +โ”‚ Skills: โ”‚ โ”‚ +โ”‚ โ”œโ”€ smart-routing โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ””โ”€ quota-management โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ Routing Decision Logger โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ OmniRoute Gateway (internal) + /v1/chat/completions, /api/combos, /api/usage/quota +``` + +--- + +## Mulai Cepat + +### Agent Discovery + +Every A2A-compatible agent exposes an **Agent Card** at `/.well-known/agent.json`: + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +**Response:** + +```json +{ + "name": "OmniRoute", + "description": "Intelligent AI gateway with auto-routing across 50+ providers", + "url": "http://localhost:20128/a2a", + "version": "1.8.1", + "capabilities": { + "streaming": true, + "pushNotifications": false + }, + "skills": [ + { + "id": "smart-routing", + "name": "Smart Routing", + "description": "Routes prompts through OmniRoute intelligent pipeline", + "tags": ["routing", "llm", "multi-provider", "cost-optimization"], + "examples": [ + "Write a hello world in Python", + "Explain quantum computing using the cheapest provider" + ] + }, + { + "id": "quota-management", + "name": "Quota Management", + "description": "Natural-language queries about provider quotas", + "tags": ["quota", "analytics", "cost"], + "examples": [ + "Which provider has the most quota remaining?", + "Suggest a free combo for coding" + ] + } + ], + "authentication": { + "schemes": ["bearer"], + "apiKeyHeader": "Authorization" + } +} +``` + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Send a message to a skill and receive the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python hello world"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "a1b2c3d4-...", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "print('Hello, World!')" }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.0030)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "2026-03-04T..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"Quantum computing..."}}} + +: heartbeat 2026-03-04T21:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Running Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Skills Reference + +### `smart-routing` + +Routes prompts through OmniRoute's intelligent pipeline with full observability. + +**Parameters (in `metadata`):** + +| Parameter | Type | Default | Description | +| --------- | -------- | ------------ | ---------------------------------------------------------------------------------------- | +| `model` | `string` | `"auto"` | Target model (e.g., `claude-sonnet-4`, `gpt-4o`, `auto`) | +| `combo` | `string` | active combo | Specific combo to route through | +| `budget` | `number` | none | Maximum cost in USD for this request | +| `role` | `string` | none | Task role hint: `coding`, `review`, `planning`, `analysis`, `debugging`, `documentation` | + +**Returns:** + +| Field | Description | +| ------------------------------ | --------------------------------------------------------- | +| `artifacts[].content` | The LLM response text | +| `metadata.routing_explanation` | Human-readable explanation of routing decision | +| `metadata.cost_envelope` | Estimated vs actual cost with currency | +| `metadata.resilience_trace` | Array of events (primary_selected, fallback_needed, etc.) | +| `metadata.policy_verdict` | Whether the request was allowed and why | + +### `quota-management` + +Answers natural-language queries about provider quotas. + +**Query types (inferred from message content):** + +| Query Pattern | Response Type | +| ---------------------------------------------- | -------------------------------------------------------- | +| Contains `"ranking"`, `"most quota"`, `"best"` | Providers ranked by remaining quota | +| Contains `"free"`, `"suggest"` | Lists free combos or suggests free-tier providers | +| Default | Full quota summary with warnings for low-quota providers | + +--- + +## Task Lifecycle + +``` +submitted โ”€โ”€โ†’ working โ”€โ”€โ†’ completed + โ”€โ”€โ†’ failed + โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ†’ cancelled +``` + +| State | Description | +| ----------- | ----------------------------------------------------- | +| `submitted` | Task created, queued for execution | +| `working` | Skill handler is executing | +| `completed` | Execution succeeded, artifacts available | +| `failed` | Execution failed or task expired (TTL: 5 min default) | +| `cancelled` | Cancelled by client via `tasks/cancel` | + +- Terminal states: `completed`, `failed`, `cancelled` (no further transitions) +- Expired tasks in `submitted` or `working` are auto-marked as `failed` +- Tasks are garbage-collected after 2ร— TTL + +--- + +## Client Examples + +### Python โ€” Orchestrator Agent + +```python +""" +A2A Client โ€” Python example. +Discovers OmniRoute agent, sends a task, and processes the result. +""" +import requests +import json + +BASE_URL = "http://localhost:20128" +API_KEY = "your-api-key" +HEADERS = { + "Content-Type": "application/json", + "Authorization": f"Bearer {API_KEY}", +} + +# 1. Discover agent capabilities +agent_card = requests.get(f"{BASE_URL}/.well-known/agent.json").json() +print(f"Agent: {agent_card['name']} v{agent_card['version']}") +print(f"Skills: {[s['id'] for s in agent_card['skills']]}") + +# 2. Send a smart-routing task +response = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python quicksort implementation"}], + "metadata": { + "model": "auto", + "combo": "fast-coding", + "budget": 0.10, + } + } +}) +result = response.json()["result"] +print(f"\n๐Ÿ“ Response: {result['artifacts'][0]['content'][:200]}...") +print(f"๐Ÿ”€ Routing: {result['metadata']['routing_explanation']}") +print(f"๐Ÿ’ฐ Cost: ${result['metadata']['cost_envelope']['actual']}") +print(f"๐Ÿ›ก๏ธ Policy: {result['metadata']['policy_verdict']['reason']}") + +# 3. Query quota status +quota_resp = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-2", + "method": "message/send", + "params": { + "skill": "quota-management", + "messages": [{"role": "user", "content": "Which provider has the most quota remaining?"}], + } +}) +quota_result = quota_resp.json()["result"] +print(f"\n๐Ÿ“Š Quota: {quota_result['artifacts'][0]['content']}") +``` + +### TypeScript โ€” Multi-Agent Orchestrator + +```typescript +/** + * A2A Client โ€” TypeScript example. + * Shows agent discovery, task delegation, and streaming. + */ + +const BASE_URL = "http://localhost:20128"; +const API_KEY = "your-api-key"; + +interface JsonRpcResponse { + jsonrpc: "2.0"; + id: string | number; + result?: T; + error?: { code: number; message: string }; +} + +async function a2aCall(method: string, params: Record): Promise { + const resp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: `${method}-${Date.now()}`, + method, + params, + }), + }); + const json: JsonRpcResponse = await resp.json(); + if (json.error) throw new Error(`[${json.error.code}] ${json.error.message}`); + return json.result!; +} + +// โ”€โ”€ Agent Discovery โ”€โ”€ +const agentCard = await fetch(`${BASE_URL}/.well-known/agent.json`).then((r) => r.json()); +console.log(`Connected to: ${agentCard.name} (${agentCard.skills.length} skills)`); + +// โ”€โ”€ Smart Routing: Send a coding task โ”€โ”€ +const routingResult = await a2aCall("message/send", { + skill: "smart-routing", + messages: [{ role: "user", content: "Implement a Redis cache wrapper in TypeScript" }], + metadata: { model: "claude-sonnet-4", role: "coding" }, +}); +console.log("Response:", routingResult.artifacts[0].content); +console.log("Provider:", routingResult.metadata.routing_explanation); + +// โ”€โ”€ Quota Management: Find free alternatives โ”€โ”€ +const quotaResult = await a2aCall("message/send", { + skill: "quota-management", + messages: [{ role: "user", content: "Suggest free combos for documentation" }], +}); +console.log("Free combos:", quotaResult.artifacts[0].content); + +// โ”€โ”€ Streaming: Real-time response โ”€โ”€ +const streamResp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "stream-1", + method: "message/stream", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Explain microservices architecture" }], + }, + }), +}); + +const reader = streamResp.body!.getReader(); +const decoder = new TextDecoder(); +while (true) { + const { done, value } = await reader.read(); + if (done) break; + const chunk = decoder.decode(value); + for (const line of chunk.split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + if (event.params.chunk) { + process.stdout.write(event.params.chunk.content); + } + if (event.params.task.state === "completed") { + console.log("\nโœ… Stream completed"); + } + } + } +} +``` + +### Python โ€” LangChain A2A Integration + +```python +""" +LangChain integration โ€” Use OmniRoute A2A as a custom LLM. +""" +from langchain.llms.base import BaseLLM +from langchain.schema import LLMResult, Generation +import requests +from typing import List, Optional + +class OmniRouteA2A(BaseLLM): + base_url: str = "http://localhost:20128" + api_key: str = "" + model: str = "auto" + combo: Optional[str] = None + + @property + def _llm_type(self) -> str: + return "omniroute-a2a" + + def _call(self, prompt: str, stop: Optional[List[str]] = None, **kwargs) -> str: + response = requests.post( + f"{self.base_url}/a2a", + headers={ + "Content-Type": "application/json", + "Authorization": f"Bearer {self.api_key}", + }, + json={ + "jsonrpc": "2.0", + "id": "langchain-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": prompt}], + "metadata": { + "model": self.model, + **({"combo": self.combo} if self.combo else {}), + }, + }, + }, + ) + result = response.json()["result"] + return result["artifacts"][0]["content"] + + def _generate(self, prompts: List[str], stop=None, **kwargs) -> LLMResult: + return LLMResult( + generations=[[Generation(text=self._call(p, stop))] for p in prompts] + ) + +# Usage +llm = OmniRouteA2A( + base_url="http://localhost:20128", + api_key="your-key", + model="auto", + combo="fast-coding", +) +result = llm("Write a Python function to merge two sorted lists") +print(result) +``` + +### Go โ€” A2A Client + +```go +package main + +import ( + "bytes" + "encoding/json" + "fmt" + "io" + "net/http" +) + +const baseURL = "http://localhost:20128" +const apiKey = "your-api-key" + +type JsonRpcRequest struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Method string `json:"method"` + Params interface{} `json:"params"` +} + +type JsonRpcResponse struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Result interface{} `json:"result"` + Error *struct { + Code int `json:"code"` + Message string `json:"message"` + } `json:"error"` +} + +func a2aCall(method string, params interface{}) (*JsonRpcResponse, error) { + body, _ := json.Marshal(JsonRpcRequest{ + Jsonrpc: "2.0", + ID: "go-1", + Method: method, + Params: params, + }) + + req, _ := http.NewRequest("POST", baseURL+"/a2a", bytes.NewReader(body)) + req.Header.Set("Content-Type", "application/json") + req.Header.Set("Authorization", "Bearer "+apiKey) + + resp, err := http.DefaultClient.Do(req) + if err != nil { + return nil, err + } + defer resp.Body.Close() + data, _ := io.ReadAll(resp.Body) + + var result JsonRpcResponse + json.Unmarshal(data, &result) + return &result, nil +} + +func main() { + // Discover agent + resp, _ := http.Get(baseURL + "/.well-known/agent.json") + defer resp.Body.Close() + body, _ := io.ReadAll(resp.Body) + fmt.Println("Agent Card:", string(body)) + + // Send smart-routing task + result, _ := a2aCall("message/send", map[string]interface{}{ + "skill": "smart-routing", + "messages": []map[string]string{{"role": "user", "content": "Hello from Go!"}}, + "metadata": map[string]interface{}{"model": "auto"}, + }) + out, _ := json.MarshalIndent(result.Result, "", " ") + fmt.Println("Result:", string(out)) +} +``` + +--- + +## Use Cases + +### ๐Ÿค– Use Case 1: Multi-Agent Coding Pipeline + +An orchestrator agent delegates code generation to OmniRoute, then passes the output to a review agent. + +```python +def coding_pipeline(task: str): + # Step 1: Generate code via OmniRoute A2A + code_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Write production-quality code: {task}"} + ], metadata={"model": "auto", "role": "coding"}) + code = code_result["artifacts"][0]["content"] + + # Step 2: Review the code via OmniRoute A2A (different model) + review_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Review this code for bugs and improvements:\n\n{code}"} + ], metadata={"model": "auto", "role": "review"}) + review = review_result["artifacts"][0]["content"] + + # Step 3: Check costs + print(f"Code cost: ${code_result['metadata']['cost_envelope']['actual']}") + print(f"Review cost: ${review_result['metadata']['cost_envelope']['actual']}") + + return {"code": code, "review": review} +``` + +### ๐Ÿ’ก Use Case 2: Quota-Aware Agent Swarm + +Multiple agents share quota through OmniRoute, using the quota skill to coordinate. + +```python +async def quota_aware_agent(agent_name: str, task: str): + # Check quota before starting + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Which provider has the most quota remaining?"} + ]) + print(f"[{agent_name}] {quota['artifacts'][0]['content']}") + + # Send request with budget constraint + result = a2a_send("smart-routing", [ + {"role": "user", "content": task} + ], metadata={"budget": 0.05}) + + policy = result["metadata"]["policy_verdict"] + if not policy["allowed"]: + print(f"[{agent_name}] โš ๏ธ Budget exceeded: {policy['reason']}") + # Fall back to free combo + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Suggest free combos"} + ]) + print(f"[{agent_name}] Free alternatives: {quota['artifacts'][0]['content']}") + + return result +``` + +### ๐Ÿ“Š Use Case 3: Real-Time Streaming Dashboard + +A monitoring agent streams responses and displays progress in real-time. + +```typescript +async function streamingDashboard(prompt: string) { + const response = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { "Content-Type": "application/json", Authorization: `Bearer ${API_KEY}` }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "dash-1", + method: "message/stream", + params: { skill: "smart-routing", messages: [{ role: "user", content: prompt }] }, + }), + }); + + let totalChunks = 0; + const reader = response.body!.getReader(); + const decoder = new TextDecoder(); + + while (true) { + const { done, value } = await reader.read(); + if (done) break; + + for (const line of decoder.decode(value).split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + const state = event.params.task.state; + + if (state === "working" && event.params.chunk) { + totalChunks++; + process.stdout.write( + `\r[Chunk ${totalChunks}] ${event.params.chunk.content.slice(0, 50)}...` + ); + } + if (state === "completed") { + const meta = event.params.metadata; + console.log( + `\nโœ… Done | Cost: $${meta?.cost_envelope?.actual || 0} | Route: ${meta?.routing_explanation || "N/A"}` + ); + } + if (state === "failed") { + console.error(`\nโŒ Failed: ${event.params.metadata?.error}`); + } + } + } + } +} +``` + +### ๐Ÿ” Use Case 4: Task Polling Pattern + +For long-running tasks, poll the task status instead of waiting synchronously. + +```python +import time + +def poll_task(task_id: str, timeout: int = 60): + """Poll task status until completion or timeout.""" + start = time.time() + while time.time() - start < timeout: + result = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "poll-1", + "method": "tasks/get", + "params": {"taskId": task_id}, + }).json() + + task = result["result"]["task"] + state = task["state"] + print(f" Task {task_id[:8]}... state={state}") + + if state in ("completed", "failed", "cancelled"): + return task + time.sleep(2) + + # Timeout โ€” cancel the task + requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "cancel-1", + "method": "tasks/cancel", + "params": {"taskId": task_id}, + }) + raise TimeoutError(f"Task {task_id} timed out after {timeout}s") +``` + +--- + +## Error Codes + +| Code | Constant | Meaning | +| ------ | ------------------------ | ---------------------------------------- | +| -32700 | โ€” | Parse error (invalid JSON) | +| -32600 | `INVALID_REQUEST` | Invalid JSON-RPC request or unauthorized | +| -32601 | `METHOD_NOT_FOUND` | Unknown method or skill | +| -32602 | `INVALID_PARAMS` | Missing or invalid parameters | +| -32603 | `INTERNAL_ERROR` | Skill execution failed | +| -32001 | `TASK_NOT_FOUND` | Task ID not found | +| -32002 | `TASK_ALREADY_COMPLETED` | Cannot modify a completed task | +| -32003 | `UNAUTHORIZED` | Invalid or missing API key | +| -32004 | `BUDGET_EXCEEDED` | Request exceeds configured budget | +| -32005 | `PROVIDER_UNAVAILABLE` | No available providers | + +--- + +## Authentication + +All `/a2a` requests require a Bearer token via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server (`OMNIROUTE_API_KEY` is empty), authentication is bypassed. + +--- + +## File Structure + +``` +src/lib/a2a/ +โ”œโ”€โ”€ taskManager.ts # Task lifecycle (create/update/cancel/list), TTL, cleanup +โ”œโ”€โ”€ taskExecution.ts # Generic task executor with state management +โ”œโ”€โ”€ streaming.ts # SSE stream formatting, heartbeat, chunk/completion events +โ”œโ”€โ”€ routingLogger.ts # Routing decision logger (stats, history, retention) +โ””โ”€โ”€ skills/ + โ”œโ”€โ”€ smartRouting.ts # Smart routing skill (routes via /v1/chat/completions) + โ””โ”€โ”€ quotaManagement.ts # Quota management skill (natural-language quota queries) + +src/app/a2a/ +โ””โ”€โ”€ route.ts # Next.js API route handler (JSON-RPC 2.0 dispatch) + +open-sse/mcp-server/ +โ””โ”€โ”€ schemas/a2a.ts # Zod schemas (AgentCard, Task, JSON-RPC, SSE events) +``` + +--- + +## Comparison: MCP vs A2A + +| Feature | MCP Server | A2A Server | +| ----------------- | ---------------------------- | ------------------------------------------------- | +| **Protocol** | Model Context Protocol | Agent-to-Agent Protocol v0.3 | +| **Transport** | stdio / HTTP | HTTP (JSON-RPC 2.0) | +| **Discovery** | Tool listing via MCP | `/.well-known/agent.json` | +| **Granularity** | 16 individual tools | 2 high-level skills | +| **Best for** | IDE agents (Cursor, VS Code) | Multi-agent systems (LangChain, CrewAI) | +| **Streaming** | Not supported | SSE via `message/stream` | +| **Task tracking** | No | Full lifecycle (submitted โ†’ completed) | +| **Observability** | Audit log per tool call | Cost envelope + resilience trace + policy verdict | + +--- + +## Lisensi + +Part of [OmniRoute](https://github.com/diegosouzapw/OmniRoute) โ€” MIT License. diff --git a/docs/i18n/in/A2A-SERVER.md b/docs/i18n/in/A2A-SERVER.md deleted file mode 100644 index 01531ff482..0000000000 --- a/docs/i18n/in/A2A-SERVER.md +++ /dev/null @@ -1,200 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/A2A-SERVER.md) - ---- - -# OmniRoute A2A Server Documentation - -> Agent-to-Agent Protocol v0.3 โ€” OmniRoute as an intelligent routing agent - -## Agent Discovery - -```bash -curl http://localhost:20128/.well-known/agent.json -``` - -Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements. - ---- - -## Authentication - -All `/a2a` requests require an API key via the `Authorization` header: - -``` -Authorization: Bearer YOUR_OMNIROUTE_API_KEY -``` - -If no API key is configured on the server, authentication is bypassed. - ---- - -## JSON-RPC 2.0 Methods - -### `message/send` โ€” Synchronous Execution - -Sends a message to a skill and waits for the complete response. - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{ - "jsonrpc": "2.0", - "id": "1", - "method": "message/send", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Write a hello world in Python"}], - "metadata": {"model": "auto", "combo": "fast-coding"} - } - }' -``` - -**Response:** - -```json -{ - "jsonrpc": "2.0", - "id": "1", - "result": { - "task": { "id": "uuid", "state": "completed" }, - "artifacts": [{ "type": "text", "content": "..." }], - "metadata": { - "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)", - "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, - "resilience_trace": [ - { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." } - ], - "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } - } - } -} -``` - -### `message/stream` โ€” SSE Streaming - -Same as `message/send` but returns Server-Sent Events for real-time streaming. - -```bash -curl -N -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{ - "jsonrpc": "2.0", - "id": "1", - "method": "message/stream", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Explain quantum computing"}] - } - }' -``` - -**SSE Events:** - -``` -data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}} - -: heartbeat 2026-03-03T17:00:00Z - -data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} -``` - -### `tasks/get` โ€” Query Task Status - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' -``` - -### `tasks/cancel` โ€” Cancel a Task - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' -``` - ---- - -## Available Skills - -| Skill | Description | -| :----------------- | :------------------------------------------------------------------------------------------------------------------------------ | -| `smart-routing` | Routes prompts through OmniRoute's intelligent pipeline. Returns response with routing explanation, cost, and resilience trace. | -| `quota-management` | Answers natural-language queries about provider quotas, suggests free combos, and provides quota rankings. | - ---- - -## Task Lifecycle - -``` -submitted โ†’ working โ†’ completed - โ†’ failed - โ†’ cancelled -``` - -- Tasks expire after 5 minutes (configurable) -- Terminal states: `completed`, `failed`, `cancelled` -- Event log tracks every state transition - ---- - -## Error Codes - -| Code | Meaning | -| :----- | :----------------------------- | -| -32700 | Parse error (invalid JSON) | -| -32600 | Invalid request / Unauthorized | -| -32601 | Method or skill not found | -| -32602 | Invalid params | -| -32603 | Internal error | - ---- - -## Integration Examples - -### Python (requests) - -```python -import requests - -resp = requests.post("http://localhost:20128/a2a", json={ - "jsonrpc": "2.0", "id": "1", - "method": "message/send", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Hello"}] - } -}, headers={"Authorization": "Bearer YOUR_KEY"}) - -result = resp.json()["result"] -print(result["artifacts"][0]["content"]) -print(result["metadata"]["routing_explanation"]) -``` - -### TypeScript (fetch) - -```typescript -const resp = await fetch("http://localhost:20128/a2a", { - method: "POST", - headers: { - "Content-Type": "application/json", - Authorization: "Bearer YOUR_KEY", - }, - body: JSON.stringify({ - jsonrpc: "2.0", - id: "1", - method: "message/send", - params: { - skill: "smart-routing", - messages: [{ role: "user", content: "Hello" }], - }, - }), -}); -const { result } = await resp.json(); -console.log(result.metadata.routing_explanation); -``` diff --git a/docs/i18n/in/API_REFERENCE.md b/docs/i18n/in/API_REFERENCE.md deleted file mode 100644 index b878605221..0000000000 --- a/docs/i18n/in/API_REFERENCE.md +++ /dev/null @@ -1,455 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/API_REFERENCE.md) - ---- - -# API Reference - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/API_REFERENCE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/API_REFERENCE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/API_REFERENCE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/API_REFERENCE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/API_REFERENCE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/API_REFERENCE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/API_REFERENCE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/API_REFERENCE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/API_REFERENCE.md) - -Complete reference for all OmniRoute API endpoints. - ---- - -## Table of Contents - -- [Chat Completions](#chat-completions) -- [Embeddings](#embeddings) -- [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`. - -### ACP Agents - -| Endpoint | Method | Description | -| ----------------- | ------ | -------------------------------------------------------- | -| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | -| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | -| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | - -GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). - -### Resilience & Rate Limits - -| Endpoint | Method | Description | -| ----------------------- | ------- | ------------------------------- | -| `/api/resilience` | 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` diff --git a/docs/i18n/in/ARCHITECTURE.md b/docs/i18n/in/ARCHITECTURE.md deleted file mode 100644 index 4ea06a29f2..0000000000 --- a/docs/i18n/in/ARCHITECTURE.md +++ /dev/null @@ -1,787 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/ARCHITECTURE.md) - ---- - -# OmniRoute Architecture - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/ARCHITECTURE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/ARCHITECTURE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/ARCHITECTURE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/ARCHITECTURE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/ARCHITECTURE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/ARCHITECTURE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/ARCHITECTURE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/ARCHITECTURE.md) - -_Last updated: 2026-03-04_ - -## 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 (`...`) for reasoning models -- Response sanitization for strict OpenAI SDK compatibility -- Role normalization (developerโ†’system, systemโ†’user) for cross-provider compatibility -- Structured output conversion (json_schema โ†’ Gemini responseSchema) -- Local persistence for providers, keys, aliases, combos, settings, pricing -- Usage/cost tracking and request logging -- Optional cloud sync for multi-device/state sync -- IP allowlist/blocklist for API access control -- Thinking budget management (passthrough/auto/custom/adaptive) -- Global system prompt injection -- Session tracking and fingerprinting -- Per-account enhanced rate limiting with provider-specific profiles -- Circuit breaker pattern for provider resilience -- Anti-thundering herd protection with mutex locking -- Signature-based request deduplication cache -- Domain layer: model availability, cost rules, fallback policy, lockout policy -- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) -- Policy engine for centralized request evaluation (lockout โ†’ budget โ†’ fallback) -- Request telemetry with p50/p95/p99 latency aggregation -- Correlation ID (X-Request-Id) for end-to-end tracing -- Compliance audit logging with opt-out per API key -- Eval framework for LLM quality assurance -- Resilience UI dashboard with real-time circuit breaker status -- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) - -Primary runtime model: - -- Next.js 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[(storage.sqlite)] - UDB[(usage tables + log artifacts)] - end - - subgraph Upstreams[Upstream Providers] - P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/Qoder/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/route.ts` (GET) -- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) -- OAuth: `src/app/api/oauth/*` -- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` -- Usage: `src/app/api/usage/*` -- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` -- CLI tooling helpers: `src/app/api/cli-tools/*` -- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) -- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) -- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) -- Sessions: `src/app/api/sessions` (GET) -- Rate limits: `src/app/api/rate-limits` (GET) -- Resilience: `src/app/api/resilience` (GET/PATCH) โ€” provider profiles, circuit breaker, rate limit state -- Resilience reset: `src/app/api/resilience/reset` (POST) โ€” reset breakers + cooldowns -- Cache stats: `src/app/api/cache/stats` (GET/DELETE) -- Model availability: `src/app/api/models/availability` (GET/POST) -- Telemetry: `src/app/api/telemetry/summary` (GET) -- Budget: `src/app/api/usage/budget` (GET/POST) -- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) -- Compliance audit: `src/app/api/compliance/audit-log` (GET) -- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) -- Policies: `src/app/api/policies` (GET/POST) - -## 2) SSE + 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` -- Response sanitization: `open-sse/handlers/responseSanitizer.ts` -- Role normalization: `open-sse/services/roleNormalizer.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`, `qoder.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 (SQLite): - -- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) -- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) -- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) -- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** - -Usage persistence: - -- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) -- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` -- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) -- legacy JSON files are migrated to SQLite by startup migrations when present - -Domain State DB (SQLite): - -- `src/lib/db/domainState.ts` โ€” CRUD operations 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: - -- primary runtime DB: `${DATA_DIR}/storage.sqlite` -- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) -- structured call payload archives: `${DATA_DIR}/call_logs/` -- optional translator/request debug sessions: `/logs/...` - -## Deployment Topology - -```mermaid -flowchart LR - 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[(storage.sqlite)] - UsageDB[(usage tables + log artifacts)] - end - - subgraph External[External Services] - Providers[AI Providers] - SyncCloud[Cloud Sync Service] - end - - CLI --> Next - Browser --> Next - Next --> Core - Next --> MainDB - Core --> MainDB - Core --> UsageDB - Core --> Providers - Next --> SyncCloud -``` - -## Module Mapping (Decision-Critical) - -### Route and API Modules - -- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs -- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) -- `src/app/api/providers*`: provider CRUD, validation, testing -- `src/app/api/provider-nodes*`: custom compatible node management -- `src/app/api/provider-models`: custom model management (CRUD) -- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) -- `src/app/api/oauth/*`: OAuth/device-code flows -- `src/app/api/keys*`: local API key lifecycle -- `src/app/api/models/alias`: alias management -- `src/app/api/combos*`: fallback combo management -- `src/app/api/pricing`: pricing overrides for cost calculation -- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) -- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) -- `src/app/api/usage/*`: usage and logs APIs -- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers -- `src/app/api/cli-tools/*`: local CLI config writers/checkers -- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) -- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) -- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) -- `src/app/api/sessions`: active session listing (GET) -- `src/app/api/rate-limits`: per-account rate limit status (GET) - -### Routing and Execution Core - -- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop -- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup -- `open-sse/executors/*`: provider-specific network and format behavior - -### Translation Registry and Format Converters - -- `open-sse/translator/index.ts`: translator registry and orchestration -- Request translators: `open-sse/translator/request/*` -- Response translators: `open-sse/translator/response/*` -- Format constants: `open-sse/translator/formats.ts` - -### Persistence - -- `src/lib/db/*`: persistent config/state and domain persistence on SQLite -- `src/lib/localDb.ts`: compatibility re-export for DB modules -- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables - -## Provider Executor Coverage (Strategy Pattern) - -Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. - -| Executor | Provider(s) | Special Handling | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | -| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, Qoder, 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 | -| Qoder | openai | OAuth (Basic) | โœ… | โœ… | โœ… | โš ๏ธ Per request | -| OpenRouter | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| GLM/Kimi/MiniMax | claude | API Key | โœ… | โœ… | โŒ | โŒ | -| DeepSeek | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Groq | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| xAI (Grok) | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Mistral | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Perplexity | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Together AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Fireworks AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Cerebras | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Cohere | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| NVIDIA NIM | openai | API Key | โœ… | โœ… | โŒ | โŒ | - -## Format Translation Coverage - -Detected source formats include: - -- `openai` -- `openai-responses` -- `claude` -- `gemini` - -Target formats include: - -- OpenAI chat/Responses -- Claude -- Gemini/Gemini-CLI/Antigravity envelope -- Kiro -- Cursor - -Translations use **OpenAI as the hub format** โ€” all conversions go through OpenAI as intermediate: - -``` -Source Format โ†’ OpenAI (hub) โ†’ Target Format -``` - -Translations are selected dynamically based on source payload shape and provider target format. - -Additional processing layers in the translation pipeline: - -- **Response sanitization** โ€” Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance -- **Role normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI targets; merges `system` โ†’ `user` for models that reject the system role (GLM, ERNIE) -- **Think tag extraction** โ€” Parses `...` blocks from content into `reasoning_content` field -- **Structured output** โ€” Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` - -## Supported API Endpoints - -| 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 `/logs//` 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 - -- SQLite schema migrations and auto-upgrade hooks at startup -- legacy JSON โ†’ SQLite migration compatibility path - -## Observability and Operational Signals - -Runtime visibility sources: - -- console logs from `src/sse/utils/logger.ts` -- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) -- textual request status log in `log.txt` (optional/compat) -- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` -- dashboard usage endpoints (`/api/usage/*`) for UI consumption - -## Security-Sensitive Boundaries - -- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing -- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning -- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format -- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level -- Cloud sync endpoints rely on API key auth + machine id semantics - -## Environment and Runtime Matrix - -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` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. -2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. -3. Request logger writes full headers/body when enabled; treat log directory as sensitive. -4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. -5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. -6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). -7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). -8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). - -## Operational Verification Checklist - -- Build from source: `npm run build` -- Build Docker image: `docker build -t omniroute .` -- Start service and verify: -- `GET /api/settings` -- `GET /api/v1/models` -- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/in/AUTO-COMBO.md b/docs/i18n/in/AUTO-COMBO.md deleted file mode 100644 index 2166e41dff..0000000000 --- a/docs/i18n/in/AUTO-COMBO.md +++ /dev/null @@ -1,67 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/AUTO-COMBO.md) - ---- - -# OmniRoute Auto-Combo Engine - -> Self-managing model chains with adaptive scoring - -## How It Works - -The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**: - -| Factor | Weight | Description | -| :--------- | :----- | :---------------------------------------------- | -| Quota | 0.20 | Remaining capacity [0..1] | -| Health | 0.25 | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 | -| CostInv | 0.20 | Inverse cost (cheaper = higher score) | -| LatencyInv | 0.15 | Inverse p95 latency (faster = higher) | -| TaskFit | 0.10 | Model ร— task type fitness score | -| Stability | 0.10 | Low variance in latency/errors | - -## Mode Packs - -| Pack | Focus | Key Weight | -| :---------------------- | :----------- | :--------------- | -| ๐Ÿš€ **Ship Fast** | Speed | latencyInv: 0.35 | -| ๐Ÿ’ฐ **Cost Saver** | Economy | costInv: 0.40 | -| ๐ŸŽฏ **Quality First** | Best model | taskFit: 0.40 | -| ๐Ÿ“ก **Offline Friendly** | Availability | quota: 0.40 | - -## Self-Healing - -- **Temporary exclusion**: Score < 0.2 โ†’ excluded for 5 min (progressive backoff, max 30 min) -- **Circuit breaker awareness**: OPEN โ†’ auto-excluded; HALF_OPEN โ†’ probe requests -- **Incident mode**: >50% OPEN โ†’ disable exploration, maximize stability -- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout - -## Bandit Exploration - -5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode. - -## API - -```bash -# Create auto-combo -curl -X POST http://localhost:20128/api/combos/auto \ - -H "Content-Type: application/json" \ - -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}' - -# List auto-combos -curl http://localhost:20128/api/combos/auto -``` - -## Task Fitness - -30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` โ†’ high coding score). - -## Files - -| File | Purpose | -| :------------------------------------------- | :------------------------------------ | -| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization | -| `open-sse/services/autoCombo/taskFitness.ts` | Model ร— task fitness lookup | -| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap | -| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode | -| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles | -| `src/app/api/combos/auto/route.ts` | REST API | diff --git a/docs/i18n/in/CHANGELOG.md b/docs/i18n/in/CHANGELOG.md index 557613d375..9a6d1d31ce 100644 --- a/docs/i18n/in/CHANGELOG.md +++ b/docs/i18n/in/CHANGELOG.md @@ -1,12 +1,92 @@ # Changelog (เคนเคฟเคจเฅเคฆเฅ€) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CHANGELOG.md) --- - ## [Unreleased] +### ๐Ÿ› ๏ธ Maintenance + +- **AGENTS.md rewrite:** Condensed from 297โ†’153 lines. Added build/lint/test commands (including single-test execution), code style guidelines (Prettier, TypeScript, ESLint, naming, imports, error handling, security), and trimmed verbose architecture tables for AI agent consumption. + +## [3.4.2] - 2026-04-01 + +### ๐Ÿ› Bug Fixes + +- **CI Stabilization:** Fixed failing analytics/settings Playwright selectors and request assertions so GitHub Actions E2E runs pass reliably across localized UIs and switch-based controls. +- **Deterministic Tests:** Removed date-sensitive quota fixtures from Copilot usage tests and aligned idempotency/model catalog tests with the merged runtime behavior. +- **MCP Type Hardening:** Removed zero-budget explicit `any` regressions from the MCP server tool registration path, restoring the `check:any-budget:t11` workflow gate. + +### ๐Ÿ› ๏ธ Maintenance + +- **Release Branch Integration:** Consolidated the active feature branches into `release/v3.4.2` on top of current `main` and validated the branch with lint, unit, coverage, build, and CI-mode E2E runs. + +## [3.4.1] - 2026-03-31 + +> [!WARNING] +> **BREAKING CHANGE: request logging, retention, and logging environment variables have been redesigned.** +> On the first startup after upgrading, OmniRoute archives legacy request logs from `DATA_DIR/logs/`, legacy `DATA_DIR/call_logs/`, and `DATA_DIR/log.txt` into `DATA_DIR/log_archives/*.zip`, then removes the deprecated layout and switches to the new unified artifact format under `DATA_DIR/call_logs/`. + +### โœจ New Features + +- **.ENV Migration Utility:** Included `scripts/migrate-env.mjs` to seamlessly migrate ` Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` - ---- - -## Step 2 โ€” Install CLI Tools - -All npm-based tools require Node.js 18+: - -```bash -# Claude Code (Anthropic) -npm install -g @anthropic-ai/claude-code - -# OpenAI Codex -npm install -g @openai/codex - -# Gemini CLI (Google) -npm install -g @google/gemini-cli - -# OpenCode -npm install -g opencode-ai - -# Cline -npm install -g cline - -# KiloCode -npm install -g kilecode - -# Kiro CLI (Amazon โ€” requires curl + unzip) -apt-get install -y unzip # on Debian/Ubuntu -curl -fsSL https://cli.kiro.dev/install | bash -export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc -``` - -**Verify:** - -```bash -claude --version # 2.x.x -codex --version # 0.x.x -gemini --version # 0.x.x -opencode --version # x.x.x -cline --version # 2.x.x -kilocode --version # x.x.x (or: kilo --version) -kiro-cli --version # 1.x.x -``` - ---- - -## Step 3 โ€” Set Global Environment Variables - -Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`: - -```bash -# OmniRoute Universal Endpoint -export OPENAI_BASE_URL="http://localhost:20128/v1" -export OPENAI_API_KEY="sk-your-omniroute-key" -export ANTHROPIC_BASE_URL="http://localhost:20128/v1" -export ANTHROPIC_API_KEY="sk-your-omniroute-key" -export GEMINI_BASE_URL="http://localhost:20128/v1" -export GEMINI_API_KEY="sk-your-omniroute-key" -``` - -> For a **remote server** replace `localhost:20128` with the server IP or domain, -> e.g. `http://192.168.0.15:20128`. - ---- - -## Step 4 โ€” Configure Each Tool - -### Claude Code - -```bash -# Via CLI: -claude config set --global api-base-url http://localhost:20128/v1 - -# Or create ~/.claude/settings.json: -mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF -{ - "apiBaseUrl": "http://localhost:20128/v1", - "apiKey": "sk-your-omniroute-key" -} -EOF -``` - -**Test:** `claude "say hello"` - ---- - -### OpenAI Codex - -```bash -mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF -model: auto -apiKey: sk-your-omniroute-key -apiBaseUrl: http://localhost:20128/v1 -EOF -``` - -**Test:** `codex "what is 2+2?"` - ---- - -### Gemini CLI - -```bash -mkdir -p ~/.gemini && cat > ~/.gemini/settings.json << EOF -{ - "apiKey": "sk-your-omniroute-key", - "baseUrl": "http://localhost:20128/v1" -} -EOF -``` - -**Test:** `gemini "hello"` - ---- - -### OpenCode - -```bash -mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF -[provider.openai] -base_url = "http://localhost:20128/v1" -api_key = "sk-your-omniroute-key" -EOF -``` - -**Test:** `opencode` - ---- - -### Cline (CLI or VS Code) - -**CLI mode:** - -```bash -mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF -{ - "apiProvider": "openai", - "openAiBaseUrl": "http://localhost:20128/v1", - "openAiApiKey": "sk-your-omniroute-key" -} -EOF -``` - -**VS Code mode:** -Cline extension settings โ†’ API Provider: `OpenAI Compatible` โ†’ Base URL: `http://localhost:20128/v1` - -Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ Cline โ†’ Apply Config**. - ---- - -### KiloCode (CLI or VS Code) - -**CLI mode:** - -```bash -kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key -``` - -**VS Code settings:** - -```json -{ - "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", - "kilo-code.apiKey": "sk-your-omniroute-key" -} -``` - -Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ KiloCode โ†’ Apply Config**. - ---- - -### Continue (VS Code Extension) - -Edit `~/.continue/config.yaml`: - -```yaml -models: - - name: OmniRoute - provider: openai - model: auto - apiBase: http://localhost:20128/v1 - apiKey: sk-your-omniroute-key - default: true -``` - -Restart VS Code after editing. - ---- - -### Kiro CLI (Amazon) - -```bash -# Login to your AWS/Kiro account: -kiro-cli login - -# The CLI uses its own auth โ€” OmniRoute is not needed as backend for Kiro CLI itself. -# Use kiro-cli alongside OmniRoute for other tools. -kiro-cli status -``` - ---- - -### Cursor (Desktop App) - -> **Note:** Cursor routes requests through its cloud. For OmniRoute integration, -> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL. - -Via GUI: **Settings โ†’ Models โ†’ OpenAI API Key** - -- Base URL: `https://your-domain.com/v1` -- API Key: your OmniRoute key - ---- - -## Dashboard Auto-Configuration - -The OmniRoute dashboard automates configuration for most tools: - -1. Go to `http://localhost:20128/dashboard/cli-tools` -2. Expand any tool card -3. Select your API key from the dropdown -4. Click **Apply Config** (if tool is detected as installed) -5. Or copy the generated config snippet manually - ---- - -## Built-in Agents: Droid & OpenClaw - -**Droid** and **OpenClaw** are AI agents built directly into OmniRoute โ€” no installation needed. -They run as internal routes and use OmniRoute's model routing automatically. - -- Access: `http://localhost:20128/dashboard/agents` -- Configure: same combos and providers as all other tools -- No API key or CLI install required - ---- - -## Available API Endpoints - -| Endpoint | Description | Use For | -| -------------------------- | ----------------------------- | --------------------------- | -| `/v1/chat/completions` | Standard chat (all providers) | All modern tools | -| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows | -| `/v1/completions` | Legacy text completions | Older tools using `prompt:` | -| `/v1/embeddings` | Text embeddings | RAG, search | -| `/v1/images/generations` | Image generation | DALL-E, Flux, etc. | -| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS | -| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI | - ---- - -## Troubleshooting - -| Error | Cause | Fix | -| ------------------------- | ----------------------- | ------------------------------------------ | -| `Connection refused` | OmniRoute not running | `pm2 start omniroute` | -| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` | -| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` | -| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` | -| CLI shows "not installed" | Binary not in PATH | Check `which ` | -| `kiro-cli: not found` | Not in PATH | `export PATH="$HOME/.local/bin:$PATH"` | - ---- - -## Quick Setup Script (One Command) - -```bash -# Install all CLIs and configure for OmniRoute (replace with your key and server URL) -OMNIROUTE_URL="http://localhost:20128/v1" -OMNIROUTE_KEY="sk-your-omniroute-key" - -npm install -g @anthropic-ai/claude-code @openai/codex @google/gemini-cli opencode-ai cline kilecode - -# Kiro CLI -apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash - -# Write configs -mkdir -p ~/.claude ~/.codex ~/.gemini ~/.config/opencode ~/.continue - -cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" -cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" -cat > ~/.gemini/settings.json <<< "{\"apiKey\":\"$OMNIROUTE_KEY\",\"baseUrl\":\"$OMNIROUTE_URL\"}" -cat >> ~/.bashrc << EOF -export OPENAI_BASE_URL="$OMNIROUTE_URL" -export OPENAI_API_KEY="$OMNIROUTE_KEY" -export ANTHROPIC_BASE_URL="$OMNIROUTE_URL" -export ANTHROPIC_API_KEY="$OMNIROUTE_KEY" -EOF - -source ~/.bashrc -echo "โœ… All CLIs installed and configured for OmniRoute" -``` diff --git a/docs/i18n/in/CODEBASE_DOCUMENTATION.md b/docs/i18n/in/CODEBASE_DOCUMENTATION.md deleted file mode 100644 index e2d7950052..0000000000 --- a/docs/i18n/in/CODEBASE_DOCUMENTATION.md +++ /dev/null @@ -1,593 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CODEBASE_DOCUMENTATION.md) - ---- - -# omniroute โ€” Codebase Documentation - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) - -> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. - ---- - -## 1. 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
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, Qoder, 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 | -| Qoder | 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"] -``` diff --git a/docs/i18n/in/CONTRIBUTING.md b/docs/i18n/in/CONTRIBUTING.md new file mode 100644 index 0000000000..b9a4068f41 --- /dev/null +++ b/docs/i18n/in/CONTRIBUTING.md @@ -0,0 +1,299 @@ +# Contributing to OmniRoute (เคนเคฟเคจเฅเคฆเฅ€) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CONTRIBUTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CONTRIBUTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CONTRIBUTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CONTRIBUTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CONTRIBUTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CONTRIBUTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CONTRIBUTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CONTRIBUTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CONTRIBUTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CONTRIBUTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CONTRIBUTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CONTRIBUTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CONTRIBUTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CONTRIBUTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CONTRIBUTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CONTRIBUTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CONTRIBUTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CONTRIBUTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CONTRIBUTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CONTRIBUTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CONTRIBUTING.md) + +--- + +Thank you for your interest in contributing! This guide covers everything you need to get started. + +--- + +## Development Setup + +### Prerequisites + +- **Node.js** >= 18 < 24 (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` | `20128` | Server port | +| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | Base URL for frontend | +| `JWT_SECRET` | (generate above) | JWT signing secret | +| `INITIAL_PASSWORD` | `CHANGEME` | First login password | +| `APP_LOG_LEVEL` | `info` | Log verbosity level | + +### Dashboard Settings + +The dashboard provides UI toggles for features that can also be configured via environment variables: + +| Setting Location | Toggle | Description | +| ------------------- | ------------------ | ------------------------------ | +| Settings โ†’ Advanced | Debug Mode | Enable debug request logs (UI) | +| Settings โ†’ General | Sidebar Visibility | Show/hide sidebar sections | + +These settings are stored in the database and persist across restarts, overriding env var defaults when set. + +### 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:20128/dashboard` +- **API**: `http://localhost:20128/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`, `mcp`, `a2a`, `memory`, `skills`. + +--- + +## Running Tests + +```bash +# All tests (unit + vitest + ecosystem + e2e) +npm run test:all + +# Single test file (Node.js native test runner โ€” most tests use this) +node --import tsx/esm --test tests/unit/your-file.test.mjs + +# Vitest (MCP server, autoCombo, cache) +npm run test:vitest + +# E2E tests (requires Playwright) +npm run test:e2e + +# Protocol clients E2E (MCP transports, A2A) +npm run test:protocols:e2e + +# Ecosystem compatibility tests +npm run test:ecosystem + +# Coverage (55% min statements/lines/functions; 60% branches) +npm run test:coverage +npm run coverage:report + +# Lint + format check +npm run lint +npm run check +``` + +Coverage notes: + +- `npm run test:coverage` measures source coverage for the main unit test suite, excludes `tests/**`, and includes `open-sse/**` +- `npm run coverage:report` prints the detailed file-by-file report from the latest coverage run +- `npm run test:coverage:legacy` preserves the older metric for historical comparison +- See `docs/COVERAGE_PLAN.md` for the phased coverage improvement roadmap + +Current test status: **122 unit test files** covering: + +- Provider translators and format conversion +- Rate limiting, circuit breaker, and resilience +- Semantic cache, idempotency, progress tracking +- Database operations and schema (21 DB modules) +- OAuth flows and authentication +- API endpoint validation (Zod v4) +- MCP server tools and scope enforcement +- Memory and Skills systems + +--- + +## Code Style + +- **ESLint** โ€” Run `npm run lint` before committing +- **Prettier** โ€” Auto-formatted via `lint-staged` on commit (2 spaces, semicolons, double quotes, 100 char width, es5 trailing commas) +- **TypeScript** โ€” All `src/` code uses `.ts`/`.tsx`; `open-sse/` uses `.ts`/`.js`; document with TSDoc (`@param`, `@returns`, `@throws`) +- **No `eval()`** โ€” ESLint enforces `no-eval`, `no-implied-eval`, `no-new-func` +- **Zod validation** โ€” Use Zod v4 schemas for all API input validation +- **Naming**: Files = camelCase/kebab-case, components = PascalCase, constants = UPPER_SNAKE + +--- + +## Project Structure + +``` +src/ # TypeScript (.ts / .tsx) +โ”œโ”€โ”€ app/ # Next.js 16 App Router +โ”‚ โ”œโ”€โ”€ (dashboard)/ # Dashboard pages (23 sections) +โ”‚ โ”œโ”€โ”€ api/ # API routes (51 directories) +โ”‚ โ””โ”€โ”€ login/ # Auth pages (.tsx) +โ”œโ”€โ”€ domain/ # Policy engine (policyEngine, comboResolver, costRules, etc.) +โ”œโ”€โ”€ lib/ # Core business logic (.ts) +โ”‚ โ”œโ”€โ”€ a2a/ # Agent-to-Agent v0.3 protocol server +โ”‚ โ”œโ”€โ”€ acp/ # Agent Communication Protocol registry +โ”‚ โ”œโ”€โ”€ compliance/ # Compliance policy engine +โ”‚ โ”œโ”€โ”€ db/ # SQLite database layer (21 modules + 16 migrations) +โ”‚ โ”œโ”€โ”€ memory/ # Persistent conversational memory +โ”‚ โ”œโ”€โ”€ oauth/ # OAuth providers, services, and utilities +โ”‚ โ”œโ”€โ”€ skills/ # Extensible skill framework +โ”‚ โ”œโ”€โ”€ usage/ # Usage tracking and cost calculation +โ”‚ โ””โ”€โ”€ localDb.ts # Re-export layer only โ€” never add logic here +โ”œโ”€โ”€ middleware/ # Request middleware (promptInjectionGuard) +โ”œโ”€โ”€ mitm/ # MITM proxy (cert, DNS, target routing) +โ”œโ”€โ”€ shared/ +โ”‚ โ”œโ”€โ”€ components/ # React components (.tsx) +โ”‚ โ”œโ”€โ”€ constants/ # Provider definitions (60+), MCP scopes, routing strategies +โ”‚ โ”œโ”€โ”€ utils/ # Circuit breaker, sanitizer, auth helpers +โ”‚ โ””โ”€โ”€ validation/ # Zod v4 schemas +โ””โ”€โ”€ sse/ # SSE proxy pipeline + +open-sse/ # @omniroute/open-sse workspace +โ”œโ”€โ”€ executors/ # 14 provider-specific request executors +โ”œโ”€โ”€ handlers/ # 11 request handlers (chat, responses, embeddings, images, etc.) +โ”œโ”€โ”€ mcp-server/ # MCP server (25 tools, 3 transports, 10 scopes) +โ”œโ”€โ”€ services/ # 36+ services (combo, autoCombo, rateLimitManager, etc.) +โ”œโ”€โ”€ translator/ # Format translators (OpenAI โ†” Claude โ†” Gemini โ†” Responses โ†” Ollama) +โ”œโ”€โ”€ transformer/ # Responses API transformer +โ””โ”€โ”€ utils/ # 22 utility modules (stream, TLS, proxy, logging) + +electron/ # Electron desktop app (cross-platform) + +tests/ +โ”œโ”€โ”€ unit/ # Node.js test runner (122 test files) +โ”œโ”€โ”€ integration/ # Integration tests +โ”œโ”€โ”€ e2e/ # Playwright tests +โ”œโ”€โ”€ security/ # Security tests +โ”œโ”€โ”€ translator/ # Translator-specific tests +โ””โ”€โ”€ load/ # Load tests + +docs/ # Documentation +โ”œโ”€โ”€ ARCHITECTURE.md # System architecture +โ”œโ”€โ”€ API_REFERENCE.md # All endpoints +โ”œโ”€โ”€ USER_GUIDE.md # Provider setup, CLI integration +โ”œโ”€โ”€ TROUBLESHOOTING.md # Common issues +โ”œโ”€โ”€ MCP-SERVER.md # MCP server (25 tools) +โ”œโ”€โ”€ A2A-SERVER.md # A2A agent protocol +โ”œโ”€โ”€ AUTO-COMBO.md # Auto-combo engine +โ”œโ”€โ”€ CLI-TOOLS.md # CLI tools integration +โ”œโ”€โ”€ COVERAGE_PLAN.md # Test coverage improvement plan +โ”œโ”€โ”€ openapi.yaml # OpenAPI specification +โ””โ”€โ”€ adr/ # Architecture Decision Records +``` + +--- + +## Adding a New Provider + +### Step 1: Register Provider Constants + +Add to `src/shared/constants/providers.ts` โ€” Zod-validated at module load. + +### Step 2: Add Executor (if custom logic needed) + +Create executor in `open-sse/executors/your-provider.ts` extending the base executor. + +### Step 3: Add Translator (if non-OpenAI format) + +Create request/response translators in `open-sse/translator/`. + +### Step 4: Add OAuth Config (if OAuth-based) + +Add OAuth credentials in `src/lib/oauth/constants/oauth.ts` and service in `src/lib/oauth/services/`. + +### Step 5: Register Models + +Add model definitions in `open-sse/config/providerRegistry.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 +- [ ] All inputs validated with Zod schemas +- [ ] CHANGELOG updated (if user-facing change) +- [ ] Documentation updated (if applicable) + +--- + +## Releasing + +Releases are managed via the `/generate-release` workflow. When a new GitHub Release is created, the package is **automatically published to npm** via GitHub Actions. + +--- + +## Getting Help + +- **Architecture**: See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) +- **API Reference**: See [`docs/API_REFERENCE.md`](docs/API_REFERENCE.md) +- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **ADRs**: See `docs/adr/` for architectural decision records diff --git a/docs/i18n/in/FEATURES.md b/docs/i18n/in/FEATURES.md deleted file mode 100644 index 8f6537af4d..0000000000 --- a/docs/i18n/in/FEATURES.md +++ /dev/null @@ -1,147 +0,0 @@ -# OmniRoute โ€” Dashboard Features Gallery (เคนเคฟเคจเฅเคฆเฅ€) - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) - -> ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../docs/FEATURES.md) - ---- - -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 (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. - -![Providers Dashboard](screenshots/01-providers.png) - ---- - -## ๐ŸŽจ Combos - -Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. - -![Combos Dashboard](screenshots/02-combos.png) - ---- - -## ๐Ÿ“Š Analytics - -Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. - -![Analytics Dashboard](screenshots/03-analytics.png) - ---- - -## ๐Ÿฅ System Health - -Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. - -![Health Dashboard](screenshots/04-health.png) - ---- - -## ๐Ÿ”ง Translator Playground - -Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). - -![Translator Playground](screenshots/05-translator.png) - ---- - -## ๐ŸŽฎ Model Playground _(v2.0.9+)_ - -Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. - ---- - -## ๐ŸŽจ Themes _(v2.0.5+)_ - -Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. - ---- - -## โš™๏ธ Settings - -Comprehensive settings panel with tabs: - -- **General** โ€” System storage, backup management (export/import database) -- **Appearance** โ€” Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls -- **Security** โ€” API endpoint protection, custom provider blocking, IP filtering, session info -- **Routing** โ€” Model aliases, background task degradation -- **Resilience** โ€” Rate limit persistence, circuit breaker tuning -- **Advanced** โ€” Configuration overrides - -![Settings Dashboard](screenshots/06-settings.png) - ---- - -## ๐Ÿ”ง CLI Tools - -One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. - -![CLI Tools Dashboard](screenshots/07-cli-tools.png) - ---- - -## ๐Ÿค– CLI Agents _(v2.0.11+)_ - -Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: - -- **Installation status** โ€” Installed / Not Found with version detection -- **Protocol badges** โ€” stdio, HTTP, etc. -- **Custom agents** โ€” Register any CLI tool via form (name, binary, version command, spawn args) -- **CLI Fingerprint Matching** โ€” Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP - ---- - -## ๐Ÿ–ผ๏ธ Media _(v2.0.3+)_ - -Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. - ---- - -## ๐Ÿ“ Request Logs - -Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. - -![Usage Logs](screenshots/08-usage.png) - ---- - -## ๐ŸŒ API Endpoint - -Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. - -![Endpoint Dashboard](screenshots/09-endpoint.png) - ---- - -## ๐Ÿ”‘ API Key Management - -Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. - ---- - -## ๐Ÿ“‹ Audit Log - -Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. - ---- - -## ๐Ÿ–ฅ๏ธ Desktop Application - -Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. - -Key features: - -- Server readiness polling (no blank screen on cold start) -- System tray with port management -- Content Security Policy -- Single-instance lock -- Auto-update on restart -- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) -- Hardened Electron build packaging โ€” symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+) - -๐Ÿ“– See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/in/MCP-SERVER.md b/docs/i18n/in/MCP-SERVER.md deleted file mode 100644 index 829acd30b1..0000000000 --- a/docs/i18n/in/MCP-SERVER.md +++ /dev/null @@ -1,87 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/MCP-SERVER.md) - ---- - -# OmniRoute MCP Server Documentation - -> Model Context Protocol server with 16 intelligent tools - -## Installation - -OmniRoute MCP is built-in. Start it with: - -```bash -omniroute --mcp -``` - -Or via the open-sse transport: - -```bash -# HTTP streamable transport (port 20130) -omniroute --dev # MCP auto-starts on /mcp endpoint -``` - -## IDE Configuration - -See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup. - ---- - -## Essential Tools (8) - -| Tool | Description | -| :------------------------------ | :--------------------------------------- | -| `omniroute_get_health` | Gateway health, circuit breakers, uptime | -| `omniroute_list_combos` | All configured combos with models | -| `omniroute_get_combo_metrics` | Performance metrics for a specific combo | -| `omniroute_switch_combo` | Switch active combo by ID/name | -| `omniroute_check_quota` | Quota status per provider or all | -| `omniroute_route_request` | Send a chat completion through OmniRoute | -| `omniroute_cost_report` | Cost analytics for a time period | -| `omniroute_list_models_catalog` | Full model catalog with capabilities | - -## Advanced Tools (8) - -| Tool | Description | -| :--------------------------------- | :---------------------------------------------- | -| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | -| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | -| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | -| `omniroute_test_combo` | Live-test all models in a combo | -| `omniroute_get_provider_metrics` | Detailed metrics for one provider | -| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | -| `omniroute_explain_route` | Explain a past routing decision | -| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | - -## Authentication - -MCP tools are authenticated via API key scopes. Each tool requires specific scopes: - -| Scope | Tools | -| :------------- | :----------------------------------------------- | -| `read:health` | get_health, get_provider_metrics | -| `read:combos` | list_combos, get_combo_metrics | -| `write:combos` | switch_combo | -| `read:quota` | check_quota | -| `write:route` | route_request, simulate_route, test_combo | -| `read:usage` | cost_report, get_session_snapshot, explain_route | -| `write:config` | set_budget_guard, set_resilience_profile | -| `read:models` | list_models_catalog, best_combo_for_task | - -## Audit Logging - -Every tool call is logged to `mcp_tool_audit` with: - -- Tool name, arguments, result -- Duration (ms), success/failure -- API key hash, timestamp - -## Files - -| File | Purpose | -| :------------------------------------------- | :------------------------------------------ | -| `open-sse/mcp-server/server.ts` | MCP server creation + 16 tool registrations | -| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport | -| `open-sse/mcp-server/auth.ts` | API key + scope validation | -| `open-sse/mcp-server/audit.ts` | Tool call audit logging | -| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers | diff --git a/docs/i18n/in/README.md b/docs/i18n/in/README.md index 1109eda61d..f2a089377a 100644 --- a/docs/i18n/in/README.md +++ b/docs/i18n/in/README.md @@ -1,12 +1,12 @@ # ๐Ÿš€ OmniRoute โ€” The Free AI Gateway (เคนเคฟเคจเฅเคฆเฅ€) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/README.md) --- ### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback. -_Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._ +_Your universal API proxy โ€” one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._ **Chat Completions โ€ข Embeddings โ€ข Image Generation โ€ข Video โ€ข Music โ€ข Audio โ€ข Reranking โ€ข **Web Search** โ€ข MCP Server โ€ข A2A Protocol โ€ข 100% TypeScript** @@ -46,15 +46,17 @@ _Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now wi > - `APP_LOG_FILE_PATH` > - `APP_LOG_MAX_FILE_SIZE` > - `APP_LOG_RETENTION_DAYS` +> - `APP_LOG_MAX_FILES` > - `APP_LOG_LEVEL` > - `APP_LOG_FORMAT` > - `CALL_LOG_RETENTION_DAYS` +> - `CALL_LOG_MAX_ENTRIES` > > For release details and upgrade notes, see the [CHANGELOG](CHANGELOG.md). --- -## ๐Ÿ†• What's New in v3.0.0 +## ๐Ÿ†• What's New > **Upgrading from v2.9.5?** โ€” See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes. @@ -274,7 +276,7 @@ Developers pay $20โ€“200/month for Claude Pro, Codex Pro, or GitHub Copilot. Eve - **Smart 4-Tier Fallback** โ€” If subscription quota runs out, automatically redirects to API Key โ†’ Cheap โ†’ Free with zero manual intervention - **Real-Time Quota Tracking** โ€” Shows token consumption in real-time with reset countdown (5h, daily, weekly) - **Multi-Account Support** โ€” Multiple accounts per provider with auto round-robin โ€” when one runs out, switches to the next -- **Custom Combos** โ€” Customizable fallback chains with 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Custom Combos** โ€” Customizable fallback chains with 9 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random) - **Codex Business Quotas** โ€” Business/Team workspace quota monitoring directly in the dashboard @@ -286,7 +288,7 @@ OpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If **How OmniRoute solves it:** -- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 67+ providers +- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 60+ providers - **Format Translation** โ€” Automatic and transparent: OpenAI โ†” Claude โ†” Gemini โ†” Responses API - **Response Sanitization** โ€” Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+ - **Role Normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI providers; `system` โ†’ `user` for GLM/ERNIE @@ -372,7 +374,7 @@ Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code.. - **CLI Tools Dashboard** โ€” Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline - **GitHub Copilot Config Generator** โ€” Generates `chatLanguageModels.json` for VS Code with bulk model selection - **Onboarding Wizard** โ€” Guided 4-step setup for first-time users -- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 67+ providers +- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 60+ providers @@ -419,7 +421,7 @@ When a call fails, the dev doesn't know if it was a rate limit, expired token, w - **SQLite Proxy Logs** โ€” Persistent logs that survive server restarts - **Translator Playground** โ€” 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time) - **Request Telemetry** โ€” p50/p95/p99 latency + X-Request-Id tracing -- **File-Based Logging with Rotation** โ€” Console interceptor captures everything to JSON log with size-based rotation +- **File-Based Logging with Rotation** โ€” App logs rotate by size, retention days, and archive count; call log artifacts rotate by retention days and file count - **System Info Report** โ€” `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage. @@ -514,7 +516,7 @@ Developers who want all responses in a specific language, with a specific tone, - **System Prompt Injection** โ€” Global prompt applied to all requests - **Thinking Budget Validation** โ€” Reasoning token allocation control per request (passthrough, auto, custom, adaptive) -- **6 Routing Strategies** โ€” Global strategies that determine how requests are distributed +- **9 Routing Strategies** โ€” Global strategies that determine how requests are distributed - **Wildcard Router** โ€” `provider/*` patterns route dynamically to any provider - **Combo Enable/Disable Toggle** โ€” Toggle combos directly from the dashboard - **Provider Toggle** โ€” Enable/disable all connections for a provider with one click @@ -581,7 +583,7 @@ Different clients should have least-privilege access to tool categories. **How OmniRoute solves it:** -- 9 granular MCP scopes for controlled tool access +- 10 granular MCP scopes for controlled tool access - Scope enforcement and visibility in MCP management UI - Safe default posture for operational tooling @@ -1325,19 +1327,19 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. ### ๐Ÿค– Agent & Protocol Operations (v2.0) -| Feature | What It Does | -| ------------------------------------- | -------------------------------------------------------------------------------------------------- | -| ๐Ÿ”ง **MCP Server (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) | -| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | -| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | -| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | -| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | -| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | -| ๐Ÿ” **MCP Scope Enforcement** | 9 granular scope permissions for controlled tool access | -| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | -| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | -| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | -| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | +| Feature | What It Does | +| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| ๐Ÿ”ง **MCP Server (25 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools | +| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | +| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | +| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | +| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | +| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | +| ๐Ÿ” **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access | +| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | +| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | +| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | +| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | ### ๐Ÿง  Routing & Intelligence @@ -1348,7 +1350,7 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. | ๐Ÿ”„ **Format Translation** | OpenAI โ†” Claude โ†” Gemini โ†” Responses with schema-safe conversions | | ๐Ÿ‘ฅ **Multi-Account Support** | Multiple accounts per provider with intelligent selection | | ๐Ÿ”„ **Auto Token Refresh** | OAuth tokens refresh automatically with retry | -| ๐ŸŽจ **Custom Combos** | 6 balancing strategies + fallback chain control | +| ๐ŸŽจ **Custom Combos** | 9 balancing strategies + fallback chain control | | ๐ŸŒ **Wildcard Router** | `provider/*` dynamic routing | | ๐Ÿง  **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits | | ๐Ÿ”€ **Model Aliases** | Built-in + custom model aliasing and migration safety | @@ -1949,6 +1951,7 @@ opencode - Request artifacts are written to `DATA_DIR/call_logs/` as one JSON file per request - Enable pipeline capture from Dashboard โ†’ Logs โ†’ Request Logs if you need detailed per-stage payloads - Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log` +- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed **Connection test shows "Invalid" for OpenAI-compatible providers** diff --git a/docs/i18n/in/RELEASE_CHECKLIST.md b/docs/i18n/in/RELEASE_CHECKLIST.md deleted file mode 100644 index 903e812c3f..0000000000 --- a/docs/i18n/in/RELEASE_CHECKLIST.md +++ /dev/null @@ -1,37 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/RELEASE_CHECKLIST.md) - ---- - -# Release Checklist - -Use this checklist before tagging or publishing a new OmniRoute release. - -## Version and Changelog - -1. Bump `package.json` version (`x.y.z`) in the release branch. -2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: - - `## [x.y.z] โ€” YYYY-MM-DD` -3. Keep `## [Unreleased]` as the first changelog section for upcoming work. -4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. - -## API Docs - -1. Update `docs/openapi.yaml`: - - `info.version` must equal `package.json` version. -2. Validate endpoint examples if API contracts changed. - -## Runtime Docs - -1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. -2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. -3. Update localized docs if source docs changed significantly. - -## Automated Check - -Run the sync guard locally before opening PR: - -```bash -npm run check:docs-sync -``` - -CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/in/SECURITY.md b/docs/i18n/in/SECURITY.md new file mode 100644 index 0000000000..391241bc39 --- /dev/null +++ b/docs/i18n/in/SECURITY.md @@ -0,0 +1,179 @@ +# Security Policy (เคนเคฟเคจเฅเคฆเฅ€) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../SECURITY.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/SECURITY.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/SECURITY.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/SECURITY.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/SECURITY.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/SECURITY.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/SECURITY.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/SECURITY.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/SECURITY.md) + +--- + +## 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 | +| ------- | -------------- | +| 3.4.x | โœ… Active | +| 3.0.x | โœ… Security | +| < 3.0.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 | +| **MCP Scopes** | 10 granular scopes for MCP tool access control | + +### ๐Ÿ›ก๏ธ 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:::` +- 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** | Allowlist/blocklist IP ranges in dashboard | +| **Rate Limiting** | Per-provider rate limits with automatic backoff | +| **Anti-Thundering Herd** | Mutex + per-connection locking prevents cascading 502s | +| **TLS Fingerprint** | Browser-like TLS fingerprint spoofing to reduce bot detection | +| **CLI Fingerprint** | Per-provider header/body ordering to match native CLI signatures | + +### ๐Ÿ”Œ Resilience & Availability + +| 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 `CALL_LOG_RETENTION_DAYS` | +| **No-Log Opt-out** | Per API key `noLog` flag disables request logging | +| **Audit Log** | Administrative actions tracked in `audit_log` table | +| **MCP Audit** | SQLite-backed audit logging for all MCP tool calls | +| **Zod Validation** | All API inputs validated with Zod v4 schemas at module load | + +--- + +## 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 +- Provider constants validated at module load via Zod (`src/shared/validation/providerSchema.ts`) diff --git a/docs/i18n/in/TROUBLESHOOTING.md b/docs/i18n/in/TROUBLESHOOTING.md deleted file mode 100644 index 63c148000a..0000000000 --- a/docs/i18n/in/TROUBLESHOOTING.md +++ /dev/null @@ -1,258 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/TROUBLESHOOTING.md) - ---- - -# Troubleshooting - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/TROUBLESHOOTING.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/TROUBLESHOOTING.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/TROUBLESHOOTING.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/TROUBLESHOOTING.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/TROUBLESHOOTING.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/TROUBLESHOOTING.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/TROUBLESHOOTING.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/TROUBLESHOOTING.md) - -Common problems and solutions for OmniRoute. - ---- - -## Quick Fixes - -| Problem | Solution | -| ----------------------------- | ------------------------------------------------------------------ | -| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | -| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | -| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | -| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | -| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | - ---- - -## Provider Issues - -### "Language model did not provide messages" - -**Cause:** Provider quota exhausted. - -**Fix:** - -1. 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, Qoder) 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}/storage.sqlite` (providers, combos, aliases, keys, settings) -- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` -- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) - ---- - -## Circuit Breaker Issues - -### Provider stuck in OPEN state - -When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. - -**Fix:** - -1. 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 -- **SDK returns raw string instead of object** โ€” Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures -- **GLM/ERNIE rejects `system` role** โ€” Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models -- **`developer` role not recognized** โ€” Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers -- **`json_schema` not working with Gemini** โ€” Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` - ---- - -## Resilience Settings - -### Auto rate-limit not triggering - -- 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. - ---- - -## Optional RAG / LLM failure taxonomy (16 problems) - -Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. - -In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. - -If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: - -- retrieval drift and broken context boundaries -- empty or stale indexes and vector stores -- embedding versus semantic mismatch -- prompt assembly and context window issues -- logic collapse and overconfident answers -- long chain and agent coordination failures -- multi agent memory and role drift -- deployment and bootstrap ordering problems - -The idea is simple: - -1. When you investigate a bad response, capture: - - user task and request - - route or provider combo in OmniRoute - - any RAG context used downstream (retrieved documents, tool calls, etc) -2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` โ€ฆ `No.16`). -3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. -4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. - -Full text and concrete recipes live here (MIT license, text only): - -[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) - -You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. - ---- - -## Still Stuck? - -- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details -- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints -- **Health Dashboard**: Check **Dashboard โ†’ Health** for real-time system status -- **Translator**: Use **Dashboard โ†’ Translator** to debug format issues diff --git a/docs/i18n/in/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/in/VM_DEPLOYMENT_GUIDE.md deleted file mode 100644 index a428fbe33b..0000000000 --- a/docs/i18n/in/VM_DEPLOYMENT_GUIDE.md +++ /dev/null @@ -1,295 +0,0 @@ -# เค“เคฎเคจเฅ€เคฐเฅ‚เคŸ - เค•เฅเคฒเคพเค‰เคกเคซเฅเคฒเฅ‡เคฏเคฐ เค•เฅ‡ เคธเคพเคฅ เคตเฅ€เคเคฎ เคชเคฐ เคชเคฐเคฟเคจเคฟเคฏเฅ‹เคœเคจ เค—เคพเค‡เคก - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](../pt-BR/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](../es/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](../fr/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](../it/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](../ru/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](../zh-CN/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](../de/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](../in/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](../th/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](../uk-UA/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](../ar/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](../ja/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](../vi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](../bg/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](../da/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](../fi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](../he/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](../hu/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](../id/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](../ko/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](../ms/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](../nl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](../no/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](../pt/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](../ro/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](../pl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](../sk/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](../sv/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](../phi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](../cs/VM_DEPLOYMENT_GUIDE.md) - -เค•เฅเคฒเคพเค‰เคกเคซเฅเคฒเฅ‡เคฏเคฐ เค•เฅ‡ เคฎเคพเคงเฅเคฏเคฎ เคธเฅ‡ เคชเฅเคฐเคฌเค‚เคงเคฟเคค เคกเฅ‹เคฎเฅ‡เคจ เค•เฅ‡ เคธเคพเคฅ เคตเฅ€เคเคฎ (เคตเฅ€เคชเฅ€เคเคธ) เคชเคฐ เค“เคฎเคจเฅ€เคฐเฅ‚เคŸ เค•เฅ‹ เคธเฅเคฅเคพเคชเคฟเคค เค”เคฐ เค•เฅ‰เคจเฅเคซเคผเคฟเค—เคฐ เค•เคฐเคจเฅ‡ เค•เฅ‡ เคฒเคฟเค เคชเฅ‚เคฐเฅ€ เค—เคพเค‡เคกเฅค - ---- - -## เคชเฅ‚เคฐเฅเคตเคพเคตเคถเฅเคฏเค•เคคเคพเคเค - -| เค†เค‡เคŸเคฎ | เคจเฅเคฏเฅ‚เคจเคคเคฎ | เค…เคจเฅเคถเค‚เคธเคฟเคค | -| ---------- | --------------------- | ------------------ | -| **เคธเฅ€เคชเฅ€เคฏเฅ‚** | 1 เคตเฅ€เคธเฅ€เคชเฅ€เคฏเฅ‚ | 2 เคตเฅ€เคธเฅ€เคชเฅ€เคฏเฅ‚ | -| **เคฐเคพเคฎ** | 1 เคœเฅ€เคฌเฅ€ | 2 เคœเฅ€เคฌเฅ€ | -| **เคกเคฟเคธเฅเค•** | 10 เคœเฅ€เคฌเฅ€ เคเคธเคเคธเคกเฅ€ | 25 เคœเฅ€เคฌเฅ€ เคเคธเคเคธเคกเฅ€ | -| **เค“เคเคธ** | เค‰เคฌเค‚เคŸเฅ‚ 22.04 เคเคฒเคŸเฅ€เคเคธ | เค‰เคฌเค‚เคŸเฅ‚ 24.04 เคเคฒเคŸเฅ€เคเคธ | -| **เคกเฅ‹เคฎเฅ‡เคจ** | Cloudflare เคชเคฐ เคชเค‚เคœเฅ€เค•เฅƒเคค | โ€” | -| **เคกเฅ‰เค•เคฐ** | เคกเฅ‰เค•เคฐ เค‡เค‚เคœเคจ 24+ | เคกเฅ‰เค•เคฐ 27+ | - -**เคชเคฐเฅ€เค•เฅเคทเคฟเคค เคชเฅเคฐเคฆเคพเคคเคพ**: เค…เค•เคพเคฎเคพเคˆ (เคฒเคฟเคจเฅ‹เคก), เคกเคฟเคœเคฟเคŸเคฒเค“เคถเคจ, เคตเคฒเฅเคšเคฐ, เคนเฅ‡เคŸเฅเคœเคผเคจเคฐ, เคเคกเคฌเฅเคฒเฅเคฏเฅ‚เคเคธ เคฒเคพเค‡เคŸเคธเฅ‡เคฒเฅค - ---- - -## 1. เคตเฅ€เคเคฎ เค•เฅ‹ เค•เฅ‰เคจเฅเคซเคผเคฟเค—เคฐ เค•เคฐเฅ‡เค‚ - -### 1.1 เค‰เคฆเคพเคนเคฐเคฃ เคฌเคจเคพเคเค - -เค†เคชเค•เฅ‡ เคชเคธเค‚เคฆเฅ€เคฆเคพ VPS เคชเฅเคฐเคฆเคพเคคเคพ เคชเคฐ: - -- เค‰เคฌเค‚เคŸเฅ‚ 24.04 เคเคฒเคŸเฅ€เคเคธ เคšเฅเคจเฅ‡เค‚ -- เคจเฅเคฏเฅ‚เคจเคคเคฎ เคฏเฅ‹เคœเคจเคพ เคšเฅเคจเฅ‡เค‚ (1 เคตเฅ€เคธเฅ€เคชเฅ€เคฏเฅ‚ / 1 เคœเฅ€เคฌเฅ€ เคฐเฅˆเคฎ) -- เคเค• เคฎเคœเคฌเฅ‚เคค เคฐเฅ‚เคŸ เคชเคพเคธเคตเคฐเฅเคก เคธเฅ‡เคŸ เค•เคฐเฅ‡เค‚ เคฏเคพ SSH เค•เฅเค‚เคœเฅ€ เค•เฅ‰เคจเฅเคซเคผเคฟเค—เคฐ เค•เคฐเฅ‡เค‚ -- **เคธเคพเคฐเฅเคตเคœเคจเคฟเค• เค†เคˆเคชเฅ€** เคชเคฐ เคงเฅเคฏเคพเคจ เคฆเฅ‡เค‚ (เคœเฅˆเคธเฅ‡, `203.0.113.10`) - -### 1.2 เคเคธเคเคธเคเคš เค•เฅ‡ เคฎเคพเคงเฅเคฏเคฎ เคธเฅ‡ เค•เคจเฅ‡เค•เฅเคŸ เค•เคฐเฅ‡เค‚ - -```bash -ssh root@203.0.113.10 -``` - -### 1.3 เคธเคฟเคธเฅเคŸเคฎ เค•เฅ‹ เค…เคชเคกเฅ‡เคŸ เค•เคฐเฅ‡เค‚ - -**OMNI_เคŸเฅ‹เค•เคจ_1** - -### 1.4 เคกเฅ‰เค•เคฐ เคธเฅเคฅเคพเคชเคฟเคค เค•เคฐเฅ‡เค‚ - -```bash -# Install dependencies -apt install -y ca-certificates curl gnupg - -# Add official Docker repository -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 nginx เคธเฅเคฅเคพเคชเคฟเคค เค•เคฐเฅ‡เค‚ - -```bash -apt install -y nginx -``` - -### 1.6 เคซเคผเคพเคฏเคฐเคตเฅ‰เคฒ เค•เฅ‰เคจเฅเคซเคผเคฟเค—เคฐ เค•เคฐเฅ‡เค‚ (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 -``` - -> **เคŸเคฟเคช**: เค…เคงเคฟเค•เคคเคฎ เคธเฅเคฐเค•เฅเคทเคพ เค•เฅ‡ เคฒเคฟเค, เคชเฅ‹เคฐเฅเคŸ 80 เค”เคฐ 443 เค•เฅ‹ เค•เฅ‡เคตเคฒ เค•เฅเคฒเคพเค‰เคกเคซเคผเฅ‡เคฏเคฐ เค†เคˆเคชเฅ€ เคคเค• เคธเฅ€เคฎเคฟเคค เคฐเค–เฅ‡เค‚เฅค [Advanced Security](#advanced-security) เค…เคจเฅเคญเคพเค— เคฆเฅ‡เค–เฅ‡เค‚เฅค - ---- - -## 2. เค“เคฎเคจเฅ€เคฐเฅ‚เคŸ เคธเฅเคฅเคพเคชเคฟเคค เค•เคฐเฅ‡เค‚ - -### 2.1 เค•เฅ‰เคจเฅเคซเคผเคฟเค—เคฐเฅ‡เคถเคจ เคจเคฟเคฐเฅเคฆเฅ‡เคถเคฟเค•เคพ เคฌเคจเคพเคเค‚ - -**OMNI_เคŸเฅ‹เค•เคจ_5** - -### 2.2 เคชเคฐเฅเคฏเคพเคตเคฐเคฃ เคšเคฐ เคซเคผเคพเค‡เคฒ เคฌเคจเคพเคเค - -**OMNI_เคŸเฅ‹เค•เคจ_6** - -> โš ๏ธ **เคฎเคนเคคเฅเคตเคชเฅ‚เคฐเฅเคฃ**: เค…เคฆเฅเคตเคฟเคคเฅ€เคฏ เค—เฅเคชเฅเคค เค•เฅเค‚เคœเคฟเคฏเคพเค เค‰เคคเฅเคชเคจเฅเคจ เค•เคฐเฅ‡เค‚! เคชเฅเคฐเคคเฅเคฏเฅ‡เค• เค•เฅเค‚เคœเฅ€ เค•เฅ‡ เคฒเคฟเค `openssl rand -hex 32` เค•เคพ เค‰เคชเคฏเฅ‹เค— เค•เคฐเฅ‡เค‚เฅค - -### 2.3 เค•เค‚เคŸเฅ‡เคจเคฐ เคชเฅเคฐเคพเคฐเค‚เคญ เค•เคฐเฅ‡เค‚ - -```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 เคธเคคเฅเคฏเคพเคชเคฟเคค เค•เคฐเฅ‡เค‚ เค•เคฟ เคฏเคน เคšเคฒ เคฐเคนเคพ เคนเฅˆ - -**OMNI_เคŸเฅ‹เค•เคจ_8** - -เค‡เคธเฅ‡ เคชเฅเคฐเคฆเคฐเฅเคถเคฟเคค เค•เคฐเคจเคพ เคšเคพเคนเคฟเค: `[DB] SQLite database ready` เค”เคฐ `listening on port 20128`เฅค - ---- - -## 3. nginx เค•เฅ‰เคจเฅเคซเคผเคฟเค—เคฐ เค•เคฐเฅ‡เค‚ (เคฐเคฟเคตเคฐเฅเคธ เคชเฅเคฐเฅ‰เค•เฅเคธเฅ€) - -### 3.1 เคเคธเคเคธเคเคฒ เคชเฅเคฐเคฎเคพเคฃเคชเคคเฅเคฐ เค‰เคคเฅเคชเคจเฅเคจ เค•เคฐเฅ‡เค‚ (เค•เฅเคฒเคพเค‰เคกเคซเฅเคฒเฅ‡เคฏเคฐ เค“เคฐเคฟเคœเคฟเคจ) - -เค•เฅเคฒเคพเค‰เคกเคซเฅเคฒเฅ‡เคฏเคฐ เคกเฅˆเคถเคฌเฅ‹เคฐเฅเคก เคฎเฅ‡เค‚: - -1. **เคเคธเคเคธเคเคฒ/เคŸเฅ€เคเคฒเคเคธ โ†’ เค“เคฐเคฟเคœเคฟเคจ เคธเคฐเฅเคตเคฐ** เคชเคฐ เคœเคพเคเค‚ -2. **เคชเฅเคฐเคฎเคพเคฃเคชเคคเฅเคฐ เคฌเคจเคพเคเค‚** เคชเคฐ เค•เฅเคฒเคฟเค• เค•เคฐเฅ‡เค‚ -3. เคกเคฟเคซเคผเฅ‰เคฒเฅเคŸ เคฐเค–เฅ‡เค‚ (15 เคตเคฐเฅเคท, \*.yourdomain.com) -4. **เคฎเฅ‚เคฒ เคชเฅเคฐเคฎเคพเคฃเคชเคคเฅเคฐ** เค”เคฐ **เคจเคฟเคœเฅ€ เค•เฅเค‚เคœเฅ€** เค•เฅ€ เคชเฅเคฐเคคเคฟเคฒเคฟเคชเคฟ เคฌเคจเคพเคเค - -```bash -mkdir -p /etc/nginx/ssl - -# Paste the certificate -nano /etc/nginx/ssl/origin.crt - -# Paste the private key -nano /etc/nginx/ssl/origin.key - -chmod 600 /etc/nginx/ssl/origin.key -``` - -### 3.2 เคจเค—เคจเฅ‡เค•เฅเคธ เค•เฅ‰เคจเฅเคซเคผเคฟเค—เคฐเฅ‡เคถเคจ - -```bash -cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ -# Default server โ€” blocks direct access via 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.yourdomain.com; # Change to your domain - - 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.yourdomain.com; - return 301 https://$server_name$request_uri; -} -NGINX -``` - -### 3.3 เคธเค•เฅเคทเคฎ เค•เคฐเฅ‡เค‚ เค”เคฐ เคชเคฐเฅ€เค•เฅเคทเคฃ เค•เคฐเฅ‡เค‚ - -**OMNI_เคŸเฅ‹เค•เคจ_11** - ---- - -## 4. เค•เฅเคฒเคพเค‰เคกเคซเฅเคฒเฅ‡เคฏเคฐ เคกเฅ€เคเคจเคเคธ เค•เฅ‰เคจเฅเคซเคผเคฟเค—เคฐ เค•เคฐเฅ‡เค‚ - -### 4.1 เคกเฅ€เคเคจเคเคธ เคฐเคฟเค•เฅ‰เคฐเฅเคก เคœเฅ‹เคกเคผเฅ‡เค‚ - -เค•เฅเคฒเคพเค‰เคกเคซเคผเฅ‡เคฏเคฐ เคกเฅˆเคถเคฌเฅ‹เคฐเฅเคก เคฎเฅ‡เค‚ โ†’ DNS: - -| เคชเฅเคฐเค•เคพเคฐ | เคจเคพเคฎ | เคธเคพเคฎเค—เฅเคฐเฅ€ | เคชเฅเคฐเฅ‰เค•เฅเคธเฅ€ | -| ------ | ------ | ---------------------- | ----------- | -| เค | `llms` | `203.0.113.10` (VM IP) | โœ… เคชเฅเคฐเฅ‰เค•เฅเคธเฅ€ | - -### 4.2 เคเคธเคเคธเคเคฒ เค•เฅ‰เคจเฅเคซเคผเคฟเค—เคฐ เค•เคฐเฅ‡เค‚ - -**เคเคธเคเคธเคเคฒ/เคŸเฅ€เคเคฒเคเคธ โ†’ เค…เคตเคฒเฅ‹เค•เคจ** เค•เฅ‡ เค…เค‚เคคเคฐเฅเค—เคค: - -- เคฎเฅ‹เคก: **เคชเฅ‚เคฐเฅเคฃ (เคธเค–เฅเคค)** - -**เคเคธเคเคธเคเคฒ/เคŸเฅ€เคเคฒเคเคธ โ†’ เคเคœ เคธเคฐเฅเคŸเคฟเคซเคฟเค•เฅ‡เคŸ** เค•เฅ‡ เค…เค‚เคคเคฐเฅเค—เคค: - -- เคนเคฎเฅ‡เคถเคพ HTTPS เค•เคพ เค‰เคชเคฏเฅ‹เค— เค•เคฐเฅ‡เค‚: โœ… เคšเคพเคฒเฅ‚ -- เคจเฅเคฏเฅ‚เคจเคคเคฎ เคŸเฅ€เคเคฒเคเคธ เคธเค‚เคธเฅเค•เคฐเคฃ: เคŸเฅ€เคเคฒเคเคธ 1.2 -- เคธเฅเคตเคšเคพเคฒเคฟเคค HTTPS เคชเฅเคจเคฐเฅเคฒเฅ‡เค–เคจ: โœ… เคšเคพเคฒเฅ‚ - -### 4.3 เคชเคฐเฅ€เค•เฅเคทเคฃ - -**OMNI_เคŸเฅ‹เค•เคจ_12** - ---- - -## 5. เคธเค‚เคšเคพเคฒเคจ เคเคตเค‚ เคฐเค–เคฐเค–เคพเคต - -### เคจเค เคธเค‚เคธเฅเค•เคฐเคฃ เคฎเฅ‡เค‚ เค…เคชเค—เฅเคฐเฅ‡เคก เค•เคฐเฅ‡เค‚ - -**OMNI_เคŸเฅ‹เค•เคจ_13** - -### เคฒเฅ‰เค— เคฆเฅ‡เค–เฅ‡เค‚ - -**OMNI_เคŸเฅ‹เค•เคจ_14** - -### เคฎเฅˆเคจเฅเค…เคฒ เคกเฅ‡เคŸเคพเคฌเฅ‡เคธ เคฌเฅˆเค•เค…เคช - -**OMNI_เคŸเฅ‹เค•เคจ_15** - -### เคฌเฅˆเค•เค…เคช เคธเฅ‡ เคชเฅเคจเคฐเฅเคธเฅเคฅเคพเคชเคฟเคค เค•เคฐเฅ‡เค‚ - -**OMNI_เคŸเฅ‹เค•เคจ_16** - ---- - -## 6. เค‰เคจเฅเคจเคค เคธเฅเคฐเค•เฅเคทเคพ - -### nginx เค•เฅ‹ Cloudflare IP เคคเค• เคธเฅ€เคฎเคฟเคค เค•เคฐเฅ‡เค‚ - -**OMNI_เคŸเฅ‹เค•เคจ_17** - -เคจเคฟเคฎเฅเคจเคฒเคฟเค–เคฟเคค เค•เฅ‹ `http {}` เคฌเฅเคฒเฅ‰เค• เค•เฅ‡ เค…เค‚เคฆเคฐ `nginx.conf` เคฎเฅ‡เค‚ เคœเฅ‹เคกเคผเฅ‡เค‚: - -**OMNI_เคŸเฅ‹เค•เคจ_18** - -### เคซเฅ‡เคฒ2เคฌเฅˆเคจ เคธเฅเคฅเคพเคชเคฟเคค เค•เคฐเฅ‡เค‚ - -**OMNI_เคŸเฅ‹เค•เคจ_19** - -### เคกเฅ‰เค•เคฐ เคชเฅ‹เคฐเฅเคŸ เคคเค• เคธเฅ€เคงเฅ€ เคชเคนเฅเค‚เคš เค•เฅ‹ เค…เคตเคฐเฅเคฆเฅเคง เค•เคฐเฅ‡เค‚ - -```bash -# Prevent direct external access to port 20128 -iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP -iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT - -# Persist the rules -apt install -y iptables-persistent -netfilter-persistent save -``` - ---- - -## 7. เค•เฅเคฒเคพเค‰เคกเคซเฅเคฒเฅ‡เคฏเคฐ เคถเฅเคฐเคฎเคฟเค•เฅ‹เค‚ เค•เฅ€ เคคเฅˆเคจเคพเคคเฅ€ (เคตเฅˆเค•เคฒเฅเคชเคฟเค•) - -เค•เฅเคฒเคพเค‰เคกเคซเฅเคฒเฅ‡เคฏเคฐ เคตเคฐเฅเค•เคฐเฅเคธ เค•เฅ‡ เคฎเคพเคงเฅเคฏเคฎ เคธเฅ‡ เคฐเคฟเคฎเฅ‹เคŸ เคเค•เฅเคธเฅ‡เคธ เค•เฅ‡ เคฒเคฟเค (เคตเฅ€เคเคฎ เค•เฅ‹ เคธเฅ€เคงเฅ‡ เค‰เคœเคพเค—เคฐ เค•เคฟเค เคฌเคฟเคจเคพ): - -**OMNI_เคŸเฅ‹เค•เคจ_21** - -เคชเฅ‚เคฐเคพ เคฆเคธเฅเคคเคพเคตเฅ‡เคœเคผ [omnirouteCloud/README.md](../omnirouteCloud/README.md) เคชเคฐ เคฆเฅ‡เค–เฅ‡เค‚เฅค - ---- - -## เคชเฅ‹เคฐเฅเคŸ เคธเคพเคฐเคพเค‚เคถ - -| เคฌเค‚เคฆเคฐเค—เคพเคน | เคธเฅ‡เคตเคพ | เคชเคนเฅเค‚เคš | -| ------- | ----------- | ----------------------------------- | -| 22 | เคเคธเคเคธเคเคš | เคธเคพเคฐเฅเคตเคœเคจเคฟเค• (fail2ban เค•เฅ‡ เคธเคพเคฅ) | -| 80 | nginx HTTP | เคฐเฅ€เคกเคพเคฏเคฐเฅ‡เค•เฅเคŸ โ†’ HTTPS | -| 443 | nginx HTTPS | เค•เฅเคฒเคพเค‰เคกเคซเฅเคฒเฅ‡เคฏเคฐ เคชเฅเคฐเฅ‰เค•เฅเคธเฅ€ เค•เฅ‡ เคฎเคพเคงเฅเคฏเคฎ เคธเฅ‡ | -| 20128 | เค“เคฎเคจเฅ€เคฐเฅ‚เคŸ | เค•เฅ‡เคตเคฒ เคฒเฅ‹เค•เคฒเคนเฅ‹เคธเฅเคŸ (nginx เค•เฅ‡ เคฎเคพเคงเฅเคฏเคฎ เคธเฅ‡) | diff --git a/docs/i18n/in/docs/A2A-SERVER.md b/docs/i18n/in/docs/A2A-SERVER.md new file mode 100644 index 0000000000..601cd603c0 --- /dev/null +++ b/docs/i18n/in/docs/A2A-SERVER.md @@ -0,0 +1,200 @@ +# OmniRoute A2A Server Documentation (เคนเคฟเคจเฅเคฆเฅ€) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/A2A-SERVER.md) + +--- + +> Agent-to-Agent Protocol v0.3 โ€” OmniRoute as an intelligent routing agent + +## Agent Discovery + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements. + +--- + +## Authentication + +All `/a2a` requests require an API key via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server, authentication is bypassed. + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Sends a message to a skill and waits for the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a hello world in Python"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "uuid", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "..." }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}} + +: heartbeat 2026-03-03T17:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Available Skills + +| Skill | Description | +| :----------------- | :------------------------------------------------------------------------------------------------------------------------------ | +| `smart-routing` | Routes prompts through OmniRoute's intelligent pipeline. Returns response with routing explanation, cost, and resilience trace. | +| `quota-management` | Answers natural-language queries about provider quotas, suggests free combos, and provides quota rankings. | + +--- + +## Task Lifecycle + +``` +submitted โ†’ working โ†’ completed + โ†’ failed + โ†’ cancelled +``` + +- Tasks expire after 5 minutes (configurable) +- Terminal states: `completed`, `failed`, `cancelled` +- Event log tracks every state transition + +--- + +## Error Codes + +| Code | Meaning | +| :----- | :----------------------------- | +| -32700 | Parse error (invalid JSON) | +| -32600 | Invalid request / Unauthorized | +| -32601 | Method or skill not found | +| -32602 | Invalid params | +| -32603 | Internal error | + +--- + +## Integration Examples + +### Python (requests) + +```python +import requests + +resp = requests.post("http://localhost:20128/a2a", json={ + "jsonrpc": "2.0", "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Hello"}] + } +}, headers={"Authorization": "Bearer YOUR_KEY"}) + +result = resp.json()["result"] +print(result["artifacts"][0]["content"]) +print(result["metadata"]["routing_explanation"]) +``` + +### TypeScript (fetch) + +```typescript +const resp = await fetch("http://localhost:20128/a2a", { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: "Bearer YOUR_KEY", + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "1", + method: "message/send", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Hello" }], + }, + }), +}); +const { result } = await resp.json(); +console.log(result.metadata.routing_explanation); +``` diff --git a/docs/i18n/in/docs/API_REFERENCE.md b/docs/i18n/in/docs/API_REFERENCE.md new file mode 100644 index 0000000000..a1e8f1b6bb --- /dev/null +++ b/docs/i18n/in/docs/API_REFERENCE.md @@ -0,0 +1,465 @@ +# API Reference (เคนเคฟเคจเฅเคฆเฅ€) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/API_REFERENCE.md) + +--- + +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 | +| `X-Session-Id` | Request | Sticky session key for external session affinity | +| `x_session_id` | Request | Underscore variant also accepted (direct HTTP) | +| `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 | +| `X-OmniRoute-Session-Id` | Response | Effective session ID used by OmniRoute | + +> Nginx note: if you rely on underscore headers (for example `x_session_id`), enable `underscores_in_headers 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/stats + +# Clear all caches +DELETE /api/cache/stats +``` + +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/PATCH | 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 + provider summary (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`) | +| `/api/cache/stats` | 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 | + +### Tunnels + +| Endpoint | Method | Description | +| -------------------------- | ------ | ----------------------------------------------------------------------- | +| `/api/tunnels/cloudflared` | GET | Read Cloudflare Quick Tunnel install/runtime status for the dashboard | +| `/api/tunnels/cloudflared` | POST | Enable or disable the Cloudflare Quick Tunnel (`action=enable/disable`) | + +### 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`. + +### ACP Agents + +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | + +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). + +### Resilience & Rate Limits + +| Endpoint | Method | Description | +| ----------------------- | --------- | ------------------------------- | +| `/api/resilience` | GET/PATCH | 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` diff --git a/docs/i18n/in/docs/ARCHITECTURE.md b/docs/i18n/in/docs/ARCHITECTURE.md new file mode 100644 index 0000000000..4a6db73760 --- /dev/null +++ b/docs/i18n/in/docs/ARCHITECTURE.md @@ -0,0 +1,814 @@ +# OmniRoute Architecture (เคนเคฟเคจเฅเคฆเฅ€) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/ARCHITECTURE.md) + +--- + +_Last updated: 2026-03-28_ + +## 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 (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developerโ†’system, systemโ†’user) for cross-provider compatibility +- Structured output conversion (json_schema โ†’ Gemini responseSchema) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) +- Global system prompt injection +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout โ†’ budget โ†’ fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) + +Primary runtime model: + +- Next.js 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.) + +## Dashboard Surface (Current) + +Main pages under `src/app/(dashboard)/dashboard/`: + +- `/dashboard` โ€” quick start + provider overview +- `/dashboard/endpoint` โ€” endpoint proxy + MCP + A2A + API endpoint tabs +- `/dashboard/providers` โ€” provider connections and credentials +- `/dashboard/combos` โ€” combo strategies, templates, model routing rules +- `/dashboard/costs` โ€” cost aggregation and pricing visibility +- `/dashboard/analytics` โ€” usage analytics and evaluations +- `/dashboard/limits` โ€” quota/rate controls +- `/dashboard/cli-tools` โ€” CLI onboarding, runtime detection, config generation +- `/dashboard/agents` โ€” detected ACP agents + custom agent registration +- `/dashboard/media` โ€” image/video/music playground +- `/dashboard/search-tools` โ€” search provider testing and history +- `/dashboard/health` โ€” uptime, circuit breakers, rate limits +- `/dashboard/logs` โ€” request/proxy/audit/console logs +- `/dashboard/settings` โ€” system settings tabs (general, routing, combo defaults, etc.) +- `/dashboard/api-manager` โ€” API key lifecycle and model permissions + +## 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[(storage.sqlite)] + UDB[(usage tables + log artifacts)] + end + + subgraph Upstreams[Upstream Providers] + P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/Qoder/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/route.ts` (GET) +- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- OAuth: `src/app/api/oauth/*` +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` +- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI tooling helpers: `src/app/api/cli-tools/*` +- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) +- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) โ€” provider profiles, circuit breaker, rate limit state +- Resilience reset: `src/app/api/resilience/reset` (POST) โ€” reset breakers + cooldowns +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) +- Telemetry: `src/app/api/telemetry/summary` (GET) +- Budget: `src/app/api/usage/budget` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Policies: `src/app/api/policies` (GET/POST) + +## 2) SSE + 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` +- Response sanitization: `open-sse/handlers/responseSanitizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.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`, `qoder.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 (SQLite): + +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** + +Usage persistence: + +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present + +Domain State DB (SQLite): + +- `src/lib/db/domainState.ts` โ€” CRUD operations 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`, `src/shared/services/modelSyncScheduler.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Periodic task: `src/shared/services/modelSyncScheduler.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. Combo routing adds one extra guard: provider-scoped 400s such as upstream content-block and role-validation failures are treated as model-local failures so later combo targets can still run. + +## 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: + +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` + +## Deployment Topology + +```mermaid +flowchart LR + 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[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] + end + + subgraph External[External Services] + Providers[AI Providers] + SyncCloud[Cloud Sync Service] + end + + CLI --> Next + Browser --> Next + Next --> Core + Next --> MainDB + Core --> MainDB + Core --> UsageDB + Core --> Providers + Next --> SyncCloud +``` + +## Module Mapping (Decision-Critical) + +### Route and API Modules + +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle +- `src/app/api/models/alias`: alias management +- `src/app/api/combos*`: fallback combo management +- `src/app/api/pricing`: pricing overrides for cost calculation +- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers +- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) +- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) +- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) +- `src/app/api/sessions`: active session listing (GET) +- `src/app/api/rate-limits`: per-account rate limit status (GET) + +### Routing and Execution Core + +- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior + +### Translation Registry and Format Converters + +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` +- Format constants: `open-sse/translator/formats.ts` + +### Persistence + +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables + +## Provider Executor Coverage (Strategy Pattern) + +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. + +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, Qoder, 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 | +| Qoder | openai | OAuth (Basic) | โœ… | โœ… | โœ… | โš ๏ธ Per request | +| OpenRouter | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| GLM/Kimi/MiniMax | claude | API Key | โœ… | โœ… | โŒ | โŒ | +| DeepSeek | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Groq | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| xAI (Grok) | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Mistral | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Perplexity | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Together AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Fireworks AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Cerebras | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Cohere | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| NVIDIA NIM | openai | API Key | โœ… | โœ… | โŒ | โŒ | + +## Format Translation Coverage + +Detected source formats include: + +- `openai` +- `openai-responses` +- `claude` +- `gemini` + +Target formats include: + +- OpenAI chat/Responses +- Claude +- Gemini/Gemini-CLI/Antigravity envelope +- Kiro +- Cursor + +Translations use **OpenAI as the hub format** โ€” all conversions go through OpenAI as intermediate: + +``` +Source Format โ†’ OpenAI (hub) โ†’ Target Format +``` + +Translations are selected dynamically based on source payload shape and provider target format. + +Additional processing layers in the translation pipeline: + +- **Response sanitization** โ€” Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI targets; merges `system` โ†’ `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** โ€” Parses `...` blocks from content into `reasoning_content` field +- **Structured output** โ€” Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` + +## Supported API Endpoints + +| 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` | Provider Models | Provider model metadata backing custom and managed available models | + +## 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 `/logs//` 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 + +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON โ†’ SQLite migration compatibility path + +## Observability and Operational Signals + +Runtime visibility sources: + +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- four-stage detailed payload captures in SQLite (`request_detail_logs`) when `settings.detailed_logs_enabled=true` +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption + +Detailed request payload capture stores up to four JSON payload stages per routed call: + +- raw request received from the client +- translated request actually sent upstream +- provider response reconstructed as JSON; streamed responses are compacted to the final summary plus stream metadata +- final client response returned by OmniRoute; streamed responses are stored in the same compact summary form + +## Security-Sensitive Boundaries + +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics + +## Environment and Runtime Matrix + +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` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). + +## Operational Verification Checklist + +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: +- `GET /api/settings` +- `GET /api/v1/models` +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/in/docs/AUTO-COMBO.md b/docs/i18n/in/docs/AUTO-COMBO.md new file mode 100644 index 0000000000..3126d79b3b --- /dev/null +++ b/docs/i18n/in/docs/AUTO-COMBO.md @@ -0,0 +1,67 @@ +# OmniRoute Auto-Combo Engine (เคนเคฟเคจเฅเคฆเฅ€) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/AUTO-COMBO.md) + +--- + +> Self-managing model chains with adaptive scoring + +## How It Works + +The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**: + +| Factor | Weight | Description | +| :--------- | :----- | :---------------------------------------------- | +| Quota | 0.20 | Remaining capacity [0..1] | +| Health | 0.25 | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 | +| CostInv | 0.20 | Inverse cost (cheaper = higher score) | +| LatencyInv | 0.15 | Inverse p95 latency (faster = higher) | +| TaskFit | 0.10 | Model ร— task type fitness score | +| Stability | 0.10 | Low variance in latency/errors | + +## Mode Packs + +| Pack | Focus | Key Weight | +| :---------------------- | :----------- | :--------------- | +| ๐Ÿš€ **Ship Fast** | Speed | latencyInv: 0.35 | +| ๐Ÿ’ฐ **Cost Saver** | Economy | costInv: 0.40 | +| ๐ŸŽฏ **Quality First** | Best model | taskFit: 0.40 | +| ๐Ÿ“ก **Offline Friendly** | Availability | quota: 0.40 | + +## Self-Healing + +- **Temporary exclusion**: Score < 0.2 โ†’ excluded for 5 min (progressive backoff, max 30 min) +- **Circuit breaker awareness**: OPEN โ†’ auto-excluded; HALF_OPEN โ†’ probe requests +- **Incident mode**: >50% OPEN โ†’ disable exploration, maximize stability +- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout + +## Bandit Exploration + +5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode. + +## API + +```bash +# Create auto-combo +curl -X POST http://localhost:20128/api/combos/auto \ + -H "Content-Type: application/json" \ + -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}' + +# List auto-combos +curl http://localhost:20128/api/combos/auto +``` + +## Task Fitness + +30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` โ†’ high coding score). + +## Files + +| File | Purpose | +| :------------------------------------------- | :------------------------------------ | +| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization | +| `open-sse/services/autoCombo/taskFitness.ts` | Model ร— task fitness lookup | +| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap | +| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode | +| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles | +| `src/app/api/combos/auto/route.ts` | REST API | diff --git a/docs/i18n/in/docs/CLI-TOOLS.md b/docs/i18n/in/docs/CLI-TOOLS.md new file mode 100644 index 0000000000..c1f87f62f8 --- /dev/null +++ b/docs/i18n/in/docs/CLI-TOOLS.md @@ -0,0 +1,348 @@ +# CLI Tools Setup Guide โ€” OmniRoute (เคนเคฟเคจเฅเคฆเฅ€) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CLI-TOOLS.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CLI-TOOLS.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CLI-TOOLS.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CLI-TOOLS.md) + +--- + +This guide explains how to install and configure all supported AI coding CLI tools +to use **OmniRoute** as the unified backend, giving you centralized key management, +cost tracking, model switching, and request logging across every tool. + +--- + +## How It Works + +``` +Claude / Codex / OpenCode / Cline / KiloCode / Continue / Kiro / Cursor / Copilot + โ”‚ + โ–ผ (all point to OmniRoute) + http://YOUR_SERVER:20128/v1 + โ”‚ + โ–ผ (OmniRoute routes to the right provider) + Anthropic / OpenAI / Gemini / DeepSeek / Groq / Mistral / ... +``` + +**Benefits:** + +- One API key to manage all tools +- Cost tracking across all CLIs in the dashboard +- Model switching without reconfiguring every tool +- Works locally and on remote servers (VPS) + +--- + +## Supported Tools (Dashboard Source of Truth) + +The dashboard cards in `/dashboard/cli-tools` are generated from `src/shared/constants/cliTools.ts`. +Current list (v3.0.0-rc.16): + +| Tool | ID | Command | Setup Mode | Install Method | +| ------------------ | ------------- | ---------- | ---------- | -------------- | +| **Claude Code** | `claude` | `claude` | env | npm | +| **OpenAI Codex** | `codex` | `codex` | custom | npm | +| **Factory Droid** | `droid` | `droid` | custom | bundled/CLI | +| **OpenClaw** | `openclaw` | `openclaw` | custom | bundled/CLI | +| **Cursor** | `cursor` | app | guide | desktop app | +| **Cline** | `cline` | `cline` | custom | npm | +| **Kilo Code** | `kilo` | `kilocode` | custom | npm | +| **Continue** | `continue` | extension | guide | VS Code | +| **Antigravity** | `antigravity` | internal | mitm | OmniRoute | +| **GitHub Copilot** | `copilot` | extension | custom | VS Code | +| **OpenCode** | `opencode` | `opencode` | guide | npm | +| **Kiro AI** | `kiro` | app/cli | mitm | desktop/CLI | + +### CLI fingerprint sync (Agents + Settings) + +`/dashboard/agents` and `Settings > CLI Fingerprint` use `src/shared/constants/cliCompatProviders.ts`. +This keeps provider IDs aligned with CLI cards and legacy IDs. + +| CLI ID | Fingerprint Provider ID | +| ---------------------------------------------------------------------------------------------------- | ----------------------- | +| `kilo` | `kilocode` | +| `copilot` | `github` | +| `claude` / `codex` / `antigravity` / `kiro` / `cursor` / `cline` / `opencode` / `droid` / `openclaw` | same ID | + +Legacy IDs still accepted for compatibility: `copilot`, `kimi-coding`, `qwen`. + +--- + +## Step 1 โ€” Get an OmniRoute API Key + +1. Open the OmniRoute dashboard โ†’ **API Manager** (`/dashboard/api-manager`) +2. Click **Create API Key** +3. Give it a name (e.g. `cli-tools`) and select all permissions +4. Copy the key โ€” you'll need it for every CLI below + +> Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` + +--- + +## Step 2 โ€” Install CLI Tools + +All npm-based tools require Node.js 18+: + +```bash +# Claude Code (Anthropic) +npm install -g @anthropic-ai/claude-code + +# OpenAI Codex +npm install -g @openai/codex + +# OpenCode +npm install -g opencode-ai + +# Cline +npm install -g cline + +# KiloCode +npm install -g kilocode + +# Kiro CLI (Amazon โ€” requires curl + unzip) +apt-get install -y unzip # on Debian/Ubuntu +curl -fsSL https://cli.kiro.dev/install | bash +export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc +``` + +**Verify:** + +```bash +claude --version # 2.x.x +codex --version # 0.x.x +opencode --version # x.x.x +cline --version # 2.x.x +kilocode --version # x.x.x (or: kilo --version) +kiro-cli --version # 1.x.x +``` + +--- + +## Step 3 โ€” Set Global Environment Variables + +Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`: + +```bash +# OmniRoute Universal Endpoint +export OPENAI_BASE_URL="http://localhost:20128/v1" +export OPENAI_API_KEY="sk-your-omniroute-key" +export ANTHROPIC_BASE_URL="http://localhost:20128/v1" +export ANTHROPIC_API_KEY="sk-your-omniroute-key" +export GEMINI_BASE_URL="http://localhost:20128/v1" +export GEMINI_API_KEY="sk-your-omniroute-key" +``` + +> For a **remote server** replace `localhost:20128` with the server IP or domain, +> e.g. `http://192.168.0.15:20128`. + +--- + +## Step 4 โ€” Configure Each Tool + +### Claude Code + +```bash +# Via CLI: +claude config set --global api-base-url http://localhost:20128/v1 + +# Or create ~/.claude/settings.json: +mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF +{ + "apiBaseUrl": "http://localhost:20128/v1", + "apiKey": "sk-your-omniroute-key" +} +EOF +``` + +**Test:** `claude "say hello"` + +--- + +### OpenAI Codex + +```bash +mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF +model: auto +apiKey: sk-your-omniroute-key +apiBaseUrl: http://localhost:20128/v1 +EOF +``` + +**Test:** `codex "what is 2+2?"` + +--- + +### OpenCode + +```bash +mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF +[provider.openai] +base_url = "http://localhost:20128/v1" +api_key = "sk-your-omniroute-key" +EOF +``` + +**Test:** `opencode` + +--- + +### Cline (CLI or VS Code) + +**CLI mode:** + +```bash +mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF +{ + "apiProvider": "openai", + "openAiBaseUrl": "http://localhost:20128/v1", + "openAiApiKey": "sk-your-omniroute-key" +} +EOF +``` + +**VS Code mode:** +Cline extension settings โ†’ API Provider: `OpenAI Compatible` โ†’ Base URL: `http://localhost:20128/v1` + +Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ Cline โ†’ Apply Config**. + +--- + +### KiloCode (CLI or VS Code) + +**CLI mode:** + +```bash +kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key +``` + +**VS Code settings:** + +```json +{ + "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", + "kilo-code.apiKey": "sk-your-omniroute-key" +} +``` + +Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ KiloCode โ†’ Apply Config**. + +--- + +### Continue (VS Code Extension) + +Edit `~/.continue/config.yaml`: + +```yaml +models: + - name: OmniRoute + provider: openai + model: auto + apiBase: http://localhost:20128/v1 + apiKey: sk-your-omniroute-key + default: true +``` + +Restart VS Code after editing. + +--- + +### Kiro CLI (Amazon) + +```bash +# Login to your AWS/Kiro account: +kiro-cli login + +# The CLI uses its own auth โ€” OmniRoute is not needed as backend for Kiro CLI itself. +# Use kiro-cli alongside OmniRoute for other tools. +kiro-cli status +``` + +--- + +### Cursor (Desktop App) + +> **Note:** Cursor routes requests through its cloud. For OmniRoute integration, +> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL. + +Via GUI: **Settings โ†’ Models โ†’ OpenAI API Key** + +- Base URL: `https://your-domain.com/v1` +- API Key: your OmniRoute key + +--- + +## Dashboard Auto-Configuration + +The OmniRoute dashboard automates configuration for most tools: + +1. Go to `http://localhost:20128/dashboard/cli-tools` +2. Expand any tool card +3. Select your API key from the dropdown +4. Click **Apply Config** (if tool is detected as installed) +5. Or copy the generated config snippet manually + +--- + +## Built-in Agents: Droid & OpenClaw + +**Droid** and **OpenClaw** are AI agents built directly into OmniRoute โ€” no installation needed. +They run as internal routes and use OmniRoute's model routing automatically. + +- Access: `http://localhost:20128/dashboard/agents` +- Configure: same combos and providers as all other tools +- No API key or CLI install required + +--- + +## Available API Endpoints + +| Endpoint | Description | Use For | +| -------------------------- | ----------------------------- | --------------------------- | +| `/v1/chat/completions` | Standard chat (all providers) | All modern tools | +| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows | +| `/v1/completions` | Legacy text completions | Older tools using `prompt:` | +| `/v1/embeddings` | Text embeddings | RAG, search | +| `/v1/images/generations` | Image generation | DALL-E, Flux, etc. | +| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS | +| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI | + +--- + +## เคธเคฎเคธเฅเคฏเคพ เคจเคฟเคตเคพเคฐเคฃ + +| Error | Cause | Fix | +| ------------------------- | ----------------------- | ------------------------------------------ | +| `Connection refused` | OmniRoute not running | `pm2 start omniroute` | +| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` | +| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` | +| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` | +| CLI shows "not installed" | Binary not in PATH | Check `which ` | +| `kiro-cli: not found` | Not in PATH | `export PATH="$HOME/.local/bin:$PATH"` | + +--- + +## Quick Setup Script (One Command) + +```bash +# Install all CLIs and configure for OmniRoute (replace with your key and server URL) +OMNIROUTE_URL="http://localhost:20128/v1" +OMNIROUTE_KEY="sk-your-omniroute-key" + +npm install -g @anthropic-ai/claude-code @openai/codex opencode-ai cline kilocode + +# Kiro CLI +apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash + +# Write configs +mkdir -p ~/.claude ~/.codex ~/.config/opencode ~/.continue + +cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" +cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" +cat >> ~/.bashrc << EOF +export OPENAI_BASE_URL="$OMNIROUTE_URL" +export OPENAI_API_KEY="$OMNIROUTE_KEY" +export ANTHROPIC_BASE_URL="$OMNIROUTE_URL" +export ANTHROPIC_API_KEY="$OMNIROUTE_KEY" +EOF + +source ~/.bashrc +echo "โœ… All CLIs installed and configured for OmniRoute" +``` diff --git a/docs/i18n/in/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/in/docs/CODEBASE_DOCUMENTATION.md new file mode 100644 index 0000000000..56ae66a8fb --- /dev/null +++ b/docs/i18n/in/docs/CODEBASE_DOCUMENTATION.md @@ -0,0 +1,591 @@ +# omniroute โ€” Codebase Documentation (เคนเคฟเคจเฅเคฆเฅ€) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CODEBASE_DOCUMENTATION.md) + +--- + +> 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
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, Qoder, 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. + +#### เค†เคฐเฅเค•เคฟเคŸเฅ‡เค•เฅเคšเคฐ + +```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 | +| Qoder | 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"] +``` diff --git a/docs/i18n/in/docs/COVERAGE_PLAN.md b/docs/i18n/in/docs/COVERAGE_PLAN.md new file mode 100644 index 0000000000..4484ddc962 --- /dev/null +++ b/docs/i18n/in/docs/COVERAGE_PLAN.md @@ -0,0 +1,170 @@ +# Test Coverage Plan (เคนเคฟเคจเฅเคฆเฅ€) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/COVERAGE_PLAN.md) + +--- + +Last updated: 2026-03-28 + +## Baseline + +There are multiple coverage numbers depending on how the report is computed. For planning, only one of them is useful. + +| Metric | Scope | Statements / Lines | Branches | Functions | Notes | +| -------------------- | ----------------------------------------------------- | -----------------: | -------: | --------: | --------------------------------------------------- | +| Legacy | Old `npm run test:coverage` | 79.42% | 75.15% | 67.94% | Inflated: counts test files and excludes `open-sse` | +| Diagnostic | Source-only, excluding tests and excluding `open-sse` | 68.16% | 63.55% | 64.06% | Useful only to isolate `src/**` | +| Recommended baseline | Source-only, excluding tests and including `open-sse` | 56.95% | 66.05% | 57.80% | This is the project-wide baseline to improve | + +The recommended baseline is the number to optimize against. + +## Rules + +- Coverage targets apply to source files, not to `tests/**`. +- `open-sse/**` is part of the product and must remain in scope. +- New code should not reduce coverage in touched areas. +- Prefer testing behavior and branch outcomes over implementation details. +- Prefer temp SQLite databases and small fixtures over broad mocks for `src/lib/db/**`. + +## Current command set + +- `npm run test:coverage` + - Main source coverage gate for the unit test suite + - Generates `text-summary`, `html`, `json-summary`, and `lcov` +- `npm run coverage:report` + - Detailed file-by-file report from the latest run +- `npm run test:coverage:legacy` + - Historical comparison only + +## Milestones + +| Phase | Target | Focus | +| ------- | ---------------------: | ------------------------------------------------- | +| Phase 1 | 60% statements / lines | Quick wins and low-risk utility coverage | +| Phase 2 | 65% statements / lines | DB and route foundations | +| Phase 3 | 70% statements / lines | Provider validation and usage analytics | +| Phase 4 | 75% statements / lines | `open-sse` translators and helpers | +| Phase 5 | 80% statements / lines | `open-sse` handlers and executor branches | +| Phase 6 | 85% statements / lines | Harder edge cases, branch debt, regression suites | +| Phase 7 | 90% statements / lines | Final sweep, gap closure, strict ratchet | + +Branches and functions should ratchet upward with each phase, but the primary hard target is statements / lines. + +## Priority hotspots + +These files or areas offer the best return for the next phases: + +1. `open-sse/handlers` + - `chatCore.ts` at 7.57% + - Overall directory at 29.07% +2. `open-sse/translator/request` + - Overall directory at 36.39% + - Many translators are still near single-digit coverage +3. `open-sse/translator/response` + - Overall directory at 8.07% +4. `open-sse/executors` + - Overall directory at 36.62% +5. `src/lib/db` + - `models.ts` at 20.66% + - `registeredKeys.ts` at 34.46% + - `modelComboMappings.ts` at 36.25% + - `settings.ts` at 46.40% + - `webhooks.ts` at 33.33% +6. `src/lib/usage` + - `usageHistory.ts` at 21.12% + - `usageStats.ts` at 9.56% + - `costCalculator.ts` at 30.00% +7. `src/lib/providers` + - `validation.ts` at 41.16% +8. Low-risk utility and API files for early gains + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/api/errorResponse.ts` + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +## Execution checklist + +### Phase 1: 56.95% -> 60% + +- [x] Fix coverage metric so it reflects source code instead of test files +- [x] Keep a legacy coverage script for comparison +- [x] Record the baseline and hotspots in-repo +- [ ] Add focused tests for low-risk utilities: + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/fetchTimeout.ts` + - `src/lib/api/errorResponse.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/display/names.ts` +- [ ] Add route tests for: + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +### Phase 2: 60% -> 65% + +- [ ] Add DB-backed tests for: + - `src/lib/db/modelComboMappings.ts` + - `src/lib/db/settings.ts` + - `src/lib/db/registeredKeys.ts` +- [ ] Cover branch behavior in: + - `src/lib/providers/validation.ts` + - `src/app/api/v1/embeddings/route.ts` + - `src/app/api/v1/moderations/route.ts` + +### Phase 3: 65% -> 70% + +- [ ] Add usage analytics tests for: + - `src/lib/usage/usageHistory.ts` + - `src/lib/usage/usageStats.ts` + - `src/lib/usage/costCalculator.ts` +- [ ] Expand route coverage for proxy management and settings branches + +### Phase 4: 70% -> 75% + +- [ ] Cover translator helpers and central translation paths: + - `open-sse/translator/index.ts` + - `open-sse/translator/helpers/*` + - `open-sse/translator/request/*` + - `open-sse/translator/response/*` + +### Phase 5: 75% -> 80% + +- [ ] Add handler-level tests for: + - `open-sse/handlers/chatCore.ts` + - `open-sse/handlers/responsesHandler.js` + - `open-sse/handlers/imageGeneration.js` + - `open-sse/handlers/embeddings.js` +- [ ] Add executor branch coverage for provider-specific auth, retries, and endpoint overrides + +### Phase 6: 80% -> 85% + +- [ ] Merge more edge-case suites into the main coverage path +- [ ] Increase function coverage for DB modules with weak constructor/helper coverage +- [ ] Close branch gaps in `settings.ts`, `registeredKeys.ts`, `validation.ts`, and translator helpers + +### Phase 7: 85% -> 90% + +- [ ] Treat the remaining low-coverage files as blockers +- [ ] Add regression tests for every uncovered production bug fixed during the push to 90% +- [ ] Raise the coverage gate in CI only after the local baseline is stable for at least two consecutive runs + +## Ratchet policy + +Update `npm run test:coverage` thresholds only after the project actually exceeds the next milestone with a comfortable buffer. + +Recommended ratchet sequence: + +1. 55/60/55 +2. 60/62/58 +3. 65/64/62 +4. 70/66/66 +5. 75/70/72 +6. 80/75/78 +7. 85/80/84 +8. 90/85/88 + +Order is `statements-lines / branches / functions`. + +## Known gap + +The current coverage command measures the main Node unit suite and includes source reached from it, including `open-sse`. It does not yet merge Vitest coverage into a single unified report. That merge is worth doing later, but it is not a blocker for starting the 60% -> 80% climb. diff --git a/docs/i18n/in/docs/FEATURES.md b/docs/i18n/in/docs/FEATURES.md index 0e00239bb6..f3c8dcdd2b 100644 --- a/docs/i18n/in/docs/FEATURES.md +++ b/docs/i18n/in/docs/FEATURES.md @@ -1,6 +1,6 @@ # OmniRoute โ€” Dashboard Features Gallery (เคนเคฟเคจเฅเคฆเฅ€) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/FEATURES.md) --- @@ -10,7 +10,7 @@ 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). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. ![Providers Dashboard](screenshots/01-providers.png) diff --git a/docs/i18n/in/docs/MCP-SERVER.md b/docs/i18n/in/docs/MCP-SERVER.md new file mode 100644 index 0000000000..8310a87704 --- /dev/null +++ b/docs/i18n/in/docs/MCP-SERVER.md @@ -0,0 +1,87 @@ +# OmniRoute MCP Server Documentation (เคนเคฟเคจเฅเคฆเฅ€) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/MCP-SERVER.md) + +--- + +> Model Context Protocol server with 16 intelligent tools + +## เคธเฅเคฅเคพเคชเคฟเคค เค•เคฐเฅ‡เค‚ + +OmniRoute MCP is built-in. Start it with: + +```bash +omniroute --mcp +``` + +Or via the open-sse transport: + +```bash +# HTTP streamable transport (port 20130) +omniroute --dev # MCP auto-starts on /mcp endpoint +``` + +## IDE Configuration + +See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup. + +--- + +## Essential Tools (8) + +| Tool | Description | +| :------------------------------ | :--------------------------------------- | +| `omniroute_get_health` | Gateway health, circuit breakers, uptime | +| `omniroute_list_combos` | All configured combos with models | +| `omniroute_get_combo_metrics` | Performance metrics for a specific combo | +| `omniroute_switch_combo` | Switch active combo by ID/name | +| `omniroute_check_quota` | Quota status per provider or all | +| `omniroute_route_request` | Send a chat completion through OmniRoute | +| `omniroute_cost_report` | Cost analytics for a time period | +| `omniroute_list_models_catalog` | Full model catalog with capabilities | + +## Advanced Tools (8) + +| Tool | Description | +| :--------------------------------- | :---------------------------------------------------------- | +| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | +| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | +| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | +| `omniroute_test_combo` | Live-test all models in a combo via a real upstream request | +| `omniroute_get_provider_metrics` | Detailed metrics for one provider | +| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | +| `omniroute_explain_route` | Explain a past routing decision | +| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | + +## Authentication + +MCP tools are authenticated via API key scopes. Each tool requires specific scopes: + +| Scope | Tools | +| :------------- | :----------------------------------------------- | +| `read:health` | get_health, get_provider_metrics | +| `read:combos` | list_combos, get_combo_metrics | +| `write:combos` | switch_combo | +| `read:quota` | check_quota | +| `write:route` | route_request, simulate_route, test_combo | +| `read:usage` | cost_report, get_session_snapshot, explain_route | +| `write:config` | set_budget_guard, set_resilience_profile | +| `read:models` | list_models_catalog, best_combo_for_task | + +## Audit Logging + +Every tool call is logged to `mcp_tool_audit` with: + +- Tool name, arguments, result +- Duration (ms), success/failure +- API key hash, timestamp + +## Files + +| File | Purpose | +| :------------------------------------------- | :------------------------------------------ | +| `open-sse/mcp-server/server.ts` | MCP server creation + 16 tool registrations | +| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport | +| `open-sse/mcp-server/auth.ts` | API key + scope validation | +| `open-sse/mcp-server/audit.ts` | Tool call audit logging | +| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers | diff --git a/docs/i18n/in/docs/RELEASE_CHECKLIST.md b/docs/i18n/in/docs/RELEASE_CHECKLIST.md new file mode 100644 index 0000000000..e55e6d7533 --- /dev/null +++ b/docs/i18n/in/docs/RELEASE_CHECKLIST.md @@ -0,0 +1,37 @@ +# Release Checklist (เคนเคฟเคจเฅเคฆเฅ€) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/RELEASE_CHECKLIST.md) + +--- + +Use this checklist before tagging or publishing a new OmniRoute release. + +## Version and Changelog + +1. Bump `package.json` version (`x.y.z`) in the release branch. +2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: + - `## [x.y.z] โ€” YYYY-MM-DD` +3. Keep `## [Unreleased]` as the first changelog section for upcoming work. +4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. + +## API Docs + +1. Update `docs/openapi.yaml`: + - `info.version` must equal `package.json` version. +2. Validate endpoint examples if API contracts changed. + +## Runtime Docs + +1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. +2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. +3. Update localized docs if source docs changed significantly. + +## Automated Check + +Run the sync guard locally before opening PR: + +```bash +npm run check:docs-sync +``` + +CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/in/docs/TROUBLESHOOTING.md b/docs/i18n/in/docs/TROUBLESHOOTING.md new file mode 100644 index 0000000000..4c397b471f --- /dev/null +++ b/docs/i18n/in/docs/TROUBLESHOOTING.md @@ -0,0 +1,256 @@ +# Troubleshooting (เคนเคฟเคจเฅเคฆเฅ€) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/TROUBLESHOOTING.md) + +--- + +Common problems and solutions for OmniRoute. + +--- + +## Quick Fixes + +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | + +--- + +## Provider Issues + +### "Language model did not provide messages" + +**Cause:** Provider quota exhausted. + +**Fix:** + +1. 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, Qoder) 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}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) + +--- + +## Circuit Breaker Issues + +### Provider stuck in OPEN state + +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. + +**Fix:** + +1. 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 +- **SDK returns raw string instead of object** โ€” Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** โ€” Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** โ€” Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** โ€” Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` + +--- + +## Resilience Settings + +### Auto rate-limit not triggering + +- 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. + +--- + +## Optional RAG / LLM failure taxonomy (16 problems) + +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` โ€ฆ `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard โ†’ Health** for real-time system status +- **Translator**: Use **Dashboard โ†’ Translator** to debug format issues diff --git a/docs/i18n/in/USER_GUIDE.md b/docs/i18n/in/docs/USER_GUIDE.md similarity index 82% rename from docs/i18n/in/USER_GUIDE.md rename to docs/i18n/in/docs/USER_GUIDE.md index f7f12c7965..389d00cb69 100644 --- a/docs/i18n/in/USER_GUIDE.md +++ b/docs/i18n/in/docs/USER_GUIDE.md @@ -1,8 +1,6 @@ # User Guide (เคนเคฟเคจเฅเคฆเฅ€) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/USER_GUIDE.md) - -> ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/USER_GUIDE.md) --- @@ -320,7 +318,7 @@ Model: cc/claude-opus-4-6 --- -## ๐Ÿš€ Deployment +## เคคเฅˆเคจเคพเคคเฅ€ ### Global npm install (Recommended) @@ -511,23 +509,26 @@ post_install() { ### Environment Variables -| Variable | Default | Description | -| ------------------------- | ------------------------------------ | ------------------------------------------------------- | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | -| `INITIAL_PASSWORD` | `123456` | First login password | -| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | -| `PORT` | framework default | Service port (`20128` in examples) | -| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | -| `NODE_ENV` | runtime default | Set `production` for deploy | -| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | -| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | -| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | -| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | -| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | -| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | -| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | -| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | +| 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/*` | +| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand | +| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | For the full environment variable reference, see the [README](../README.md). @@ -598,6 +599,11 @@ curl -X POST http://localhost:20128/api/provider-models \ Or use Dashboard: **Providers โ†’ [Provider] โ†’ Custom Models**. +Notes: + +- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers. +- The **Custom Models** section is intended for providers that do not expose managed available-model imports. + ### Dedicated Provider Routes Route requests directly to a specific provider with model validation: @@ -642,6 +648,14 @@ Returns models grouped by provider with types (`chat`, `embedding`, `image`). - Automatic background sync with timeout + fail-fast - Prefer server-side `BASE_URL`/`CLOUD_URL` in production +### Cloudflare Quick Tunnel + +- Available in **Dashboard โ†’ Endpoints** for Docker and other self-hosted deployments +- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint +- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary +- Tunnel URLs are ephemeral and change every time you stop/start the tunnel +- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download + ### LLM Gateway Intelligence (Phase 9) - **Semantic Cache** โ€” Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) @@ -757,11 +771,11 @@ OmniRoute implements provider-level resilience with four components: 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 | +| 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 unless `DISABLE_SQLITE_AUTO_BACKUP=true` | ```bash # API: Export database @@ -787,10 +801,11 @@ curl -X POST http://localhost:20128/api/db-backups/import \ ### Settings Dashboard -The settings page is organized into 5 tabs for easy navigation: +The settings page is organized into 6 tabs for easy navigation: | Tab | Contents | | -------------- | ---------------------------------------------------------------------------------------------- | +| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility | | **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | | **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | | **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | diff --git a/docs/i18n/in/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/in/docs/VM_DEPLOYMENT_GUIDE.md new file mode 100644 index 0000000000..8ed764b802 --- /dev/null +++ b/docs/i18n/in/docs/VM_DEPLOYMENT_GUIDE.md @@ -0,0 +1,403 @@ +# OmniRoute โ€” Deployment Guide on VM with Cloudflare (เคนเคฟเคจเฅเคฆเฅ€) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/VM_DEPLOYMENT_GUIDE.md) + +--- + +Complete guide to install and configure OmniRoute on a VM (VPS) with domain managed via Cloudflare. + +--- + +## Prerequisites + +| Item | Minimum | Recommended | +| ---------- | ------------------------ | ---------------- | +| **CPU** | 1 vCPU | 2 vCPU | +| **RAM** | 1 GB | 2 GB | +| **Disk** | 10 GB SSD | 25 GB SSD | +| **OS** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS | +| **Domain** | Registered on Cloudflare | โ€” | +| **Docker** | Docker Engine 24+ | Docker 27+ | + +**Tested providers**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. + +--- + +## 1. Configure the VM + +### 1.1 Create the instance + +On your preferred VPS provider: + +- Choose Ubuntu 24.04 LTS +- Select the minimum plan (1 vCPU / 1 GB RAM) +- Set a strong root password or configure SSH key +- Note the **public IP** (e.g., `203.0.113.10`) + +### 1.2 Connect via SSH + +```bash +ssh root@203.0.113.10 +``` + +### 1.3 Update the system + +```bash +apt update && apt upgrade -y +``` + +### 1.4 Install Docker + +```bash +# Install dependencies +apt install -y ca-certificates curl gnupg + +# Add official Docker repository +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 Install nginx + +```bash +apt install -y nginx +``` + +### 1.6 Configure 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 +``` + +> **Tip**: For maximum security, restrict ports 80 and 443 to Cloudflare IPs only. See the [Advanced Security](#advanced-security) section. + +--- + +## 2. Install OmniRoute + +### 2.1 Create configuration directory + +```bash +mkdir -p /opt/omniroute +``` + +### 2.2 Create environment variables file + +```bash +cat > /opt/omniroute/.env << โ€˜EOFโ€™ +# === Security === +JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY +INITIAL_PASSWORD=YourSecurePassword123! +API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY +STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY +STORAGE_ENCRYPTION_KEY_VERSION=v1 +MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT + +# === 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 (change to your domain) === +BASE_URL=https://llms.seudominio.com +NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com + +# === Cloud Sync (optional) === +# CLOUD_URL=https://cloud.omniroute.online +# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online +EOF +``` + +> โš ๏ธ **IMPORTANT**: Generate unique secret keys! Use `openssl rand -hex 32` for each key. + +### 2.3 Start the 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 Verify that it is running + +```bash +docker ps | grep omniroute +docker logs omniroute --tail 20 +``` + +It should display: `[DB] SQLite database ready` and `listening on port 20128`. + +--- + +## 3. Configure nginx (Reverse Proxy) + +### 3.1 Generate SSL certificate (Cloudflare Origin) + +In the Cloudflare dashboard: + +1. Go to **SSL/TLS โ†’ Origin Server** +2. Click **Create Certificate** +3. Keep the defaults (15 years, \*.yourdomain.com) +4. Copy the **Origin Certificate** and the **Private Key** + +```bash +mkdir -p /etc/nginx/ssl + +# Paste the certificate +nano /etc/nginx/ssl/origin.crt + +# Paste the private key +nano /etc/nginx/ssl/origin.key + +chmod 600 /etc/nginx/ssl/origin.key +``` + +### 3.2 Nginx Configuration + +```bash +cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ +# Default server โ€” blocks direct access via 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.yourdomain.com; # Change to your domain + + 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.yourdomain.com; + return 301 https://$server_name$request_uri; +} +NGINX +``` + +### 3.3 Enable and Test + +```bash +# Remove default configuration +rm -f /etc/nginx/sites-enabled/default + +# Enable OmniRoute +ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute + +# Test and reload +nginx -t && systemctl reload nginx +``` + +--- + +## 4. Configure Cloudflare DNS + +### 4.1 Add DNS record + +In the Cloudflare dashboard โ†’ DNS: + +| Type | Name | Content | Proxy | +| ---- | ------ | ---------------------- | ---------- | +| A | `llms` | `203.0.113.10` (VM IP) | โœ… Proxied | + +### 4.2 Configure SSL + +Under **SSL/TLS โ†’ Overview**: + +- Mode: **Full (Strict)** + +Under **SSL/TLS โ†’ Edge Certificates**: + +- Always Use HTTPS: โœ… On +- Minimum TLS Version: TLS 1.2 +- Automatic HTTPS Rewrites: โœ… On + +### 4.3 Testing + +```bash +curl -sI https://llms.seudominio.com/health +# Should return HTTP/2 200 +``` + +--- + +## 5. Operations and Maintenance + +### Upgrade to a new version + +```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 +``` + +### View logs + +```bash +docker logs -f omniroute # Real-time stream +docker logs omniroute --tail 50 # Last 50 lines +``` + +### Manual database backup + +```bash +# Copy data from the volume to the host +docker cp omniroute:/app/data ./backup-$(date +%F) + +# Or compress the entire volume +docker run --rm -v omniroute-data:/data -v $(pwd):/backup \ + alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data +``` + +### Restore from 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. Advanced Security + +### Restrict nginx to Cloudflare IPs + +```bash +cat > /etc/nginx/cloudflare-ips.conf << โ€˜CFโ€™ +# Cloudflare IPv4 ranges โ€” update periodically +# 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 +``` + +Add the following to `nginx.conf` inside the `http {}` block: + +```nginx +include /etc/nginx/cloudflare-ips.conf; +``` + +### Install fail2ban + +```bash +apt install -y fail2ban +systemctl enable fail2ban +systemctl start fail2ban + +# Check status +fail2ban-client status sshd +``` + +### Block direct access to the Docker port + +```bash +# Prevent direct external access to port 20128 +iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP +iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT + +# Persist the rules +apt install -y iptables-persistent +netfilter-persistent save +``` + +--- + +## 7. Deploy to Cloudflare Workers (Optional) + +For remote access via Cloudflare Workers (without exposing the VM directly): + +```bash +# In the local repository +cd omnirouteCloud +npm install +npx wrangler login +npx wrangler deploy +``` + +See the full documentation at [omnirouteCloud/README.md](../omnirouteCloud/README.md). + +--- + +## Port Summary + +| Port | Service | Access | +| ----- | ----------- | -------------------------- | +| 22 | SSH | Public (with fail2ban) | +| 80 | nginx HTTP | Redirect โ†’ HTTPS | +| 443 | nginx HTTPS | Via Cloudflare Proxy | +| 20128 | OmniRoute | Localhost only (via nginx) | diff --git a/docs/i18n/in/src/lib/a2a/README.md b/docs/i18n/in/src/lib/a2a/README.md new file mode 100644 index 0000000000..4d1bbde8ef --- /dev/null +++ b/docs/i18n/in/src/lib/a2a/README.md @@ -0,0 +1,752 @@ +# OmniRoute A2A Server (เคนเคฟเคจเฅเคฆเฅ€) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../../../src/lib/a2a/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../../../es/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../../../fr/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../../../de/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../../../it/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../../../ru/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../../../zh-CN/src/lib/a2a/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../../../ja/src/lib/a2a/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../../../ko/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../../../ar/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../../../in/src/lib/a2a/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../../../th/src/lib/a2a/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../../../vi/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../../../id/src/lib/a2a/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../../../ms/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../../../nl/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../../../pl/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../../../sv/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../../../no/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../../../da/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../../../fi/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../../../pt/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../../../ro/src/lib/a2a/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../../../hu/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../../../bg/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../../../sk/src/lib/a2a/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../../../uk-UA/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../../../he/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../../../phi/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../../../pt-BR/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../../../cs/src/lib/a2a/README.md) + +--- + +> **Agent-to-Agent Protocol v0.3** โ€” Enables any AI agent to use OmniRoute as an intelligent routing agent via JSON-RPC 2.0. + +The A2A Server exposes OmniRoute as a **first-class agent** that other agents can discover, delegate tasks to, and collaborate with using the [A2A Protocol](https://google.github.io/A2A/). + +--- + +## เค†เคฐเฅเค•เคฟเคŸเฅ‡เค•เฅเคšเคฐ + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Orchestrator Agent โ”‚ +โ”‚ (LangChain, CrewAI, AutoGen, Custom Agent) โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ 1. GET /.well-known/agent.json (discover) + โ”‚ 2. POST /a2a (JSON-RPC 2.0) + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ OmniRoute A2A Server โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Task Manager โ”‚ โ”‚ Skill Engine โ”‚ โ”‚ SSE Streaming โ”‚ โ”‚ +โ”‚ โ”‚ (lifecycle) โ”‚โ”€โ”€โ”‚ (registry) โ”‚โ”€โ”€โ”‚ (real-time) โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ +โ”‚ Skills: โ”‚ โ”‚ +โ”‚ โ”œโ”€ smart-routing โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ””โ”€ quota-management โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ Routing Decision Logger โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ OmniRoute Gateway (internal) + /v1/chat/completions, /api/combos, /api/usage/quota +``` + +--- + +## เคคเฅเคตเคฐเคฟเคค เคชเฅเคฐเคพเคฐเค‚เคญ + +### Agent Discovery + +Every A2A-compatible agent exposes an **Agent Card** at `/.well-known/agent.json`: + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +**Response:** + +```json +{ + "name": "OmniRoute", + "description": "Intelligent AI gateway with auto-routing across 50+ providers", + "url": "http://localhost:20128/a2a", + "version": "1.8.1", + "capabilities": { + "streaming": true, + "pushNotifications": false + }, + "skills": [ + { + "id": "smart-routing", + "name": "Smart Routing", + "description": "Routes prompts through OmniRoute intelligent pipeline", + "tags": ["routing", "llm", "multi-provider", "cost-optimization"], + "examples": [ + "Write a hello world in Python", + "Explain quantum computing using the cheapest provider" + ] + }, + { + "id": "quota-management", + "name": "Quota Management", + "description": "Natural-language queries about provider quotas", + "tags": ["quota", "analytics", "cost"], + "examples": [ + "Which provider has the most quota remaining?", + "Suggest a free combo for coding" + ] + } + ], + "authentication": { + "schemes": ["bearer"], + "apiKeyHeader": "Authorization" + } +} +``` + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Send a message to a skill and receive the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python hello world"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "a1b2c3d4-...", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "print('Hello, World!')" }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.0030)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "2026-03-04T..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"Quantum computing..."}}} + +: heartbeat 2026-03-04T21:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Running Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Skills Reference + +### `smart-routing` + +Routes prompts through OmniRoute's intelligent pipeline with full observability. + +**Parameters (in `metadata`):** + +| Parameter | Type | Default | Description | +| --------- | -------- | ------------ | ---------------------------------------------------------------------------------------- | +| `model` | `string` | `"auto"` | Target model (e.g., `claude-sonnet-4`, `gpt-4o`, `auto`) | +| `combo` | `string` | active combo | Specific combo to route through | +| `budget` | `number` | none | Maximum cost in USD for this request | +| `role` | `string` | none | Task role hint: `coding`, `review`, `planning`, `analysis`, `debugging`, `documentation` | + +**Returns:** + +| Field | Description | +| ------------------------------ | --------------------------------------------------------- | +| `artifacts[].content` | The LLM response text | +| `metadata.routing_explanation` | Human-readable explanation of routing decision | +| `metadata.cost_envelope` | Estimated vs actual cost with currency | +| `metadata.resilience_trace` | Array of events (primary_selected, fallback_needed, etc.) | +| `metadata.policy_verdict` | Whether the request was allowed and why | + +### `quota-management` + +Answers natural-language queries about provider quotas. + +**Query types (inferred from message content):** + +| Query Pattern | Response Type | +| ---------------------------------------------- | -------------------------------------------------------- | +| Contains `"ranking"`, `"most quota"`, `"best"` | Providers ranked by remaining quota | +| Contains `"free"`, `"suggest"` | Lists free combos or suggests free-tier providers | +| Default | Full quota summary with warnings for low-quota providers | + +--- + +## Task Lifecycle + +``` +submitted โ”€โ”€โ†’ working โ”€โ”€โ†’ completed + โ”€โ”€โ†’ failed + โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ†’ cancelled +``` + +| State | Description | +| ----------- | ----------------------------------------------------- | +| `submitted` | Task created, queued for execution | +| `working` | Skill handler is executing | +| `completed` | Execution succeeded, artifacts available | +| `failed` | Execution failed or task expired (TTL: 5 min default) | +| `cancelled` | Cancelled by client via `tasks/cancel` | + +- Terminal states: `completed`, `failed`, `cancelled` (no further transitions) +- Expired tasks in `submitted` or `working` are auto-marked as `failed` +- Tasks are garbage-collected after 2ร— TTL + +--- + +## Client Examples + +### Python โ€” Orchestrator Agent + +```python +""" +A2A Client โ€” Python example. +Discovers OmniRoute agent, sends a task, and processes the result. +""" +import requests +import json + +BASE_URL = "http://localhost:20128" +API_KEY = "your-api-key" +HEADERS = { + "Content-Type": "application/json", + "Authorization": f"Bearer {API_KEY}", +} + +# 1. Discover agent capabilities +agent_card = requests.get(f"{BASE_URL}/.well-known/agent.json").json() +print(f"Agent: {agent_card['name']} v{agent_card['version']}") +print(f"Skills: {[s['id'] for s in agent_card['skills']]}") + +# 2. Send a smart-routing task +response = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python quicksort implementation"}], + "metadata": { + "model": "auto", + "combo": "fast-coding", + "budget": 0.10, + } + } +}) +result = response.json()["result"] +print(f"\n๐Ÿ“ Response: {result['artifacts'][0]['content'][:200]}...") +print(f"๐Ÿ”€ Routing: {result['metadata']['routing_explanation']}") +print(f"๐Ÿ’ฐ Cost: ${result['metadata']['cost_envelope']['actual']}") +print(f"๐Ÿ›ก๏ธ Policy: {result['metadata']['policy_verdict']['reason']}") + +# 3. Query quota status +quota_resp = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-2", + "method": "message/send", + "params": { + "skill": "quota-management", + "messages": [{"role": "user", "content": "Which provider has the most quota remaining?"}], + } +}) +quota_result = quota_resp.json()["result"] +print(f"\n๐Ÿ“Š Quota: {quota_result['artifacts'][0]['content']}") +``` + +### TypeScript โ€” Multi-Agent Orchestrator + +```typescript +/** + * A2A Client โ€” TypeScript example. + * Shows agent discovery, task delegation, and streaming. + */ + +const BASE_URL = "http://localhost:20128"; +const API_KEY = "your-api-key"; + +interface JsonRpcResponse { + jsonrpc: "2.0"; + id: string | number; + result?: T; + error?: { code: number; message: string }; +} + +async function a2aCall(method: string, params: Record): Promise { + const resp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: `${method}-${Date.now()}`, + method, + params, + }), + }); + const json: JsonRpcResponse = await resp.json(); + if (json.error) throw new Error(`[${json.error.code}] ${json.error.message}`); + return json.result!; +} + +// โ”€โ”€ Agent Discovery โ”€โ”€ +const agentCard = await fetch(`${BASE_URL}/.well-known/agent.json`).then((r) => r.json()); +console.log(`Connected to: ${agentCard.name} (${agentCard.skills.length} skills)`); + +// โ”€โ”€ Smart Routing: Send a coding task โ”€โ”€ +const routingResult = await a2aCall("message/send", { + skill: "smart-routing", + messages: [{ role: "user", content: "Implement a Redis cache wrapper in TypeScript" }], + metadata: { model: "claude-sonnet-4", role: "coding" }, +}); +console.log("Response:", routingResult.artifacts[0].content); +console.log("Provider:", routingResult.metadata.routing_explanation); + +// โ”€โ”€ Quota Management: Find free alternatives โ”€โ”€ +const quotaResult = await a2aCall("message/send", { + skill: "quota-management", + messages: [{ role: "user", content: "Suggest free combos for documentation" }], +}); +console.log("Free combos:", quotaResult.artifacts[0].content); + +// โ”€โ”€ Streaming: Real-time response โ”€โ”€ +const streamResp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "stream-1", + method: "message/stream", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Explain microservices architecture" }], + }, + }), +}); + +const reader = streamResp.body!.getReader(); +const decoder = new TextDecoder(); +while (true) { + const { done, value } = await reader.read(); + if (done) break; + const chunk = decoder.decode(value); + for (const line of chunk.split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + if (event.params.chunk) { + process.stdout.write(event.params.chunk.content); + } + if (event.params.task.state === "completed") { + console.log("\nโœ… Stream completed"); + } + } + } +} +``` + +### Python โ€” LangChain A2A Integration + +```python +""" +LangChain integration โ€” Use OmniRoute A2A as a custom LLM. +""" +from langchain.llms.base import BaseLLM +from langchain.schema import LLMResult, Generation +import requests +from typing import List, Optional + +class OmniRouteA2A(BaseLLM): + base_url: str = "http://localhost:20128" + api_key: str = "" + model: str = "auto" + combo: Optional[str] = None + + @property + def _llm_type(self) -> str: + return "omniroute-a2a" + + def _call(self, prompt: str, stop: Optional[List[str]] = None, **kwargs) -> str: + response = requests.post( + f"{self.base_url}/a2a", + headers={ + "Content-Type": "application/json", + "Authorization": f"Bearer {self.api_key}", + }, + json={ + "jsonrpc": "2.0", + "id": "langchain-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": prompt}], + "metadata": { + "model": self.model, + **({"combo": self.combo} if self.combo else {}), + }, + }, + }, + ) + result = response.json()["result"] + return result["artifacts"][0]["content"] + + def _generate(self, prompts: List[str], stop=None, **kwargs) -> LLMResult: + return LLMResult( + generations=[[Generation(text=self._call(p, stop))] for p in prompts] + ) + +# Usage +llm = OmniRouteA2A( + base_url="http://localhost:20128", + api_key="your-key", + model="auto", + combo="fast-coding", +) +result = llm("Write a Python function to merge two sorted lists") +print(result) +``` + +### Go โ€” A2A Client + +```go +package main + +import ( + "bytes" + "encoding/json" + "fmt" + "io" + "net/http" +) + +const baseURL = "http://localhost:20128" +const apiKey = "your-api-key" + +type JsonRpcRequest struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Method string `json:"method"` + Params interface{} `json:"params"` +} + +type JsonRpcResponse struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Result interface{} `json:"result"` + Error *struct { + Code int `json:"code"` + Message string `json:"message"` + } `json:"error"` +} + +func a2aCall(method string, params interface{}) (*JsonRpcResponse, error) { + body, _ := json.Marshal(JsonRpcRequest{ + Jsonrpc: "2.0", + ID: "go-1", + Method: method, + Params: params, + }) + + req, _ := http.NewRequest("POST", baseURL+"/a2a", bytes.NewReader(body)) + req.Header.Set("Content-Type", "application/json") + req.Header.Set("Authorization", "Bearer "+apiKey) + + resp, err := http.DefaultClient.Do(req) + if err != nil { + return nil, err + } + defer resp.Body.Close() + data, _ := io.ReadAll(resp.Body) + + var result JsonRpcResponse + json.Unmarshal(data, &result) + return &result, nil +} + +func main() { + // Discover agent + resp, _ := http.Get(baseURL + "/.well-known/agent.json") + defer resp.Body.Close() + body, _ := io.ReadAll(resp.Body) + fmt.Println("Agent Card:", string(body)) + + // Send smart-routing task + result, _ := a2aCall("message/send", map[string]interface{}{ + "skill": "smart-routing", + "messages": []map[string]string{{"role": "user", "content": "Hello from Go!"}}, + "metadata": map[string]interface{}{"model": "auto"}, + }) + out, _ := json.MarshalIndent(result.Result, "", " ") + fmt.Println("Result:", string(out)) +} +``` + +--- + +## Use Cases + +### ๐Ÿค– Use Case 1: Multi-Agent Coding Pipeline + +An orchestrator agent delegates code generation to OmniRoute, then passes the output to a review agent. + +```python +def coding_pipeline(task: str): + # Step 1: Generate code via OmniRoute A2A + code_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Write production-quality code: {task}"} + ], metadata={"model": "auto", "role": "coding"}) + code = code_result["artifacts"][0]["content"] + + # Step 2: Review the code via OmniRoute A2A (different model) + review_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Review this code for bugs and improvements:\n\n{code}"} + ], metadata={"model": "auto", "role": "review"}) + review = review_result["artifacts"][0]["content"] + + # Step 3: Check costs + print(f"Code cost: ${code_result['metadata']['cost_envelope']['actual']}") + print(f"Review cost: ${review_result['metadata']['cost_envelope']['actual']}") + + return {"code": code, "review": review} +``` + +### ๐Ÿ’ก Use Case 2: Quota-Aware Agent Swarm + +Multiple agents share quota through OmniRoute, using the quota skill to coordinate. + +```python +async def quota_aware_agent(agent_name: str, task: str): + # Check quota before starting + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Which provider has the most quota remaining?"} + ]) + print(f"[{agent_name}] {quota['artifacts'][0]['content']}") + + # Send request with budget constraint + result = a2a_send("smart-routing", [ + {"role": "user", "content": task} + ], metadata={"budget": 0.05}) + + policy = result["metadata"]["policy_verdict"] + if not policy["allowed"]: + print(f"[{agent_name}] โš ๏ธ Budget exceeded: {policy['reason']}") + # Fall back to free combo + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Suggest free combos"} + ]) + print(f"[{agent_name}] Free alternatives: {quota['artifacts'][0]['content']}") + + return result +``` + +### ๐Ÿ“Š Use Case 3: Real-Time Streaming Dashboard + +A monitoring agent streams responses and displays progress in real-time. + +```typescript +async function streamingDashboard(prompt: string) { + const response = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { "Content-Type": "application/json", Authorization: `Bearer ${API_KEY}` }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "dash-1", + method: "message/stream", + params: { skill: "smart-routing", messages: [{ role: "user", content: prompt }] }, + }), + }); + + let totalChunks = 0; + const reader = response.body!.getReader(); + const decoder = new TextDecoder(); + + while (true) { + const { done, value } = await reader.read(); + if (done) break; + + for (const line of decoder.decode(value).split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + const state = event.params.task.state; + + if (state === "working" && event.params.chunk) { + totalChunks++; + process.stdout.write( + `\r[Chunk ${totalChunks}] ${event.params.chunk.content.slice(0, 50)}...` + ); + } + if (state === "completed") { + const meta = event.params.metadata; + console.log( + `\nโœ… Done | Cost: $${meta?.cost_envelope?.actual || 0} | Route: ${meta?.routing_explanation || "N/A"}` + ); + } + if (state === "failed") { + console.error(`\nโŒ Failed: ${event.params.metadata?.error}`); + } + } + } + } +} +``` + +### ๐Ÿ” Use Case 4: Task Polling Pattern + +For long-running tasks, poll the task status instead of waiting synchronously. + +```python +import time + +def poll_task(task_id: str, timeout: int = 60): + """Poll task status until completion or timeout.""" + start = time.time() + while time.time() - start < timeout: + result = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "poll-1", + "method": "tasks/get", + "params": {"taskId": task_id}, + }).json() + + task = result["result"]["task"] + state = task["state"] + print(f" Task {task_id[:8]}... state={state}") + + if state in ("completed", "failed", "cancelled"): + return task + time.sleep(2) + + # Timeout โ€” cancel the task + requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "cancel-1", + "method": "tasks/cancel", + "params": {"taskId": task_id}, + }) + raise TimeoutError(f"Task {task_id} timed out after {timeout}s") +``` + +--- + +## Error Codes + +| Code | Constant | Meaning | +| ------ | ------------------------ | ---------------------------------------- | +| -32700 | โ€” | Parse error (invalid JSON) | +| -32600 | `INVALID_REQUEST` | Invalid JSON-RPC request or unauthorized | +| -32601 | `METHOD_NOT_FOUND` | Unknown method or skill | +| -32602 | `INVALID_PARAMS` | Missing or invalid parameters | +| -32603 | `INTERNAL_ERROR` | Skill execution failed | +| -32001 | `TASK_NOT_FOUND` | Task ID not found | +| -32002 | `TASK_ALREADY_COMPLETED` | Cannot modify a completed task | +| -32003 | `UNAUTHORIZED` | Invalid or missing API key | +| -32004 | `BUDGET_EXCEEDED` | Request exceeds configured budget | +| -32005 | `PROVIDER_UNAVAILABLE` | No available providers | + +--- + +## Authentication + +All `/a2a` requests require a Bearer token via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server (`OMNIROUTE_API_KEY` is empty), authentication is bypassed. + +--- + +## File Structure + +``` +src/lib/a2a/ +โ”œโ”€โ”€ taskManager.ts # Task lifecycle (create/update/cancel/list), TTL, cleanup +โ”œโ”€โ”€ taskExecution.ts # Generic task executor with state management +โ”œโ”€โ”€ streaming.ts # SSE stream formatting, heartbeat, chunk/completion events +โ”œโ”€โ”€ routingLogger.ts # Routing decision logger (stats, history, retention) +โ””โ”€โ”€ skills/ + โ”œโ”€โ”€ smartRouting.ts # Smart routing skill (routes via /v1/chat/completions) + โ””โ”€โ”€ quotaManagement.ts # Quota management skill (natural-language quota queries) + +src/app/a2a/ +โ””โ”€โ”€ route.ts # Next.js API route handler (JSON-RPC 2.0 dispatch) + +open-sse/mcp-server/ +โ””โ”€โ”€ schemas/a2a.ts # Zod schemas (AgentCard, Task, JSON-RPC, SSE events) +``` + +--- + +## Comparison: MCP vs A2A + +| Feature | MCP Server | A2A Server | +| ----------------- | ---------------------------- | ------------------------------------------------- | +| **Protocol** | Model Context Protocol | Agent-to-Agent Protocol v0.3 | +| **Transport** | stdio / HTTP | HTTP (JSON-RPC 2.0) | +| **Discovery** | Tool listing via MCP | `/.well-known/agent.json` | +| **Granularity** | 16 individual tools | 2 high-level skills | +| **Best for** | IDE agents (Cursor, VS Code) | Multi-agent systems (LangChain, CrewAI) | +| **Streaming** | Not supported | SSE via `message/stream` | +| **Task tracking** | No | Full lifecycle (submitted โ†’ completed) | +| **Observability** | Audit log per tool call | Cost envelope + resilience trace + policy verdict | + +--- + +## เคฒเคพเค‡เคธเฅ‡เค‚เคธ + +Part of [OmniRoute](https://github.com/diegosouzapw/OmniRoute) โ€” MIT License. diff --git a/docs/i18n/it/A2A-SERVER.md b/docs/i18n/it/A2A-SERVER.md deleted file mode 100644 index 01531ff482..0000000000 --- a/docs/i18n/it/A2A-SERVER.md +++ /dev/null @@ -1,200 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/A2A-SERVER.md) - ---- - -# OmniRoute A2A Server Documentation - -> Agent-to-Agent Protocol v0.3 โ€” OmniRoute as an intelligent routing agent - -## Agent Discovery - -```bash -curl http://localhost:20128/.well-known/agent.json -``` - -Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements. - ---- - -## Authentication - -All `/a2a` requests require an API key via the `Authorization` header: - -``` -Authorization: Bearer YOUR_OMNIROUTE_API_KEY -``` - -If no API key is configured on the server, authentication is bypassed. - ---- - -## JSON-RPC 2.0 Methods - -### `message/send` โ€” Synchronous Execution - -Sends a message to a skill and waits for the complete response. - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{ - "jsonrpc": "2.0", - "id": "1", - "method": "message/send", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Write a hello world in Python"}], - "metadata": {"model": "auto", "combo": "fast-coding"} - } - }' -``` - -**Response:** - -```json -{ - "jsonrpc": "2.0", - "id": "1", - "result": { - "task": { "id": "uuid", "state": "completed" }, - "artifacts": [{ "type": "text", "content": "..." }], - "metadata": { - "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)", - "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, - "resilience_trace": [ - { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." } - ], - "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } - } - } -} -``` - -### `message/stream` โ€” SSE Streaming - -Same as `message/send` but returns Server-Sent Events for real-time streaming. - -```bash -curl -N -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{ - "jsonrpc": "2.0", - "id": "1", - "method": "message/stream", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Explain quantum computing"}] - } - }' -``` - -**SSE Events:** - -``` -data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}} - -: heartbeat 2026-03-03T17:00:00Z - -data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} -``` - -### `tasks/get` โ€” Query Task Status - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' -``` - -### `tasks/cancel` โ€” Cancel a Task - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' -``` - ---- - -## Available Skills - -| Skill | Description | -| :----------------- | :------------------------------------------------------------------------------------------------------------------------------ | -| `smart-routing` | Routes prompts through OmniRoute's intelligent pipeline. Returns response with routing explanation, cost, and resilience trace. | -| `quota-management` | Answers natural-language queries about provider quotas, suggests free combos, and provides quota rankings. | - ---- - -## Task Lifecycle - -``` -submitted โ†’ working โ†’ completed - โ†’ failed - โ†’ cancelled -``` - -- Tasks expire after 5 minutes (configurable) -- Terminal states: `completed`, `failed`, `cancelled` -- Event log tracks every state transition - ---- - -## Error Codes - -| Code | Meaning | -| :----- | :----------------------------- | -| -32700 | Parse error (invalid JSON) | -| -32600 | Invalid request / Unauthorized | -| -32601 | Method or skill not found | -| -32602 | Invalid params | -| -32603 | Internal error | - ---- - -## Integration Examples - -### Python (requests) - -```python -import requests - -resp = requests.post("http://localhost:20128/a2a", json={ - "jsonrpc": "2.0", "id": "1", - "method": "message/send", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Hello"}] - } -}, headers={"Authorization": "Bearer YOUR_KEY"}) - -result = resp.json()["result"] -print(result["artifacts"][0]["content"]) -print(result["metadata"]["routing_explanation"]) -``` - -### TypeScript (fetch) - -```typescript -const resp = await fetch("http://localhost:20128/a2a", { - method: "POST", - headers: { - "Content-Type": "application/json", - Authorization: "Bearer YOUR_KEY", - }, - body: JSON.stringify({ - jsonrpc: "2.0", - id: "1", - method: "message/send", - params: { - skill: "smart-routing", - messages: [{ role: "user", content: "Hello" }], - }, - }), -}); -const { result } = await resp.json(); -console.log(result.metadata.routing_explanation); -``` diff --git a/docs/i18n/it/API_REFERENCE.md b/docs/i18n/it/API_REFERENCE.md deleted file mode 100644 index b878605221..0000000000 --- a/docs/i18n/it/API_REFERENCE.md +++ /dev/null @@ -1,455 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/API_REFERENCE.md) - ---- - -# API Reference - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/API_REFERENCE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/API_REFERENCE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/API_REFERENCE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/API_REFERENCE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/API_REFERENCE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/API_REFERENCE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/API_REFERENCE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/API_REFERENCE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/API_REFERENCE.md) - -Complete reference for all OmniRoute API endpoints. - ---- - -## Table of Contents - -- [Chat Completions](#chat-completions) -- [Embeddings](#embeddings) -- [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`. - -### ACP Agents - -| Endpoint | Method | Description | -| ----------------- | ------ | -------------------------------------------------------- | -| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | -| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | -| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | - -GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). - -### Resilience & Rate Limits - -| Endpoint | Method | Description | -| ----------------------- | ------- | ------------------------------- | -| `/api/resilience` | 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` diff --git a/docs/i18n/it/ARCHITECTURE.md b/docs/i18n/it/ARCHITECTURE.md deleted file mode 100644 index 4ea06a29f2..0000000000 --- a/docs/i18n/it/ARCHITECTURE.md +++ /dev/null @@ -1,787 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/ARCHITECTURE.md) - ---- - -# OmniRoute Architecture - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/ARCHITECTURE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/ARCHITECTURE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/ARCHITECTURE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/ARCHITECTURE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/ARCHITECTURE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/ARCHITECTURE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/ARCHITECTURE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/ARCHITECTURE.md) - -_Last updated: 2026-03-04_ - -## 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 (`...`) for reasoning models -- Response sanitization for strict OpenAI SDK compatibility -- Role normalization (developerโ†’system, systemโ†’user) for cross-provider compatibility -- Structured output conversion (json_schema โ†’ Gemini responseSchema) -- Local persistence for providers, keys, aliases, combos, settings, pricing -- Usage/cost tracking and request logging -- Optional cloud sync for multi-device/state sync -- IP allowlist/blocklist for API access control -- Thinking budget management (passthrough/auto/custom/adaptive) -- Global system prompt injection -- Session tracking and fingerprinting -- Per-account enhanced rate limiting with provider-specific profiles -- Circuit breaker pattern for provider resilience -- Anti-thundering herd protection with mutex locking -- Signature-based request deduplication cache -- Domain layer: model availability, cost rules, fallback policy, lockout policy -- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) -- Policy engine for centralized request evaluation (lockout โ†’ budget โ†’ fallback) -- Request telemetry with p50/p95/p99 latency aggregation -- Correlation ID (X-Request-Id) for end-to-end tracing -- Compliance audit logging with opt-out per API key -- Eval framework for LLM quality assurance -- Resilience UI dashboard with real-time circuit breaker status -- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) - -Primary runtime model: - -- Next.js 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[(storage.sqlite)] - UDB[(usage tables + log artifacts)] - end - - subgraph Upstreams[Upstream Providers] - P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/Qoder/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/route.ts` (GET) -- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) -- OAuth: `src/app/api/oauth/*` -- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` -- Usage: `src/app/api/usage/*` -- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` -- CLI tooling helpers: `src/app/api/cli-tools/*` -- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) -- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) -- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) -- Sessions: `src/app/api/sessions` (GET) -- Rate limits: `src/app/api/rate-limits` (GET) -- Resilience: `src/app/api/resilience` (GET/PATCH) โ€” provider profiles, circuit breaker, rate limit state -- Resilience reset: `src/app/api/resilience/reset` (POST) โ€” reset breakers + cooldowns -- Cache stats: `src/app/api/cache/stats` (GET/DELETE) -- Model availability: `src/app/api/models/availability` (GET/POST) -- Telemetry: `src/app/api/telemetry/summary` (GET) -- Budget: `src/app/api/usage/budget` (GET/POST) -- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) -- Compliance audit: `src/app/api/compliance/audit-log` (GET) -- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) -- Policies: `src/app/api/policies` (GET/POST) - -## 2) SSE + 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` -- Response sanitization: `open-sse/handlers/responseSanitizer.ts` -- Role normalization: `open-sse/services/roleNormalizer.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`, `qoder.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 (SQLite): - -- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) -- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) -- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) -- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** - -Usage persistence: - -- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) -- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` -- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) -- legacy JSON files are migrated to SQLite by startup migrations when present - -Domain State DB (SQLite): - -- `src/lib/db/domainState.ts` โ€” CRUD operations 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: - -- primary runtime DB: `${DATA_DIR}/storage.sqlite` -- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) -- structured call payload archives: `${DATA_DIR}/call_logs/` -- optional translator/request debug sessions: `/logs/...` - -## Deployment Topology - -```mermaid -flowchart LR - 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[(storage.sqlite)] - UsageDB[(usage tables + log artifacts)] - end - - subgraph External[External Services] - Providers[AI Providers] - SyncCloud[Cloud Sync Service] - end - - CLI --> Next - Browser --> Next - Next --> Core - Next --> MainDB - Core --> MainDB - Core --> UsageDB - Core --> Providers - Next --> SyncCloud -``` - -## Module Mapping (Decision-Critical) - -### Route and API Modules - -- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs -- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) -- `src/app/api/providers*`: provider CRUD, validation, testing -- `src/app/api/provider-nodes*`: custom compatible node management -- `src/app/api/provider-models`: custom model management (CRUD) -- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) -- `src/app/api/oauth/*`: OAuth/device-code flows -- `src/app/api/keys*`: local API key lifecycle -- `src/app/api/models/alias`: alias management -- `src/app/api/combos*`: fallback combo management -- `src/app/api/pricing`: pricing overrides for cost calculation -- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) -- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) -- `src/app/api/usage/*`: usage and logs APIs -- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers -- `src/app/api/cli-tools/*`: local CLI config writers/checkers -- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) -- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) -- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) -- `src/app/api/sessions`: active session listing (GET) -- `src/app/api/rate-limits`: per-account rate limit status (GET) - -### Routing and Execution Core - -- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop -- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup -- `open-sse/executors/*`: provider-specific network and format behavior - -### Translation Registry and Format Converters - -- `open-sse/translator/index.ts`: translator registry and orchestration -- Request translators: `open-sse/translator/request/*` -- Response translators: `open-sse/translator/response/*` -- Format constants: `open-sse/translator/formats.ts` - -### Persistence - -- `src/lib/db/*`: persistent config/state and domain persistence on SQLite -- `src/lib/localDb.ts`: compatibility re-export for DB modules -- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables - -## Provider Executor Coverage (Strategy Pattern) - -Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. - -| Executor | Provider(s) | Special Handling | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | -| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, Qoder, 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 | -| Qoder | openai | OAuth (Basic) | โœ… | โœ… | โœ… | โš ๏ธ Per request | -| OpenRouter | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| GLM/Kimi/MiniMax | claude | API Key | โœ… | โœ… | โŒ | โŒ | -| DeepSeek | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Groq | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| xAI (Grok) | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Mistral | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Perplexity | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Together AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Fireworks AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Cerebras | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Cohere | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| NVIDIA NIM | openai | API Key | โœ… | โœ… | โŒ | โŒ | - -## Format Translation Coverage - -Detected source formats include: - -- `openai` -- `openai-responses` -- `claude` -- `gemini` - -Target formats include: - -- OpenAI chat/Responses -- Claude -- Gemini/Gemini-CLI/Antigravity envelope -- Kiro -- Cursor - -Translations use **OpenAI as the hub format** โ€” all conversions go through OpenAI as intermediate: - -``` -Source Format โ†’ OpenAI (hub) โ†’ Target Format -``` - -Translations are selected dynamically based on source payload shape and provider target format. - -Additional processing layers in the translation pipeline: - -- **Response sanitization** โ€” Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance -- **Role normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI targets; merges `system` โ†’ `user` for models that reject the system role (GLM, ERNIE) -- **Think tag extraction** โ€” Parses `...` blocks from content into `reasoning_content` field -- **Structured output** โ€” Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` - -## Supported API Endpoints - -| 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 `/logs//` 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 - -- SQLite schema migrations and auto-upgrade hooks at startup -- legacy JSON โ†’ SQLite migration compatibility path - -## Observability and Operational Signals - -Runtime visibility sources: - -- console logs from `src/sse/utils/logger.ts` -- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) -- textual request status log in `log.txt` (optional/compat) -- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` -- dashboard usage endpoints (`/api/usage/*`) for UI consumption - -## Security-Sensitive Boundaries - -- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing -- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning -- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format -- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level -- Cloud sync endpoints rely on API key auth + machine id semantics - -## Environment and Runtime Matrix - -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` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. -2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. -3. Request logger writes full headers/body when enabled; treat log directory as sensitive. -4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. -5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. -6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). -7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). -8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). - -## Operational Verification Checklist - -- Build from source: `npm run build` -- Build Docker image: `docker build -t omniroute .` -- Start service and verify: -- `GET /api/settings` -- `GET /api/v1/models` -- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/it/AUTO-COMBO.md b/docs/i18n/it/AUTO-COMBO.md deleted file mode 100644 index 2166e41dff..0000000000 --- a/docs/i18n/it/AUTO-COMBO.md +++ /dev/null @@ -1,67 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/AUTO-COMBO.md) - ---- - -# OmniRoute Auto-Combo Engine - -> Self-managing model chains with adaptive scoring - -## How It Works - -The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**: - -| Factor | Weight | Description | -| :--------- | :----- | :---------------------------------------------- | -| Quota | 0.20 | Remaining capacity [0..1] | -| Health | 0.25 | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 | -| CostInv | 0.20 | Inverse cost (cheaper = higher score) | -| LatencyInv | 0.15 | Inverse p95 latency (faster = higher) | -| TaskFit | 0.10 | Model ร— task type fitness score | -| Stability | 0.10 | Low variance in latency/errors | - -## Mode Packs - -| Pack | Focus | Key Weight | -| :---------------------- | :----------- | :--------------- | -| ๐Ÿš€ **Ship Fast** | Speed | latencyInv: 0.35 | -| ๐Ÿ’ฐ **Cost Saver** | Economy | costInv: 0.40 | -| ๐ŸŽฏ **Quality First** | Best model | taskFit: 0.40 | -| ๐Ÿ“ก **Offline Friendly** | Availability | quota: 0.40 | - -## Self-Healing - -- **Temporary exclusion**: Score < 0.2 โ†’ excluded for 5 min (progressive backoff, max 30 min) -- **Circuit breaker awareness**: OPEN โ†’ auto-excluded; HALF_OPEN โ†’ probe requests -- **Incident mode**: >50% OPEN โ†’ disable exploration, maximize stability -- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout - -## Bandit Exploration - -5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode. - -## API - -```bash -# Create auto-combo -curl -X POST http://localhost:20128/api/combos/auto \ - -H "Content-Type: application/json" \ - -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}' - -# List auto-combos -curl http://localhost:20128/api/combos/auto -``` - -## Task Fitness - -30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` โ†’ high coding score). - -## Files - -| File | Purpose | -| :------------------------------------------- | :------------------------------------ | -| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization | -| `open-sse/services/autoCombo/taskFitness.ts` | Model ร— task fitness lookup | -| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap | -| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode | -| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles | -| `src/app/api/combos/auto/route.ts` | REST API | diff --git a/docs/i18n/it/CHANGELOG.md b/docs/i18n/it/CHANGELOG.md index bbe64fcbb5..f167a83689 100644 --- a/docs/i18n/it/CHANGELOG.md +++ b/docs/i18n/it/CHANGELOG.md @@ -1,12 +1,92 @@ # Changelog (Italiano) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CHANGELOG.md) --- - ## [Unreleased] +### ๐Ÿ› ๏ธ Maintenance + +- **AGENTS.md rewrite:** Condensed from 297โ†’153 lines. Added build/lint/test commands (including single-test execution), code style guidelines (Prettier, TypeScript, ESLint, naming, imports, error handling, security), and trimmed verbose architecture tables for AI agent consumption. + +## [3.4.2] - 2026-04-01 + +### ๐Ÿ› Bug Fixes + +- **CI Stabilization:** Fixed failing analytics/settings Playwright selectors and request assertions so GitHub Actions E2E runs pass reliably across localized UIs and switch-based controls. +- **Deterministic Tests:** Removed date-sensitive quota fixtures from Copilot usage tests and aligned idempotency/model catalog tests with the merged runtime behavior. +- **MCP Type Hardening:** Removed zero-budget explicit `any` regressions from the MCP server tool registration path, restoring the `check:any-budget:t11` workflow gate. + +### ๐Ÿ› ๏ธ Maintenance + +- **Release Branch Integration:** Consolidated the active feature branches into `release/v3.4.2` on top of current `main` and validated the branch with lint, unit, coverage, build, and CI-mode E2E runs. + +## [3.4.1] - 2026-03-31 + +> [!WARNING] +> **BREAKING CHANGE: request logging, retention, and logging environment variables have been redesigned.** +> On the first startup after upgrading, OmniRoute archives legacy request logs from `DATA_DIR/logs/`, legacy `DATA_DIR/call_logs/`, and `DATA_DIR/log.txt` into `DATA_DIR/log_archives/*.zip`, then removes the deprecated layout and switches to the new unified artifact format under `DATA_DIR/call_logs/`. + +### โœจ New Features + +- **.ENV Migration Utility:** Included `scripts/migrate-env.mjs` to seamlessly migrate ` Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` - ---- - -## Step 2 โ€” Install CLI Tools - -All npm-based tools require Node.js 18+: - -```bash -# Claude Code (Anthropic) -npm install -g @anthropic-ai/claude-code - -# OpenAI Codex -npm install -g @openai/codex - -# Gemini CLI (Google) -npm install -g @google/gemini-cli - -# OpenCode -npm install -g opencode-ai - -# Cline -npm install -g cline - -# KiloCode -npm install -g kilecode - -# Kiro CLI (Amazon โ€” requires curl + unzip) -apt-get install -y unzip # on Debian/Ubuntu -curl -fsSL https://cli.kiro.dev/install | bash -export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc -``` - -**Verify:** - -```bash -claude --version # 2.x.x -codex --version # 0.x.x -gemini --version # 0.x.x -opencode --version # x.x.x -cline --version # 2.x.x -kilocode --version # x.x.x (or: kilo --version) -kiro-cli --version # 1.x.x -``` - ---- - -## Step 3 โ€” Set Global Environment Variables - -Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`: - -```bash -# OmniRoute Universal Endpoint -export OPENAI_BASE_URL="http://localhost:20128/v1" -export OPENAI_API_KEY="sk-your-omniroute-key" -export ANTHROPIC_BASE_URL="http://localhost:20128/v1" -export ANTHROPIC_API_KEY="sk-your-omniroute-key" -export GEMINI_BASE_URL="http://localhost:20128/v1" -export GEMINI_API_KEY="sk-your-omniroute-key" -``` - -> For a **remote server** replace `localhost:20128` with the server IP or domain, -> e.g. `http://192.168.0.15:20128`. - ---- - -## Step 4 โ€” Configure Each Tool - -### Claude Code - -```bash -# Via CLI: -claude config set --global api-base-url http://localhost:20128/v1 - -# Or create ~/.claude/settings.json: -mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF -{ - "apiBaseUrl": "http://localhost:20128/v1", - "apiKey": "sk-your-omniroute-key" -} -EOF -``` - -**Test:** `claude "say hello"` - ---- - -### OpenAI Codex - -```bash -mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF -model: auto -apiKey: sk-your-omniroute-key -apiBaseUrl: http://localhost:20128/v1 -EOF -``` - -**Test:** `codex "what is 2+2?"` - ---- - -### Gemini CLI - -```bash -mkdir -p ~/.gemini && cat > ~/.gemini/settings.json << EOF -{ - "apiKey": "sk-your-omniroute-key", - "baseUrl": "http://localhost:20128/v1" -} -EOF -``` - -**Test:** `gemini "hello"` - ---- - -### OpenCode - -```bash -mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF -[provider.openai] -base_url = "http://localhost:20128/v1" -api_key = "sk-your-omniroute-key" -EOF -``` - -**Test:** `opencode` - ---- - -### Cline (CLI or VS Code) - -**CLI mode:** - -```bash -mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF -{ - "apiProvider": "openai", - "openAiBaseUrl": "http://localhost:20128/v1", - "openAiApiKey": "sk-your-omniroute-key" -} -EOF -``` - -**VS Code mode:** -Cline extension settings โ†’ API Provider: `OpenAI Compatible` โ†’ Base URL: `http://localhost:20128/v1` - -Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ Cline โ†’ Apply Config**. - ---- - -### KiloCode (CLI or VS Code) - -**CLI mode:** - -```bash -kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key -``` - -**VS Code settings:** - -```json -{ - "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", - "kilo-code.apiKey": "sk-your-omniroute-key" -} -``` - -Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ KiloCode โ†’ Apply Config**. - ---- - -### Continue (VS Code Extension) - -Edit `~/.continue/config.yaml`: - -```yaml -models: - - name: OmniRoute - provider: openai - model: auto - apiBase: http://localhost:20128/v1 - apiKey: sk-your-omniroute-key - default: true -``` - -Restart VS Code after editing. - ---- - -### Kiro CLI (Amazon) - -```bash -# Login to your AWS/Kiro account: -kiro-cli login - -# The CLI uses its own auth โ€” OmniRoute is not needed as backend for Kiro CLI itself. -# Use kiro-cli alongside OmniRoute for other tools. -kiro-cli status -``` - ---- - -### Cursor (Desktop App) - -> **Note:** Cursor routes requests through its cloud. For OmniRoute integration, -> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL. - -Via GUI: **Settings โ†’ Models โ†’ OpenAI API Key** - -- Base URL: `https://your-domain.com/v1` -- API Key: your OmniRoute key - ---- - -## Dashboard Auto-Configuration - -The OmniRoute dashboard automates configuration for most tools: - -1. Go to `http://localhost:20128/dashboard/cli-tools` -2. Expand any tool card -3. Select your API key from the dropdown -4. Click **Apply Config** (if tool is detected as installed) -5. Or copy the generated config snippet manually - ---- - -## Built-in Agents: Droid & OpenClaw - -**Droid** and **OpenClaw** are AI agents built directly into OmniRoute โ€” no installation needed. -They run as internal routes and use OmniRoute's model routing automatically. - -- Access: `http://localhost:20128/dashboard/agents` -- Configure: same combos and providers as all other tools -- No API key or CLI install required - ---- - -## Available API Endpoints - -| Endpoint | Description | Use For | -| -------------------------- | ----------------------------- | --------------------------- | -| `/v1/chat/completions` | Standard chat (all providers) | All modern tools | -| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows | -| `/v1/completions` | Legacy text completions | Older tools using `prompt:` | -| `/v1/embeddings` | Text embeddings | RAG, search | -| `/v1/images/generations` | Image generation | DALL-E, Flux, etc. | -| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS | -| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI | - ---- - -## Troubleshooting - -| Error | Cause | Fix | -| ------------------------- | ----------------------- | ------------------------------------------ | -| `Connection refused` | OmniRoute not running | `pm2 start omniroute` | -| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` | -| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` | -| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` | -| CLI shows "not installed" | Binary not in PATH | Check `which ` | -| `kiro-cli: not found` | Not in PATH | `export PATH="$HOME/.local/bin:$PATH"` | - ---- - -## Quick Setup Script (One Command) - -```bash -# Install all CLIs and configure for OmniRoute (replace with your key and server URL) -OMNIROUTE_URL="http://localhost:20128/v1" -OMNIROUTE_KEY="sk-your-omniroute-key" - -npm install -g @anthropic-ai/claude-code @openai/codex @google/gemini-cli opencode-ai cline kilecode - -# Kiro CLI -apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash - -# Write configs -mkdir -p ~/.claude ~/.codex ~/.gemini ~/.config/opencode ~/.continue - -cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" -cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" -cat > ~/.gemini/settings.json <<< "{\"apiKey\":\"$OMNIROUTE_KEY\",\"baseUrl\":\"$OMNIROUTE_URL\"}" -cat >> ~/.bashrc << EOF -export OPENAI_BASE_URL="$OMNIROUTE_URL" -export OPENAI_API_KEY="$OMNIROUTE_KEY" -export ANTHROPIC_BASE_URL="$OMNIROUTE_URL" -export ANTHROPIC_API_KEY="$OMNIROUTE_KEY" -EOF - -source ~/.bashrc -echo "โœ… All CLIs installed and configured for OmniRoute" -``` diff --git a/docs/i18n/it/CODEBASE_DOCUMENTATION.md b/docs/i18n/it/CODEBASE_DOCUMENTATION.md deleted file mode 100644 index e2d7950052..0000000000 --- a/docs/i18n/it/CODEBASE_DOCUMENTATION.md +++ /dev/null @@ -1,593 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CODEBASE_DOCUMENTATION.md) - ---- - -# omniroute โ€” Codebase Documentation - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) - -> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. - ---- - -## 1. 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
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, Qoder, 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 | -| Qoder | 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"] -``` diff --git a/docs/i18n/it/CONTRIBUTING.md b/docs/i18n/it/CONTRIBUTING.md new file mode 100644 index 0000000000..a0c326c9f7 --- /dev/null +++ b/docs/i18n/it/CONTRIBUTING.md @@ -0,0 +1,299 @@ +# Contributing to OmniRoute (Italiano) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CONTRIBUTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CONTRIBUTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CONTRIBUTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CONTRIBUTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CONTRIBUTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CONTRIBUTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CONTRIBUTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CONTRIBUTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CONTRIBUTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CONTRIBUTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CONTRIBUTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CONTRIBUTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CONTRIBUTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CONTRIBUTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CONTRIBUTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CONTRIBUTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CONTRIBUTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CONTRIBUTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CONTRIBUTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CONTRIBUTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CONTRIBUTING.md) + +--- + +Thank you for your interest in contributing! This guide covers everything you need to get started. + +--- + +## Development Setup + +### Prerequisites + +- **Node.js** >= 18 < 24 (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` | `20128` | Server port | +| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | Base URL for frontend | +| `JWT_SECRET` | (generate above) | JWT signing secret | +| `INITIAL_PASSWORD` | `CHANGEME` | First login password | +| `APP_LOG_LEVEL` | `info` | Log verbosity level | + +### Dashboard Settings + +The dashboard provides UI toggles for features that can also be configured via environment variables: + +| Setting Location | Toggle | Description | +| ------------------- | ------------------ | ------------------------------ | +| Settings โ†’ Advanced | Debug Mode | Enable debug request logs (UI) | +| Settings โ†’ General | Sidebar Visibility | Show/hide sidebar sections | + +These settings are stored in the database and persist across restarts, overriding env var defaults when set. + +### 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:20128/dashboard` +- **API**: `http://localhost:20128/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`, `mcp`, `a2a`, `memory`, `skills`. + +--- + +## Running Tests + +```bash +# All tests (unit + vitest + ecosystem + e2e) +npm run test:all + +# Single test file (Node.js native test runner โ€” most tests use this) +node --import tsx/esm --test tests/unit/your-file.test.mjs + +# Vitest (MCP server, autoCombo, cache) +npm run test:vitest + +# E2E tests (requires Playwright) +npm run test:e2e + +# Protocol clients E2E (MCP transports, A2A) +npm run test:protocols:e2e + +# Ecosystem compatibility tests +npm run test:ecosystem + +# Coverage (55% min statements/lines/functions; 60% branches) +npm run test:coverage +npm run coverage:report + +# Lint + format check +npm run lint +npm run check +``` + +Coverage notes: + +- `npm run test:coverage` measures source coverage for the main unit test suite, excludes `tests/**`, and includes `open-sse/**` +- `npm run coverage:report` prints the detailed file-by-file report from the latest coverage run +- `npm run test:coverage:legacy` preserves the older metric for historical comparison +- See `docs/COVERAGE_PLAN.md` for the phased coverage improvement roadmap + +Current test status: **122 unit test files** covering: + +- Provider translators and format conversion +- Rate limiting, circuit breaker, and resilience +- Semantic cache, idempotency, progress tracking +- Database operations and schema (21 DB modules) +- OAuth flows and authentication +- API endpoint validation (Zod v4) +- MCP server tools and scope enforcement +- Memory and Skills systems + +--- + +## Code Style + +- **ESLint** โ€” Run `npm run lint` before committing +- **Prettier** โ€” Auto-formatted via `lint-staged` on commit (2 spaces, semicolons, double quotes, 100 char width, es5 trailing commas) +- **TypeScript** โ€” All `src/` code uses `.ts`/`.tsx`; `open-sse/` uses `.ts`/`.js`; document with TSDoc (`@param`, `@returns`, `@throws`) +- **No `eval()`** โ€” ESLint enforces `no-eval`, `no-implied-eval`, `no-new-func` +- **Zod validation** โ€” Use Zod v4 schemas for all API input validation +- **Naming**: Files = camelCase/kebab-case, components = PascalCase, constants = UPPER_SNAKE + +--- + +## Project Structure + +``` +src/ # TypeScript (.ts / .tsx) +โ”œโ”€โ”€ app/ # Next.js 16 App Router +โ”‚ โ”œโ”€โ”€ (dashboard)/ # Dashboard pages (23 sections) +โ”‚ โ”œโ”€โ”€ api/ # API routes (51 directories) +โ”‚ โ””โ”€โ”€ login/ # Auth pages (.tsx) +โ”œโ”€โ”€ domain/ # Policy engine (policyEngine, comboResolver, costRules, etc.) +โ”œโ”€โ”€ lib/ # Core business logic (.ts) +โ”‚ โ”œโ”€โ”€ a2a/ # Agent-to-Agent v0.3 protocol server +โ”‚ โ”œโ”€โ”€ acp/ # Agent Communication Protocol registry +โ”‚ โ”œโ”€โ”€ compliance/ # Compliance policy engine +โ”‚ โ”œโ”€โ”€ db/ # SQLite database layer (21 modules + 16 migrations) +โ”‚ โ”œโ”€โ”€ memory/ # Persistent conversational memory +โ”‚ โ”œโ”€โ”€ oauth/ # OAuth providers, services, and utilities +โ”‚ โ”œโ”€โ”€ skills/ # Extensible skill framework +โ”‚ โ”œโ”€โ”€ usage/ # Usage tracking and cost calculation +โ”‚ โ””โ”€โ”€ localDb.ts # Re-export layer only โ€” never add logic here +โ”œโ”€โ”€ middleware/ # Request middleware (promptInjectionGuard) +โ”œโ”€โ”€ mitm/ # MITM proxy (cert, DNS, target routing) +โ”œโ”€โ”€ shared/ +โ”‚ โ”œโ”€โ”€ components/ # React components (.tsx) +โ”‚ โ”œโ”€โ”€ constants/ # Provider definitions (60+), MCP scopes, routing strategies +โ”‚ โ”œโ”€โ”€ utils/ # Circuit breaker, sanitizer, auth helpers +โ”‚ โ””โ”€โ”€ validation/ # Zod v4 schemas +โ””โ”€โ”€ sse/ # SSE proxy pipeline + +open-sse/ # @omniroute/open-sse workspace +โ”œโ”€โ”€ executors/ # 14 provider-specific request executors +โ”œโ”€โ”€ handlers/ # 11 request handlers (chat, responses, embeddings, images, etc.) +โ”œโ”€โ”€ mcp-server/ # MCP server (25 tools, 3 transports, 10 scopes) +โ”œโ”€โ”€ services/ # 36+ services (combo, autoCombo, rateLimitManager, etc.) +โ”œโ”€โ”€ translator/ # Format translators (OpenAI โ†” Claude โ†” Gemini โ†” Responses โ†” Ollama) +โ”œโ”€โ”€ transformer/ # Responses API transformer +โ””โ”€โ”€ utils/ # 22 utility modules (stream, TLS, proxy, logging) + +electron/ # Electron desktop app (cross-platform) + +tests/ +โ”œโ”€โ”€ unit/ # Node.js test runner (122 test files) +โ”œโ”€โ”€ integration/ # Integration tests +โ”œโ”€โ”€ e2e/ # Playwright tests +โ”œโ”€โ”€ security/ # Security tests +โ”œโ”€โ”€ translator/ # Translator-specific tests +โ””โ”€โ”€ load/ # Load tests + +docs/ # Documentation +โ”œโ”€โ”€ ARCHITECTURE.md # System architecture +โ”œโ”€โ”€ API_REFERENCE.md # All endpoints +โ”œโ”€โ”€ USER_GUIDE.md # Provider setup, CLI integration +โ”œโ”€โ”€ TROUBLESHOOTING.md # Common issues +โ”œโ”€โ”€ MCP-SERVER.md # MCP server (25 tools) +โ”œโ”€โ”€ A2A-SERVER.md # A2A agent protocol +โ”œโ”€โ”€ AUTO-COMBO.md # Auto-combo engine +โ”œโ”€โ”€ CLI-TOOLS.md # CLI tools integration +โ”œโ”€โ”€ COVERAGE_PLAN.md # Test coverage improvement plan +โ”œโ”€โ”€ openapi.yaml # OpenAPI specification +โ””โ”€โ”€ adr/ # Architecture Decision Records +``` + +--- + +## Adding a New Provider + +### Step 1: Register Provider Constants + +Add to `src/shared/constants/providers.ts` โ€” Zod-validated at module load. + +### Step 2: Add Executor (if custom logic needed) + +Create executor in `open-sse/executors/your-provider.ts` extending the base executor. + +### Step 3: Add Translator (if non-OpenAI format) + +Create request/response translators in `open-sse/translator/`. + +### Step 4: Add OAuth Config (if OAuth-based) + +Add OAuth credentials in `src/lib/oauth/constants/oauth.ts` and service in `src/lib/oauth/services/`. + +### Step 5: Register Models + +Add model definitions in `open-sse/config/providerRegistry.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 +- [ ] All inputs validated with Zod schemas +- [ ] CHANGELOG updated (if user-facing change) +- [ ] Documentation updated (if applicable) + +--- + +## Releasing + +Releases are managed via the `/generate-release` workflow. When a new GitHub Release is created, the package is **automatically published to npm** via GitHub Actions. + +--- + +## Getting Help + +- **Architecture**: See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) +- **API Reference**: See [`docs/API_REFERENCE.md`](docs/API_REFERENCE.md) +- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **ADRs**: See `docs/adr/` for architectural decision records diff --git a/docs/i18n/it/FEATURES.md b/docs/i18n/it/FEATURES.md deleted file mode 100644 index d1b056ddc4..0000000000 --- a/docs/i18n/it/FEATURES.md +++ /dev/null @@ -1,147 +0,0 @@ -# OmniRoute โ€” Dashboard Features Gallery (Italiano) - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) - -> ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../docs/FEATURES.md) - ---- - -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 (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. - -![Providers Dashboard](screenshots/01-providers.png) - ---- - -## ๐ŸŽจ Combos - -Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. - -![Combos Dashboard](screenshots/02-combos.png) - ---- - -## ๐Ÿ“Š Analytics - -Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. - -![Analytics Dashboard](screenshots/03-analytics.png) - ---- - -## ๐Ÿฅ System Health - -Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. - -![Health Dashboard](screenshots/04-health.png) - ---- - -## ๐Ÿ”ง Translator Playground - -Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). - -![Translator Playground](screenshots/05-translator.png) - ---- - -## ๐ŸŽฎ Model Playground _(v2.0.9+)_ - -Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. - ---- - -## ๐ŸŽจ Themes _(v2.0.5+)_ - -Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. - ---- - -## โš™๏ธ Settings - -Comprehensive settings panel with tabs: - -- **General** โ€” System storage, backup management (export/import database) -- **Appearance** โ€” Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls -- **Security** โ€” API endpoint protection, custom provider blocking, IP filtering, session info -- **Routing** โ€” Model aliases, background task degradation -- **Resilience** โ€” Rate limit persistence, circuit breaker tuning -- **Advanced** โ€” Configuration overrides - -![Settings Dashboard](screenshots/06-settings.png) - ---- - -## ๐Ÿ”ง CLI Tools - -One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. - -![CLI Tools Dashboard](screenshots/07-cli-tools.png) - ---- - -## ๐Ÿค– CLI Agents _(v2.0.11+)_ - -Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: - -- **Installation status** โ€” Installed / Not Found with version detection -- **Protocol badges** โ€” stdio, HTTP, etc. -- **Custom agents** โ€” Register any CLI tool via form (name, binary, version command, spawn args) -- **CLI Fingerprint Matching** โ€” Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP - ---- - -## ๐Ÿ–ผ๏ธ Media _(v2.0.3+)_ - -Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. - ---- - -## ๐Ÿ“ Request Logs - -Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. - -![Usage Logs](screenshots/08-usage.png) - ---- - -## ๐ŸŒ API Endpoint - -Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. - -![Endpoint Dashboard](screenshots/09-endpoint.png) - ---- - -## ๐Ÿ”‘ API Key Management - -Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. - ---- - -## ๐Ÿ“‹ Audit Log - -Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. - ---- - -## ๐Ÿ–ฅ๏ธ Desktop Application - -Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. - -Key features: - -- Server readiness polling (no blank screen on cold start) -- System tray with port management -- Content Security Policy -- Single-instance lock -- Auto-update on restart -- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) -- Hardened Electron build packaging โ€” symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+) - -๐Ÿ“– See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/it/MCP-SERVER.md b/docs/i18n/it/MCP-SERVER.md deleted file mode 100644 index 829acd30b1..0000000000 --- a/docs/i18n/it/MCP-SERVER.md +++ /dev/null @@ -1,87 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/MCP-SERVER.md) - ---- - -# OmniRoute MCP Server Documentation - -> Model Context Protocol server with 16 intelligent tools - -## Installation - -OmniRoute MCP is built-in. Start it with: - -```bash -omniroute --mcp -``` - -Or via the open-sse transport: - -```bash -# HTTP streamable transport (port 20130) -omniroute --dev # MCP auto-starts on /mcp endpoint -``` - -## IDE Configuration - -See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup. - ---- - -## Essential Tools (8) - -| Tool | Description | -| :------------------------------ | :--------------------------------------- | -| `omniroute_get_health` | Gateway health, circuit breakers, uptime | -| `omniroute_list_combos` | All configured combos with models | -| `omniroute_get_combo_metrics` | Performance metrics for a specific combo | -| `omniroute_switch_combo` | Switch active combo by ID/name | -| `omniroute_check_quota` | Quota status per provider or all | -| `omniroute_route_request` | Send a chat completion through OmniRoute | -| `omniroute_cost_report` | Cost analytics for a time period | -| `omniroute_list_models_catalog` | Full model catalog with capabilities | - -## Advanced Tools (8) - -| Tool | Description | -| :--------------------------------- | :---------------------------------------------- | -| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | -| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | -| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | -| `omniroute_test_combo` | Live-test all models in a combo | -| `omniroute_get_provider_metrics` | Detailed metrics for one provider | -| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | -| `omniroute_explain_route` | Explain a past routing decision | -| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | - -## Authentication - -MCP tools are authenticated via API key scopes. Each tool requires specific scopes: - -| Scope | Tools | -| :------------- | :----------------------------------------------- | -| `read:health` | get_health, get_provider_metrics | -| `read:combos` | list_combos, get_combo_metrics | -| `write:combos` | switch_combo | -| `read:quota` | check_quota | -| `write:route` | route_request, simulate_route, test_combo | -| `read:usage` | cost_report, get_session_snapshot, explain_route | -| `write:config` | set_budget_guard, set_resilience_profile | -| `read:models` | list_models_catalog, best_combo_for_task | - -## Audit Logging - -Every tool call is logged to `mcp_tool_audit` with: - -- Tool name, arguments, result -- Duration (ms), success/failure -- API key hash, timestamp - -## Files - -| File | Purpose | -| :------------------------------------------- | :------------------------------------------ | -| `open-sse/mcp-server/server.ts` | MCP server creation + 16 tool registrations | -| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport | -| `open-sse/mcp-server/auth.ts` | API key + scope validation | -| `open-sse/mcp-server/audit.ts` | Tool call audit logging | -| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers | diff --git a/docs/i18n/it/README.md b/docs/i18n/it/README.md index 02c58bf01c..794557cd73 100644 --- a/docs/i18n/it/README.md +++ b/docs/i18n/it/README.md @@ -1,12 +1,12 @@ # ๐Ÿš€ OmniRoute โ€” The Free AI Gateway (Italiano) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/README.md) --- ### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback. -_Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._ +_Your universal API proxy โ€” one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._ **Chat Completions โ€ข Embeddings โ€ข Image Generation โ€ข Video โ€ข Music โ€ข Audio โ€ข Reranking โ€ข **Web Search** โ€ข MCP Server โ€ข A2A Protocol โ€ข 100% TypeScript** @@ -46,15 +46,17 @@ _Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now wi > - `APP_LOG_FILE_PATH` > - `APP_LOG_MAX_FILE_SIZE` > - `APP_LOG_RETENTION_DAYS` +> - `APP_LOG_MAX_FILES` > - `APP_LOG_LEVEL` > - `APP_LOG_FORMAT` > - `CALL_LOG_RETENTION_DAYS` +> - `CALL_LOG_MAX_ENTRIES` > > For release details and upgrade notes, see the [CHANGELOG](CHANGELOG.md). --- -## ๐Ÿ†• What's New in v3.0.0 +## ๐Ÿ†• What's New > **Upgrading from v2.9.5?** โ€” See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes. @@ -274,7 +276,7 @@ Developers pay $20โ€“200/month for Claude Pro, Codex Pro, or GitHub Copilot. Eve - **Smart 4-Tier Fallback** โ€” If subscription quota runs out, automatically redirects to API Key โ†’ Cheap โ†’ Free with zero manual intervention - **Real-Time Quota Tracking** โ€” Shows token consumption in real-time with reset countdown (5h, daily, weekly) - **Multi-Account Support** โ€” Multiple accounts per provider with auto round-robin โ€” when one runs out, switches to the next -- **Custom Combos** โ€” Customizable fallback chains with 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Custom Combos** โ€” Customizable fallback chains with 9 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random) - **Codex Business Quotas** โ€” Business/Team workspace quota monitoring directly in the dashboard @@ -286,7 +288,7 @@ OpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If **How OmniRoute solves it:** -- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 67+ providers +- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 60+ providers - **Format Translation** โ€” Automatic and transparent: OpenAI โ†” Claude โ†” Gemini โ†” Responses API - **Response Sanitization** โ€” Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+ - **Role Normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI providers; `system` โ†’ `user` for GLM/ERNIE @@ -372,7 +374,7 @@ Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code.. - **CLI Tools Dashboard** โ€” Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline - **GitHub Copilot Config Generator** โ€” Generates `chatLanguageModels.json` for VS Code with bulk model selection - **Onboarding Wizard** โ€” Guided 4-step setup for first-time users -- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 67+ providers +- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 60+ providers @@ -419,7 +421,7 @@ When a call fails, the dev doesn't know if it was a rate limit, expired token, w - **SQLite Proxy Logs** โ€” Persistent logs that survive server restarts - **Translator Playground** โ€” 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time) - **Request Telemetry** โ€” p50/p95/p99 latency + X-Request-Id tracing -- **File-Based Logging with Rotation** โ€” Console interceptor captures everything to JSON log with size-based rotation +- **File-Based Logging with Rotation** โ€” App logs rotate by size, retention days, and archive count; call log artifacts rotate by retention days and file count - **System Info Report** โ€” `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage. @@ -514,7 +516,7 @@ Developers who want all responses in a specific language, with a specific tone, - **System Prompt Injection** โ€” Global prompt applied to all requests - **Thinking Budget Validation** โ€” Reasoning token allocation control per request (passthrough, auto, custom, adaptive) -- **6 Routing Strategies** โ€” Global strategies that determine how requests are distributed +- **9 Routing Strategies** โ€” Global strategies that determine how requests are distributed - **Wildcard Router** โ€” `provider/*` patterns route dynamically to any provider - **Combo Enable/Disable Toggle** โ€” Toggle combos directly from the dashboard - **Provider Toggle** โ€” Enable/disable all connections for a provider with one click @@ -581,7 +583,7 @@ Different clients should have least-privilege access to tool categories. **How OmniRoute solves it:** -- 9 granular MCP scopes for controlled tool access +- 10 granular MCP scopes for controlled tool access - Scope enforcement and visibility in MCP management UI - Safe default posture for operational tooling @@ -1325,19 +1327,19 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. ### ๐Ÿค– Agent & Protocol Operations (v2.0) -| Feature | What It Does | -| ------------------------------------- | -------------------------------------------------------------------------------------------------- | -| ๐Ÿ”ง **MCP Server (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) | -| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | -| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | -| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | -| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | -| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | -| ๐Ÿ” **MCP Scope Enforcement** | 9 granular scope permissions for controlled tool access | -| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | -| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | -| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | -| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | +| Feature | What It Does | +| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| ๐Ÿ”ง **MCP Server (25 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools | +| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | +| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | +| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | +| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | +| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | +| ๐Ÿ” **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access | +| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | +| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | +| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | +| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | ### ๐Ÿง  Routing & Intelligence @@ -1348,7 +1350,7 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. | ๐Ÿ”„ **Format Translation** | OpenAI โ†” Claude โ†” Gemini โ†” Responses with schema-safe conversions | | ๐Ÿ‘ฅ **Multi-Account Support** | Multiple accounts per provider with intelligent selection | | ๐Ÿ”„ **Auto Token Refresh** | OAuth tokens refresh automatically with retry | -| ๐ŸŽจ **Custom Combos** | 6 balancing strategies + fallback chain control | +| ๐ŸŽจ **Custom Combos** | 9 balancing strategies + fallback chain control | | ๐ŸŒ **Wildcard Router** | `provider/*` dynamic routing | | ๐Ÿง  **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits | | ๐Ÿ”€ **Model Aliases** | Built-in + custom model aliasing and migration safety | @@ -1949,6 +1951,7 @@ opencode - Request artifacts are written to `DATA_DIR/call_logs/` as one JSON file per request - Enable pipeline capture from Dashboard โ†’ Logs โ†’ Request Logs if you need detailed per-stage payloads - Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log` +- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed **Connection test shows "Invalid" for OpenAI-compatible providers** diff --git a/docs/i18n/it/RELEASE_CHECKLIST.md b/docs/i18n/it/RELEASE_CHECKLIST.md deleted file mode 100644 index 903e812c3f..0000000000 --- a/docs/i18n/it/RELEASE_CHECKLIST.md +++ /dev/null @@ -1,37 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/RELEASE_CHECKLIST.md) - ---- - -# Release Checklist - -Use this checklist before tagging or publishing a new OmniRoute release. - -## Version and Changelog - -1. Bump `package.json` version (`x.y.z`) in the release branch. -2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: - - `## [x.y.z] โ€” YYYY-MM-DD` -3. Keep `## [Unreleased]` as the first changelog section for upcoming work. -4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. - -## API Docs - -1. Update `docs/openapi.yaml`: - - `info.version` must equal `package.json` version. -2. Validate endpoint examples if API contracts changed. - -## Runtime Docs - -1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. -2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. -3. Update localized docs if source docs changed significantly. - -## Automated Check - -Run the sync guard locally before opening PR: - -```bash -npm run check:docs-sync -``` - -CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/it/SECURITY.md b/docs/i18n/it/SECURITY.md new file mode 100644 index 0000000000..8cba79cba0 --- /dev/null +++ b/docs/i18n/it/SECURITY.md @@ -0,0 +1,179 @@ +# Security Policy (Italiano) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../SECURITY.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/SECURITY.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/SECURITY.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/SECURITY.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/SECURITY.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/SECURITY.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/SECURITY.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/SECURITY.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/SECURITY.md) + +--- + +## 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 | +| ------- | -------------- | +| 3.4.x | โœ… Active | +| 3.0.x | โœ… Security | +| < 3.0.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 | +| **MCP Scopes** | 10 granular scopes for MCP tool access control | + +### ๐Ÿ›ก๏ธ 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:::` +- 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** | Allowlist/blocklist IP ranges in dashboard | +| **Rate Limiting** | Per-provider rate limits with automatic backoff | +| **Anti-Thundering Herd** | Mutex + per-connection locking prevents cascading 502s | +| **TLS Fingerprint** | Browser-like TLS fingerprint spoofing to reduce bot detection | +| **CLI Fingerprint** | Per-provider header/body ordering to match native CLI signatures | + +### ๐Ÿ”Œ Resilience & Availability + +| 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 `CALL_LOG_RETENTION_DAYS` | +| **No-Log Opt-out** | Per API key `noLog` flag disables request logging | +| **Audit Log** | Administrative actions tracked in `audit_log` table | +| **MCP Audit** | SQLite-backed audit logging for all MCP tool calls | +| **Zod Validation** | All API inputs validated with Zod v4 schemas at module load | + +--- + +## 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 +- Provider constants validated at module load via Zod (`src/shared/validation/providerSchema.ts`) diff --git a/docs/i18n/it/TROUBLESHOOTING.md b/docs/i18n/it/TROUBLESHOOTING.md deleted file mode 100644 index 63c148000a..0000000000 --- a/docs/i18n/it/TROUBLESHOOTING.md +++ /dev/null @@ -1,258 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/TROUBLESHOOTING.md) - ---- - -# Troubleshooting - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/TROUBLESHOOTING.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/TROUBLESHOOTING.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/TROUBLESHOOTING.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/TROUBLESHOOTING.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/TROUBLESHOOTING.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/TROUBLESHOOTING.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/TROUBLESHOOTING.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/TROUBLESHOOTING.md) - -Common problems and solutions for OmniRoute. - ---- - -## Quick Fixes - -| Problem | Solution | -| ----------------------------- | ------------------------------------------------------------------ | -| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | -| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | -| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | -| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | -| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | - ---- - -## Provider Issues - -### "Language model did not provide messages" - -**Cause:** Provider quota exhausted. - -**Fix:** - -1. 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, Qoder) 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}/storage.sqlite` (providers, combos, aliases, keys, settings) -- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` -- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) - ---- - -## Circuit Breaker Issues - -### Provider stuck in OPEN state - -When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. - -**Fix:** - -1. 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 -- **SDK returns raw string instead of object** โ€” Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures -- **GLM/ERNIE rejects `system` role** โ€” Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models -- **`developer` role not recognized** โ€” Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers -- **`json_schema` not working with Gemini** โ€” Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` - ---- - -## Resilience Settings - -### Auto rate-limit not triggering - -- 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. - ---- - -## Optional RAG / LLM failure taxonomy (16 problems) - -Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. - -In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. - -If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: - -- retrieval drift and broken context boundaries -- empty or stale indexes and vector stores -- embedding versus semantic mismatch -- prompt assembly and context window issues -- logic collapse and overconfident answers -- long chain and agent coordination failures -- multi agent memory and role drift -- deployment and bootstrap ordering problems - -The idea is simple: - -1. When you investigate a bad response, capture: - - user task and request - - route or provider combo in OmniRoute - - any RAG context used downstream (retrieved documents, tool calls, etc) -2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` โ€ฆ `No.16`). -3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. -4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. - -Full text and concrete recipes live here (MIT license, text only): - -[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) - -You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. - ---- - -## Still Stuck? - -- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details -- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints -- **Health Dashboard**: Check **Dashboard โ†’ Health** for real-time system status -- **Translator**: Use **Dashboard โ†’ Translator** to debug format issues diff --git a/docs/i18n/it/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/it/VM_DEPLOYMENT_GUIDE.md deleted file mode 100644 index c0581b1777..0000000000 --- a/docs/i18n/it/VM_DEPLOYMENT_GUIDE.md +++ /dev/null @@ -1,401 +0,0 @@ -# OmniRoute: guida alla distribuzione su VM con Cloudflare - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](../pt-BR/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](../es/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](../fr/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](../it/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](../ru/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](../zh-CN/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](../de/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](../in/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](../th/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](../uk-UA/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](../ar/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](../ja/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](../vi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](../bg/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](../da/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](../fi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](../he/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](../hu/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](../id/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](../ko/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](../ms/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](../nl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](../no/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](../pt/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](../ro/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](../pl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](../sk/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](../sv/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](../phi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](../cs/VM_DEPLOYMENT_GUIDE.md) - -Guida completa per installare e configurare OmniRoute su una VM (VPS) con dominio gestito tramite Cloudflare. - ---- - -## Prerequisiti - -| Articolo | Minimo | Consigliato | -| --------------------- | ------------------------ | ---------------- | -| **CPU** | 1 CPU virtuale | 2 vCPU | -| **RAM** | 1GB | 2GB | -| **Disco** | SSD da 10GB | SSD da 25GB | -| **Sistema operativo** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS | -| **Dominio** | Registrato su Cloudflare | โ€” | -| **Docker** | Motore Docker24+ | Docker27+ | - -**Fornitori testati**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. - ---- - -## 1. Configura la VM - -### 1.1 Creare l'istanza - -Sul tuo provider VPS preferito: - -- Scegli Ubuntu 24.04 LTS -- Seleziona il piano minimo (1 vCPU / 1 GB RAM) -- Imposta una password root complessa o configura la chiave SSH -- Prendi nota dell'**IP pubblico** (ad esempio, `203.0.113.10`) - -### 1.2 Connetti tramite SSH - -```bash -ssh root@203.0.113.10 -``` - -### 1.3 Aggiornare il sistema - -```bash -apt update && apt upgrade -y -``` - -### 1.4 Installa Docker - -```bash -# Install dependencies -apt install -y ca-certificates curl gnupg - -# Add official Docker repository -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 Installa nginx - -```bash -apt install -y nginx -``` - -### 1.6 Configurazione del 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 -``` - -> **Suggerimento**: per la massima sicurezza, limita le porte 80 e 443 solo agli IP Cloudflare. Consulta la sezione [Advanced Security](#advanced-security). - ---- - -## 2. Installa OmniRoute - -### 2.1 Creare la directory di configurazione - -```bash -mkdir -p /opt/omniroute -``` - -### 2.2 Creare il file delle variabili d'ambiente - -```bash -cat > /opt/omniroute/.env << โ€˜EOFโ€™ -# === Security === -JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY -INITIAL_PASSWORD=YourSecurePassword123! -API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY -STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY -STORAGE_ENCRYPTION_KEY_VERSION=v1 -MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT - -# === 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 (change to your domain) === -BASE_URL=https://llms.seudominio.com -NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com - -# === Cloud Sync (optional) === -# CLOUD_URL=https://cloud.omniroute.online -# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online -EOF -``` - -> โš ๏ธ **IMPORTANTE**: genera chiavi segrete uniche! Utilizza `openssl rand -hex 32` per ciascuna chiave. - -### 2.3 Avviare il contenitore - -```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 Verificare che sia in esecuzione - -```bash -docker ps | grep omniroute -docker logs omniroute --tail 20 -``` - -Dovrebbe essere visualizzato: `[DB] SQLite database ready` e `listening on port 20128`. - ---- - -## 3. Configura nginx (proxy inverso) - -### 3.1 Genera certificato SSL (Cloudflare Origin) - -Nella dashboard di Cloudflare: - -1. Vai su **SSL/TLS โ†’ Server di origine** -2. Fai clic su **Crea certificato** -3. Mantieni le impostazioni predefinite (15 anni, \*.tuodominio.com) -4. Copia il **Certificato di Origine** e la **Chiave Privata** - -```bash -mkdir -p /etc/nginx/ssl - -# Paste the certificate -nano /etc/nginx/ssl/origin.crt - -# Paste the private key -nano /etc/nginx/ssl/origin.key - -chmod 600 /etc/nginx/ssl/origin.key -``` - -### 3.2 Configurazione Nginx - -```bash -cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ -# Default server โ€” blocks direct access via 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.yourdomain.com; # Change to your domain - - 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.yourdomain.com; - return 301 https://$server_name$request_uri; -} -NGINX -``` - -### 3.3 Abilita e prova - -```bash -# Remove default configuration -rm -f /etc/nginx/sites-enabled/default - -# Enable OmniRoute -ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute - -# Test and reload -nginx -t && systemctl reload nginx -``` - ---- - -## 4. Configura il DNS di Cloudflare - -### 4.1 Aggiungi record DNS - -Nella dashboard di Cloudflare โ†’ DNS: - -| Digitare | Nome | Contenuto | Procura | -| -------- | ------ | ------------------------------------------- | ---------- | -| A | `llms` | `203.0.113.10` (IP della macchina virtuale) | โœ… Procura | - -### 4.2 Configurare SSL - -In **SSL/TLS โ†’ Panoramica**: - -- Modalitร : **Completa (Ristretta)** - -In **SSL/TLS โ†’ Certificati Edge**: - -- Usa sempre HTTPS: โœ… Attivo -- Versione TLS minima: TLS 1.2 -- Riscritture HTTPS automatiche: โœ… On - -### 4.3 Test - -```bash -curl -sI https://llms.seudominio.com/health -# Should return HTTP/2 200 -``` - ---- - -## 5. Operazioni e manutenzione - -### Aggiorna a una nuova versione - -```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 -``` - -### Visualizza i registri - -```bash -docker logs -f omniroute # Real-time stream -docker logs omniroute --tail 50 # Last 50 lines -``` - -### Backup manuale del database - -```bash -# Copy data from the volume to the host -docker cp omniroute:/app/data ./backup-$(date +%F) - -# Or compress the entire volume -docker run --rm -v omniroute-data:/data -v $(pwd):/backup \ - alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data -``` - -### Ripristina dal 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. Sicurezza avanzata - -### Limita nginx agli IP Cloudflare - -```bash -cat > /etc/nginx/cloudflare-ips.conf << โ€˜CFโ€™ -# Cloudflare IPv4 ranges โ€” update periodically -# 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 -``` - -Aggiungi quanto segue a `nginx.conf` all'interno del blocco `http {}`: - -```nginx -include /etc/nginx/cloudflare-ips.conf; -``` - -### Installa fail2ban - -```bash -apt install -y fail2ban -systemctl enable fail2ban -systemctl start fail2ban - -# Check status -fail2ban-client status sshd -``` - -### Blocca l'accesso diretto alla porta Docker - -```bash -# Prevent direct external access to port 20128 -iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP -iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT - -# Persist the rules -apt install -y iptables-persistent -netfilter-persistent save -``` - ---- - -## 7. Distribuzione ai dipendenti Cloudflare (facoltativo) - -Per l'accesso remoto tramite Cloudflare Workers (senza esporre direttamente la VM): - -```bash -# In the local repository -cd omnirouteCloud -npm install -npx wrangler login -npx wrangler deploy -``` - -Consulta la documentazione completa su [omnirouteCloud/README.md](../omnirouteCloud/README.md). - ---- - -## Riepilogo delle porte - -| Porto | Servizio | Accesso | -| ----- | ----------- | -------------------------------- | -| 22 | SSH | Pubblico (con fail2ban) | -| 80 | nginxHTTP | Reindirizzamento โ†’ HTTPS | -| 443 | nginx HTTPS | Tramite proxy Cloudflare | -| 20128 | OmniRoute | Solo host locale (tramite nginx) | diff --git a/docs/i18n/it/docs/A2A-SERVER.md b/docs/i18n/it/docs/A2A-SERVER.md new file mode 100644 index 0000000000..98d12968b4 --- /dev/null +++ b/docs/i18n/it/docs/A2A-SERVER.md @@ -0,0 +1,200 @@ +# OmniRoute A2A Server Documentation (Italiano) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/A2A-SERVER.md) + +--- + +> Agent-to-Agent Protocol v0.3 โ€” OmniRoute as an intelligent routing agent + +## Agent Discovery + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements. + +--- + +## Authentication + +All `/a2a` requests require an API key via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server, authentication is bypassed. + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Sends a message to a skill and waits for the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a hello world in Python"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "uuid", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "..." }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}} + +: heartbeat 2026-03-03T17:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Available Skills + +| Skill | Description | +| :----------------- | :------------------------------------------------------------------------------------------------------------------------------ | +| `smart-routing` | Routes prompts through OmniRoute's intelligent pipeline. Returns response with routing explanation, cost, and resilience trace. | +| `quota-management` | Answers natural-language queries about provider quotas, suggests free combos, and provides quota rankings. | + +--- + +## Task Lifecycle + +``` +submitted โ†’ working โ†’ completed + โ†’ failed + โ†’ cancelled +``` + +- Tasks expire after 5 minutes (configurable) +- Terminal states: `completed`, `failed`, `cancelled` +- Event log tracks every state transition + +--- + +## Error Codes + +| Code | Meaning | +| :----- | :----------------------------- | +| -32700 | Parse error (invalid JSON) | +| -32600 | Invalid request / Unauthorized | +| -32601 | Method or skill not found | +| -32602 | Invalid params | +| -32603 | Internal error | + +--- + +## Integration Examples + +### Python (requests) + +```python +import requests + +resp = requests.post("http://localhost:20128/a2a", json={ + "jsonrpc": "2.0", "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Hello"}] + } +}, headers={"Authorization": "Bearer YOUR_KEY"}) + +result = resp.json()["result"] +print(result["artifacts"][0]["content"]) +print(result["metadata"]["routing_explanation"]) +``` + +### TypeScript (fetch) + +```typescript +const resp = await fetch("http://localhost:20128/a2a", { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: "Bearer YOUR_KEY", + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "1", + method: "message/send", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Hello" }], + }, + }), +}); +const { result } = await resp.json(); +console.log(result.metadata.routing_explanation); +``` diff --git a/docs/i18n/it/docs/API_REFERENCE.md b/docs/i18n/it/docs/API_REFERENCE.md new file mode 100644 index 0000000000..1d31c2fef1 --- /dev/null +++ b/docs/i18n/it/docs/API_REFERENCE.md @@ -0,0 +1,465 @@ +# API Reference (Italiano) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/API_REFERENCE.md) + +--- + +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 | +| `X-Session-Id` | Request | Sticky session key for external session affinity | +| `x_session_id` | Request | Underscore variant also accepted (direct HTTP) | +| `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 | +| `X-OmniRoute-Session-Id` | Response | Effective session ID used by OmniRoute | + +> Nginx note: if you rely on underscore headers (for example `x_session_id`), enable `underscores_in_headers 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/stats + +# Clear all caches +DELETE /api/cache/stats +``` + +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/PATCH | 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 + provider summary (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`) | +| `/api/cache/stats` | 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 | + +### Tunnels + +| Endpoint | Method | Description | +| -------------------------- | ------ | ----------------------------------------------------------------------- | +| `/api/tunnels/cloudflared` | GET | Read Cloudflare Quick Tunnel install/runtime status for the dashboard | +| `/api/tunnels/cloudflared` | POST | Enable or disable the Cloudflare Quick Tunnel (`action=enable/disable`) | + +### 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`. + +### ACP Agents + +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | + +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). + +### Resilience & Rate Limits + +| Endpoint | Method | Description | +| ----------------------- | --------- | ------------------------------- | +| `/api/resilience` | GET/PATCH | 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` diff --git a/docs/i18n/it/docs/ARCHITECTURE.md b/docs/i18n/it/docs/ARCHITECTURE.md new file mode 100644 index 0000000000..591ddf3418 --- /dev/null +++ b/docs/i18n/it/docs/ARCHITECTURE.md @@ -0,0 +1,814 @@ +# OmniRoute Architecture (Italiano) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/ARCHITECTURE.md) + +--- + +_Last updated: 2026-03-28_ + +## 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 (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developerโ†’system, systemโ†’user) for cross-provider compatibility +- Structured output conversion (json_schema โ†’ Gemini responseSchema) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) +- Global system prompt injection +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout โ†’ budget โ†’ fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) + +Primary runtime model: + +- Next.js 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.) + +## Dashboard Surface (Current) + +Main pages under `src/app/(dashboard)/dashboard/`: + +- `/dashboard` โ€” quick start + provider overview +- `/dashboard/endpoint` โ€” endpoint proxy + MCP + A2A + API endpoint tabs +- `/dashboard/providers` โ€” provider connections and credentials +- `/dashboard/combos` โ€” combo strategies, templates, model routing rules +- `/dashboard/costs` โ€” cost aggregation and pricing visibility +- `/dashboard/analytics` โ€” usage analytics and evaluations +- `/dashboard/limits` โ€” quota/rate controls +- `/dashboard/cli-tools` โ€” CLI onboarding, runtime detection, config generation +- `/dashboard/agents` โ€” detected ACP agents + custom agent registration +- `/dashboard/media` โ€” image/video/music playground +- `/dashboard/search-tools` โ€” search provider testing and history +- `/dashboard/health` โ€” uptime, circuit breakers, rate limits +- `/dashboard/logs` โ€” request/proxy/audit/console logs +- `/dashboard/settings` โ€” system settings tabs (general, routing, combo defaults, etc.) +- `/dashboard/api-manager` โ€” API key lifecycle and model permissions + +## 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[(storage.sqlite)] + UDB[(usage tables + log artifacts)] + end + + subgraph Upstreams[Upstream Providers] + P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/Qoder/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/route.ts` (GET) +- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- OAuth: `src/app/api/oauth/*` +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` +- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI tooling helpers: `src/app/api/cli-tools/*` +- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) +- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) โ€” provider profiles, circuit breaker, rate limit state +- Resilience reset: `src/app/api/resilience/reset` (POST) โ€” reset breakers + cooldowns +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) +- Telemetry: `src/app/api/telemetry/summary` (GET) +- Budget: `src/app/api/usage/budget` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Policies: `src/app/api/policies` (GET/POST) + +## 2) SSE + 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` +- Response sanitization: `open-sse/handlers/responseSanitizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.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`, `qoder.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 (SQLite): + +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** + +Usage persistence: + +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present + +Domain State DB (SQLite): + +- `src/lib/db/domainState.ts` โ€” CRUD operations 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`, `src/shared/services/modelSyncScheduler.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Periodic task: `src/shared/services/modelSyncScheduler.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. Combo routing adds one extra guard: provider-scoped 400s such as upstream content-block and role-validation failures are treated as model-local failures so later combo targets can still run. + +## 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: + +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` + +## Deployment Topology + +```mermaid +flowchart LR + 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[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] + end + + subgraph External[External Services] + Providers[AI Providers] + SyncCloud[Cloud Sync Service] + end + + CLI --> Next + Browser --> Next + Next --> Core + Next --> MainDB + Core --> MainDB + Core --> UsageDB + Core --> Providers + Next --> SyncCloud +``` + +## Module Mapping (Decision-Critical) + +### Route and API Modules + +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle +- `src/app/api/models/alias`: alias management +- `src/app/api/combos*`: fallback combo management +- `src/app/api/pricing`: pricing overrides for cost calculation +- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers +- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) +- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) +- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) +- `src/app/api/sessions`: active session listing (GET) +- `src/app/api/rate-limits`: per-account rate limit status (GET) + +### Routing and Execution Core + +- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior + +### Translation Registry and Format Converters + +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` +- Format constants: `open-sse/translator/formats.ts` + +### Persistence + +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables + +## Provider Executor Coverage (Strategy Pattern) + +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. + +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, Qoder, 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 | +| Qoder | openai | OAuth (Basic) | โœ… | โœ… | โœ… | โš ๏ธ Per request | +| OpenRouter | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| GLM/Kimi/MiniMax | claude | API Key | โœ… | โœ… | โŒ | โŒ | +| DeepSeek | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Groq | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| xAI (Grok) | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Mistral | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Perplexity | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Together AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Fireworks AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Cerebras | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Cohere | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| NVIDIA NIM | openai | API Key | โœ… | โœ… | โŒ | โŒ | + +## Format Translation Coverage + +Detected source formats include: + +- `openai` +- `openai-responses` +- `claude` +- `gemini` + +Target formats include: + +- OpenAI chat/Responses +- Claude +- Gemini/Gemini-CLI/Antigravity envelope +- Kiro +- Cursor + +Translations use **OpenAI as the hub format** โ€” all conversions go through OpenAI as intermediate: + +``` +Source Format โ†’ OpenAI (hub) โ†’ Target Format +``` + +Translations are selected dynamically based on source payload shape and provider target format. + +Additional processing layers in the translation pipeline: + +- **Response sanitization** โ€” Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI targets; merges `system` โ†’ `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** โ€” Parses `...` blocks from content into `reasoning_content` field +- **Structured output** โ€” Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` + +## Supported API Endpoints + +| 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` | Provider Models | Provider model metadata backing custom and managed available models | + +## 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 `/logs//` 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 + +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON โ†’ SQLite migration compatibility path + +## Observability and Operational Signals + +Runtime visibility sources: + +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- four-stage detailed payload captures in SQLite (`request_detail_logs`) when `settings.detailed_logs_enabled=true` +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption + +Detailed request payload capture stores up to four JSON payload stages per routed call: + +- raw request received from the client +- translated request actually sent upstream +- provider response reconstructed as JSON; streamed responses are compacted to the final summary plus stream metadata +- final client response returned by OmniRoute; streamed responses are stored in the same compact summary form + +## Security-Sensitive Boundaries + +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics + +## Environment and Runtime Matrix + +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` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). + +## Operational Verification Checklist + +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: +- `GET /api/settings` +- `GET /api/v1/models` +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/it/docs/AUTO-COMBO.md b/docs/i18n/it/docs/AUTO-COMBO.md new file mode 100644 index 0000000000..c4e91ca086 --- /dev/null +++ b/docs/i18n/it/docs/AUTO-COMBO.md @@ -0,0 +1,67 @@ +# OmniRoute Auto-Combo Engine (Italiano) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/AUTO-COMBO.md) + +--- + +> Self-managing model chains with adaptive scoring + +## How It Works + +The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**: + +| Factor | Weight | Description | +| :--------- | :----- | :---------------------------------------------- | +| Quota | 0.20 | Remaining capacity [0..1] | +| Health | 0.25 | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 | +| CostInv | 0.20 | Inverse cost (cheaper = higher score) | +| LatencyInv | 0.15 | Inverse p95 latency (faster = higher) | +| TaskFit | 0.10 | Model ร— task type fitness score | +| Stability | 0.10 | Low variance in latency/errors | + +## Mode Packs + +| Pack | Focus | Key Weight | +| :---------------------- | :----------- | :--------------- | +| ๐Ÿš€ **Ship Fast** | Speed | latencyInv: 0.35 | +| ๐Ÿ’ฐ **Cost Saver** | Economy | costInv: 0.40 | +| ๐ŸŽฏ **Quality First** | Best model | taskFit: 0.40 | +| ๐Ÿ“ก **Offline Friendly** | Availability | quota: 0.40 | + +## Self-Healing + +- **Temporary exclusion**: Score < 0.2 โ†’ excluded for 5 min (progressive backoff, max 30 min) +- **Circuit breaker awareness**: OPEN โ†’ auto-excluded; HALF_OPEN โ†’ probe requests +- **Incident mode**: >50% OPEN โ†’ disable exploration, maximize stability +- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout + +## Bandit Exploration + +5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode. + +## API + +```bash +# Create auto-combo +curl -X POST http://localhost:20128/api/combos/auto \ + -H "Content-Type: application/json" \ + -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}' + +# List auto-combos +curl http://localhost:20128/api/combos/auto +``` + +## Task Fitness + +30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` โ†’ high coding score). + +## Files + +| File | Purpose | +| :------------------------------------------- | :------------------------------------ | +| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization | +| `open-sse/services/autoCombo/taskFitness.ts` | Model ร— task fitness lookup | +| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap | +| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode | +| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles | +| `src/app/api/combos/auto/route.ts` | REST API | diff --git a/docs/i18n/it/docs/CLI-TOOLS.md b/docs/i18n/it/docs/CLI-TOOLS.md new file mode 100644 index 0000000000..248f4e1cdb --- /dev/null +++ b/docs/i18n/it/docs/CLI-TOOLS.md @@ -0,0 +1,348 @@ +# CLI Tools Setup Guide โ€” OmniRoute (Italiano) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CLI-TOOLS.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CLI-TOOLS.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CLI-TOOLS.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CLI-TOOLS.md) + +--- + +This guide explains how to install and configure all supported AI coding CLI tools +to use **OmniRoute** as the unified backend, giving you centralized key management, +cost tracking, model switching, and request logging across every tool. + +--- + +## How It Works + +``` +Claude / Codex / OpenCode / Cline / KiloCode / Continue / Kiro / Cursor / Copilot + โ”‚ + โ–ผ (all point to OmniRoute) + http://YOUR_SERVER:20128/v1 + โ”‚ + โ–ผ (OmniRoute routes to the right provider) + Anthropic / OpenAI / Gemini / DeepSeek / Groq / Mistral / ... +``` + +**Benefits:** + +- One API key to manage all tools +- Cost tracking across all CLIs in the dashboard +- Model switching without reconfiguring every tool +- Works locally and on remote servers (VPS) + +--- + +## Supported Tools (Dashboard Source of Truth) + +The dashboard cards in `/dashboard/cli-tools` are generated from `src/shared/constants/cliTools.ts`. +Current list (v3.0.0-rc.16): + +| Tool | ID | Command | Setup Mode | Install Method | +| ------------------ | ------------- | ---------- | ---------- | -------------- | +| **Claude Code** | `claude` | `claude` | env | npm | +| **OpenAI Codex** | `codex` | `codex` | custom | npm | +| **Factory Droid** | `droid` | `droid` | custom | bundled/CLI | +| **OpenClaw** | `openclaw` | `openclaw` | custom | bundled/CLI | +| **Cursor** | `cursor` | app | guide | desktop app | +| **Cline** | `cline` | `cline` | custom | npm | +| **Kilo Code** | `kilo` | `kilocode` | custom | npm | +| **Continue** | `continue` | extension | guide | VS Code | +| **Antigravity** | `antigravity` | internal | mitm | OmniRoute | +| **GitHub Copilot** | `copilot` | extension | custom | VS Code | +| **OpenCode** | `opencode` | `opencode` | guide | npm | +| **Kiro AI** | `kiro` | app/cli | mitm | desktop/CLI | + +### CLI fingerprint sync (Agents + Settings) + +`/dashboard/agents` and `Settings > CLI Fingerprint` use `src/shared/constants/cliCompatProviders.ts`. +This keeps provider IDs aligned with CLI cards and legacy IDs. + +| CLI ID | Fingerprint Provider ID | +| ---------------------------------------------------------------------------------------------------- | ----------------------- | +| `kilo` | `kilocode` | +| `copilot` | `github` | +| `claude` / `codex` / `antigravity` / `kiro` / `cursor` / `cline` / `opencode` / `droid` / `openclaw` | same ID | + +Legacy IDs still accepted for compatibility: `copilot`, `kimi-coding`, `qwen`. + +--- + +## Step 1 โ€” Get an OmniRoute API Key + +1. Open the OmniRoute dashboard โ†’ **API Manager** (`/dashboard/api-manager`) +2. Click **Create API Key** +3. Give it a name (e.g. `cli-tools`) and select all permissions +4. Copy the key โ€” you'll need it for every CLI below + +> Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` + +--- + +## Step 2 โ€” Install CLI Tools + +All npm-based tools require Node.js 18+: + +```bash +# Claude Code (Anthropic) +npm install -g @anthropic-ai/claude-code + +# OpenAI Codex +npm install -g @openai/codex + +# OpenCode +npm install -g opencode-ai + +# Cline +npm install -g cline + +# KiloCode +npm install -g kilocode + +# Kiro CLI (Amazon โ€” requires curl + unzip) +apt-get install -y unzip # on Debian/Ubuntu +curl -fsSL https://cli.kiro.dev/install | bash +export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc +``` + +**Verify:** + +```bash +claude --version # 2.x.x +codex --version # 0.x.x +opencode --version # x.x.x +cline --version # 2.x.x +kilocode --version # x.x.x (or: kilo --version) +kiro-cli --version # 1.x.x +``` + +--- + +## Step 3 โ€” Set Global Environment Variables + +Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`: + +```bash +# OmniRoute Universal Endpoint +export OPENAI_BASE_URL="http://localhost:20128/v1" +export OPENAI_API_KEY="sk-your-omniroute-key" +export ANTHROPIC_BASE_URL="http://localhost:20128/v1" +export ANTHROPIC_API_KEY="sk-your-omniroute-key" +export GEMINI_BASE_URL="http://localhost:20128/v1" +export GEMINI_API_KEY="sk-your-omniroute-key" +``` + +> For a **remote server** replace `localhost:20128` with the server IP or domain, +> e.g. `http://192.168.0.15:20128`. + +--- + +## Step 4 โ€” Configure Each Tool + +### Claude Code + +```bash +# Via CLI: +claude config set --global api-base-url http://localhost:20128/v1 + +# Or create ~/.claude/settings.json: +mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF +{ + "apiBaseUrl": "http://localhost:20128/v1", + "apiKey": "sk-your-omniroute-key" +} +EOF +``` + +**Test:** `claude "say hello"` + +--- + +### OpenAI Codex + +```bash +mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF +model: auto +apiKey: sk-your-omniroute-key +apiBaseUrl: http://localhost:20128/v1 +EOF +``` + +**Test:** `codex "what is 2+2?"` + +--- + +### OpenCode + +```bash +mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF +[provider.openai] +base_url = "http://localhost:20128/v1" +api_key = "sk-your-omniroute-key" +EOF +``` + +**Test:** `opencode` + +--- + +### Cline (CLI or VS Code) + +**CLI mode:** + +```bash +mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF +{ + "apiProvider": "openai", + "openAiBaseUrl": "http://localhost:20128/v1", + "openAiApiKey": "sk-your-omniroute-key" +} +EOF +``` + +**VS Code mode:** +Cline extension settings โ†’ API Provider: `OpenAI Compatible` โ†’ Base URL: `http://localhost:20128/v1` + +Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ Cline โ†’ Apply Config**. + +--- + +### KiloCode (CLI or VS Code) + +**CLI mode:** + +```bash +kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key +``` + +**VS Code settings:** + +```json +{ + "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", + "kilo-code.apiKey": "sk-your-omniroute-key" +} +``` + +Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ KiloCode โ†’ Apply Config**. + +--- + +### Continue (VS Code Extension) + +Edit `~/.continue/config.yaml`: + +```yaml +models: + - name: OmniRoute + provider: openai + model: auto + apiBase: http://localhost:20128/v1 + apiKey: sk-your-omniroute-key + default: true +``` + +Restart VS Code after editing. + +--- + +### Kiro CLI (Amazon) + +```bash +# Login to your AWS/Kiro account: +kiro-cli login + +# The CLI uses its own auth โ€” OmniRoute is not needed as backend for Kiro CLI itself. +# Use kiro-cli alongside OmniRoute for other tools. +kiro-cli status +``` + +--- + +### Cursor (Desktop App) + +> **Note:** Cursor routes requests through its cloud. For OmniRoute integration, +> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL. + +Via GUI: **Settings โ†’ Models โ†’ OpenAI API Key** + +- Base URL: `https://your-domain.com/v1` +- API Key: your OmniRoute key + +--- + +## Dashboard Auto-Configuration + +The OmniRoute dashboard automates configuration for most tools: + +1. Go to `http://localhost:20128/dashboard/cli-tools` +2. Expand any tool card +3. Select your API key from the dropdown +4. Click **Apply Config** (if tool is detected as installed) +5. Or copy the generated config snippet manually + +--- + +## Built-in Agents: Droid & OpenClaw + +**Droid** and **OpenClaw** are AI agents built directly into OmniRoute โ€” no installation needed. +They run as internal routes and use OmniRoute's model routing automatically. + +- Access: `http://localhost:20128/dashboard/agents` +- Configure: same combos and providers as all other tools +- No API key or CLI install required + +--- + +## Available API Endpoints + +| Endpoint | Description | Use For | +| -------------------------- | ----------------------------- | --------------------------- | +| `/v1/chat/completions` | Standard chat (all providers) | All modern tools | +| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows | +| `/v1/completions` | Legacy text completions | Older tools using `prompt:` | +| `/v1/embeddings` | Text embeddings | RAG, search | +| `/v1/images/generations` | Image generation | DALL-E, Flux, etc. | +| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS | +| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI | + +--- + +## Risoluzione dei Problemi + +| Error | Cause | Fix | +| ------------------------- | ----------------------- | ------------------------------------------ | +| `Connection refused` | OmniRoute not running | `pm2 start omniroute` | +| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` | +| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` | +| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` | +| CLI shows "not installed" | Binary not in PATH | Check `which ` | +| `kiro-cli: not found` | Not in PATH | `export PATH="$HOME/.local/bin:$PATH"` | + +--- + +## Quick Setup Script (One Command) + +```bash +# Install all CLIs and configure for OmniRoute (replace with your key and server URL) +OMNIROUTE_URL="http://localhost:20128/v1" +OMNIROUTE_KEY="sk-your-omniroute-key" + +npm install -g @anthropic-ai/claude-code @openai/codex opencode-ai cline kilocode + +# Kiro CLI +apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash + +# Write configs +mkdir -p ~/.claude ~/.codex ~/.config/opencode ~/.continue + +cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" +cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" +cat >> ~/.bashrc << EOF +export OPENAI_BASE_URL="$OMNIROUTE_URL" +export OPENAI_API_KEY="$OMNIROUTE_KEY" +export ANTHROPIC_BASE_URL="$OMNIROUTE_URL" +export ANTHROPIC_API_KEY="$OMNIROUTE_KEY" +EOF + +source ~/.bashrc +echo "โœ… All CLIs installed and configured for OmniRoute" +``` diff --git a/docs/i18n/it/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/it/docs/CODEBASE_DOCUMENTATION.md new file mode 100644 index 0000000000..84ffd4279c --- /dev/null +++ b/docs/i18n/it/docs/CODEBASE_DOCUMENTATION.md @@ -0,0 +1,591 @@ +# omniroute โ€” Codebase Documentation (Italiano) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CODEBASE_DOCUMENTATION.md) + +--- + +> 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
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, Qoder, 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. + +#### Architettura + +```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 | +| Qoder | 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"] +``` diff --git a/docs/i18n/it/docs/COVERAGE_PLAN.md b/docs/i18n/it/docs/COVERAGE_PLAN.md new file mode 100644 index 0000000000..c260d43c80 --- /dev/null +++ b/docs/i18n/it/docs/COVERAGE_PLAN.md @@ -0,0 +1,170 @@ +# Test Coverage Plan (Italiano) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/COVERAGE_PLAN.md) + +--- + +Last updated: 2026-03-28 + +## Baseline + +There are multiple coverage numbers depending on how the report is computed. For planning, only one of them is useful. + +| Metric | Scope | Statements / Lines | Branches | Functions | Notes | +| -------------------- | ----------------------------------------------------- | -----------------: | -------: | --------: | --------------------------------------------------- | +| Legacy | Old `npm run test:coverage` | 79.42% | 75.15% | 67.94% | Inflated: counts test files and excludes `open-sse` | +| Diagnostic | Source-only, excluding tests and excluding `open-sse` | 68.16% | 63.55% | 64.06% | Useful only to isolate `src/**` | +| Recommended baseline | Source-only, excluding tests and including `open-sse` | 56.95% | 66.05% | 57.80% | This is the project-wide baseline to improve | + +The recommended baseline is the number to optimize against. + +## Rules + +- Coverage targets apply to source files, not to `tests/**`. +- `open-sse/**` is part of the product and must remain in scope. +- New code should not reduce coverage in touched areas. +- Prefer testing behavior and branch outcomes over implementation details. +- Prefer temp SQLite databases and small fixtures over broad mocks for `src/lib/db/**`. + +## Current command set + +- `npm run test:coverage` + - Main source coverage gate for the unit test suite + - Generates `text-summary`, `html`, `json-summary`, and `lcov` +- `npm run coverage:report` + - Detailed file-by-file report from the latest run +- `npm run test:coverage:legacy` + - Historical comparison only + +## Milestones + +| Phase | Target | Focus | +| ------- | ---------------------: | ------------------------------------------------- | +| Phase 1 | 60% statements / lines | Quick wins and low-risk utility coverage | +| Phase 2 | 65% statements / lines | DB and route foundations | +| Phase 3 | 70% statements / lines | Provider validation and usage analytics | +| Phase 4 | 75% statements / lines | `open-sse` translators and helpers | +| Phase 5 | 80% statements / lines | `open-sse` handlers and executor branches | +| Phase 6 | 85% statements / lines | Harder edge cases, branch debt, regression suites | +| Phase 7 | 90% statements / lines | Final sweep, gap closure, strict ratchet | + +Branches and functions should ratchet upward with each phase, but the primary hard target is statements / lines. + +## Priority hotspots + +These files or areas offer the best return for the next phases: + +1. `open-sse/handlers` + - `chatCore.ts` at 7.57% + - Overall directory at 29.07% +2. `open-sse/translator/request` + - Overall directory at 36.39% + - Many translators are still near single-digit coverage +3. `open-sse/translator/response` + - Overall directory at 8.07% +4. `open-sse/executors` + - Overall directory at 36.62% +5. `src/lib/db` + - `models.ts` at 20.66% + - `registeredKeys.ts` at 34.46% + - `modelComboMappings.ts` at 36.25% + - `settings.ts` at 46.40% + - `webhooks.ts` at 33.33% +6. `src/lib/usage` + - `usageHistory.ts` at 21.12% + - `usageStats.ts` at 9.56% + - `costCalculator.ts` at 30.00% +7. `src/lib/providers` + - `validation.ts` at 41.16% +8. Low-risk utility and API files for early gains + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/api/errorResponse.ts` + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +## Execution checklist + +### Phase 1: 56.95% -> 60% + +- [x] Fix coverage metric so it reflects source code instead of test files +- [x] Keep a legacy coverage script for comparison +- [x] Record the baseline and hotspots in-repo +- [ ] Add focused tests for low-risk utilities: + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/fetchTimeout.ts` + - `src/lib/api/errorResponse.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/display/names.ts` +- [ ] Add route tests for: + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +### Phase 2: 60% -> 65% + +- [ ] Add DB-backed tests for: + - `src/lib/db/modelComboMappings.ts` + - `src/lib/db/settings.ts` + - `src/lib/db/registeredKeys.ts` +- [ ] Cover branch behavior in: + - `src/lib/providers/validation.ts` + - `src/app/api/v1/embeddings/route.ts` + - `src/app/api/v1/moderations/route.ts` + +### Phase 3: 65% -> 70% + +- [ ] Add usage analytics tests for: + - `src/lib/usage/usageHistory.ts` + - `src/lib/usage/usageStats.ts` + - `src/lib/usage/costCalculator.ts` +- [ ] Expand route coverage for proxy management and settings branches + +### Phase 4: 70% -> 75% + +- [ ] Cover translator helpers and central translation paths: + - `open-sse/translator/index.ts` + - `open-sse/translator/helpers/*` + - `open-sse/translator/request/*` + - `open-sse/translator/response/*` + +### Phase 5: 75% -> 80% + +- [ ] Add handler-level tests for: + - `open-sse/handlers/chatCore.ts` + - `open-sse/handlers/responsesHandler.js` + - `open-sse/handlers/imageGeneration.js` + - `open-sse/handlers/embeddings.js` +- [ ] Add executor branch coverage for provider-specific auth, retries, and endpoint overrides + +### Phase 6: 80% -> 85% + +- [ ] Merge more edge-case suites into the main coverage path +- [ ] Increase function coverage for DB modules with weak constructor/helper coverage +- [ ] Close branch gaps in `settings.ts`, `registeredKeys.ts`, `validation.ts`, and translator helpers + +### Phase 7: 85% -> 90% + +- [ ] Treat the remaining low-coverage files as blockers +- [ ] Add regression tests for every uncovered production bug fixed during the push to 90% +- [ ] Raise the coverage gate in CI only after the local baseline is stable for at least two consecutive runs + +## Ratchet policy + +Update `npm run test:coverage` thresholds only after the project actually exceeds the next milestone with a comfortable buffer. + +Recommended ratchet sequence: + +1. 55/60/55 +2. 60/62/58 +3. 65/64/62 +4. 70/66/66 +5. 75/70/72 +6. 80/75/78 +7. 85/80/84 +8. 90/85/88 + +Order is `statements-lines / branches / functions`. + +## Known gap + +The current coverage command measures the main Node unit suite and includes source reached from it, including `open-sse`. It does not yet merge Vitest coverage into a single unified report. That merge is worth doing later, but it is not a blocker for starting the 60% -> 80% climb. diff --git a/docs/i18n/it/docs/FEATURES.md b/docs/i18n/it/docs/FEATURES.md index d3f56477a9..0a68fa7fc0 100644 --- a/docs/i18n/it/docs/FEATURES.md +++ b/docs/i18n/it/docs/FEATURES.md @@ -1,6 +1,6 @@ # OmniRoute โ€” Dashboard Features Gallery (Italiano) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/FEATURES.md) --- @@ -10,7 +10,7 @@ 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). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. ![Providers Dashboard](screenshots/01-providers.png) diff --git a/docs/i18n/it/docs/MCP-SERVER.md b/docs/i18n/it/docs/MCP-SERVER.md new file mode 100644 index 0000000000..87beb4a484 --- /dev/null +++ b/docs/i18n/it/docs/MCP-SERVER.md @@ -0,0 +1,87 @@ +# OmniRoute MCP Server Documentation (Italiano) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/MCP-SERVER.md) + +--- + +> Model Context Protocol server with 16 intelligent tools + +## Installare + +OmniRoute MCP is built-in. Start it with: + +```bash +omniroute --mcp +``` + +Or via the open-sse transport: + +```bash +# HTTP streamable transport (port 20130) +omniroute --dev # MCP auto-starts on /mcp endpoint +``` + +## IDE Configuration + +See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup. + +--- + +## Essential Tools (8) + +| Tool | Description | +| :------------------------------ | :--------------------------------------- | +| `omniroute_get_health` | Gateway health, circuit breakers, uptime | +| `omniroute_list_combos` | All configured combos with models | +| `omniroute_get_combo_metrics` | Performance metrics for a specific combo | +| `omniroute_switch_combo` | Switch active combo by ID/name | +| `omniroute_check_quota` | Quota status per provider or all | +| `omniroute_route_request` | Send a chat completion through OmniRoute | +| `omniroute_cost_report` | Cost analytics for a time period | +| `omniroute_list_models_catalog` | Full model catalog with capabilities | + +## Advanced Tools (8) + +| Tool | Description | +| :--------------------------------- | :---------------------------------------------------------- | +| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | +| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | +| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | +| `omniroute_test_combo` | Live-test all models in a combo via a real upstream request | +| `omniroute_get_provider_metrics` | Detailed metrics for one provider | +| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | +| `omniroute_explain_route` | Explain a past routing decision | +| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | + +## Authentication + +MCP tools are authenticated via API key scopes. Each tool requires specific scopes: + +| Scope | Tools | +| :------------- | :----------------------------------------------- | +| `read:health` | get_health, get_provider_metrics | +| `read:combos` | list_combos, get_combo_metrics | +| `write:combos` | switch_combo | +| `read:quota` | check_quota | +| `write:route` | route_request, simulate_route, test_combo | +| `read:usage` | cost_report, get_session_snapshot, explain_route | +| `write:config` | set_budget_guard, set_resilience_profile | +| `read:models` | list_models_catalog, best_combo_for_task | + +## Audit Logging + +Every tool call is logged to `mcp_tool_audit` with: + +- Tool name, arguments, result +- Duration (ms), success/failure +- API key hash, timestamp + +## Files + +| File | Purpose | +| :------------------------------------------- | :------------------------------------------ | +| `open-sse/mcp-server/server.ts` | MCP server creation + 16 tool registrations | +| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport | +| `open-sse/mcp-server/auth.ts` | API key + scope validation | +| `open-sse/mcp-server/audit.ts` | Tool call audit logging | +| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers | diff --git a/docs/i18n/it/docs/RELEASE_CHECKLIST.md b/docs/i18n/it/docs/RELEASE_CHECKLIST.md new file mode 100644 index 0000000000..b08d4c811d --- /dev/null +++ b/docs/i18n/it/docs/RELEASE_CHECKLIST.md @@ -0,0 +1,37 @@ +# Release Checklist (Italiano) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/RELEASE_CHECKLIST.md) + +--- + +Use this checklist before tagging or publishing a new OmniRoute release. + +## Version and Changelog + +1. Bump `package.json` version (`x.y.z`) in the release branch. +2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: + - `## [x.y.z] โ€” YYYY-MM-DD` +3. Keep `## [Unreleased]` as the first changelog section for upcoming work. +4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. + +## API Docs + +1. Update `docs/openapi.yaml`: + - `info.version` must equal `package.json` version. +2. Validate endpoint examples if API contracts changed. + +## Runtime Docs + +1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. +2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. +3. Update localized docs if source docs changed significantly. + +## Automated Check + +Run the sync guard locally before opening PR: + +```bash +npm run check:docs-sync +``` + +CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/it/docs/TROUBLESHOOTING.md b/docs/i18n/it/docs/TROUBLESHOOTING.md new file mode 100644 index 0000000000..6f42d1889f --- /dev/null +++ b/docs/i18n/it/docs/TROUBLESHOOTING.md @@ -0,0 +1,256 @@ +# Troubleshooting (Italiano) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/TROUBLESHOOTING.md) + +--- + +Common problems and solutions for OmniRoute. + +--- + +## Quick Fixes + +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | + +--- + +## Provider Issues + +### "Language model did not provide messages" + +**Cause:** Provider quota exhausted. + +**Fix:** + +1. 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, Qoder) 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}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) + +--- + +## Circuit Breaker Issues + +### Provider stuck in OPEN state + +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. + +**Fix:** + +1. 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 +- **SDK returns raw string instead of object** โ€” Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** โ€” Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** โ€” Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** โ€” Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` + +--- + +## Resilience Settings + +### Auto rate-limit not triggering + +- 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. + +--- + +## Optional RAG / LLM failure taxonomy (16 problems) + +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` โ€ฆ `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard โ†’ Health** for real-time system status +- **Translator**: Use **Dashboard โ†’ Translator** to debug format issues diff --git a/docs/i18n/it/USER_GUIDE.md b/docs/i18n/it/docs/USER_GUIDE.md similarity index 82% rename from docs/i18n/it/USER_GUIDE.md rename to docs/i18n/it/docs/USER_GUIDE.md index 326a32c1d0..2d6f3ccfa2 100644 --- a/docs/i18n/it/USER_GUIDE.md +++ b/docs/i18n/it/docs/USER_GUIDE.md @@ -1,8 +1,6 @@ # User Guide (Italiano) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/USER_GUIDE.md) - -> ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/USER_GUIDE.md) --- @@ -320,7 +318,7 @@ Model: cc/claude-opus-4-6 --- -## ๐Ÿš€ Deployment +## Distribuzione ### Global npm install (Recommended) @@ -511,23 +509,26 @@ post_install() { ### Environment Variables -| Variable | Default | Description | -| ------------------------- | ------------------------------------ | ------------------------------------------------------- | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | -| `INITIAL_PASSWORD` | `123456` | First login password | -| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | -| `PORT` | framework default | Service port (`20128` in examples) | -| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | -| `NODE_ENV` | runtime default | Set `production` for deploy | -| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | -| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | -| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | -| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | -| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | -| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | -| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | -| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | +| 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/*` | +| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand | +| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | For the full environment variable reference, see the [README](../README.md). @@ -598,6 +599,11 @@ curl -X POST http://localhost:20128/api/provider-models \ Or use Dashboard: **Providers โ†’ [Provider] โ†’ Custom Models**. +Notes: + +- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers. +- The **Custom Models** section is intended for providers that do not expose managed available-model imports. + ### Dedicated Provider Routes Route requests directly to a specific provider with model validation: @@ -642,6 +648,14 @@ Returns models grouped by provider with types (`chat`, `embedding`, `image`). - Automatic background sync with timeout + fail-fast - Prefer server-side `BASE_URL`/`CLOUD_URL` in production +### Cloudflare Quick Tunnel + +- Available in **Dashboard โ†’ Endpoints** for Docker and other self-hosted deployments +- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint +- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary +- Tunnel URLs are ephemeral and change every time you stop/start the tunnel +- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download + ### LLM Gateway Intelligence (Phase 9) - **Semantic Cache** โ€” Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) @@ -757,11 +771,11 @@ OmniRoute implements provider-level resilience with four components: 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 | +| 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 unless `DISABLE_SQLITE_AUTO_BACKUP=true` | ```bash # API: Export database @@ -787,10 +801,11 @@ curl -X POST http://localhost:20128/api/db-backups/import \ ### Settings Dashboard -The settings page is organized into 5 tabs for easy navigation: +The settings page is organized into 6 tabs for easy navigation: | Tab | Contents | | -------------- | ---------------------------------------------------------------------------------------------- | +| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility | | **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | | **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | | **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | diff --git a/docs/i18n/da/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/it/docs/VM_DEPLOYMENT_GUIDE.md similarity index 55% rename from docs/i18n/da/VM_DEPLOYMENT_GUIDE.md rename to docs/i18n/it/docs/VM_DEPLOYMENT_GUIDE.md index b71c827936..eeb82d3452 100644 --- a/docs/i18n/da/VM_DEPLOYMENT_GUIDE.md +++ b/docs/i18n/it/docs/VM_DEPLOYMENT_GUIDE.md @@ -1,50 +1,52 @@ -# OmniRoute โ€” Installationsvejledning pรฅ VM med Cloudflare +# OmniRoute โ€” Deployment Guide on VM with Cloudflare (Italiano) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](../pt-BR/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](../es/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](../fr/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](../it/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](../ru/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](../zh-CN/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](../de/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](../in/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](../th/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](../uk-UA/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](../ar/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](../ja/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](../vi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](../bg/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](../da/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](../fi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](../he/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](../hu/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](../id/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](../ko/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](../ms/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](../nl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](../no/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](../pt/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](../ro/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](../pl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](../sk/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](../sv/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](../phi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](../cs/VM_DEPLOYMENT_GUIDE.md) - -Komplet guide til at installere og konfigurere OmniRoute pรฅ en VM (VPS) med domรฆne administreret via Cloudflare. +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/VM_DEPLOYMENT_GUIDE.md) --- -## Forudsรฆtninger - -| Vare | Minimum | Anbefalet | -| ---------- | ------------------------- | ---------------- | -| **CPU** | 1 vCPU | 2 vCPU | -| **RAM** | 1 GB | 2 GB | -| **Disk** | 10 GB SSD | 25 GB SSD | -| **OS** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS | -| **Domรฆne** | Registreret pรฅ Cloudflare | โ€” | -| **Docker** | Docker Engine 24+ | Docker 27+ | - -**Testede udbydere**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. +Complete guide to install and configure OmniRoute on a VM (VPS) with domain managed via Cloudflare. --- -## 1. Konfigurer VM'en +## Prerequisites -### 1.1 Opret instansen +| Item | Minimum | Recommended | +| ---------- | ------------------------ | ---------------- | +| **CPU** | 1 vCPU | 2 vCPU | +| **RAM** | 1 GB | 2 GB | +| **Disk** | 10 GB SSD | 25 GB SSD | +| **OS** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS | +| **Domain** | Registered on Cloudflare | โ€” | +| **Docker** | Docker Engine 24+ | Docker 27+ | -Pรฅ din foretrukne VPS-udbyder: +**Tested providers**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. -- Vรฆlg Ubuntu 24.04 LTS -- Vรฆlg minimumsplanen (1 vCPU / 1 GB RAM) -- Indstil en stรฆrk root-adgangskode eller konfigurer SSH-nรธgle -- Bemรฆrk den **offentlige IP** (f.eks. `203.0.113.10`) +--- -### 1.2 Tilslut via SSH +## 1. Configure the VM + +### 1.1 Create the instance + +On your preferred VPS provider: + +- Choose Ubuntu 24.04 LTS +- Select the minimum plan (1 vCPU / 1 GB RAM) +- Set a strong root password or configure SSH key +- Note the **public IP** (e.g., `203.0.113.10`) + +### 1.2 Connect via SSH ```bash ssh root@203.0.113.10 ``` -### 1.3 Opdater systemet +### 1.3 Update the system ```bash apt update && apt upgrade -y ``` -### 1.4 Installer Docker +### 1.4 Install Docker ```bash # Install dependencies @@ -59,13 +61,13 @@ apt update apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin ``` -### 1.5 Installer nginx +### 1.5 Install nginx ```bash apt install -y nginx ``` -### 1.6 Konfigurer firewall (UFW) +### 1.6 Configure Firewall (UFW) ```bash ufw default deny incoming @@ -76,19 +78,19 @@ ufw allow 443/tcp # HTTPS ufw enable ``` -> **Tip**: For maksimal sikkerhed skal du begrรฆnse porte 80 og 443 til kun Cloudflare IP'er. Se afsnittet [Advanced Security](#advanced-security). +> **Tip**: For maximum security, restrict ports 80 and 443 to Cloudflare IPs only. See the [Advanced Security](#advanced-security) section. --- -## 2. Installer OmniRoute +## 2. Install OmniRoute -### 2.1 Opret konfigurationsmappe +### 2.1 Create configuration directory ```bash mkdir -p /opt/omniroute ``` -### 2.2 Opret fil med miljรธvariabler +### 2.2 Create environment variables file ```bash cat > /opt/omniroute/.env << โ€˜EOFโ€™ @@ -120,9 +122,9 @@ NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com EOF ``` -> โš ๏ธ **VIGTIG**: Generer unikke hemmelige nรธgler! Brug `openssl rand -hex 32` for hver nรธgle. +> โš ๏ธ **IMPORTANT**: Generate unique secret keys! Use `openssl rand -hex 32` for each key. -### 2.3 Start beholderen +### 2.3 Start the container ```bash docker pull diegosouzapw/omniroute:latest @@ -136,27 +138,27 @@ docker run -d \ diegosouzapw/omniroute:latest ``` -### 2.4 Bekrรฆft, at den kรธrer +### 2.4 Verify that it is running ```bash docker ps | grep omniroute docker logs omniroute --tail 20 ``` -Den skal vise: `[DB] SQLite database ready` og `listening on port 20128`. +It should display: `[DB] SQLite database ready` and `listening on port 20128`. --- -## 3. Konfigurer nginx (omvendt proxy) +## 3. Configure nginx (Reverse Proxy) -### 3.1 Generer SSL-certifikat (Cloudflare Origin) +### 3.1 Generate SSL certificate (Cloudflare Origin) -I Cloudflare-dashboardet: +In the Cloudflare dashboard: -1. Gรฅ til **SSL/TLS โ†’ Origin Server** -2. Klik pรฅ **Opret certifikat** -3. Behold standardindstillingerne (15 รฅr, \*.ditdomรฆne.com) -4. Kopiรฉr **Oprindelsescertifikatet** og den **Private nรธgle** +1. Go to **SSL/TLS โ†’ Origin Server** +2. Click **Create Certificate** +3. Keep the defaults (15 years, \*.yourdomain.com) +4. Copy the **Origin Certificate** and the **Private Key** ```bash mkdir -p /etc/nginx/ssl @@ -170,7 +172,7 @@ nano /etc/nginx/ssl/origin.key chmod 600 /etc/nginx/ssl/origin.key ``` -### 3.2 Nginx-konfiguration +### 3.2 Nginx Configuration ```bash cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ @@ -228,7 +230,7 @@ server { NGINX ``` -### 3.3 Aktiver og test +### 3.3 Enable and Test ```bash # Remove default configuration @@ -243,29 +245,29 @@ nginx -t && systemctl reload nginx --- -## 4. Konfigurer Cloudflare DNS +## 4. Configure Cloudflare DNS -### 4.1 Tilfรธj DNS-post +### 4.1 Add DNS record -I Cloudflare-dashboardet โ†’ DNS: +In the Cloudflare dashboard โ†’ DNS: -| Skriv | Navn | Indhold | Fuldmagt | -| ----- | ------ | ---------------------- | ----------- | -| A | `llms` | `203.0.113.10` (VM IP) | โœ… Fuldmagt | +| Type | Name | Content | Proxy | +| ---- | ------ | ---------------------- | ---------- | +| A | `llms` | `203.0.113.10` (VM IP) | โœ… Proxied | -### 4.2 Konfigurer SSL +### 4.2 Configure SSL -Under **SSL/TLS โ†’ Oversigt**: +Under **SSL/TLS โ†’ Overview**: -- Tilstand: **Fuld (streng)** +- Mode: **Full (Strict)** -Under **SSL/TLS โ†’ Edge-certifikater**: +Under **SSL/TLS โ†’ Edge Certificates**: -- Brug altid HTTPS: โœ… Til -- Minimum TLS-version: TLS 1.2 -- Automatiske HTTPS-omskrivninger: โœ… Til +- Always Use HTTPS: โœ… On +- Minimum TLS Version: TLS 1.2 +- Automatic HTTPS Rewrites: โœ… On -### 4.3 Test +### 4.3 Testing ```bash curl -sI https://llms.seudominio.com/health @@ -274,9 +276,9 @@ curl -sI https://llms.seudominio.com/health --- -## 5. Drift og vedligeholdelse +## 5. Operations and Maintenance -### Opgrader til en ny version +### Upgrade to a new version ```bash docker pull diegosouzapw/omniroute:latest @@ -288,14 +290,14 @@ docker run -d --name omniroute --restart unless-stopped \ diegosouzapw/omniroute:latest ``` -### Se logfiler +### View logs ```bash docker logs -f omniroute # Real-time stream docker logs omniroute --tail 50 # Last 50 lines ``` -### Manuel database backup +### Manual database backup ```bash # Copy data from the volume to the host @@ -306,7 +308,7 @@ docker run --rm -v omniroute-data:/data -v $(pwd):/backup \ alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data ``` -### Gendan fra backup +### Restore from backup ```bash docker stop omniroute @@ -317,9 +319,9 @@ docker start omniroute --- -## 6. Avanceret sikkerhed +## 6. Advanced Security -### Begrรฆns nginx til Cloudflare IP'er +### Restrict nginx to Cloudflare IPs ```bash cat > /etc/nginx/cloudflare-ips.conf << โ€˜CFโ€™ @@ -344,13 +346,13 @@ real_ip_header CF-Connecting-IP; CF ``` -Tilfรธj fรธlgende til `nginx.conf` inde i `http {}` blokken: +Add the following to `nginx.conf` inside the `http {}` block: ```nginx include /etc/nginx/cloudflare-ips.conf; ``` -### Installer fail2ban +### Install fail2ban ```bash apt install -y fail2ban @@ -361,7 +363,7 @@ systemctl start fail2ban fail2ban-client status sshd ``` -### Bloker direkte adgang til Docker-porten +### Block direct access to the Docker port ```bash # Prevent direct external access to port 20128 @@ -375,9 +377,9 @@ netfilter-persistent save --- -## 7. Implementer til Cloudflare-arbejdere (valgfrit) +## 7. Deploy to Cloudflare Workers (Optional) -For fjernadgang via Cloudflare Workers (uden at eksponere VM'en direkte): +For remote access via Cloudflare Workers (without exposing the VM directly): ```bash # In the local repository @@ -387,15 +389,15 @@ npx wrangler login npx wrangler deploy ``` -Se den fulde dokumentation pรฅ [omnirouteCloud/README.md](../omnirouteCloud/README.md). +See the full documentation at [omnirouteCloud/README.md](../omnirouteCloud/README.md). --- -## Portoversigt +## Port Summary -| Havn | Service | Adgang | -| ----- | ----------- | ------------------------- | -| 22 | SSH | Offentlig (med fail2ban) | -| 80 | nginx HTTP | Omdirigering โ†’ HTTPS | -| 443 | nginx HTTPS | Via Cloudflare Proxy | -| 20128 | OmniRoute | Kun Localhost (via nginx) | +| Port | Service | Access | +| ----- | ----------- | -------------------------- | +| 22 | SSH | Public (with fail2ban) | +| 80 | nginx HTTP | Redirect โ†’ HTTPS | +| 443 | nginx HTTPS | Via Cloudflare Proxy | +| 20128 | OmniRoute | Localhost only (via nginx) | diff --git a/docs/i18n/it/src/lib/a2a/README.md b/docs/i18n/it/src/lib/a2a/README.md new file mode 100644 index 0000000000..b4812584a4 --- /dev/null +++ b/docs/i18n/it/src/lib/a2a/README.md @@ -0,0 +1,752 @@ +# OmniRoute A2A Server (Italiano) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../../../src/lib/a2a/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../../../es/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../../../fr/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../../../de/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../../../it/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../../../ru/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../../../zh-CN/src/lib/a2a/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../../../ja/src/lib/a2a/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../../../ko/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../../../ar/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../../../in/src/lib/a2a/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../../../th/src/lib/a2a/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../../../vi/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../../../id/src/lib/a2a/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../../../ms/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../../../nl/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../../../pl/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../../../sv/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../../../no/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../../../da/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../../../fi/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../../../pt/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../../../ro/src/lib/a2a/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../../../hu/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../../../bg/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../../../sk/src/lib/a2a/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../../../uk-UA/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../../../he/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../../../phi/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../../../pt-BR/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../../../cs/src/lib/a2a/README.md) + +--- + +> **Agent-to-Agent Protocol v0.3** โ€” Enables any AI agent to use OmniRoute as an intelligent routing agent via JSON-RPC 2.0. + +The A2A Server exposes OmniRoute as a **first-class agent** that other agents can discover, delegate tasks to, and collaborate with using the [A2A Protocol](https://google.github.io/A2A/). + +--- + +## Architettura + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Orchestrator Agent โ”‚ +โ”‚ (LangChain, CrewAI, AutoGen, Custom Agent) โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ 1. GET /.well-known/agent.json (discover) + โ”‚ 2. POST /a2a (JSON-RPC 2.0) + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ OmniRoute A2A Server โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Task Manager โ”‚ โ”‚ Skill Engine โ”‚ โ”‚ SSE Streaming โ”‚ โ”‚ +โ”‚ โ”‚ (lifecycle) โ”‚โ”€โ”€โ”‚ (registry) โ”‚โ”€โ”€โ”‚ (real-time) โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ +โ”‚ Skills: โ”‚ โ”‚ +โ”‚ โ”œโ”€ smart-routing โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ””โ”€ quota-management โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ Routing Decision Logger โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ OmniRoute Gateway (internal) + /v1/chat/completions, /api/combos, /api/usage/quota +``` + +--- + +## Avvio Rapido + +### Agent Discovery + +Every A2A-compatible agent exposes an **Agent Card** at `/.well-known/agent.json`: + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +**Response:** + +```json +{ + "name": "OmniRoute", + "description": "Intelligent AI gateway with auto-routing across 50+ providers", + "url": "http://localhost:20128/a2a", + "version": "1.8.1", + "capabilities": { + "streaming": true, + "pushNotifications": false + }, + "skills": [ + { + "id": "smart-routing", + "name": "Smart Routing", + "description": "Routes prompts through OmniRoute intelligent pipeline", + "tags": ["routing", "llm", "multi-provider", "cost-optimization"], + "examples": [ + "Write a hello world in Python", + "Explain quantum computing using the cheapest provider" + ] + }, + { + "id": "quota-management", + "name": "Quota Management", + "description": "Natural-language queries about provider quotas", + "tags": ["quota", "analytics", "cost"], + "examples": [ + "Which provider has the most quota remaining?", + "Suggest a free combo for coding" + ] + } + ], + "authentication": { + "schemes": ["bearer"], + "apiKeyHeader": "Authorization" + } +} +``` + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Send a message to a skill and receive the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python hello world"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "a1b2c3d4-...", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "print('Hello, World!')" }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.0030)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "2026-03-04T..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"Quantum computing..."}}} + +: heartbeat 2026-03-04T21:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Running Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Skills Reference + +### `smart-routing` + +Routes prompts through OmniRoute's intelligent pipeline with full observability. + +**Parameters (in `metadata`):** + +| Parameter | Type | Default | Description | +| --------- | -------- | ------------ | ---------------------------------------------------------------------------------------- | +| `model` | `string` | `"auto"` | Target model (e.g., `claude-sonnet-4`, `gpt-4o`, `auto`) | +| `combo` | `string` | active combo | Specific combo to route through | +| `budget` | `number` | none | Maximum cost in USD for this request | +| `role` | `string` | none | Task role hint: `coding`, `review`, `planning`, `analysis`, `debugging`, `documentation` | + +**Returns:** + +| Field | Description | +| ------------------------------ | --------------------------------------------------------- | +| `artifacts[].content` | The LLM response text | +| `metadata.routing_explanation` | Human-readable explanation of routing decision | +| `metadata.cost_envelope` | Estimated vs actual cost with currency | +| `metadata.resilience_trace` | Array of events (primary_selected, fallback_needed, etc.) | +| `metadata.policy_verdict` | Whether the request was allowed and why | + +### `quota-management` + +Answers natural-language queries about provider quotas. + +**Query types (inferred from message content):** + +| Query Pattern | Response Type | +| ---------------------------------------------- | -------------------------------------------------------- | +| Contains `"ranking"`, `"most quota"`, `"best"` | Providers ranked by remaining quota | +| Contains `"free"`, `"suggest"` | Lists free combos or suggests free-tier providers | +| Default | Full quota summary with warnings for low-quota providers | + +--- + +## Task Lifecycle + +``` +submitted โ”€โ”€โ†’ working โ”€โ”€โ†’ completed + โ”€โ”€โ†’ failed + โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ†’ cancelled +``` + +| State | Description | +| ----------- | ----------------------------------------------------- | +| `submitted` | Task created, queued for execution | +| `working` | Skill handler is executing | +| `completed` | Execution succeeded, artifacts available | +| `failed` | Execution failed or task expired (TTL: 5 min default) | +| `cancelled` | Cancelled by client via `tasks/cancel` | + +- Terminal states: `completed`, `failed`, `cancelled` (no further transitions) +- Expired tasks in `submitted` or `working` are auto-marked as `failed` +- Tasks are garbage-collected after 2ร— TTL + +--- + +## Client Examples + +### Python โ€” Orchestrator Agent + +```python +""" +A2A Client โ€” Python example. +Discovers OmniRoute agent, sends a task, and processes the result. +""" +import requests +import json + +BASE_URL = "http://localhost:20128" +API_KEY = "your-api-key" +HEADERS = { + "Content-Type": "application/json", + "Authorization": f"Bearer {API_KEY}", +} + +# 1. Discover agent capabilities +agent_card = requests.get(f"{BASE_URL}/.well-known/agent.json").json() +print(f"Agent: {agent_card['name']} v{agent_card['version']}") +print(f"Skills: {[s['id'] for s in agent_card['skills']]}") + +# 2. Send a smart-routing task +response = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python quicksort implementation"}], + "metadata": { + "model": "auto", + "combo": "fast-coding", + "budget": 0.10, + } + } +}) +result = response.json()["result"] +print(f"\n๐Ÿ“ Response: {result['artifacts'][0]['content'][:200]}...") +print(f"๐Ÿ”€ Routing: {result['metadata']['routing_explanation']}") +print(f"๐Ÿ’ฐ Cost: ${result['metadata']['cost_envelope']['actual']}") +print(f"๐Ÿ›ก๏ธ Policy: {result['metadata']['policy_verdict']['reason']}") + +# 3. Query quota status +quota_resp = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-2", + "method": "message/send", + "params": { + "skill": "quota-management", + "messages": [{"role": "user", "content": "Which provider has the most quota remaining?"}], + } +}) +quota_result = quota_resp.json()["result"] +print(f"\n๐Ÿ“Š Quota: {quota_result['artifacts'][0]['content']}") +``` + +### TypeScript โ€” Multi-Agent Orchestrator + +```typescript +/** + * A2A Client โ€” TypeScript example. + * Shows agent discovery, task delegation, and streaming. + */ + +const BASE_URL = "http://localhost:20128"; +const API_KEY = "your-api-key"; + +interface JsonRpcResponse { + jsonrpc: "2.0"; + id: string | number; + result?: T; + error?: { code: number; message: string }; +} + +async function a2aCall(method: string, params: Record): Promise { + const resp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: `${method}-${Date.now()}`, + method, + params, + }), + }); + const json: JsonRpcResponse = await resp.json(); + if (json.error) throw new Error(`[${json.error.code}] ${json.error.message}`); + return json.result!; +} + +// โ”€โ”€ Agent Discovery โ”€โ”€ +const agentCard = await fetch(`${BASE_URL}/.well-known/agent.json`).then((r) => r.json()); +console.log(`Connected to: ${agentCard.name} (${agentCard.skills.length} skills)`); + +// โ”€โ”€ Smart Routing: Send a coding task โ”€โ”€ +const routingResult = await a2aCall("message/send", { + skill: "smart-routing", + messages: [{ role: "user", content: "Implement a Redis cache wrapper in TypeScript" }], + metadata: { model: "claude-sonnet-4", role: "coding" }, +}); +console.log("Response:", routingResult.artifacts[0].content); +console.log("Provider:", routingResult.metadata.routing_explanation); + +// โ”€โ”€ Quota Management: Find free alternatives โ”€โ”€ +const quotaResult = await a2aCall("message/send", { + skill: "quota-management", + messages: [{ role: "user", content: "Suggest free combos for documentation" }], +}); +console.log("Free combos:", quotaResult.artifacts[0].content); + +// โ”€โ”€ Streaming: Real-time response โ”€โ”€ +const streamResp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "stream-1", + method: "message/stream", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Explain microservices architecture" }], + }, + }), +}); + +const reader = streamResp.body!.getReader(); +const decoder = new TextDecoder(); +while (true) { + const { done, value } = await reader.read(); + if (done) break; + const chunk = decoder.decode(value); + for (const line of chunk.split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + if (event.params.chunk) { + process.stdout.write(event.params.chunk.content); + } + if (event.params.task.state === "completed") { + console.log("\nโœ… Stream completed"); + } + } + } +} +``` + +### Python โ€” LangChain A2A Integration + +```python +""" +LangChain integration โ€” Use OmniRoute A2A as a custom LLM. +""" +from langchain.llms.base import BaseLLM +from langchain.schema import LLMResult, Generation +import requests +from typing import List, Optional + +class OmniRouteA2A(BaseLLM): + base_url: str = "http://localhost:20128" + api_key: str = "" + model: str = "auto" + combo: Optional[str] = None + + @property + def _llm_type(self) -> str: + return "omniroute-a2a" + + def _call(self, prompt: str, stop: Optional[List[str]] = None, **kwargs) -> str: + response = requests.post( + f"{self.base_url}/a2a", + headers={ + "Content-Type": "application/json", + "Authorization": f"Bearer {self.api_key}", + }, + json={ + "jsonrpc": "2.0", + "id": "langchain-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": prompt}], + "metadata": { + "model": self.model, + **({"combo": self.combo} if self.combo else {}), + }, + }, + }, + ) + result = response.json()["result"] + return result["artifacts"][0]["content"] + + def _generate(self, prompts: List[str], stop=None, **kwargs) -> LLMResult: + return LLMResult( + generations=[[Generation(text=self._call(p, stop))] for p in prompts] + ) + +# Usage +llm = OmniRouteA2A( + base_url="http://localhost:20128", + api_key="your-key", + model="auto", + combo="fast-coding", +) +result = llm("Write a Python function to merge two sorted lists") +print(result) +``` + +### Go โ€” A2A Client + +```go +package main + +import ( + "bytes" + "encoding/json" + "fmt" + "io" + "net/http" +) + +const baseURL = "http://localhost:20128" +const apiKey = "your-api-key" + +type JsonRpcRequest struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Method string `json:"method"` + Params interface{} `json:"params"` +} + +type JsonRpcResponse struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Result interface{} `json:"result"` + Error *struct { + Code int `json:"code"` + Message string `json:"message"` + } `json:"error"` +} + +func a2aCall(method string, params interface{}) (*JsonRpcResponse, error) { + body, _ := json.Marshal(JsonRpcRequest{ + Jsonrpc: "2.0", + ID: "go-1", + Method: method, + Params: params, + }) + + req, _ := http.NewRequest("POST", baseURL+"/a2a", bytes.NewReader(body)) + req.Header.Set("Content-Type", "application/json") + req.Header.Set("Authorization", "Bearer "+apiKey) + + resp, err := http.DefaultClient.Do(req) + if err != nil { + return nil, err + } + defer resp.Body.Close() + data, _ := io.ReadAll(resp.Body) + + var result JsonRpcResponse + json.Unmarshal(data, &result) + return &result, nil +} + +func main() { + // Discover agent + resp, _ := http.Get(baseURL + "/.well-known/agent.json") + defer resp.Body.Close() + body, _ := io.ReadAll(resp.Body) + fmt.Println("Agent Card:", string(body)) + + // Send smart-routing task + result, _ := a2aCall("message/send", map[string]interface{}{ + "skill": "smart-routing", + "messages": []map[string]string{{"role": "user", "content": "Hello from Go!"}}, + "metadata": map[string]interface{}{"model": "auto"}, + }) + out, _ := json.MarshalIndent(result.Result, "", " ") + fmt.Println("Result:", string(out)) +} +``` + +--- + +## Use Cases + +### ๐Ÿค– Use Case 1: Multi-Agent Coding Pipeline + +An orchestrator agent delegates code generation to OmniRoute, then passes the output to a review agent. + +```python +def coding_pipeline(task: str): + # Step 1: Generate code via OmniRoute A2A + code_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Write production-quality code: {task}"} + ], metadata={"model": "auto", "role": "coding"}) + code = code_result["artifacts"][0]["content"] + + # Step 2: Review the code via OmniRoute A2A (different model) + review_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Review this code for bugs and improvements:\n\n{code}"} + ], metadata={"model": "auto", "role": "review"}) + review = review_result["artifacts"][0]["content"] + + # Step 3: Check costs + print(f"Code cost: ${code_result['metadata']['cost_envelope']['actual']}") + print(f"Review cost: ${review_result['metadata']['cost_envelope']['actual']}") + + return {"code": code, "review": review} +``` + +### ๐Ÿ’ก Use Case 2: Quota-Aware Agent Swarm + +Multiple agents share quota through OmniRoute, using the quota skill to coordinate. + +```python +async def quota_aware_agent(agent_name: str, task: str): + # Check quota before starting + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Which provider has the most quota remaining?"} + ]) + print(f"[{agent_name}] {quota['artifacts'][0]['content']}") + + # Send request with budget constraint + result = a2a_send("smart-routing", [ + {"role": "user", "content": task} + ], metadata={"budget": 0.05}) + + policy = result["metadata"]["policy_verdict"] + if not policy["allowed"]: + print(f"[{agent_name}] โš ๏ธ Budget exceeded: {policy['reason']}") + # Fall back to free combo + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Suggest free combos"} + ]) + print(f"[{agent_name}] Free alternatives: {quota['artifacts'][0]['content']}") + + return result +``` + +### ๐Ÿ“Š Use Case 3: Real-Time Streaming Dashboard + +A monitoring agent streams responses and displays progress in real-time. + +```typescript +async function streamingDashboard(prompt: string) { + const response = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { "Content-Type": "application/json", Authorization: `Bearer ${API_KEY}` }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "dash-1", + method: "message/stream", + params: { skill: "smart-routing", messages: [{ role: "user", content: prompt }] }, + }), + }); + + let totalChunks = 0; + const reader = response.body!.getReader(); + const decoder = new TextDecoder(); + + while (true) { + const { done, value } = await reader.read(); + if (done) break; + + for (const line of decoder.decode(value).split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + const state = event.params.task.state; + + if (state === "working" && event.params.chunk) { + totalChunks++; + process.stdout.write( + `\r[Chunk ${totalChunks}] ${event.params.chunk.content.slice(0, 50)}...` + ); + } + if (state === "completed") { + const meta = event.params.metadata; + console.log( + `\nโœ… Done | Cost: $${meta?.cost_envelope?.actual || 0} | Route: ${meta?.routing_explanation || "N/A"}` + ); + } + if (state === "failed") { + console.error(`\nโŒ Failed: ${event.params.metadata?.error}`); + } + } + } + } +} +``` + +### ๐Ÿ” Use Case 4: Task Polling Pattern + +For long-running tasks, poll the task status instead of waiting synchronously. + +```python +import time + +def poll_task(task_id: str, timeout: int = 60): + """Poll task status until completion or timeout.""" + start = time.time() + while time.time() - start < timeout: + result = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "poll-1", + "method": "tasks/get", + "params": {"taskId": task_id}, + }).json() + + task = result["result"]["task"] + state = task["state"] + print(f" Task {task_id[:8]}... state={state}") + + if state in ("completed", "failed", "cancelled"): + return task + time.sleep(2) + + # Timeout โ€” cancel the task + requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "cancel-1", + "method": "tasks/cancel", + "params": {"taskId": task_id}, + }) + raise TimeoutError(f"Task {task_id} timed out after {timeout}s") +``` + +--- + +## Error Codes + +| Code | Constant | Meaning | +| ------ | ------------------------ | ---------------------------------------- | +| -32700 | โ€” | Parse error (invalid JSON) | +| -32600 | `INVALID_REQUEST` | Invalid JSON-RPC request or unauthorized | +| -32601 | `METHOD_NOT_FOUND` | Unknown method or skill | +| -32602 | `INVALID_PARAMS` | Missing or invalid parameters | +| -32603 | `INTERNAL_ERROR` | Skill execution failed | +| -32001 | `TASK_NOT_FOUND` | Task ID not found | +| -32002 | `TASK_ALREADY_COMPLETED` | Cannot modify a completed task | +| -32003 | `UNAUTHORIZED` | Invalid or missing API key | +| -32004 | `BUDGET_EXCEEDED` | Request exceeds configured budget | +| -32005 | `PROVIDER_UNAVAILABLE` | No available providers | + +--- + +## Authentication + +All `/a2a` requests require a Bearer token via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server (`OMNIROUTE_API_KEY` is empty), authentication is bypassed. + +--- + +## File Structure + +``` +src/lib/a2a/ +โ”œโ”€โ”€ taskManager.ts # Task lifecycle (create/update/cancel/list), TTL, cleanup +โ”œโ”€โ”€ taskExecution.ts # Generic task executor with state management +โ”œโ”€โ”€ streaming.ts # SSE stream formatting, heartbeat, chunk/completion events +โ”œโ”€โ”€ routingLogger.ts # Routing decision logger (stats, history, retention) +โ””โ”€โ”€ skills/ + โ”œโ”€โ”€ smartRouting.ts # Smart routing skill (routes via /v1/chat/completions) + โ””โ”€โ”€ quotaManagement.ts # Quota management skill (natural-language quota queries) + +src/app/a2a/ +โ””โ”€โ”€ route.ts # Next.js API route handler (JSON-RPC 2.0 dispatch) + +open-sse/mcp-server/ +โ””โ”€โ”€ schemas/a2a.ts # Zod schemas (AgentCard, Task, JSON-RPC, SSE events) +``` + +--- + +## Comparison: MCP vs A2A + +| Feature | MCP Server | A2A Server | +| ----------------- | ---------------------------- | ------------------------------------------------- | +| **Protocol** | Model Context Protocol | Agent-to-Agent Protocol v0.3 | +| **Transport** | stdio / HTTP | HTTP (JSON-RPC 2.0) | +| **Discovery** | Tool listing via MCP | `/.well-known/agent.json` | +| **Granularity** | 16 individual tools | 2 high-level skills | +| **Best for** | IDE agents (Cursor, VS Code) | Multi-agent systems (LangChain, CrewAI) | +| **Streaming** | Not supported | SSE via `message/stream` | +| **Task tracking** | No | Full lifecycle (submitted โ†’ completed) | +| **Observability** | Audit log per tool call | Cost envelope + resilience trace + policy verdict | + +--- + +## Licenza + +Part of [OmniRoute](https://github.com/diegosouzapw/OmniRoute) โ€” MIT License. diff --git a/docs/i18n/ja/A2A-SERVER.md b/docs/i18n/ja/A2A-SERVER.md deleted file mode 100644 index 01531ff482..0000000000 --- a/docs/i18n/ja/A2A-SERVER.md +++ /dev/null @@ -1,200 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/A2A-SERVER.md) - ---- - -# OmniRoute A2A Server Documentation - -> Agent-to-Agent Protocol v0.3 โ€” OmniRoute as an intelligent routing agent - -## Agent Discovery - -```bash -curl http://localhost:20128/.well-known/agent.json -``` - -Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements. - ---- - -## Authentication - -All `/a2a` requests require an API key via the `Authorization` header: - -``` -Authorization: Bearer YOUR_OMNIROUTE_API_KEY -``` - -If no API key is configured on the server, authentication is bypassed. - ---- - -## JSON-RPC 2.0 Methods - -### `message/send` โ€” Synchronous Execution - -Sends a message to a skill and waits for the complete response. - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{ - "jsonrpc": "2.0", - "id": "1", - "method": "message/send", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Write a hello world in Python"}], - "metadata": {"model": "auto", "combo": "fast-coding"} - } - }' -``` - -**Response:** - -```json -{ - "jsonrpc": "2.0", - "id": "1", - "result": { - "task": { "id": "uuid", "state": "completed" }, - "artifacts": [{ "type": "text", "content": "..." }], - "metadata": { - "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)", - "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, - "resilience_trace": [ - { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." } - ], - "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } - } - } -} -``` - -### `message/stream` โ€” SSE Streaming - -Same as `message/send` but returns Server-Sent Events for real-time streaming. - -```bash -curl -N -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{ - "jsonrpc": "2.0", - "id": "1", - "method": "message/stream", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Explain quantum computing"}] - } - }' -``` - -**SSE Events:** - -``` -data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}} - -: heartbeat 2026-03-03T17:00:00Z - -data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} -``` - -### `tasks/get` โ€” Query Task Status - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' -``` - -### `tasks/cancel` โ€” Cancel a Task - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' -``` - ---- - -## Available Skills - -| Skill | Description | -| :----------------- | :------------------------------------------------------------------------------------------------------------------------------ | -| `smart-routing` | Routes prompts through OmniRoute's intelligent pipeline. Returns response with routing explanation, cost, and resilience trace. | -| `quota-management` | Answers natural-language queries about provider quotas, suggests free combos, and provides quota rankings. | - ---- - -## Task Lifecycle - -``` -submitted โ†’ working โ†’ completed - โ†’ failed - โ†’ cancelled -``` - -- Tasks expire after 5 minutes (configurable) -- Terminal states: `completed`, `failed`, `cancelled` -- Event log tracks every state transition - ---- - -## Error Codes - -| Code | Meaning | -| :----- | :----------------------------- | -| -32700 | Parse error (invalid JSON) | -| -32600 | Invalid request / Unauthorized | -| -32601 | Method or skill not found | -| -32602 | Invalid params | -| -32603 | Internal error | - ---- - -## Integration Examples - -### Python (requests) - -```python -import requests - -resp = requests.post("http://localhost:20128/a2a", json={ - "jsonrpc": "2.0", "id": "1", - "method": "message/send", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Hello"}] - } -}, headers={"Authorization": "Bearer YOUR_KEY"}) - -result = resp.json()["result"] -print(result["artifacts"][0]["content"]) -print(result["metadata"]["routing_explanation"]) -``` - -### TypeScript (fetch) - -```typescript -const resp = await fetch("http://localhost:20128/a2a", { - method: "POST", - headers: { - "Content-Type": "application/json", - Authorization: "Bearer YOUR_KEY", - }, - body: JSON.stringify({ - jsonrpc: "2.0", - id: "1", - method: "message/send", - params: { - skill: "smart-routing", - messages: [{ role: "user", content: "Hello" }], - }, - }), -}); -const { result } = await resp.json(); -console.log(result.metadata.routing_explanation); -``` diff --git a/docs/i18n/ja/API_REFERENCE.md b/docs/i18n/ja/API_REFERENCE.md deleted file mode 100644 index b878605221..0000000000 --- a/docs/i18n/ja/API_REFERENCE.md +++ /dev/null @@ -1,455 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/API_REFERENCE.md) - ---- - -# API Reference - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/API_REFERENCE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/API_REFERENCE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/API_REFERENCE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/API_REFERENCE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/API_REFERENCE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/API_REFERENCE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/API_REFERENCE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/API_REFERENCE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/API_REFERENCE.md) - -Complete reference for all OmniRoute API endpoints. - ---- - -## Table of Contents - -- [Chat Completions](#chat-completions) -- [Embeddings](#embeddings) -- [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`. - -### ACP Agents - -| Endpoint | Method | Description | -| ----------------- | ------ | -------------------------------------------------------- | -| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | -| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | -| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | - -GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). - -### Resilience & Rate Limits - -| Endpoint | Method | Description | -| ----------------------- | ------- | ------------------------------- | -| `/api/resilience` | 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` diff --git a/docs/i18n/ja/ARCHITECTURE.md b/docs/i18n/ja/ARCHITECTURE.md deleted file mode 100644 index 4ea06a29f2..0000000000 --- a/docs/i18n/ja/ARCHITECTURE.md +++ /dev/null @@ -1,787 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/ARCHITECTURE.md) - ---- - -# OmniRoute Architecture - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/ARCHITECTURE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/ARCHITECTURE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/ARCHITECTURE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/ARCHITECTURE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/ARCHITECTURE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/ARCHITECTURE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/ARCHITECTURE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/ARCHITECTURE.md) - -_Last updated: 2026-03-04_ - -## 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 (`...`) for reasoning models -- Response sanitization for strict OpenAI SDK compatibility -- Role normalization (developerโ†’system, systemโ†’user) for cross-provider compatibility -- Structured output conversion (json_schema โ†’ Gemini responseSchema) -- Local persistence for providers, keys, aliases, combos, settings, pricing -- Usage/cost tracking and request logging -- Optional cloud sync for multi-device/state sync -- IP allowlist/blocklist for API access control -- Thinking budget management (passthrough/auto/custom/adaptive) -- Global system prompt injection -- Session tracking and fingerprinting -- Per-account enhanced rate limiting with provider-specific profiles -- Circuit breaker pattern for provider resilience -- Anti-thundering herd protection with mutex locking -- Signature-based request deduplication cache -- Domain layer: model availability, cost rules, fallback policy, lockout policy -- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) -- Policy engine for centralized request evaluation (lockout โ†’ budget โ†’ fallback) -- Request telemetry with p50/p95/p99 latency aggregation -- Correlation ID (X-Request-Id) for end-to-end tracing -- Compliance audit logging with opt-out per API key -- Eval framework for LLM quality assurance -- Resilience UI dashboard with real-time circuit breaker status -- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) - -Primary runtime model: - -- Next.js 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[(storage.sqlite)] - UDB[(usage tables + log artifacts)] - end - - subgraph Upstreams[Upstream Providers] - P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/Qoder/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/route.ts` (GET) -- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) -- OAuth: `src/app/api/oauth/*` -- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` -- Usage: `src/app/api/usage/*` -- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` -- CLI tooling helpers: `src/app/api/cli-tools/*` -- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) -- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) -- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) -- Sessions: `src/app/api/sessions` (GET) -- Rate limits: `src/app/api/rate-limits` (GET) -- Resilience: `src/app/api/resilience` (GET/PATCH) โ€” provider profiles, circuit breaker, rate limit state -- Resilience reset: `src/app/api/resilience/reset` (POST) โ€” reset breakers + cooldowns -- Cache stats: `src/app/api/cache/stats` (GET/DELETE) -- Model availability: `src/app/api/models/availability` (GET/POST) -- Telemetry: `src/app/api/telemetry/summary` (GET) -- Budget: `src/app/api/usage/budget` (GET/POST) -- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) -- Compliance audit: `src/app/api/compliance/audit-log` (GET) -- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) -- Policies: `src/app/api/policies` (GET/POST) - -## 2) SSE + 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` -- Response sanitization: `open-sse/handlers/responseSanitizer.ts` -- Role normalization: `open-sse/services/roleNormalizer.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`, `qoder.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 (SQLite): - -- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) -- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) -- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) -- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** - -Usage persistence: - -- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) -- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` -- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) -- legacy JSON files are migrated to SQLite by startup migrations when present - -Domain State DB (SQLite): - -- `src/lib/db/domainState.ts` โ€” CRUD operations 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: - -- primary runtime DB: `${DATA_DIR}/storage.sqlite` -- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) -- structured call payload archives: `${DATA_DIR}/call_logs/` -- optional translator/request debug sessions: `/logs/...` - -## Deployment Topology - -```mermaid -flowchart LR - 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[(storage.sqlite)] - UsageDB[(usage tables + log artifacts)] - end - - subgraph External[External Services] - Providers[AI Providers] - SyncCloud[Cloud Sync Service] - end - - CLI --> Next - Browser --> Next - Next --> Core - Next --> MainDB - Core --> MainDB - Core --> UsageDB - Core --> Providers - Next --> SyncCloud -``` - -## Module Mapping (Decision-Critical) - -### Route and API Modules - -- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs -- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) -- `src/app/api/providers*`: provider CRUD, validation, testing -- `src/app/api/provider-nodes*`: custom compatible node management -- `src/app/api/provider-models`: custom model management (CRUD) -- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) -- `src/app/api/oauth/*`: OAuth/device-code flows -- `src/app/api/keys*`: local API key lifecycle -- `src/app/api/models/alias`: alias management -- `src/app/api/combos*`: fallback combo management -- `src/app/api/pricing`: pricing overrides for cost calculation -- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) -- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) -- `src/app/api/usage/*`: usage and logs APIs -- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers -- `src/app/api/cli-tools/*`: local CLI config writers/checkers -- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) -- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) -- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) -- `src/app/api/sessions`: active session listing (GET) -- `src/app/api/rate-limits`: per-account rate limit status (GET) - -### Routing and Execution Core - -- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop -- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup -- `open-sse/executors/*`: provider-specific network and format behavior - -### Translation Registry and Format Converters - -- `open-sse/translator/index.ts`: translator registry and orchestration -- Request translators: `open-sse/translator/request/*` -- Response translators: `open-sse/translator/response/*` -- Format constants: `open-sse/translator/formats.ts` - -### Persistence - -- `src/lib/db/*`: persistent config/state and domain persistence on SQLite -- `src/lib/localDb.ts`: compatibility re-export for DB modules -- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables - -## Provider Executor Coverage (Strategy Pattern) - -Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. - -| Executor | Provider(s) | Special Handling | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | -| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, Qoder, 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 | -| Qoder | openai | OAuth (Basic) | โœ… | โœ… | โœ… | โš ๏ธ Per request | -| OpenRouter | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| GLM/Kimi/MiniMax | claude | API Key | โœ… | โœ… | โŒ | โŒ | -| DeepSeek | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Groq | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| xAI (Grok) | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Mistral | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Perplexity | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Together AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Fireworks AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Cerebras | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Cohere | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| NVIDIA NIM | openai | API Key | โœ… | โœ… | โŒ | โŒ | - -## Format Translation Coverage - -Detected source formats include: - -- `openai` -- `openai-responses` -- `claude` -- `gemini` - -Target formats include: - -- OpenAI chat/Responses -- Claude -- Gemini/Gemini-CLI/Antigravity envelope -- Kiro -- Cursor - -Translations use **OpenAI as the hub format** โ€” all conversions go through OpenAI as intermediate: - -``` -Source Format โ†’ OpenAI (hub) โ†’ Target Format -``` - -Translations are selected dynamically based on source payload shape and provider target format. - -Additional processing layers in the translation pipeline: - -- **Response sanitization** โ€” Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance -- **Role normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI targets; merges `system` โ†’ `user` for models that reject the system role (GLM, ERNIE) -- **Think tag extraction** โ€” Parses `...` blocks from content into `reasoning_content` field -- **Structured output** โ€” Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` - -## Supported API Endpoints - -| 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 `/logs//` 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 - -- SQLite schema migrations and auto-upgrade hooks at startup -- legacy JSON โ†’ SQLite migration compatibility path - -## Observability and Operational Signals - -Runtime visibility sources: - -- console logs from `src/sse/utils/logger.ts` -- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) -- textual request status log in `log.txt` (optional/compat) -- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` -- dashboard usage endpoints (`/api/usage/*`) for UI consumption - -## Security-Sensitive Boundaries - -- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing -- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning -- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format -- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level -- Cloud sync endpoints rely on API key auth + machine id semantics - -## Environment and Runtime Matrix - -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` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. -2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. -3. Request logger writes full headers/body when enabled; treat log directory as sensitive. -4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. -5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. -6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). -7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). -8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). - -## Operational Verification Checklist - -- Build from source: `npm run build` -- Build Docker image: `docker build -t omniroute .` -- Start service and verify: -- `GET /api/settings` -- `GET /api/v1/models` -- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/ja/AUTO-COMBO.md b/docs/i18n/ja/AUTO-COMBO.md deleted file mode 100644 index 2166e41dff..0000000000 --- a/docs/i18n/ja/AUTO-COMBO.md +++ /dev/null @@ -1,67 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/AUTO-COMBO.md) - ---- - -# OmniRoute Auto-Combo Engine - -> Self-managing model chains with adaptive scoring - -## How It Works - -The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**: - -| Factor | Weight | Description | -| :--------- | :----- | :---------------------------------------------- | -| Quota | 0.20 | Remaining capacity [0..1] | -| Health | 0.25 | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 | -| CostInv | 0.20 | Inverse cost (cheaper = higher score) | -| LatencyInv | 0.15 | Inverse p95 latency (faster = higher) | -| TaskFit | 0.10 | Model ร— task type fitness score | -| Stability | 0.10 | Low variance in latency/errors | - -## Mode Packs - -| Pack | Focus | Key Weight | -| :---------------------- | :----------- | :--------------- | -| ๐Ÿš€ **Ship Fast** | Speed | latencyInv: 0.35 | -| ๐Ÿ’ฐ **Cost Saver** | Economy | costInv: 0.40 | -| ๐ŸŽฏ **Quality First** | Best model | taskFit: 0.40 | -| ๐Ÿ“ก **Offline Friendly** | Availability | quota: 0.40 | - -## Self-Healing - -- **Temporary exclusion**: Score < 0.2 โ†’ excluded for 5 min (progressive backoff, max 30 min) -- **Circuit breaker awareness**: OPEN โ†’ auto-excluded; HALF_OPEN โ†’ probe requests -- **Incident mode**: >50% OPEN โ†’ disable exploration, maximize stability -- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout - -## Bandit Exploration - -5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode. - -## API - -```bash -# Create auto-combo -curl -X POST http://localhost:20128/api/combos/auto \ - -H "Content-Type: application/json" \ - -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}' - -# List auto-combos -curl http://localhost:20128/api/combos/auto -``` - -## Task Fitness - -30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` โ†’ high coding score). - -## Files - -| File | Purpose | -| :------------------------------------------- | :------------------------------------ | -| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization | -| `open-sse/services/autoCombo/taskFitness.ts` | Model ร— task fitness lookup | -| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap | -| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode | -| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles | -| `src/app/api/combos/auto/route.ts` | REST API | diff --git a/docs/i18n/ja/CHANGELOG.md b/docs/i18n/ja/CHANGELOG.md index 0dcbd0394d..491d61825e 100644 --- a/docs/i18n/ja/CHANGELOG.md +++ b/docs/i18n/ja/CHANGELOG.md @@ -1,12 +1,92 @@ # Changelog (ๆ—ฅๆœฌ่ชž) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CHANGELOG.md) --- - ## [Unreleased] +### ๐Ÿ› ๏ธ Maintenance + +- **AGENTS.md rewrite:** Condensed from 297โ†’153 lines. Added build/lint/test commands (including single-test execution), code style guidelines (Prettier, TypeScript, ESLint, naming, imports, error handling, security), and trimmed verbose architecture tables for AI agent consumption. + +## [3.4.2] - 2026-04-01 + +### ๐Ÿ› Bug Fixes + +- **CI Stabilization:** Fixed failing analytics/settings Playwright selectors and request assertions so GitHub Actions E2E runs pass reliably across localized UIs and switch-based controls. +- **Deterministic Tests:** Removed date-sensitive quota fixtures from Copilot usage tests and aligned idempotency/model catalog tests with the merged runtime behavior. +- **MCP Type Hardening:** Removed zero-budget explicit `any` regressions from the MCP server tool registration path, restoring the `check:any-budget:t11` workflow gate. + +### ๐Ÿ› ๏ธ Maintenance + +- **Release Branch Integration:** Consolidated the active feature branches into `release/v3.4.2` on top of current `main` and validated the branch with lint, unit, coverage, build, and CI-mode E2E runs. + +## [3.4.1] - 2026-03-31 + +> [!WARNING] +> **BREAKING CHANGE: request logging, retention, and logging environment variables have been redesigned.** +> On the first startup after upgrading, OmniRoute archives legacy request logs from `DATA_DIR/logs/`, legacy `DATA_DIR/call_logs/`, and `DATA_DIR/log.txt` into `DATA_DIR/log_archives/*.zip`, then removes the deprecated layout and switches to the new unified artifact format under `DATA_DIR/call_logs/`. + +### โœจ New Features + +- **.ENV Migration Utility:** Included `scripts/migrate-env.mjs` to seamlessly migrate ` Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` - ---- - -## Step 2 โ€” Install CLI Tools - -All npm-based tools require Node.js 18+: - -```bash -# Claude Code (Anthropic) -npm install -g @anthropic-ai/claude-code - -# OpenAI Codex -npm install -g @openai/codex - -# Gemini CLI (Google) -npm install -g @google/gemini-cli - -# OpenCode -npm install -g opencode-ai - -# Cline -npm install -g cline - -# KiloCode -npm install -g kilecode - -# Kiro CLI (Amazon โ€” requires curl + unzip) -apt-get install -y unzip # on Debian/Ubuntu -curl -fsSL https://cli.kiro.dev/install | bash -export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc -``` - -**Verify:** - -```bash -claude --version # 2.x.x -codex --version # 0.x.x -gemini --version # 0.x.x -opencode --version # x.x.x -cline --version # 2.x.x -kilocode --version # x.x.x (or: kilo --version) -kiro-cli --version # 1.x.x -``` - ---- - -## Step 3 โ€” Set Global Environment Variables - -Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`: - -```bash -# OmniRoute Universal Endpoint -export OPENAI_BASE_URL="http://localhost:20128/v1" -export OPENAI_API_KEY="sk-your-omniroute-key" -export ANTHROPIC_BASE_URL="http://localhost:20128/v1" -export ANTHROPIC_API_KEY="sk-your-omniroute-key" -export GEMINI_BASE_URL="http://localhost:20128/v1" -export GEMINI_API_KEY="sk-your-omniroute-key" -``` - -> For a **remote server** replace `localhost:20128` with the server IP or domain, -> e.g. `http://192.168.0.15:20128`. - ---- - -## Step 4 โ€” Configure Each Tool - -### Claude Code - -```bash -# Via CLI: -claude config set --global api-base-url http://localhost:20128/v1 - -# Or create ~/.claude/settings.json: -mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF -{ - "apiBaseUrl": "http://localhost:20128/v1", - "apiKey": "sk-your-omniroute-key" -} -EOF -``` - -**Test:** `claude "say hello"` - ---- - -### OpenAI Codex - -```bash -mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF -model: auto -apiKey: sk-your-omniroute-key -apiBaseUrl: http://localhost:20128/v1 -EOF -``` - -**Test:** `codex "what is 2+2?"` - ---- - -### Gemini CLI - -```bash -mkdir -p ~/.gemini && cat > ~/.gemini/settings.json << EOF -{ - "apiKey": "sk-your-omniroute-key", - "baseUrl": "http://localhost:20128/v1" -} -EOF -``` - -**Test:** `gemini "hello"` - ---- - -### OpenCode - -```bash -mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF -[provider.openai] -base_url = "http://localhost:20128/v1" -api_key = "sk-your-omniroute-key" -EOF -``` - -**Test:** `opencode` - ---- - -### Cline (CLI or VS Code) - -**CLI mode:** - -```bash -mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF -{ - "apiProvider": "openai", - "openAiBaseUrl": "http://localhost:20128/v1", - "openAiApiKey": "sk-your-omniroute-key" -} -EOF -``` - -**VS Code mode:** -Cline extension settings โ†’ API Provider: `OpenAI Compatible` โ†’ Base URL: `http://localhost:20128/v1` - -Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ Cline โ†’ Apply Config**. - ---- - -### KiloCode (CLI or VS Code) - -**CLI mode:** - -```bash -kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key -``` - -**VS Code settings:** - -```json -{ - "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", - "kilo-code.apiKey": "sk-your-omniroute-key" -} -``` - -Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ KiloCode โ†’ Apply Config**. - ---- - -### Continue (VS Code Extension) - -Edit `~/.continue/config.yaml`: - -```yaml -models: - - name: OmniRoute - provider: openai - model: auto - apiBase: http://localhost:20128/v1 - apiKey: sk-your-omniroute-key - default: true -``` - -Restart VS Code after editing. - ---- - -### Kiro CLI (Amazon) - -```bash -# Login to your AWS/Kiro account: -kiro-cli login - -# The CLI uses its own auth โ€” OmniRoute is not needed as backend for Kiro CLI itself. -# Use kiro-cli alongside OmniRoute for other tools. -kiro-cli status -``` - ---- - -### Cursor (Desktop App) - -> **Note:** Cursor routes requests through its cloud. For OmniRoute integration, -> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL. - -Via GUI: **Settings โ†’ Models โ†’ OpenAI API Key** - -- Base URL: `https://your-domain.com/v1` -- API Key: your OmniRoute key - ---- - -## Dashboard Auto-Configuration - -The OmniRoute dashboard automates configuration for most tools: - -1. Go to `http://localhost:20128/dashboard/cli-tools` -2. Expand any tool card -3. Select your API key from the dropdown -4. Click **Apply Config** (if tool is detected as installed) -5. Or copy the generated config snippet manually - ---- - -## Built-in Agents: Droid & OpenClaw - -**Droid** and **OpenClaw** are AI agents built directly into OmniRoute โ€” no installation needed. -They run as internal routes and use OmniRoute's model routing automatically. - -- Access: `http://localhost:20128/dashboard/agents` -- Configure: same combos and providers as all other tools -- No API key or CLI install required - ---- - -## Available API Endpoints - -| Endpoint | Description | Use For | -| -------------------------- | ----------------------------- | --------------------------- | -| `/v1/chat/completions` | Standard chat (all providers) | All modern tools | -| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows | -| `/v1/completions` | Legacy text completions | Older tools using `prompt:` | -| `/v1/embeddings` | Text embeddings | RAG, search | -| `/v1/images/generations` | Image generation | DALL-E, Flux, etc. | -| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS | -| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI | - ---- - -## Troubleshooting - -| Error | Cause | Fix | -| ------------------------- | ----------------------- | ------------------------------------------ | -| `Connection refused` | OmniRoute not running | `pm2 start omniroute` | -| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` | -| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` | -| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` | -| CLI shows "not installed" | Binary not in PATH | Check `which ` | -| `kiro-cli: not found` | Not in PATH | `export PATH="$HOME/.local/bin:$PATH"` | - ---- - -## Quick Setup Script (One Command) - -```bash -# Install all CLIs and configure for OmniRoute (replace with your key and server URL) -OMNIROUTE_URL="http://localhost:20128/v1" -OMNIROUTE_KEY="sk-your-omniroute-key" - -npm install -g @anthropic-ai/claude-code @openai/codex @google/gemini-cli opencode-ai cline kilecode - -# Kiro CLI -apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash - -# Write configs -mkdir -p ~/.claude ~/.codex ~/.gemini ~/.config/opencode ~/.continue - -cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" -cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" -cat > ~/.gemini/settings.json <<< "{\"apiKey\":\"$OMNIROUTE_KEY\",\"baseUrl\":\"$OMNIROUTE_URL\"}" -cat >> ~/.bashrc << EOF -export OPENAI_BASE_URL="$OMNIROUTE_URL" -export OPENAI_API_KEY="$OMNIROUTE_KEY" -export ANTHROPIC_BASE_URL="$OMNIROUTE_URL" -export ANTHROPIC_API_KEY="$OMNIROUTE_KEY" -EOF - -source ~/.bashrc -echo "โœ… All CLIs installed and configured for OmniRoute" -``` diff --git a/docs/i18n/ja/CODEBASE_DOCUMENTATION.md b/docs/i18n/ja/CODEBASE_DOCUMENTATION.md deleted file mode 100644 index e2d7950052..0000000000 --- a/docs/i18n/ja/CODEBASE_DOCUMENTATION.md +++ /dev/null @@ -1,593 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CODEBASE_DOCUMENTATION.md) - ---- - -# omniroute โ€” Codebase Documentation - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) - -> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. - ---- - -## 1. 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
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, Qoder, 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 | -| Qoder | 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"] -``` diff --git a/docs/i18n/ja/CONTRIBUTING.md b/docs/i18n/ja/CONTRIBUTING.md new file mode 100644 index 0000000000..61339f4027 --- /dev/null +++ b/docs/i18n/ja/CONTRIBUTING.md @@ -0,0 +1,299 @@ +# Contributing to OmniRoute (ๆ—ฅๆœฌ่ชž) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CONTRIBUTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CONTRIBUTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CONTRIBUTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CONTRIBUTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CONTRIBUTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CONTRIBUTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CONTRIBUTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CONTRIBUTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CONTRIBUTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CONTRIBUTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CONTRIBUTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CONTRIBUTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CONTRIBUTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CONTRIBUTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CONTRIBUTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CONTRIBUTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CONTRIBUTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CONTRIBUTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CONTRIBUTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CONTRIBUTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CONTRIBUTING.md) + +--- + +Thank you for your interest in contributing! This guide covers everything you need to get started. + +--- + +## Development Setup + +### Prerequisites + +- **Node.js** >= 18 < 24 (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` | `20128` | Server port | +| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | Base URL for frontend | +| `JWT_SECRET` | (generate above) | JWT signing secret | +| `INITIAL_PASSWORD` | `CHANGEME` | First login password | +| `APP_LOG_LEVEL` | `info` | Log verbosity level | + +### Dashboard Settings + +The dashboard provides UI toggles for features that can also be configured via environment variables: + +| Setting Location | Toggle | Description | +| ------------------- | ------------------ | ------------------------------ | +| Settings โ†’ Advanced | Debug Mode | Enable debug request logs (UI) | +| Settings โ†’ General | Sidebar Visibility | Show/hide sidebar sections | + +These settings are stored in the database and persist across restarts, overriding env var defaults when set. + +### 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:20128/dashboard` +- **API**: `http://localhost:20128/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`, `mcp`, `a2a`, `memory`, `skills`. + +--- + +## Running Tests + +```bash +# All tests (unit + vitest + ecosystem + e2e) +npm run test:all + +# Single test file (Node.js native test runner โ€” most tests use this) +node --import tsx/esm --test tests/unit/your-file.test.mjs + +# Vitest (MCP server, autoCombo, cache) +npm run test:vitest + +# E2E tests (requires Playwright) +npm run test:e2e + +# Protocol clients E2E (MCP transports, A2A) +npm run test:protocols:e2e + +# Ecosystem compatibility tests +npm run test:ecosystem + +# Coverage (55% min statements/lines/functions; 60% branches) +npm run test:coverage +npm run coverage:report + +# Lint + format check +npm run lint +npm run check +``` + +Coverage notes: + +- `npm run test:coverage` measures source coverage for the main unit test suite, excludes `tests/**`, and includes `open-sse/**` +- `npm run coverage:report` prints the detailed file-by-file report from the latest coverage run +- `npm run test:coverage:legacy` preserves the older metric for historical comparison +- See `docs/COVERAGE_PLAN.md` for the phased coverage improvement roadmap + +Current test status: **122 unit test files** covering: + +- Provider translators and format conversion +- Rate limiting, circuit breaker, and resilience +- Semantic cache, idempotency, progress tracking +- Database operations and schema (21 DB modules) +- OAuth flows and authentication +- API endpoint validation (Zod v4) +- MCP server tools and scope enforcement +- Memory and Skills systems + +--- + +## Code Style + +- **ESLint** โ€” Run `npm run lint` before committing +- **Prettier** โ€” Auto-formatted via `lint-staged` on commit (2 spaces, semicolons, double quotes, 100 char width, es5 trailing commas) +- **TypeScript** โ€” All `src/` code uses `.ts`/`.tsx`; `open-sse/` uses `.ts`/`.js`; document with TSDoc (`@param`, `@returns`, `@throws`) +- **No `eval()`** โ€” ESLint enforces `no-eval`, `no-implied-eval`, `no-new-func` +- **Zod validation** โ€” Use Zod v4 schemas for all API input validation +- **Naming**: Files = camelCase/kebab-case, components = PascalCase, constants = UPPER_SNAKE + +--- + +## Project Structure + +``` +src/ # TypeScript (.ts / .tsx) +โ”œโ”€โ”€ app/ # Next.js 16 App Router +โ”‚ โ”œโ”€โ”€ (dashboard)/ # Dashboard pages (23 sections) +โ”‚ โ”œโ”€โ”€ api/ # API routes (51 directories) +โ”‚ โ””โ”€โ”€ login/ # Auth pages (.tsx) +โ”œโ”€โ”€ domain/ # Policy engine (policyEngine, comboResolver, costRules, etc.) +โ”œโ”€โ”€ lib/ # Core business logic (.ts) +โ”‚ โ”œโ”€โ”€ a2a/ # Agent-to-Agent v0.3 protocol server +โ”‚ โ”œโ”€โ”€ acp/ # Agent Communication Protocol registry +โ”‚ โ”œโ”€โ”€ compliance/ # Compliance policy engine +โ”‚ โ”œโ”€โ”€ db/ # SQLite database layer (21 modules + 16 migrations) +โ”‚ โ”œโ”€โ”€ memory/ # Persistent conversational memory +โ”‚ โ”œโ”€โ”€ oauth/ # OAuth providers, services, and utilities +โ”‚ โ”œโ”€โ”€ skills/ # Extensible skill framework +โ”‚ โ”œโ”€โ”€ usage/ # Usage tracking and cost calculation +โ”‚ โ””โ”€โ”€ localDb.ts # Re-export layer only โ€” never add logic here +โ”œโ”€โ”€ middleware/ # Request middleware (promptInjectionGuard) +โ”œโ”€โ”€ mitm/ # MITM proxy (cert, DNS, target routing) +โ”œโ”€โ”€ shared/ +โ”‚ โ”œโ”€โ”€ components/ # React components (.tsx) +โ”‚ โ”œโ”€โ”€ constants/ # Provider definitions (60+), MCP scopes, routing strategies +โ”‚ โ”œโ”€โ”€ utils/ # Circuit breaker, sanitizer, auth helpers +โ”‚ โ””โ”€โ”€ validation/ # Zod v4 schemas +โ””โ”€โ”€ sse/ # SSE proxy pipeline + +open-sse/ # @omniroute/open-sse workspace +โ”œโ”€โ”€ executors/ # 14 provider-specific request executors +โ”œโ”€โ”€ handlers/ # 11 request handlers (chat, responses, embeddings, images, etc.) +โ”œโ”€โ”€ mcp-server/ # MCP server (25 tools, 3 transports, 10 scopes) +โ”œโ”€โ”€ services/ # 36+ services (combo, autoCombo, rateLimitManager, etc.) +โ”œโ”€โ”€ translator/ # Format translators (OpenAI โ†” Claude โ†” Gemini โ†” Responses โ†” Ollama) +โ”œโ”€โ”€ transformer/ # Responses API transformer +โ””โ”€โ”€ utils/ # 22 utility modules (stream, TLS, proxy, logging) + +electron/ # Electron desktop app (cross-platform) + +tests/ +โ”œโ”€โ”€ unit/ # Node.js test runner (122 test files) +โ”œโ”€โ”€ integration/ # Integration tests +โ”œโ”€โ”€ e2e/ # Playwright tests +โ”œโ”€โ”€ security/ # Security tests +โ”œโ”€โ”€ translator/ # Translator-specific tests +โ””โ”€โ”€ load/ # Load tests + +docs/ # Documentation +โ”œโ”€โ”€ ARCHITECTURE.md # System architecture +โ”œโ”€โ”€ API_REFERENCE.md # All endpoints +โ”œโ”€โ”€ USER_GUIDE.md # Provider setup, CLI integration +โ”œโ”€โ”€ TROUBLESHOOTING.md # Common issues +โ”œโ”€โ”€ MCP-SERVER.md # MCP server (25 tools) +โ”œโ”€โ”€ A2A-SERVER.md # A2A agent protocol +โ”œโ”€โ”€ AUTO-COMBO.md # Auto-combo engine +โ”œโ”€โ”€ CLI-TOOLS.md # CLI tools integration +โ”œโ”€โ”€ COVERAGE_PLAN.md # Test coverage improvement plan +โ”œโ”€โ”€ openapi.yaml # OpenAPI specification +โ””โ”€โ”€ adr/ # Architecture Decision Records +``` + +--- + +## Adding a New Provider + +### Step 1: Register Provider Constants + +Add to `src/shared/constants/providers.ts` โ€” Zod-validated at module load. + +### Step 2: Add Executor (if custom logic needed) + +Create executor in `open-sse/executors/your-provider.ts` extending the base executor. + +### Step 3: Add Translator (if non-OpenAI format) + +Create request/response translators in `open-sse/translator/`. + +### Step 4: Add OAuth Config (if OAuth-based) + +Add OAuth credentials in `src/lib/oauth/constants/oauth.ts` and service in `src/lib/oauth/services/`. + +### Step 5: Register Models + +Add model definitions in `open-sse/config/providerRegistry.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 +- [ ] All inputs validated with Zod schemas +- [ ] CHANGELOG updated (if user-facing change) +- [ ] Documentation updated (if applicable) + +--- + +## Releasing + +Releases are managed via the `/generate-release` workflow. When a new GitHub Release is created, the package is **automatically published to npm** via GitHub Actions. + +--- + +## Getting Help + +- **Architecture**: See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) +- **API Reference**: See [`docs/API_REFERENCE.md`](docs/API_REFERENCE.md) +- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **ADRs**: See `docs/adr/` for architectural decision records diff --git a/docs/i18n/ja/FEATURES.md b/docs/i18n/ja/FEATURES.md deleted file mode 100644 index 6cc9352b1d..0000000000 --- a/docs/i18n/ja/FEATURES.md +++ /dev/null @@ -1,147 +0,0 @@ -# OmniRoute โ€” Dashboard Features Gallery (ๆ—ฅๆœฌ่ชž) - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) - -> ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../docs/FEATURES.md) - ---- - -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 (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. - -![Providers Dashboard](screenshots/01-providers.png) - ---- - -## ๐ŸŽจ Combos - -Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. - -![Combos Dashboard](screenshots/02-combos.png) - ---- - -## ๐Ÿ“Š Analytics - -Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. - -![Analytics Dashboard](screenshots/03-analytics.png) - ---- - -## ๐Ÿฅ System Health - -Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. - -![Health Dashboard](screenshots/04-health.png) - ---- - -## ๐Ÿ”ง Translator Playground - -Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). - -![Translator Playground](screenshots/05-translator.png) - ---- - -## ๐ŸŽฎ Model Playground _(v2.0.9+)_ - -Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. - ---- - -## ๐ŸŽจ Themes _(v2.0.5+)_ - -Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. - ---- - -## โš™๏ธ Settings - -Comprehensive settings panel with tabs: - -- **General** โ€” System storage, backup management (export/import database) -- **Appearance** โ€” Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls -- **Security** โ€” API endpoint protection, custom provider blocking, IP filtering, session info -- **Routing** โ€” Model aliases, background task degradation -- **Resilience** โ€” Rate limit persistence, circuit breaker tuning -- **Advanced** โ€” Configuration overrides - -![Settings Dashboard](screenshots/06-settings.png) - ---- - -## ๐Ÿ”ง CLI Tools - -One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. - -![CLI Tools Dashboard](screenshots/07-cli-tools.png) - ---- - -## ๐Ÿค– CLI Agents _(v2.0.11+)_ - -Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: - -- **Installation status** โ€” Installed / Not Found with version detection -- **Protocol badges** โ€” stdio, HTTP, etc. -- **Custom agents** โ€” Register any CLI tool via form (name, binary, version command, spawn args) -- **CLI Fingerprint Matching** โ€” Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP - ---- - -## ๐Ÿ–ผ๏ธ Media _(v2.0.3+)_ - -Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. - ---- - -## ๐Ÿ“ Request Logs - -Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. - -![Usage Logs](screenshots/08-usage.png) - ---- - -## ๐ŸŒ API Endpoint - -Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. - -![Endpoint Dashboard](screenshots/09-endpoint.png) - ---- - -## ๐Ÿ”‘ API Key Management - -Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. - ---- - -## ๐Ÿ“‹ Audit Log - -Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. - ---- - -## ๐Ÿ–ฅ๏ธ Desktop Application - -Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. - -Key features: - -- Server readiness polling (no blank screen on cold start) -- System tray with port management -- Content Security Policy -- Single-instance lock -- Auto-update on restart -- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) -- Hardened Electron build packaging โ€” symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+) - -๐Ÿ“– See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/ja/MCP-SERVER.md b/docs/i18n/ja/MCP-SERVER.md deleted file mode 100644 index 829acd30b1..0000000000 --- a/docs/i18n/ja/MCP-SERVER.md +++ /dev/null @@ -1,87 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/MCP-SERVER.md) - ---- - -# OmniRoute MCP Server Documentation - -> Model Context Protocol server with 16 intelligent tools - -## Installation - -OmniRoute MCP is built-in. Start it with: - -```bash -omniroute --mcp -``` - -Or via the open-sse transport: - -```bash -# HTTP streamable transport (port 20130) -omniroute --dev # MCP auto-starts on /mcp endpoint -``` - -## IDE Configuration - -See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup. - ---- - -## Essential Tools (8) - -| Tool | Description | -| :------------------------------ | :--------------------------------------- | -| `omniroute_get_health` | Gateway health, circuit breakers, uptime | -| `omniroute_list_combos` | All configured combos with models | -| `omniroute_get_combo_metrics` | Performance metrics for a specific combo | -| `omniroute_switch_combo` | Switch active combo by ID/name | -| `omniroute_check_quota` | Quota status per provider or all | -| `omniroute_route_request` | Send a chat completion through OmniRoute | -| `omniroute_cost_report` | Cost analytics for a time period | -| `omniroute_list_models_catalog` | Full model catalog with capabilities | - -## Advanced Tools (8) - -| Tool | Description | -| :--------------------------------- | :---------------------------------------------- | -| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | -| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | -| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | -| `omniroute_test_combo` | Live-test all models in a combo | -| `omniroute_get_provider_metrics` | Detailed metrics for one provider | -| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | -| `omniroute_explain_route` | Explain a past routing decision | -| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | - -## Authentication - -MCP tools are authenticated via API key scopes. Each tool requires specific scopes: - -| Scope | Tools | -| :------------- | :----------------------------------------------- | -| `read:health` | get_health, get_provider_metrics | -| `read:combos` | list_combos, get_combo_metrics | -| `write:combos` | switch_combo | -| `read:quota` | check_quota | -| `write:route` | route_request, simulate_route, test_combo | -| `read:usage` | cost_report, get_session_snapshot, explain_route | -| `write:config` | set_budget_guard, set_resilience_profile | -| `read:models` | list_models_catalog, best_combo_for_task | - -## Audit Logging - -Every tool call is logged to `mcp_tool_audit` with: - -- Tool name, arguments, result -- Duration (ms), success/failure -- API key hash, timestamp - -## Files - -| File | Purpose | -| :------------------------------------------- | :------------------------------------------ | -| `open-sse/mcp-server/server.ts` | MCP server creation + 16 tool registrations | -| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport | -| `open-sse/mcp-server/auth.ts` | API key + scope validation | -| `open-sse/mcp-server/audit.ts` | Tool call audit logging | -| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers | diff --git a/docs/i18n/ja/README.md b/docs/i18n/ja/README.md index 3b783bfc94..19b7f8e7b6 100644 --- a/docs/i18n/ja/README.md +++ b/docs/i18n/ja/README.md @@ -1,12 +1,12 @@ # ๐Ÿš€ OmniRoute โ€” The Free AI Gateway (ๆ—ฅๆœฌ่ชž) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/README.md) --- ### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback. -_Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._ +_Your universal API proxy โ€” one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._ **Chat Completions โ€ข Embeddings โ€ข Image Generation โ€ข Video โ€ข Music โ€ข Audio โ€ข Reranking โ€ข **Web Search** โ€ข MCP Server โ€ข A2A Protocol โ€ข 100% TypeScript** @@ -46,15 +46,17 @@ _Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now wi > - `APP_LOG_FILE_PATH` > - `APP_LOG_MAX_FILE_SIZE` > - `APP_LOG_RETENTION_DAYS` +> - `APP_LOG_MAX_FILES` > - `APP_LOG_LEVEL` > - `APP_LOG_FORMAT` > - `CALL_LOG_RETENTION_DAYS` +> - `CALL_LOG_MAX_ENTRIES` > > For release details and upgrade notes, see the [CHANGELOG](CHANGELOG.md). --- -## ๐Ÿ†• What's New in v3.0.0 +## ๐Ÿ†• What's New > **Upgrading from v2.9.5?** โ€” See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes. @@ -274,7 +276,7 @@ Developers pay $20โ€“200/month for Claude Pro, Codex Pro, or GitHub Copilot. Eve - **Smart 4-Tier Fallback** โ€” If subscription quota runs out, automatically redirects to API Key โ†’ Cheap โ†’ Free with zero manual intervention - **Real-Time Quota Tracking** โ€” Shows token consumption in real-time with reset countdown (5h, daily, weekly) - **Multi-Account Support** โ€” Multiple accounts per provider with auto round-robin โ€” when one runs out, switches to the next -- **Custom Combos** โ€” Customizable fallback chains with 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Custom Combos** โ€” Customizable fallback chains with 9 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random) - **Codex Business Quotas** โ€” Business/Team workspace quota monitoring directly in the dashboard @@ -286,7 +288,7 @@ OpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If **How OmniRoute solves it:** -- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 67+ providers +- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 60+ providers - **Format Translation** โ€” Automatic and transparent: OpenAI โ†” Claude โ†” Gemini โ†” Responses API - **Response Sanitization** โ€” Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+ - **Role Normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI providers; `system` โ†’ `user` for GLM/ERNIE @@ -372,7 +374,7 @@ Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code.. - **CLI Tools Dashboard** โ€” Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline - **GitHub Copilot Config Generator** โ€” Generates `chatLanguageModels.json` for VS Code with bulk model selection - **Onboarding Wizard** โ€” Guided 4-step setup for first-time users -- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 67+ providers +- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 60+ providers @@ -419,7 +421,7 @@ When a call fails, the dev doesn't know if it was a rate limit, expired token, w - **SQLite Proxy Logs** โ€” Persistent logs that survive server restarts - **Translator Playground** โ€” 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time) - **Request Telemetry** โ€” p50/p95/p99 latency + X-Request-Id tracing -- **File-Based Logging with Rotation** โ€” Console interceptor captures everything to JSON log with size-based rotation +- **File-Based Logging with Rotation** โ€” App logs rotate by size, retention days, and archive count; call log artifacts rotate by retention days and file count - **System Info Report** โ€” `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage. @@ -514,7 +516,7 @@ Developers who want all responses in a specific language, with a specific tone, - **System Prompt Injection** โ€” Global prompt applied to all requests - **Thinking Budget Validation** โ€” Reasoning token allocation control per request (passthrough, auto, custom, adaptive) -- **6 Routing Strategies** โ€” Global strategies that determine how requests are distributed +- **9 Routing Strategies** โ€” Global strategies that determine how requests are distributed - **Wildcard Router** โ€” `provider/*` patterns route dynamically to any provider - **Combo Enable/Disable Toggle** โ€” Toggle combos directly from the dashboard - **Provider Toggle** โ€” Enable/disable all connections for a provider with one click @@ -581,7 +583,7 @@ Different clients should have least-privilege access to tool categories. **How OmniRoute solves it:** -- 9 granular MCP scopes for controlled tool access +- 10 granular MCP scopes for controlled tool access - Scope enforcement and visibility in MCP management UI - Safe default posture for operational tooling @@ -1325,19 +1327,19 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. ### ๐Ÿค– Agent & Protocol Operations (v2.0) -| Feature | What It Does | -| ------------------------------------- | -------------------------------------------------------------------------------------------------- | -| ๐Ÿ”ง **MCP Server (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) | -| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | -| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | -| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | -| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | -| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | -| ๐Ÿ” **MCP Scope Enforcement** | 9 granular scope permissions for controlled tool access | -| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | -| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | -| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | -| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | +| Feature | What It Does | +| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| ๐Ÿ”ง **MCP Server (25 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools | +| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | +| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | +| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | +| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | +| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | +| ๐Ÿ” **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access | +| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | +| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | +| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | +| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | ### ๐Ÿง  Routing & Intelligence @@ -1348,7 +1350,7 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. | ๐Ÿ”„ **Format Translation** | OpenAI โ†” Claude โ†” Gemini โ†” Responses with schema-safe conversions | | ๐Ÿ‘ฅ **Multi-Account Support** | Multiple accounts per provider with intelligent selection | | ๐Ÿ”„ **Auto Token Refresh** | OAuth tokens refresh automatically with retry | -| ๐ŸŽจ **Custom Combos** | 6 balancing strategies + fallback chain control | +| ๐ŸŽจ **Custom Combos** | 9 balancing strategies + fallback chain control | | ๐ŸŒ **Wildcard Router** | `provider/*` dynamic routing | | ๐Ÿง  **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits | | ๐Ÿ”€ **Model Aliases** | Built-in + custom model aliasing and migration safety | @@ -1949,6 +1951,7 @@ opencode - Request artifacts are written to `DATA_DIR/call_logs/` as one JSON file per request - Enable pipeline capture from Dashboard โ†’ Logs โ†’ Request Logs if you need detailed per-stage payloads - Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log` +- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed **Connection test shows "Invalid" for OpenAI-compatible providers** diff --git a/docs/i18n/ja/RELEASE_CHECKLIST.md b/docs/i18n/ja/RELEASE_CHECKLIST.md deleted file mode 100644 index 903e812c3f..0000000000 --- a/docs/i18n/ja/RELEASE_CHECKLIST.md +++ /dev/null @@ -1,37 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/RELEASE_CHECKLIST.md) - ---- - -# Release Checklist - -Use this checklist before tagging or publishing a new OmniRoute release. - -## Version and Changelog - -1. Bump `package.json` version (`x.y.z`) in the release branch. -2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: - - `## [x.y.z] โ€” YYYY-MM-DD` -3. Keep `## [Unreleased]` as the first changelog section for upcoming work. -4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. - -## API Docs - -1. Update `docs/openapi.yaml`: - - `info.version` must equal `package.json` version. -2. Validate endpoint examples if API contracts changed. - -## Runtime Docs - -1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. -2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. -3. Update localized docs if source docs changed significantly. - -## Automated Check - -Run the sync guard locally before opening PR: - -```bash -npm run check:docs-sync -``` - -CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/ja/SECURITY.md b/docs/i18n/ja/SECURITY.md new file mode 100644 index 0000000000..7dec831411 --- /dev/null +++ b/docs/i18n/ja/SECURITY.md @@ -0,0 +1,179 @@ +# Security Policy (ๆ—ฅๆœฌ่ชž) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../SECURITY.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/SECURITY.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/SECURITY.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/SECURITY.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/SECURITY.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/SECURITY.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/SECURITY.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/SECURITY.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/SECURITY.md) + +--- + +## 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 | +| ------- | -------------- | +| 3.4.x | โœ… Active | +| 3.0.x | โœ… Security | +| < 3.0.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 | +| **MCP Scopes** | 10 granular scopes for MCP tool access control | + +### ๐Ÿ›ก๏ธ 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:::` +- 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** | Allowlist/blocklist IP ranges in dashboard | +| **Rate Limiting** | Per-provider rate limits with automatic backoff | +| **Anti-Thundering Herd** | Mutex + per-connection locking prevents cascading 502s | +| **TLS Fingerprint** | Browser-like TLS fingerprint spoofing to reduce bot detection | +| **CLI Fingerprint** | Per-provider header/body ordering to match native CLI signatures | + +### ๐Ÿ”Œ Resilience & Availability + +| 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 `CALL_LOG_RETENTION_DAYS` | +| **No-Log Opt-out** | Per API key `noLog` flag disables request logging | +| **Audit Log** | Administrative actions tracked in `audit_log` table | +| **MCP Audit** | SQLite-backed audit logging for all MCP tool calls | +| **Zod Validation** | All API inputs validated with Zod v4 schemas at module load | + +--- + +## 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 +- Provider constants validated at module load via Zod (`src/shared/validation/providerSchema.ts`) diff --git a/docs/i18n/ja/TROUBLESHOOTING.md b/docs/i18n/ja/TROUBLESHOOTING.md deleted file mode 100644 index 63c148000a..0000000000 --- a/docs/i18n/ja/TROUBLESHOOTING.md +++ /dev/null @@ -1,258 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/TROUBLESHOOTING.md) - ---- - -# Troubleshooting - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/TROUBLESHOOTING.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/TROUBLESHOOTING.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/TROUBLESHOOTING.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/TROUBLESHOOTING.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/TROUBLESHOOTING.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/TROUBLESHOOTING.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/TROUBLESHOOTING.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/TROUBLESHOOTING.md) - -Common problems and solutions for OmniRoute. - ---- - -## Quick Fixes - -| Problem | Solution | -| ----------------------------- | ------------------------------------------------------------------ | -| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | -| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | -| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | -| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | -| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | - ---- - -## Provider Issues - -### "Language model did not provide messages" - -**Cause:** Provider quota exhausted. - -**Fix:** - -1. 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, Qoder) 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}/storage.sqlite` (providers, combos, aliases, keys, settings) -- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` -- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) - ---- - -## Circuit Breaker Issues - -### Provider stuck in OPEN state - -When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. - -**Fix:** - -1. 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 -- **SDK returns raw string instead of object** โ€” Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures -- **GLM/ERNIE rejects `system` role** โ€” Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models -- **`developer` role not recognized** โ€” Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers -- **`json_schema` not working with Gemini** โ€” Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` - ---- - -## Resilience Settings - -### Auto rate-limit not triggering - -- 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. - ---- - -## Optional RAG / LLM failure taxonomy (16 problems) - -Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. - -In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. - -If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: - -- retrieval drift and broken context boundaries -- empty or stale indexes and vector stores -- embedding versus semantic mismatch -- prompt assembly and context window issues -- logic collapse and overconfident answers -- long chain and agent coordination failures -- multi agent memory and role drift -- deployment and bootstrap ordering problems - -The idea is simple: - -1. When you investigate a bad response, capture: - - user task and request - - route or provider combo in OmniRoute - - any RAG context used downstream (retrieved documents, tool calls, etc) -2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` โ€ฆ `No.16`). -3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. -4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. - -Full text and concrete recipes live here (MIT license, text only): - -[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) - -You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. - ---- - -## Still Stuck? - -- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details -- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints -- **Health Dashboard**: Check **Dashboard โ†’ Health** for real-time system status -- **Translator**: Use **Dashboard โ†’ Translator** to debug format issues diff --git a/docs/i18n/ja/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/ja/VM_DEPLOYMENT_GUIDE.md deleted file mode 100644 index 1c866e3641..0000000000 --- a/docs/i18n/ja/VM_DEPLOYMENT_GUIDE.md +++ /dev/null @@ -1,401 +0,0 @@ -# OmniRoute โ€” Cloudflare ใ‚’ไฝฟ็”จใ—ใŸ VM ใฎๅฐŽๅ…ฅใ‚ฌใ‚คใƒ‰ - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](../pt-BR/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](../es/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](../fr/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](../it/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](../ru/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](../zh-CN/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](../de/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](../in/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](../th/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](../uk-UA/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](../ar/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](../ja/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](../vi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](../bg/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](../da/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](../fi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](../he/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](../hu/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](../id/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](../ko/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](../ms/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](../nl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](../no/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](../pt/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](../ro/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](../pl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](../sk/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](../sv/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](../phi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](../cs/VM_DEPLOYMENT_GUIDE.md) - -Cloudflare็ตŒ็”ฑใงใƒ‰ใƒกใ‚คใƒณใŒ็ฎก็†ใ•ใ‚Œใฆใ„ใ‚‹VM๏ผˆVPS๏ผ‰ใซOmniRouteใ‚’ใ‚คใƒณใ‚นใƒˆใƒผใƒซใ—ใฆๆง‹ๆˆใ™ใ‚‹ใŸใ‚ใฎๅฎŒๅ…จใชใ‚ฌใ‚คใƒ‰ใ€‚ - ---- - -## ๅ‰ๆๆกไปถ - -| ใ‚ขใ‚คใƒ†ใƒ  | ๆœ€ๅฐ | ใŠใ™ใ™ใ‚ | -| ------------ | -------------------- | ---------------- | -| **CPU** | 1 vCPU | 2 vCPU | -| **RAM** | 1GB | 2GB | -| **ใƒ‡ใ‚ฃใ‚นใ‚ฏ** | 10GB SSD | 25 GB SSD | -| **OS** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS | -| **ใƒ‰ใƒกใ‚คใƒณ** | Cloudflareใซ็™ป้Œฒๆธˆใฟ | โ€” | -| **ใƒ‰ใƒƒใ‚ซใƒผ** | Docker ใ‚จใƒณใ‚ธใƒณ 24+ | ใƒ‰ใƒƒใ‚ซใƒผ 27+ | - -**ใƒ†ใ‚นใƒˆๆธˆใฟใƒ—ใƒญใƒใ‚คใƒ€**: Akamai (Linode)ใ€DigitalOceanใ€Vultrใ€Hetznerใ€AWS Lightsailใ€‚ - ---- - -## 1. VM ใ‚’ๆง‹ๆˆใ™ใ‚‹ - -### 1.1 ใ‚คใƒณใ‚นใ‚ฟใƒณใ‚นใ‚’ไฝœๆˆใ™ใ‚‹ - -ๅฅฝใฟใฎ VPS ใƒ—ใƒญใƒใ‚คใƒ€ใƒผใง: - -- Ubuntu 24.04 LTS ใ‚’้ธๆŠžใ—ใพใ™ -- ๆœ€ๅฐใƒ—ใƒฉใƒณ (1 vCPU / 1 GB RAM) ใ‚’้ธๆŠžใ—ใพใ™ใ€‚ -- ๅผทๅŠ›ใช root ใƒ‘ใ‚นใƒฏใƒผใƒ‰ใ‚’่จญๅฎšใ™ใ‚‹ใ‹ใ€SSH ใ‚ญใƒผใ‚’ๆง‹ๆˆใ—ใพใ™ -- **ใƒ‘ใƒ–ใƒชใƒƒใ‚ฏ IP** ใซๆณจๆ„ใ—ใฆใใ ใ•ใ„ (ไพ‹: `203.0.113.10`) - -### 1.2 SSH ็ตŒ็”ฑใงๆŽฅ็ถšใ™ใ‚‹ - -```bash -ssh root@203.0.113.10 -``` - -### 1.3 ใ‚ทใ‚นใƒ†ใƒ ใ‚’ใ‚ขใƒƒใƒ—ใƒ‡ใƒผใƒˆใ™ใ‚‹ - -```bash -apt update && apt upgrade -y -``` - -### 1.4 Docker ใฎใ‚คใƒณใ‚นใƒˆใƒผใƒซ - -```bash -# Install dependencies -apt install -y ca-certificates curl gnupg - -# Add official Docker repository -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 nginx ใ‚’ใ‚คใƒณใ‚นใƒˆใƒผใƒซใ™ใ‚‹ - -```bash -apt install -y nginx -``` - -### 1.6 ใƒ•ใ‚กใ‚คใ‚ขใ‚ฆใ‚ฉใƒผใƒซใฎๆง‹ๆˆ (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 -``` - -> **ใƒ’ใƒณใƒˆ**: ใ‚ปใ‚ญใƒฅใƒชใƒ†ใ‚ฃใ‚’ๆœ€ๅคง้™ใซ้ซ˜ใ‚ใ‚‹ใซใฏใ€ใƒใƒผใƒˆ 80 ใจ 443 ใ‚’ Cloudflare IP ใฎใฟใซๅˆถ้™ใ—ใพใ™ใ€‚ [Advanced Security](#advanced-security) ใ‚ปใ‚ฏใ‚ทใƒงใƒณใ‚’ๅ‚็…งใ—ใฆใใ ใ•ใ„ใ€‚ - ---- - -## 2. OmniRoute ใ‚’ใ‚คใƒณใ‚นใƒˆใƒผใƒซใ™ใ‚‹ - -### 2.1 ๆง‹ๆˆใƒ‡ใ‚ฃใƒฌใ‚ฏใƒˆใƒชใฎไฝœๆˆ - -```bash -mkdir -p /opt/omniroute -``` - -### 2.2 ็’ฐๅขƒๅค‰ๆ•ฐใƒ•ใ‚กใ‚คใƒซใฎไฝœๆˆ - -```bash -cat > /opt/omniroute/.env << โ€˜EOFโ€™ -# === Security === -JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY -INITIAL_PASSWORD=YourSecurePassword123! -API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY -STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY -STORAGE_ENCRYPTION_KEY_VERSION=v1 -MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT - -# === 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 (change to your domain) === -BASE_URL=https://llms.seudominio.com -NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com - -# === Cloud Sync (optional) === -# CLOUD_URL=https://cloud.omniroute.online -# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online -EOF -``` - -> โš ๏ธ **้‡่ฆ**: ไธ€ๆ„ใฎ็ง˜ๅฏ†ใ‚ญใƒผใ‚’็”Ÿๆˆใ—ใฆใใ ใ•ใ„ใ€‚ๅ„ใ‚ญใƒผใซ `openssl rand -hex 32` ใ‚’ไฝฟ็”จใ—ใพใ™ใ€‚ - -### 2.3 ใ‚ณใƒณใƒ†ใƒŠใฎ่ตทๅ‹• - -```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 ๅฎŸ่กŒไธญใงใ‚ใ‚‹ใ“ใจใ‚’็ขบ่ชใ™ใ‚‹ - -```bash -docker ps | grep omniroute -docker logs omniroute --tail 20 -``` - -`[DB] SQLite database ready` ใŠใ‚ˆใณ `listening on port 20128` ใจ่กจ็คบใ•ใ‚Œใพใ™ใ€‚ - ---- - -## 3. nginx (ใƒชใƒใƒผใ‚นใƒ—ใƒญใ‚ญใ‚ท) ใฎ่จญๅฎš - -### 3.1 SSL่จผๆ˜Žๆ›ธใฎ็”Ÿๆˆ(Cloudflare Origin) - -Cloudflareใƒ€ใƒƒใ‚ทใƒฅใƒœใƒผใƒ‰ใง: - -1. **SSL/TLS โ†’ ใ‚ชใƒชใ‚ธใƒณใ‚ตใƒผใƒใƒผ** ใซ็งปๅ‹•ใ—ใพใ™ใ€‚ -2. [**่จผๆ˜Žๆ›ธใฎไฝœๆˆ**] ใ‚’ใ‚ฏใƒชใƒƒใ‚ฏใ—ใพใ™ใ€‚ -3. ใƒ‡ใƒ•ใ‚ฉใƒซใƒˆใฎใพใพ (15 ๅนดใ€\*.yourdomain.com) -4. **้€ไฟกๅ…ƒ่จผๆ˜Žๆ›ธ**ใจ**็ง˜ๅฏ†ใ‚ญใƒผ**ใ‚’ใ‚ณใƒ”ใƒผใ—ใพใ™ใ€‚ - -```bash -mkdir -p /etc/nginx/ssl - -# Paste the certificate -nano /etc/nginx/ssl/origin.crt - -# Paste the private key -nano /etc/nginx/ssl/origin.key - -chmod 600 /etc/nginx/ssl/origin.key -``` - -### 3.2 Nginx ใฎๆง‹ๆˆ - -```bash -cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ -# Default server โ€” blocks direct access via 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.yourdomain.com; # Change to your domain - - 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.yourdomain.com; - return 301 https://$server_name$request_uri; -} -NGINX -``` - -### 3.3 ๆœ‰ๅŠนๅŒ–ใจใƒ†ใ‚นใƒˆ - -```bash -# Remove default configuration -rm -f /etc/nginx/sites-enabled/default - -# Enable OmniRoute -ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute - -# Test and reload -nginx -t && systemctl reload nginx -``` - ---- - -## 4. Cloudflare DNS ใ‚’ๆง‹ๆˆใ™ใ‚‹ - -### 4.1 DNS ใƒฌใ‚ณใƒผใƒ‰ใฎ่ฟฝๅŠ  - -Cloudflareใƒ€ใƒƒใ‚ทใƒฅใƒœใƒผใƒ‰ โ†’ DNS: - -| ใ‚ฟใ‚คใƒ— | ๅๅ‰ | ใ‚ณใƒณใƒ†ใƒณใƒ„ | ใƒ—ใƒญใ‚ญใ‚ท | -| ------ | ------ | ---------------------- | ----------- | -| ใ‚ | `llms` | `203.0.113.10` (VM IP) | โœ… ใƒ—ใƒญใ‚ญใ‚ท | - -### 4.2 SSL ใฎๆง‹ๆˆ - -**SSL/TLS โ†’ ๆฆ‚่ฆ** ใฎไธ‹: - -- ใƒขใƒผใƒ‰: **ใƒ•ใƒซ (ๅŽณๅฏ†)** - -**SSL/TLS โ†’ ใ‚จใƒƒใ‚ธ่จผๆ˜Žๆ›ธ** ใฎไธ‹: - -- ๅธธใซ HTTPS ใ‚’ไฝฟ็”จใ™ใ‚‹: โœ… ใ‚ชใƒณ -- ๆœ€ๅฐ TLS ใƒใƒผใ‚ธใƒงใƒณ: TLS 1.2 -- ่‡ชๅ‹• HTTPS ๆ›ธใๆ›ใˆ: โœ… ใ‚ชใƒณ - -### 4.3 ใƒ†ใ‚นใƒˆ - -```bash -curl -sI https://llms.seudominio.com/health -# Should return HTTP/2 200 -``` - ---- - -## 5. ้‹็”จใจไฟๅฎˆ - -### ๆ–ฐใ—ใ„ใƒใƒผใ‚ธใƒงใƒณใซใ‚ขใƒƒใƒ—ใ‚ฐใƒฌใƒผใƒ‰ใ™ใ‚‹ - -```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 -``` - -### ใƒญใ‚ฐใ‚’่กจ็คบใ™ใ‚‹ - -```bash -docker logs -f omniroute # Real-time stream -docker logs omniroute --tail 50 # Last 50 lines -``` - -### ใƒ‡ใƒผใ‚ฟใƒ™ใƒผใ‚นใฎๆ‰‹ๅ‹•ใƒใƒƒใ‚ฏใ‚ขใƒƒใƒ— - -```bash -# Copy data from the volume to the host -docker cp omniroute:/app/data ./backup-$(date +%F) - -# Or compress the entire volume -docker run --rm -v omniroute-data:/data -v $(pwd):/backup \ - alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data -``` - -### ใƒใƒƒใ‚ฏใ‚ขใƒƒใƒ—ใ‹ใ‚‰ๅพฉๅ…ƒใ™ใ‚‹ - -```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. ้ซ˜ๅบฆใชใ‚ปใ‚ญใƒฅใƒชใƒ†ใ‚ฃ - -### nginx ใ‚’ Cloudflare IP ใซๅˆถ้™ใ™ใ‚‹ - -```bash -cat > /etc/nginx/cloudflare-ips.conf << โ€˜CFโ€™ -# Cloudflare IPv4 ranges โ€” update periodically -# 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 -``` - -`http {}` ใƒ–ใƒญใƒƒใ‚ฏๅ†…ใฎ `nginx.conf` ใซไปฅไธ‹ใ‚’่ฟฝๅŠ ใ—ใพใ™ใ€‚ - -```nginx -include /etc/nginx/cloudflare-ips.conf; -``` - -###fail2ban ใ‚’ใ‚คใƒณใ‚นใƒˆใƒผใƒซใ™ใ‚‹ - -```bash -apt install -y fail2ban -systemctl enable fail2ban -systemctl start fail2ban - -# Check status -fail2ban-client status sshd -``` - -### Docker ใƒใƒผใƒˆใธใฎ็›ดๆŽฅใ‚ขใ‚ฏใ‚ปใ‚นใ‚’ใƒ–ใƒญใƒƒใ‚ฏใ™ใ‚‹ - -```bash -# Prevent direct external access to port 20128 -iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP -iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT - -# Persist the rules -apt install -y iptables-persistent -netfilter-persistent save -``` - ---- - -## 7. Cloudflare ใƒฏใƒผใ‚ซใƒผใธใฎใƒ‡ใƒ—ใƒญใ‚ค (ใ‚ชใƒ—ใ‚ทใƒงใƒณ) - -Cloudflare Workersใ‚’ไป‹ใ—ใŸใƒชใƒขใƒผใƒˆใ‚ขใ‚ฏใ‚ปใ‚นใฎๅ ดๅˆ(VMใ‚’็›ดๆŽฅๅ…ฌ้–‹ใ—ใชใ„): - -```bash -# In the local repository -cd omnirouteCloud -npm install -npx wrangler login -npx wrangler deploy -``` - -[omnirouteCloud/README.md](../omnirouteCloud/README.md) ใงๅฎŒๅ…จใชใƒ‰ใ‚ญใƒฅใƒกใƒณใƒˆใ‚’ๅ‚็…งใ—ใฆใใ ใ•ใ„ใ€‚ - ---- - -## ใƒใƒผใƒˆใฎๆฆ‚่ฆ - -| ใƒใƒผใƒˆ | ใ‚ตใƒผใƒ“ใ‚น | ใ‚ขใ‚ฏใ‚ปใ‚น | -| ------ | ------------ | ------------------------------- | -| 22 | SSH | ใƒ‘ใƒ–ใƒชใƒƒใ‚ฏ (fail2ban ใ‚ใ‚Š) | -| 80 | nginx HTTP | ใƒชใƒ€ใ‚คใƒฌใ‚ฏใƒˆ โ†’ HTTPS | -| 443 | nginx HTTPS | Cloudflare ใƒ—ใƒญใ‚ญใ‚ท็ตŒ็”ฑ | -| 20128 | ใ‚ชใƒ ใƒ‹ใƒซใƒผใƒˆ | ใƒญใƒผใ‚ซใƒซใƒ›ใ‚นใƒˆใฎใฟ (nginx ็ตŒ็”ฑ) | diff --git a/docs/i18n/ja/docs/A2A-SERVER.md b/docs/i18n/ja/docs/A2A-SERVER.md new file mode 100644 index 0000000000..80771f8696 --- /dev/null +++ b/docs/i18n/ja/docs/A2A-SERVER.md @@ -0,0 +1,200 @@ +# OmniRoute A2A Server Documentation (ๆ—ฅๆœฌ่ชž) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/A2A-SERVER.md) + +--- + +> Agent-to-Agent Protocol v0.3 โ€” OmniRoute as an intelligent routing agent + +## Agent Discovery + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements. + +--- + +## Authentication + +All `/a2a` requests require an API key via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server, authentication is bypassed. + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Sends a message to a skill and waits for the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a hello world in Python"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "uuid", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "..." }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}} + +: heartbeat 2026-03-03T17:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Available Skills + +| Skill | Description | +| :----------------- | :------------------------------------------------------------------------------------------------------------------------------ | +| `smart-routing` | Routes prompts through OmniRoute's intelligent pipeline. Returns response with routing explanation, cost, and resilience trace. | +| `quota-management` | Answers natural-language queries about provider quotas, suggests free combos, and provides quota rankings. | + +--- + +## Task Lifecycle + +``` +submitted โ†’ working โ†’ completed + โ†’ failed + โ†’ cancelled +``` + +- Tasks expire after 5 minutes (configurable) +- Terminal states: `completed`, `failed`, `cancelled` +- Event log tracks every state transition + +--- + +## Error Codes + +| Code | Meaning | +| :----- | :----------------------------- | +| -32700 | Parse error (invalid JSON) | +| -32600 | Invalid request / Unauthorized | +| -32601 | Method or skill not found | +| -32602 | Invalid params | +| -32603 | Internal error | + +--- + +## Integration Examples + +### Python (requests) + +```python +import requests + +resp = requests.post("http://localhost:20128/a2a", json={ + "jsonrpc": "2.0", "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Hello"}] + } +}, headers={"Authorization": "Bearer YOUR_KEY"}) + +result = resp.json()["result"] +print(result["artifacts"][0]["content"]) +print(result["metadata"]["routing_explanation"]) +``` + +### TypeScript (fetch) + +```typescript +const resp = await fetch("http://localhost:20128/a2a", { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: "Bearer YOUR_KEY", + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "1", + method: "message/send", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Hello" }], + }, + }), +}); +const { result } = await resp.json(); +console.log(result.metadata.routing_explanation); +``` diff --git a/docs/i18n/ja/docs/API_REFERENCE.md b/docs/i18n/ja/docs/API_REFERENCE.md new file mode 100644 index 0000000000..df4275f287 --- /dev/null +++ b/docs/i18n/ja/docs/API_REFERENCE.md @@ -0,0 +1,465 @@ +# API Reference (ๆ—ฅๆœฌ่ชž) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/API_REFERENCE.md) + +--- + +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 | +| `X-Session-Id` | Request | Sticky session key for external session affinity | +| `x_session_id` | Request | Underscore variant also accepted (direct HTTP) | +| `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 | +| `X-OmniRoute-Session-Id` | Response | Effective session ID used by OmniRoute | + +> Nginx note: if you rely on underscore headers (for example `x_session_id`), enable `underscores_in_headers 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/stats + +# Clear all caches +DELETE /api/cache/stats +``` + +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/PATCH | 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 + provider summary (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`) | +| `/api/cache/stats` | 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 | + +### Tunnels + +| Endpoint | Method | Description | +| -------------------------- | ------ | ----------------------------------------------------------------------- | +| `/api/tunnels/cloudflared` | GET | Read Cloudflare Quick Tunnel install/runtime status for the dashboard | +| `/api/tunnels/cloudflared` | POST | Enable or disable the Cloudflare Quick Tunnel (`action=enable/disable`) | + +### 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`. + +### ACP Agents + +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | + +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). + +### Resilience & Rate Limits + +| Endpoint | Method | Description | +| ----------------------- | --------- | ------------------------------- | +| `/api/resilience` | GET/PATCH | 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` diff --git a/docs/i18n/ja/docs/ARCHITECTURE.md b/docs/i18n/ja/docs/ARCHITECTURE.md new file mode 100644 index 0000000000..6001bf18a3 --- /dev/null +++ b/docs/i18n/ja/docs/ARCHITECTURE.md @@ -0,0 +1,814 @@ +# OmniRoute Architecture (ๆ—ฅๆœฌ่ชž) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/ARCHITECTURE.md) + +--- + +_Last updated: 2026-03-28_ + +## 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 (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developerโ†’system, systemโ†’user) for cross-provider compatibility +- Structured output conversion (json_schema โ†’ Gemini responseSchema) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) +- Global system prompt injection +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout โ†’ budget โ†’ fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) + +Primary runtime model: + +- Next.js 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.) + +## Dashboard Surface (Current) + +Main pages under `src/app/(dashboard)/dashboard/`: + +- `/dashboard` โ€” quick start + provider overview +- `/dashboard/endpoint` โ€” endpoint proxy + MCP + A2A + API endpoint tabs +- `/dashboard/providers` โ€” provider connections and credentials +- `/dashboard/combos` โ€” combo strategies, templates, model routing rules +- `/dashboard/costs` โ€” cost aggregation and pricing visibility +- `/dashboard/analytics` โ€” usage analytics and evaluations +- `/dashboard/limits` โ€” quota/rate controls +- `/dashboard/cli-tools` โ€” CLI onboarding, runtime detection, config generation +- `/dashboard/agents` โ€” detected ACP agents + custom agent registration +- `/dashboard/media` โ€” image/video/music playground +- `/dashboard/search-tools` โ€” search provider testing and history +- `/dashboard/health` โ€” uptime, circuit breakers, rate limits +- `/dashboard/logs` โ€” request/proxy/audit/console logs +- `/dashboard/settings` โ€” system settings tabs (general, routing, combo defaults, etc.) +- `/dashboard/api-manager` โ€” API key lifecycle and model permissions + +## 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[(storage.sqlite)] + UDB[(usage tables + log artifacts)] + end + + subgraph Upstreams[Upstream Providers] + P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/Qoder/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/route.ts` (GET) +- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- OAuth: `src/app/api/oauth/*` +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` +- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI tooling helpers: `src/app/api/cli-tools/*` +- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) +- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) โ€” provider profiles, circuit breaker, rate limit state +- Resilience reset: `src/app/api/resilience/reset` (POST) โ€” reset breakers + cooldowns +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) +- Telemetry: `src/app/api/telemetry/summary` (GET) +- Budget: `src/app/api/usage/budget` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Policies: `src/app/api/policies` (GET/POST) + +## 2) SSE + 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` +- Response sanitization: `open-sse/handlers/responseSanitizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.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`, `qoder.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 (SQLite): + +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** + +Usage persistence: + +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present + +Domain State DB (SQLite): + +- `src/lib/db/domainState.ts` โ€” CRUD operations 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`, `src/shared/services/modelSyncScheduler.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Periodic task: `src/shared/services/modelSyncScheduler.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. Combo routing adds one extra guard: provider-scoped 400s such as upstream content-block and role-validation failures are treated as model-local failures so later combo targets can still run. + +## 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: + +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` + +## Deployment Topology + +```mermaid +flowchart LR + 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[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] + end + + subgraph External[External Services] + Providers[AI Providers] + SyncCloud[Cloud Sync Service] + end + + CLI --> Next + Browser --> Next + Next --> Core + Next --> MainDB + Core --> MainDB + Core --> UsageDB + Core --> Providers + Next --> SyncCloud +``` + +## Module Mapping (Decision-Critical) + +### Route and API Modules + +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle +- `src/app/api/models/alias`: alias management +- `src/app/api/combos*`: fallback combo management +- `src/app/api/pricing`: pricing overrides for cost calculation +- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers +- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) +- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) +- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) +- `src/app/api/sessions`: active session listing (GET) +- `src/app/api/rate-limits`: per-account rate limit status (GET) + +### Routing and Execution Core + +- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior + +### Translation Registry and Format Converters + +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` +- Format constants: `open-sse/translator/formats.ts` + +### Persistence + +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables + +## Provider Executor Coverage (Strategy Pattern) + +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. + +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, Qoder, 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 | +| Qoder | openai | OAuth (Basic) | โœ… | โœ… | โœ… | โš ๏ธ Per request | +| OpenRouter | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| GLM/Kimi/MiniMax | claude | API Key | โœ… | โœ… | โŒ | โŒ | +| DeepSeek | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Groq | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| xAI (Grok) | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Mistral | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Perplexity | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Together AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Fireworks AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Cerebras | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Cohere | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| NVIDIA NIM | openai | API Key | โœ… | โœ… | โŒ | โŒ | + +## Format Translation Coverage + +Detected source formats include: + +- `openai` +- `openai-responses` +- `claude` +- `gemini` + +Target formats include: + +- OpenAI chat/Responses +- Claude +- Gemini/Gemini-CLI/Antigravity envelope +- Kiro +- Cursor + +Translations use **OpenAI as the hub format** โ€” all conversions go through OpenAI as intermediate: + +``` +Source Format โ†’ OpenAI (hub) โ†’ Target Format +``` + +Translations are selected dynamically based on source payload shape and provider target format. + +Additional processing layers in the translation pipeline: + +- **Response sanitization** โ€” Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI targets; merges `system` โ†’ `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** โ€” Parses `...` blocks from content into `reasoning_content` field +- **Structured output** โ€” Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` + +## Supported API Endpoints + +| 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` | Provider Models | Provider model metadata backing custom and managed available models | + +## 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 `/logs//` 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 + +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON โ†’ SQLite migration compatibility path + +## Observability and Operational Signals + +Runtime visibility sources: + +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- four-stage detailed payload captures in SQLite (`request_detail_logs`) when `settings.detailed_logs_enabled=true` +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption + +Detailed request payload capture stores up to four JSON payload stages per routed call: + +- raw request received from the client +- translated request actually sent upstream +- provider response reconstructed as JSON; streamed responses are compacted to the final summary plus stream metadata +- final client response returned by OmniRoute; streamed responses are stored in the same compact summary form + +## Security-Sensitive Boundaries + +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics + +## Environment and Runtime Matrix + +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` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). + +## Operational Verification Checklist + +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: +- `GET /api/settings` +- `GET /api/v1/models` +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/ja/docs/AUTO-COMBO.md b/docs/i18n/ja/docs/AUTO-COMBO.md new file mode 100644 index 0000000000..c0d07aee7c --- /dev/null +++ b/docs/i18n/ja/docs/AUTO-COMBO.md @@ -0,0 +1,67 @@ +# OmniRoute Auto-Combo Engine (ๆ—ฅๆœฌ่ชž) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/AUTO-COMBO.md) + +--- + +> Self-managing model chains with adaptive scoring + +## How It Works + +The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**: + +| Factor | Weight | Description | +| :--------- | :----- | :---------------------------------------------- | +| Quota | 0.20 | Remaining capacity [0..1] | +| Health | 0.25 | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 | +| CostInv | 0.20 | Inverse cost (cheaper = higher score) | +| LatencyInv | 0.15 | Inverse p95 latency (faster = higher) | +| TaskFit | 0.10 | Model ร— task type fitness score | +| Stability | 0.10 | Low variance in latency/errors | + +## Mode Packs + +| Pack | Focus | Key Weight | +| :---------------------- | :----------- | :--------------- | +| ๐Ÿš€ **Ship Fast** | Speed | latencyInv: 0.35 | +| ๐Ÿ’ฐ **Cost Saver** | Economy | costInv: 0.40 | +| ๐ŸŽฏ **Quality First** | Best model | taskFit: 0.40 | +| ๐Ÿ“ก **Offline Friendly** | Availability | quota: 0.40 | + +## Self-Healing + +- **Temporary exclusion**: Score < 0.2 โ†’ excluded for 5 min (progressive backoff, max 30 min) +- **Circuit breaker awareness**: OPEN โ†’ auto-excluded; HALF_OPEN โ†’ probe requests +- **Incident mode**: >50% OPEN โ†’ disable exploration, maximize stability +- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout + +## Bandit Exploration + +5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode. + +## API + +```bash +# Create auto-combo +curl -X POST http://localhost:20128/api/combos/auto \ + -H "Content-Type: application/json" \ + -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}' + +# List auto-combos +curl http://localhost:20128/api/combos/auto +``` + +## Task Fitness + +30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` โ†’ high coding score). + +## Files + +| File | Purpose | +| :------------------------------------------- | :------------------------------------ | +| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization | +| `open-sse/services/autoCombo/taskFitness.ts` | Model ร— task fitness lookup | +| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap | +| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode | +| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles | +| `src/app/api/combos/auto/route.ts` | REST API | diff --git a/docs/i18n/ja/docs/CLI-TOOLS.md b/docs/i18n/ja/docs/CLI-TOOLS.md new file mode 100644 index 0000000000..81259046ed --- /dev/null +++ b/docs/i18n/ja/docs/CLI-TOOLS.md @@ -0,0 +1,348 @@ +# CLI Tools Setup Guide โ€” OmniRoute (ๆ—ฅๆœฌ่ชž) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CLI-TOOLS.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CLI-TOOLS.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CLI-TOOLS.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CLI-TOOLS.md) + +--- + +This guide explains how to install and configure all supported AI coding CLI tools +to use **OmniRoute** as the unified backend, giving you centralized key management, +cost tracking, model switching, and request logging across every tool. + +--- + +## How It Works + +``` +Claude / Codex / OpenCode / Cline / KiloCode / Continue / Kiro / Cursor / Copilot + โ”‚ + โ–ผ (all point to OmniRoute) + http://YOUR_SERVER:20128/v1 + โ”‚ + โ–ผ (OmniRoute routes to the right provider) + Anthropic / OpenAI / Gemini / DeepSeek / Groq / Mistral / ... +``` + +**Benefits:** + +- One API key to manage all tools +- Cost tracking across all CLIs in the dashboard +- Model switching without reconfiguring every tool +- Works locally and on remote servers (VPS) + +--- + +## Supported Tools (Dashboard Source of Truth) + +The dashboard cards in `/dashboard/cli-tools` are generated from `src/shared/constants/cliTools.ts`. +Current list (v3.0.0-rc.16): + +| Tool | ID | Command | Setup Mode | Install Method | +| ------------------ | ------------- | ---------- | ---------- | -------------- | +| **Claude Code** | `claude` | `claude` | env | npm | +| **OpenAI Codex** | `codex` | `codex` | custom | npm | +| **Factory Droid** | `droid` | `droid` | custom | bundled/CLI | +| **OpenClaw** | `openclaw` | `openclaw` | custom | bundled/CLI | +| **Cursor** | `cursor` | app | guide | desktop app | +| **Cline** | `cline` | `cline` | custom | npm | +| **Kilo Code** | `kilo` | `kilocode` | custom | npm | +| **Continue** | `continue` | extension | guide | VS Code | +| **Antigravity** | `antigravity` | internal | mitm | OmniRoute | +| **GitHub Copilot** | `copilot` | extension | custom | VS Code | +| **OpenCode** | `opencode` | `opencode` | guide | npm | +| **Kiro AI** | `kiro` | app/cli | mitm | desktop/CLI | + +### CLI fingerprint sync (Agents + Settings) + +`/dashboard/agents` and `Settings > CLI Fingerprint` use `src/shared/constants/cliCompatProviders.ts`. +This keeps provider IDs aligned with CLI cards and legacy IDs. + +| CLI ID | Fingerprint Provider ID | +| ---------------------------------------------------------------------------------------------------- | ----------------------- | +| `kilo` | `kilocode` | +| `copilot` | `github` | +| `claude` / `codex` / `antigravity` / `kiro` / `cursor` / `cline` / `opencode` / `droid` / `openclaw` | same ID | + +Legacy IDs still accepted for compatibility: `copilot`, `kimi-coding`, `qwen`. + +--- + +## Step 1 โ€” Get an OmniRoute API Key + +1. Open the OmniRoute dashboard โ†’ **API Manager** (`/dashboard/api-manager`) +2. Click **Create API Key** +3. Give it a name (e.g. `cli-tools`) and select all permissions +4. Copy the key โ€” you'll need it for every CLI below + +> Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` + +--- + +## Step 2 โ€” Install CLI Tools + +All npm-based tools require Node.js 18+: + +```bash +# Claude Code (Anthropic) +npm install -g @anthropic-ai/claude-code + +# OpenAI Codex +npm install -g @openai/codex + +# OpenCode +npm install -g opencode-ai + +# Cline +npm install -g cline + +# KiloCode +npm install -g kilocode + +# Kiro CLI (Amazon โ€” requires curl + unzip) +apt-get install -y unzip # on Debian/Ubuntu +curl -fsSL https://cli.kiro.dev/install | bash +export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc +``` + +**Verify:** + +```bash +claude --version # 2.x.x +codex --version # 0.x.x +opencode --version # x.x.x +cline --version # 2.x.x +kilocode --version # x.x.x (or: kilo --version) +kiro-cli --version # 1.x.x +``` + +--- + +## Step 3 โ€” Set Global Environment Variables + +Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`: + +```bash +# OmniRoute Universal Endpoint +export OPENAI_BASE_URL="http://localhost:20128/v1" +export OPENAI_API_KEY="sk-your-omniroute-key" +export ANTHROPIC_BASE_URL="http://localhost:20128/v1" +export ANTHROPIC_API_KEY="sk-your-omniroute-key" +export GEMINI_BASE_URL="http://localhost:20128/v1" +export GEMINI_API_KEY="sk-your-omniroute-key" +``` + +> For a **remote server** replace `localhost:20128` with the server IP or domain, +> e.g. `http://192.168.0.15:20128`. + +--- + +## Step 4 โ€” Configure Each Tool + +### Claude Code + +```bash +# Via CLI: +claude config set --global api-base-url http://localhost:20128/v1 + +# Or create ~/.claude/settings.json: +mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF +{ + "apiBaseUrl": "http://localhost:20128/v1", + "apiKey": "sk-your-omniroute-key" +} +EOF +``` + +**Test:** `claude "say hello"` + +--- + +### OpenAI Codex + +```bash +mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF +model: auto +apiKey: sk-your-omniroute-key +apiBaseUrl: http://localhost:20128/v1 +EOF +``` + +**Test:** `codex "what is 2+2?"` + +--- + +### OpenCode + +```bash +mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF +[provider.openai] +base_url = "http://localhost:20128/v1" +api_key = "sk-your-omniroute-key" +EOF +``` + +**Test:** `opencode` + +--- + +### Cline (CLI or VS Code) + +**CLI mode:** + +```bash +mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF +{ + "apiProvider": "openai", + "openAiBaseUrl": "http://localhost:20128/v1", + "openAiApiKey": "sk-your-omniroute-key" +} +EOF +``` + +**VS Code mode:** +Cline extension settings โ†’ API Provider: `OpenAI Compatible` โ†’ Base URL: `http://localhost:20128/v1` + +Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ Cline โ†’ Apply Config**. + +--- + +### KiloCode (CLI or VS Code) + +**CLI mode:** + +```bash +kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key +``` + +**VS Code settings:** + +```json +{ + "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", + "kilo-code.apiKey": "sk-your-omniroute-key" +} +``` + +Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ KiloCode โ†’ Apply Config**. + +--- + +### Continue (VS Code Extension) + +Edit `~/.continue/config.yaml`: + +```yaml +models: + - name: OmniRoute + provider: openai + model: auto + apiBase: http://localhost:20128/v1 + apiKey: sk-your-omniroute-key + default: true +``` + +Restart VS Code after editing. + +--- + +### Kiro CLI (Amazon) + +```bash +# Login to your AWS/Kiro account: +kiro-cli login + +# The CLI uses its own auth โ€” OmniRoute is not needed as backend for Kiro CLI itself. +# Use kiro-cli alongside OmniRoute for other tools. +kiro-cli status +``` + +--- + +### Cursor (Desktop App) + +> **Note:** Cursor routes requests through its cloud. For OmniRoute integration, +> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL. + +Via GUI: **Settings โ†’ Models โ†’ OpenAI API Key** + +- Base URL: `https://your-domain.com/v1` +- API Key: your OmniRoute key + +--- + +## Dashboard Auto-Configuration + +The OmniRoute dashboard automates configuration for most tools: + +1. Go to `http://localhost:20128/dashboard/cli-tools` +2. Expand any tool card +3. Select your API key from the dropdown +4. Click **Apply Config** (if tool is detected as installed) +5. Or copy the generated config snippet manually + +--- + +## Built-in Agents: Droid & OpenClaw + +**Droid** and **OpenClaw** are AI agents built directly into OmniRoute โ€” no installation needed. +They run as internal routes and use OmniRoute's model routing automatically. + +- Access: `http://localhost:20128/dashboard/agents` +- Configure: same combos and providers as all other tools +- No API key or CLI install required + +--- + +## Available API Endpoints + +| Endpoint | Description | Use For | +| -------------------------- | ----------------------------- | --------------------------- | +| `/v1/chat/completions` | Standard chat (all providers) | All modern tools | +| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows | +| `/v1/completions` | Legacy text completions | Older tools using `prompt:` | +| `/v1/embeddings` | Text embeddings | RAG, search | +| `/v1/images/generations` | Image generation | DALL-E, Flux, etc. | +| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS | +| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI | + +--- + +## ใƒˆใƒฉใƒ–ใƒซใ‚ทใƒฅใƒผใƒ†ใ‚ฃใƒณใ‚ฐ + +| Error | Cause | Fix | +| ------------------------- | ----------------------- | ------------------------------------------ | +| `Connection refused` | OmniRoute not running | `pm2 start omniroute` | +| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` | +| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` | +| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` | +| CLI shows "not installed" | Binary not in PATH | Check `which ` | +| `kiro-cli: not found` | Not in PATH | `export PATH="$HOME/.local/bin:$PATH"` | + +--- + +## Quick Setup Script (One Command) + +```bash +# Install all CLIs and configure for OmniRoute (replace with your key and server URL) +OMNIROUTE_URL="http://localhost:20128/v1" +OMNIROUTE_KEY="sk-your-omniroute-key" + +npm install -g @anthropic-ai/claude-code @openai/codex opencode-ai cline kilocode + +# Kiro CLI +apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash + +# Write configs +mkdir -p ~/.claude ~/.codex ~/.config/opencode ~/.continue + +cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" +cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" +cat >> ~/.bashrc << EOF +export OPENAI_BASE_URL="$OMNIROUTE_URL" +export OPENAI_API_KEY="$OMNIROUTE_KEY" +export ANTHROPIC_BASE_URL="$OMNIROUTE_URL" +export ANTHROPIC_API_KEY="$OMNIROUTE_KEY" +EOF + +source ~/.bashrc +echo "โœ… All CLIs installed and configured for OmniRoute" +``` diff --git a/docs/i18n/ja/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/ja/docs/CODEBASE_DOCUMENTATION.md new file mode 100644 index 0000000000..8acc07de92 --- /dev/null +++ b/docs/i18n/ja/docs/CODEBASE_DOCUMENTATION.md @@ -0,0 +1,591 @@ +# omniroute โ€” Codebase Documentation (ๆ—ฅๆœฌ่ชž) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CODEBASE_DOCUMENTATION.md) + +--- + +> 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
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, Qoder, 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. + +#### ใ‚ขใƒผใ‚ญใƒ†ใ‚ฏใƒใƒฃ + +```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 | +| Qoder | 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"] +``` diff --git a/docs/i18n/ja/docs/COVERAGE_PLAN.md b/docs/i18n/ja/docs/COVERAGE_PLAN.md new file mode 100644 index 0000000000..5e4a3d3e7e --- /dev/null +++ b/docs/i18n/ja/docs/COVERAGE_PLAN.md @@ -0,0 +1,170 @@ +# Test Coverage Plan (ๆ—ฅๆœฌ่ชž) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/COVERAGE_PLAN.md) + +--- + +Last updated: 2026-03-28 + +## Baseline + +There are multiple coverage numbers depending on how the report is computed. For planning, only one of them is useful. + +| Metric | Scope | Statements / Lines | Branches | Functions | Notes | +| -------------------- | ----------------------------------------------------- | -----------------: | -------: | --------: | --------------------------------------------------- | +| Legacy | Old `npm run test:coverage` | 79.42% | 75.15% | 67.94% | Inflated: counts test files and excludes `open-sse` | +| Diagnostic | Source-only, excluding tests and excluding `open-sse` | 68.16% | 63.55% | 64.06% | Useful only to isolate `src/**` | +| Recommended baseline | Source-only, excluding tests and including `open-sse` | 56.95% | 66.05% | 57.80% | This is the project-wide baseline to improve | + +The recommended baseline is the number to optimize against. + +## Rules + +- Coverage targets apply to source files, not to `tests/**`. +- `open-sse/**` is part of the product and must remain in scope. +- New code should not reduce coverage in touched areas. +- Prefer testing behavior and branch outcomes over implementation details. +- Prefer temp SQLite databases and small fixtures over broad mocks for `src/lib/db/**`. + +## Current command set + +- `npm run test:coverage` + - Main source coverage gate for the unit test suite + - Generates `text-summary`, `html`, `json-summary`, and `lcov` +- `npm run coverage:report` + - Detailed file-by-file report from the latest run +- `npm run test:coverage:legacy` + - Historical comparison only + +## Milestones + +| Phase | Target | Focus | +| ------- | ---------------------: | ------------------------------------------------- | +| Phase 1 | 60% statements / lines | Quick wins and low-risk utility coverage | +| Phase 2 | 65% statements / lines | DB and route foundations | +| Phase 3 | 70% statements / lines | Provider validation and usage analytics | +| Phase 4 | 75% statements / lines | `open-sse` translators and helpers | +| Phase 5 | 80% statements / lines | `open-sse` handlers and executor branches | +| Phase 6 | 85% statements / lines | Harder edge cases, branch debt, regression suites | +| Phase 7 | 90% statements / lines | Final sweep, gap closure, strict ratchet | + +Branches and functions should ratchet upward with each phase, but the primary hard target is statements / lines. + +## Priority hotspots + +These files or areas offer the best return for the next phases: + +1. `open-sse/handlers` + - `chatCore.ts` at 7.57% + - Overall directory at 29.07% +2. `open-sse/translator/request` + - Overall directory at 36.39% + - Many translators are still near single-digit coverage +3. `open-sse/translator/response` + - Overall directory at 8.07% +4. `open-sse/executors` + - Overall directory at 36.62% +5. `src/lib/db` + - `models.ts` at 20.66% + - `registeredKeys.ts` at 34.46% + - `modelComboMappings.ts` at 36.25% + - `settings.ts` at 46.40% + - `webhooks.ts` at 33.33% +6. `src/lib/usage` + - `usageHistory.ts` at 21.12% + - `usageStats.ts` at 9.56% + - `costCalculator.ts` at 30.00% +7. `src/lib/providers` + - `validation.ts` at 41.16% +8. Low-risk utility and API files for early gains + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/api/errorResponse.ts` + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +## Execution checklist + +### Phase 1: 56.95% -> 60% + +- [x] Fix coverage metric so it reflects source code instead of test files +- [x] Keep a legacy coverage script for comparison +- [x] Record the baseline and hotspots in-repo +- [ ] Add focused tests for low-risk utilities: + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/fetchTimeout.ts` + - `src/lib/api/errorResponse.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/display/names.ts` +- [ ] Add route tests for: + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +### Phase 2: 60% -> 65% + +- [ ] Add DB-backed tests for: + - `src/lib/db/modelComboMappings.ts` + - `src/lib/db/settings.ts` + - `src/lib/db/registeredKeys.ts` +- [ ] Cover branch behavior in: + - `src/lib/providers/validation.ts` + - `src/app/api/v1/embeddings/route.ts` + - `src/app/api/v1/moderations/route.ts` + +### Phase 3: 65% -> 70% + +- [ ] Add usage analytics tests for: + - `src/lib/usage/usageHistory.ts` + - `src/lib/usage/usageStats.ts` + - `src/lib/usage/costCalculator.ts` +- [ ] Expand route coverage for proxy management and settings branches + +### Phase 4: 70% -> 75% + +- [ ] Cover translator helpers and central translation paths: + - `open-sse/translator/index.ts` + - `open-sse/translator/helpers/*` + - `open-sse/translator/request/*` + - `open-sse/translator/response/*` + +### Phase 5: 75% -> 80% + +- [ ] Add handler-level tests for: + - `open-sse/handlers/chatCore.ts` + - `open-sse/handlers/responsesHandler.js` + - `open-sse/handlers/imageGeneration.js` + - `open-sse/handlers/embeddings.js` +- [ ] Add executor branch coverage for provider-specific auth, retries, and endpoint overrides + +### Phase 6: 80% -> 85% + +- [ ] Merge more edge-case suites into the main coverage path +- [ ] Increase function coverage for DB modules with weak constructor/helper coverage +- [ ] Close branch gaps in `settings.ts`, `registeredKeys.ts`, `validation.ts`, and translator helpers + +### Phase 7: 85% -> 90% + +- [ ] Treat the remaining low-coverage files as blockers +- [ ] Add regression tests for every uncovered production bug fixed during the push to 90% +- [ ] Raise the coverage gate in CI only after the local baseline is stable for at least two consecutive runs + +## Ratchet policy + +Update `npm run test:coverage` thresholds only after the project actually exceeds the next milestone with a comfortable buffer. + +Recommended ratchet sequence: + +1. 55/60/55 +2. 60/62/58 +3. 65/64/62 +4. 70/66/66 +5. 75/70/72 +6. 80/75/78 +7. 85/80/84 +8. 90/85/88 + +Order is `statements-lines / branches / functions`. + +## Known gap + +The current coverage command measures the main Node unit suite and includes source reached from it, including `open-sse`. It does not yet merge Vitest coverage into a single unified report. That merge is worth doing later, but it is not a blocker for starting the 60% -> 80% climb. diff --git a/docs/i18n/ja/docs/FEATURES.md b/docs/i18n/ja/docs/FEATURES.md index 5d62d97c47..c1c08468c2 100644 --- a/docs/i18n/ja/docs/FEATURES.md +++ b/docs/i18n/ja/docs/FEATURES.md @@ -1,6 +1,6 @@ # OmniRoute โ€” Dashboard Features Gallery (ๆ—ฅๆœฌ่ชž) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/FEATURES.md) --- @@ -10,7 +10,7 @@ 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). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. ![Providers Dashboard](screenshots/01-providers.png) diff --git a/docs/i18n/ja/docs/MCP-SERVER.md b/docs/i18n/ja/docs/MCP-SERVER.md new file mode 100644 index 0000000000..ae62871a29 --- /dev/null +++ b/docs/i18n/ja/docs/MCP-SERVER.md @@ -0,0 +1,87 @@ +# OmniRoute MCP Server Documentation (ๆ—ฅๆœฌ่ชž) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/MCP-SERVER.md) + +--- + +> Model Context Protocol server with 16 intelligent tools + +## ใ‚คใƒณใ‚นใƒˆใƒผใƒซ + +OmniRoute MCP is built-in. Start it with: + +```bash +omniroute --mcp +``` + +Or via the open-sse transport: + +```bash +# HTTP streamable transport (port 20130) +omniroute --dev # MCP auto-starts on /mcp endpoint +``` + +## IDE Configuration + +See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup. + +--- + +## Essential Tools (8) + +| Tool | Description | +| :------------------------------ | :--------------------------------------- | +| `omniroute_get_health` | Gateway health, circuit breakers, uptime | +| `omniroute_list_combos` | All configured combos with models | +| `omniroute_get_combo_metrics` | Performance metrics for a specific combo | +| `omniroute_switch_combo` | Switch active combo by ID/name | +| `omniroute_check_quota` | Quota status per provider or all | +| `omniroute_route_request` | Send a chat completion through OmniRoute | +| `omniroute_cost_report` | Cost analytics for a time period | +| `omniroute_list_models_catalog` | Full model catalog with capabilities | + +## Advanced Tools (8) + +| Tool | Description | +| :--------------------------------- | :---------------------------------------------------------- | +| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | +| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | +| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | +| `omniroute_test_combo` | Live-test all models in a combo via a real upstream request | +| `omniroute_get_provider_metrics` | Detailed metrics for one provider | +| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | +| `omniroute_explain_route` | Explain a past routing decision | +| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | + +## Authentication + +MCP tools are authenticated via API key scopes. Each tool requires specific scopes: + +| Scope | Tools | +| :------------- | :----------------------------------------------- | +| `read:health` | get_health, get_provider_metrics | +| `read:combos` | list_combos, get_combo_metrics | +| `write:combos` | switch_combo | +| `read:quota` | check_quota | +| `write:route` | route_request, simulate_route, test_combo | +| `read:usage` | cost_report, get_session_snapshot, explain_route | +| `write:config` | set_budget_guard, set_resilience_profile | +| `read:models` | list_models_catalog, best_combo_for_task | + +## Audit Logging + +Every tool call is logged to `mcp_tool_audit` with: + +- Tool name, arguments, result +- Duration (ms), success/failure +- API key hash, timestamp + +## Files + +| File | Purpose | +| :------------------------------------------- | :------------------------------------------ | +| `open-sse/mcp-server/server.ts` | MCP server creation + 16 tool registrations | +| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport | +| `open-sse/mcp-server/auth.ts` | API key + scope validation | +| `open-sse/mcp-server/audit.ts` | Tool call audit logging | +| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers | diff --git a/docs/i18n/ja/docs/RELEASE_CHECKLIST.md b/docs/i18n/ja/docs/RELEASE_CHECKLIST.md new file mode 100644 index 0000000000..b3138974f4 --- /dev/null +++ b/docs/i18n/ja/docs/RELEASE_CHECKLIST.md @@ -0,0 +1,37 @@ +# Release Checklist (ๆ—ฅๆœฌ่ชž) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/RELEASE_CHECKLIST.md) + +--- + +Use this checklist before tagging or publishing a new OmniRoute release. + +## Version and Changelog + +1. Bump `package.json` version (`x.y.z`) in the release branch. +2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: + - `## [x.y.z] โ€” YYYY-MM-DD` +3. Keep `## [Unreleased]` as the first changelog section for upcoming work. +4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. + +## API Docs + +1. Update `docs/openapi.yaml`: + - `info.version` must equal `package.json` version. +2. Validate endpoint examples if API contracts changed. + +## Runtime Docs + +1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. +2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. +3. Update localized docs if source docs changed significantly. + +## Automated Check + +Run the sync guard locally before opening PR: + +```bash +npm run check:docs-sync +``` + +CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/ja/docs/TROUBLESHOOTING.md b/docs/i18n/ja/docs/TROUBLESHOOTING.md new file mode 100644 index 0000000000..d2fcf34b48 --- /dev/null +++ b/docs/i18n/ja/docs/TROUBLESHOOTING.md @@ -0,0 +1,256 @@ +# Troubleshooting (ๆ—ฅๆœฌ่ชž) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/TROUBLESHOOTING.md) + +--- + +Common problems and solutions for OmniRoute. + +--- + +## Quick Fixes + +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | + +--- + +## Provider Issues + +### "Language model did not provide messages" + +**Cause:** Provider quota exhausted. + +**Fix:** + +1. 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, Qoder) 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}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) + +--- + +## Circuit Breaker Issues + +### Provider stuck in OPEN state + +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. + +**Fix:** + +1. 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 +- **SDK returns raw string instead of object** โ€” Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** โ€” Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** โ€” Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** โ€” Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` + +--- + +## Resilience Settings + +### Auto rate-limit not triggering + +- 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. + +--- + +## Optional RAG / LLM failure taxonomy (16 problems) + +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` โ€ฆ `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard โ†’ Health** for real-time system status +- **Translator**: Use **Dashboard โ†’ Translator** to debug format issues diff --git a/docs/i18n/ja/USER_GUIDE.md b/docs/i18n/ja/docs/USER_GUIDE.md similarity index 82% rename from docs/i18n/ja/USER_GUIDE.md rename to docs/i18n/ja/docs/USER_GUIDE.md index 46a9ecd494..3f0b175d16 100644 --- a/docs/i18n/ja/USER_GUIDE.md +++ b/docs/i18n/ja/docs/USER_GUIDE.md @@ -1,8 +1,6 @@ # User Guide (ๆ—ฅๆœฌ่ชž) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/USER_GUIDE.md) - -> ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/USER_GUIDE.md) --- @@ -320,7 +318,7 @@ Model: cc/claude-opus-4-6 --- -## ๐Ÿš€ Deployment +## ใƒ‡ใƒ—ใƒญใ‚ค ### Global npm install (Recommended) @@ -511,23 +509,26 @@ post_install() { ### Environment Variables -| Variable | Default | Description | -| ------------------------- | ------------------------------------ | ------------------------------------------------------- | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | -| `INITIAL_PASSWORD` | `123456` | First login password | -| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | -| `PORT` | framework default | Service port (`20128` in examples) | -| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | -| `NODE_ENV` | runtime default | Set `production` for deploy | -| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | -| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | -| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | -| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | -| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | -| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | -| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | -| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | +| 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/*` | +| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand | +| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | For the full environment variable reference, see the [README](../README.md). @@ -598,6 +599,11 @@ curl -X POST http://localhost:20128/api/provider-models \ Or use Dashboard: **Providers โ†’ [Provider] โ†’ Custom Models**. +Notes: + +- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers. +- The **Custom Models** section is intended for providers that do not expose managed available-model imports. + ### Dedicated Provider Routes Route requests directly to a specific provider with model validation: @@ -642,6 +648,14 @@ Returns models grouped by provider with types (`chat`, `embedding`, `image`). - Automatic background sync with timeout + fail-fast - Prefer server-side `BASE_URL`/`CLOUD_URL` in production +### Cloudflare Quick Tunnel + +- Available in **Dashboard โ†’ Endpoints** for Docker and other self-hosted deployments +- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint +- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary +- Tunnel URLs are ephemeral and change every time you stop/start the tunnel +- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download + ### LLM Gateway Intelligence (Phase 9) - **Semantic Cache** โ€” Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) @@ -757,11 +771,11 @@ OmniRoute implements provider-level resilience with four components: 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 | +| 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 unless `DISABLE_SQLITE_AUTO_BACKUP=true` | ```bash # API: Export database @@ -787,10 +801,11 @@ curl -X POST http://localhost:20128/api/db-backups/import \ ### Settings Dashboard -The settings page is organized into 5 tabs for easy navigation: +The settings page is organized into 6 tabs for easy navigation: | Tab | Contents | | -------------- | ---------------------------------------------------------------------------------------------- | +| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility | | **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | | **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | | **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | diff --git a/docs/i18n/ja/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/ja/docs/VM_DEPLOYMENT_GUIDE.md new file mode 100644 index 0000000000..4514cd0528 --- /dev/null +++ b/docs/i18n/ja/docs/VM_DEPLOYMENT_GUIDE.md @@ -0,0 +1,403 @@ +# OmniRoute โ€” Deployment Guide on VM with Cloudflare (ๆ—ฅๆœฌ่ชž) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/VM_DEPLOYMENT_GUIDE.md) + +--- + +Complete guide to install and configure OmniRoute on a VM (VPS) with domain managed via Cloudflare. + +--- + +## Prerequisites + +| Item | Minimum | Recommended | +| ---------- | ------------------------ | ---------------- | +| **CPU** | 1 vCPU | 2 vCPU | +| **RAM** | 1 GB | 2 GB | +| **Disk** | 10 GB SSD | 25 GB SSD | +| **OS** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS | +| **Domain** | Registered on Cloudflare | โ€” | +| **Docker** | Docker Engine 24+ | Docker 27+ | + +**Tested providers**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. + +--- + +## 1. Configure the VM + +### 1.1 Create the instance + +On your preferred VPS provider: + +- Choose Ubuntu 24.04 LTS +- Select the minimum plan (1 vCPU / 1 GB RAM) +- Set a strong root password or configure SSH key +- Note the **public IP** (e.g., `203.0.113.10`) + +### 1.2 Connect via SSH + +```bash +ssh root@203.0.113.10 +``` + +### 1.3 Update the system + +```bash +apt update && apt upgrade -y +``` + +### 1.4 Install Docker + +```bash +# Install dependencies +apt install -y ca-certificates curl gnupg + +# Add official Docker repository +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 Install nginx + +```bash +apt install -y nginx +``` + +### 1.6 Configure 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 +``` + +> **Tip**: For maximum security, restrict ports 80 and 443 to Cloudflare IPs only. See the [Advanced Security](#advanced-security) section. + +--- + +## 2. Install OmniRoute + +### 2.1 Create configuration directory + +```bash +mkdir -p /opt/omniroute +``` + +### 2.2 Create environment variables file + +```bash +cat > /opt/omniroute/.env << โ€˜EOFโ€™ +# === Security === +JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY +INITIAL_PASSWORD=YourSecurePassword123! +API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY +STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY +STORAGE_ENCRYPTION_KEY_VERSION=v1 +MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT + +# === 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 (change to your domain) === +BASE_URL=https://llms.seudominio.com +NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com + +# === Cloud Sync (optional) === +# CLOUD_URL=https://cloud.omniroute.online +# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online +EOF +``` + +> โš ๏ธ **IMPORTANT**: Generate unique secret keys! Use `openssl rand -hex 32` for each key. + +### 2.3 Start the 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 Verify that it is running + +```bash +docker ps | grep omniroute +docker logs omniroute --tail 20 +``` + +It should display: `[DB] SQLite database ready` and `listening on port 20128`. + +--- + +## 3. Configure nginx (Reverse Proxy) + +### 3.1 Generate SSL certificate (Cloudflare Origin) + +In the Cloudflare dashboard: + +1. Go to **SSL/TLS โ†’ Origin Server** +2. Click **Create Certificate** +3. Keep the defaults (15 years, \*.yourdomain.com) +4. Copy the **Origin Certificate** and the **Private Key** + +```bash +mkdir -p /etc/nginx/ssl + +# Paste the certificate +nano /etc/nginx/ssl/origin.crt + +# Paste the private key +nano /etc/nginx/ssl/origin.key + +chmod 600 /etc/nginx/ssl/origin.key +``` + +### 3.2 Nginx Configuration + +```bash +cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ +# Default server โ€” blocks direct access via 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.yourdomain.com; # Change to your domain + + 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.yourdomain.com; + return 301 https://$server_name$request_uri; +} +NGINX +``` + +### 3.3 Enable and Test + +```bash +# Remove default configuration +rm -f /etc/nginx/sites-enabled/default + +# Enable OmniRoute +ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute + +# Test and reload +nginx -t && systemctl reload nginx +``` + +--- + +## 4. Configure Cloudflare DNS + +### 4.1 Add DNS record + +In the Cloudflare dashboard โ†’ DNS: + +| Type | Name | Content | Proxy | +| ---- | ------ | ---------------------- | ---------- | +| A | `llms` | `203.0.113.10` (VM IP) | โœ… Proxied | + +### 4.2 Configure SSL + +Under **SSL/TLS โ†’ Overview**: + +- Mode: **Full (Strict)** + +Under **SSL/TLS โ†’ Edge Certificates**: + +- Always Use HTTPS: โœ… On +- Minimum TLS Version: TLS 1.2 +- Automatic HTTPS Rewrites: โœ… On + +### 4.3 Testing + +```bash +curl -sI https://llms.seudominio.com/health +# Should return HTTP/2 200 +``` + +--- + +## 5. Operations and Maintenance + +### Upgrade to a new version + +```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 +``` + +### View logs + +```bash +docker logs -f omniroute # Real-time stream +docker logs omniroute --tail 50 # Last 50 lines +``` + +### Manual database backup + +```bash +# Copy data from the volume to the host +docker cp omniroute:/app/data ./backup-$(date +%F) + +# Or compress the entire volume +docker run --rm -v omniroute-data:/data -v $(pwd):/backup \ + alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data +``` + +### Restore from 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. Advanced Security + +### Restrict nginx to Cloudflare IPs + +```bash +cat > /etc/nginx/cloudflare-ips.conf << โ€˜CFโ€™ +# Cloudflare IPv4 ranges โ€” update periodically +# 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 +``` + +Add the following to `nginx.conf` inside the `http {}` block: + +```nginx +include /etc/nginx/cloudflare-ips.conf; +``` + +### Install fail2ban + +```bash +apt install -y fail2ban +systemctl enable fail2ban +systemctl start fail2ban + +# Check status +fail2ban-client status sshd +``` + +### Block direct access to the Docker port + +```bash +# Prevent direct external access to port 20128 +iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP +iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT + +# Persist the rules +apt install -y iptables-persistent +netfilter-persistent save +``` + +--- + +## 7. Deploy to Cloudflare Workers (Optional) + +For remote access via Cloudflare Workers (without exposing the VM directly): + +```bash +# In the local repository +cd omnirouteCloud +npm install +npx wrangler login +npx wrangler deploy +``` + +See the full documentation at [omnirouteCloud/README.md](../omnirouteCloud/README.md). + +--- + +## Port Summary + +| Port | Service | Access | +| ----- | ----------- | -------------------------- | +| 22 | SSH | Public (with fail2ban) | +| 80 | nginx HTTP | Redirect โ†’ HTTPS | +| 443 | nginx HTTPS | Via Cloudflare Proxy | +| 20128 | OmniRoute | Localhost only (via nginx) | diff --git a/docs/i18n/ja/src/lib/a2a/README.md b/docs/i18n/ja/src/lib/a2a/README.md new file mode 100644 index 0000000000..dcd77dc73b --- /dev/null +++ b/docs/i18n/ja/src/lib/a2a/README.md @@ -0,0 +1,752 @@ +# OmniRoute A2A Server (ๆ—ฅๆœฌ่ชž) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../../../src/lib/a2a/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../../../es/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../../../fr/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../../../de/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../../../it/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../../../ru/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../../../zh-CN/src/lib/a2a/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../../../ja/src/lib/a2a/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../../../ko/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../../../ar/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../../../in/src/lib/a2a/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../../../th/src/lib/a2a/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../../../vi/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../../../id/src/lib/a2a/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../../../ms/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../../../nl/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../../../pl/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../../../sv/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../../../no/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../../../da/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../../../fi/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../../../pt/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../../../ro/src/lib/a2a/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../../../hu/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../../../bg/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../../../sk/src/lib/a2a/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../../../uk-UA/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../../../he/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../../../phi/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../../../pt-BR/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../../../cs/src/lib/a2a/README.md) + +--- + +> **Agent-to-Agent Protocol v0.3** โ€” Enables any AI agent to use OmniRoute as an intelligent routing agent via JSON-RPC 2.0. + +The A2A Server exposes OmniRoute as a **first-class agent** that other agents can discover, delegate tasks to, and collaborate with using the [A2A Protocol](https://google.github.io/A2A/). + +--- + +## ใ‚ขใƒผใ‚ญใƒ†ใ‚ฏใƒใƒฃ + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Orchestrator Agent โ”‚ +โ”‚ (LangChain, CrewAI, AutoGen, Custom Agent) โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ 1. GET /.well-known/agent.json (discover) + โ”‚ 2. POST /a2a (JSON-RPC 2.0) + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ OmniRoute A2A Server โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Task Manager โ”‚ โ”‚ Skill Engine โ”‚ โ”‚ SSE Streaming โ”‚ โ”‚ +โ”‚ โ”‚ (lifecycle) โ”‚โ”€โ”€โ”‚ (registry) โ”‚โ”€โ”€โ”‚ (real-time) โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ +โ”‚ Skills: โ”‚ โ”‚ +โ”‚ โ”œโ”€ smart-routing โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ””โ”€ quota-management โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ Routing Decision Logger โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ OmniRoute Gateway (internal) + /v1/chat/completions, /api/combos, /api/usage/quota +``` + +--- + +## ใ‚ฏใ‚คใƒƒใ‚ฏใ‚นใ‚ฟใƒผใƒˆ + +### Agent Discovery + +Every A2A-compatible agent exposes an **Agent Card** at `/.well-known/agent.json`: + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +**Response:** + +```json +{ + "name": "OmniRoute", + "description": "Intelligent AI gateway with auto-routing across 50+ providers", + "url": "http://localhost:20128/a2a", + "version": "1.8.1", + "capabilities": { + "streaming": true, + "pushNotifications": false + }, + "skills": [ + { + "id": "smart-routing", + "name": "Smart Routing", + "description": "Routes prompts through OmniRoute intelligent pipeline", + "tags": ["routing", "llm", "multi-provider", "cost-optimization"], + "examples": [ + "Write a hello world in Python", + "Explain quantum computing using the cheapest provider" + ] + }, + { + "id": "quota-management", + "name": "Quota Management", + "description": "Natural-language queries about provider quotas", + "tags": ["quota", "analytics", "cost"], + "examples": [ + "Which provider has the most quota remaining?", + "Suggest a free combo for coding" + ] + } + ], + "authentication": { + "schemes": ["bearer"], + "apiKeyHeader": "Authorization" + } +} +``` + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Send a message to a skill and receive the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python hello world"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "a1b2c3d4-...", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "print('Hello, World!')" }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.0030)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "2026-03-04T..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"Quantum computing..."}}} + +: heartbeat 2026-03-04T21:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Running Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Skills Reference + +### `smart-routing` + +Routes prompts through OmniRoute's intelligent pipeline with full observability. + +**Parameters (in `metadata`):** + +| Parameter | Type | Default | Description | +| --------- | -------- | ------------ | ---------------------------------------------------------------------------------------- | +| `model` | `string` | `"auto"` | Target model (e.g., `claude-sonnet-4`, `gpt-4o`, `auto`) | +| `combo` | `string` | active combo | Specific combo to route through | +| `budget` | `number` | none | Maximum cost in USD for this request | +| `role` | `string` | none | Task role hint: `coding`, `review`, `planning`, `analysis`, `debugging`, `documentation` | + +**Returns:** + +| Field | Description | +| ------------------------------ | --------------------------------------------------------- | +| `artifacts[].content` | The LLM response text | +| `metadata.routing_explanation` | Human-readable explanation of routing decision | +| `metadata.cost_envelope` | Estimated vs actual cost with currency | +| `metadata.resilience_trace` | Array of events (primary_selected, fallback_needed, etc.) | +| `metadata.policy_verdict` | Whether the request was allowed and why | + +### `quota-management` + +Answers natural-language queries about provider quotas. + +**Query types (inferred from message content):** + +| Query Pattern | Response Type | +| ---------------------------------------------- | -------------------------------------------------------- | +| Contains `"ranking"`, `"most quota"`, `"best"` | Providers ranked by remaining quota | +| Contains `"free"`, `"suggest"` | Lists free combos or suggests free-tier providers | +| Default | Full quota summary with warnings for low-quota providers | + +--- + +## Task Lifecycle + +``` +submitted โ”€โ”€โ†’ working โ”€โ”€โ†’ completed + โ”€โ”€โ†’ failed + โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ†’ cancelled +``` + +| State | Description | +| ----------- | ----------------------------------------------------- | +| `submitted` | Task created, queued for execution | +| `working` | Skill handler is executing | +| `completed` | Execution succeeded, artifacts available | +| `failed` | Execution failed or task expired (TTL: 5 min default) | +| `cancelled` | Cancelled by client via `tasks/cancel` | + +- Terminal states: `completed`, `failed`, `cancelled` (no further transitions) +- Expired tasks in `submitted` or `working` are auto-marked as `failed` +- Tasks are garbage-collected after 2ร— TTL + +--- + +## Client Examples + +### Python โ€” Orchestrator Agent + +```python +""" +A2A Client โ€” Python example. +Discovers OmniRoute agent, sends a task, and processes the result. +""" +import requests +import json + +BASE_URL = "http://localhost:20128" +API_KEY = "your-api-key" +HEADERS = { + "Content-Type": "application/json", + "Authorization": f"Bearer {API_KEY}", +} + +# 1. Discover agent capabilities +agent_card = requests.get(f"{BASE_URL}/.well-known/agent.json").json() +print(f"Agent: {agent_card['name']} v{agent_card['version']}") +print(f"Skills: {[s['id'] for s in agent_card['skills']]}") + +# 2. Send a smart-routing task +response = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python quicksort implementation"}], + "metadata": { + "model": "auto", + "combo": "fast-coding", + "budget": 0.10, + } + } +}) +result = response.json()["result"] +print(f"\n๐Ÿ“ Response: {result['artifacts'][0]['content'][:200]}...") +print(f"๐Ÿ”€ Routing: {result['metadata']['routing_explanation']}") +print(f"๐Ÿ’ฐ Cost: ${result['metadata']['cost_envelope']['actual']}") +print(f"๐Ÿ›ก๏ธ Policy: {result['metadata']['policy_verdict']['reason']}") + +# 3. Query quota status +quota_resp = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-2", + "method": "message/send", + "params": { + "skill": "quota-management", + "messages": [{"role": "user", "content": "Which provider has the most quota remaining?"}], + } +}) +quota_result = quota_resp.json()["result"] +print(f"\n๐Ÿ“Š Quota: {quota_result['artifacts'][0]['content']}") +``` + +### TypeScript โ€” Multi-Agent Orchestrator + +```typescript +/** + * A2A Client โ€” TypeScript example. + * Shows agent discovery, task delegation, and streaming. + */ + +const BASE_URL = "http://localhost:20128"; +const API_KEY = "your-api-key"; + +interface JsonRpcResponse { + jsonrpc: "2.0"; + id: string | number; + result?: T; + error?: { code: number; message: string }; +} + +async function a2aCall(method: string, params: Record): Promise { + const resp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: `${method}-${Date.now()}`, + method, + params, + }), + }); + const json: JsonRpcResponse = await resp.json(); + if (json.error) throw new Error(`[${json.error.code}] ${json.error.message}`); + return json.result!; +} + +// โ”€โ”€ Agent Discovery โ”€โ”€ +const agentCard = await fetch(`${BASE_URL}/.well-known/agent.json`).then((r) => r.json()); +console.log(`Connected to: ${agentCard.name} (${agentCard.skills.length} skills)`); + +// โ”€โ”€ Smart Routing: Send a coding task โ”€โ”€ +const routingResult = await a2aCall("message/send", { + skill: "smart-routing", + messages: [{ role: "user", content: "Implement a Redis cache wrapper in TypeScript" }], + metadata: { model: "claude-sonnet-4", role: "coding" }, +}); +console.log("Response:", routingResult.artifacts[0].content); +console.log("Provider:", routingResult.metadata.routing_explanation); + +// โ”€โ”€ Quota Management: Find free alternatives โ”€โ”€ +const quotaResult = await a2aCall("message/send", { + skill: "quota-management", + messages: [{ role: "user", content: "Suggest free combos for documentation" }], +}); +console.log("Free combos:", quotaResult.artifacts[0].content); + +// โ”€โ”€ Streaming: Real-time response โ”€โ”€ +const streamResp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "stream-1", + method: "message/stream", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Explain microservices architecture" }], + }, + }), +}); + +const reader = streamResp.body!.getReader(); +const decoder = new TextDecoder(); +while (true) { + const { done, value } = await reader.read(); + if (done) break; + const chunk = decoder.decode(value); + for (const line of chunk.split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + if (event.params.chunk) { + process.stdout.write(event.params.chunk.content); + } + if (event.params.task.state === "completed") { + console.log("\nโœ… Stream completed"); + } + } + } +} +``` + +### Python โ€” LangChain A2A Integration + +```python +""" +LangChain integration โ€” Use OmniRoute A2A as a custom LLM. +""" +from langchain.llms.base import BaseLLM +from langchain.schema import LLMResult, Generation +import requests +from typing import List, Optional + +class OmniRouteA2A(BaseLLM): + base_url: str = "http://localhost:20128" + api_key: str = "" + model: str = "auto" + combo: Optional[str] = None + + @property + def _llm_type(self) -> str: + return "omniroute-a2a" + + def _call(self, prompt: str, stop: Optional[List[str]] = None, **kwargs) -> str: + response = requests.post( + f"{self.base_url}/a2a", + headers={ + "Content-Type": "application/json", + "Authorization": f"Bearer {self.api_key}", + }, + json={ + "jsonrpc": "2.0", + "id": "langchain-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": prompt}], + "metadata": { + "model": self.model, + **({"combo": self.combo} if self.combo else {}), + }, + }, + }, + ) + result = response.json()["result"] + return result["artifacts"][0]["content"] + + def _generate(self, prompts: List[str], stop=None, **kwargs) -> LLMResult: + return LLMResult( + generations=[[Generation(text=self._call(p, stop))] for p in prompts] + ) + +# Usage +llm = OmniRouteA2A( + base_url="http://localhost:20128", + api_key="your-key", + model="auto", + combo="fast-coding", +) +result = llm("Write a Python function to merge two sorted lists") +print(result) +``` + +### Go โ€” A2A Client + +```go +package main + +import ( + "bytes" + "encoding/json" + "fmt" + "io" + "net/http" +) + +const baseURL = "http://localhost:20128" +const apiKey = "your-api-key" + +type JsonRpcRequest struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Method string `json:"method"` + Params interface{} `json:"params"` +} + +type JsonRpcResponse struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Result interface{} `json:"result"` + Error *struct { + Code int `json:"code"` + Message string `json:"message"` + } `json:"error"` +} + +func a2aCall(method string, params interface{}) (*JsonRpcResponse, error) { + body, _ := json.Marshal(JsonRpcRequest{ + Jsonrpc: "2.0", + ID: "go-1", + Method: method, + Params: params, + }) + + req, _ := http.NewRequest("POST", baseURL+"/a2a", bytes.NewReader(body)) + req.Header.Set("Content-Type", "application/json") + req.Header.Set("Authorization", "Bearer "+apiKey) + + resp, err := http.DefaultClient.Do(req) + if err != nil { + return nil, err + } + defer resp.Body.Close() + data, _ := io.ReadAll(resp.Body) + + var result JsonRpcResponse + json.Unmarshal(data, &result) + return &result, nil +} + +func main() { + // Discover agent + resp, _ := http.Get(baseURL + "/.well-known/agent.json") + defer resp.Body.Close() + body, _ := io.ReadAll(resp.Body) + fmt.Println("Agent Card:", string(body)) + + // Send smart-routing task + result, _ := a2aCall("message/send", map[string]interface{}{ + "skill": "smart-routing", + "messages": []map[string]string{{"role": "user", "content": "Hello from Go!"}}, + "metadata": map[string]interface{}{"model": "auto"}, + }) + out, _ := json.MarshalIndent(result.Result, "", " ") + fmt.Println("Result:", string(out)) +} +``` + +--- + +## Use Cases + +### ๐Ÿค– Use Case 1: Multi-Agent Coding Pipeline + +An orchestrator agent delegates code generation to OmniRoute, then passes the output to a review agent. + +```python +def coding_pipeline(task: str): + # Step 1: Generate code via OmniRoute A2A + code_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Write production-quality code: {task}"} + ], metadata={"model": "auto", "role": "coding"}) + code = code_result["artifacts"][0]["content"] + + # Step 2: Review the code via OmniRoute A2A (different model) + review_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Review this code for bugs and improvements:\n\n{code}"} + ], metadata={"model": "auto", "role": "review"}) + review = review_result["artifacts"][0]["content"] + + # Step 3: Check costs + print(f"Code cost: ${code_result['metadata']['cost_envelope']['actual']}") + print(f"Review cost: ${review_result['metadata']['cost_envelope']['actual']}") + + return {"code": code, "review": review} +``` + +### ๐Ÿ’ก Use Case 2: Quota-Aware Agent Swarm + +Multiple agents share quota through OmniRoute, using the quota skill to coordinate. + +```python +async def quota_aware_agent(agent_name: str, task: str): + # Check quota before starting + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Which provider has the most quota remaining?"} + ]) + print(f"[{agent_name}] {quota['artifacts'][0]['content']}") + + # Send request with budget constraint + result = a2a_send("smart-routing", [ + {"role": "user", "content": task} + ], metadata={"budget": 0.05}) + + policy = result["metadata"]["policy_verdict"] + if not policy["allowed"]: + print(f"[{agent_name}] โš ๏ธ Budget exceeded: {policy['reason']}") + # Fall back to free combo + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Suggest free combos"} + ]) + print(f"[{agent_name}] Free alternatives: {quota['artifacts'][0]['content']}") + + return result +``` + +### ๐Ÿ“Š Use Case 3: Real-Time Streaming Dashboard + +A monitoring agent streams responses and displays progress in real-time. + +```typescript +async function streamingDashboard(prompt: string) { + const response = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { "Content-Type": "application/json", Authorization: `Bearer ${API_KEY}` }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "dash-1", + method: "message/stream", + params: { skill: "smart-routing", messages: [{ role: "user", content: prompt }] }, + }), + }); + + let totalChunks = 0; + const reader = response.body!.getReader(); + const decoder = new TextDecoder(); + + while (true) { + const { done, value } = await reader.read(); + if (done) break; + + for (const line of decoder.decode(value).split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + const state = event.params.task.state; + + if (state === "working" && event.params.chunk) { + totalChunks++; + process.stdout.write( + `\r[Chunk ${totalChunks}] ${event.params.chunk.content.slice(0, 50)}...` + ); + } + if (state === "completed") { + const meta = event.params.metadata; + console.log( + `\nโœ… Done | Cost: $${meta?.cost_envelope?.actual || 0} | Route: ${meta?.routing_explanation || "N/A"}` + ); + } + if (state === "failed") { + console.error(`\nโŒ Failed: ${event.params.metadata?.error}`); + } + } + } + } +} +``` + +### ๐Ÿ” Use Case 4: Task Polling Pattern + +For long-running tasks, poll the task status instead of waiting synchronously. + +```python +import time + +def poll_task(task_id: str, timeout: int = 60): + """Poll task status until completion or timeout.""" + start = time.time() + while time.time() - start < timeout: + result = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "poll-1", + "method": "tasks/get", + "params": {"taskId": task_id}, + }).json() + + task = result["result"]["task"] + state = task["state"] + print(f" Task {task_id[:8]}... state={state}") + + if state in ("completed", "failed", "cancelled"): + return task + time.sleep(2) + + # Timeout โ€” cancel the task + requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "cancel-1", + "method": "tasks/cancel", + "params": {"taskId": task_id}, + }) + raise TimeoutError(f"Task {task_id} timed out after {timeout}s") +``` + +--- + +## Error Codes + +| Code | Constant | Meaning | +| ------ | ------------------------ | ---------------------------------------- | +| -32700 | โ€” | Parse error (invalid JSON) | +| -32600 | `INVALID_REQUEST` | Invalid JSON-RPC request or unauthorized | +| -32601 | `METHOD_NOT_FOUND` | Unknown method or skill | +| -32602 | `INVALID_PARAMS` | Missing or invalid parameters | +| -32603 | `INTERNAL_ERROR` | Skill execution failed | +| -32001 | `TASK_NOT_FOUND` | Task ID not found | +| -32002 | `TASK_ALREADY_COMPLETED` | Cannot modify a completed task | +| -32003 | `UNAUTHORIZED` | Invalid or missing API key | +| -32004 | `BUDGET_EXCEEDED` | Request exceeds configured budget | +| -32005 | `PROVIDER_UNAVAILABLE` | No available providers | + +--- + +## Authentication + +All `/a2a` requests require a Bearer token via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server (`OMNIROUTE_API_KEY` is empty), authentication is bypassed. + +--- + +## File Structure + +``` +src/lib/a2a/ +โ”œโ”€โ”€ taskManager.ts # Task lifecycle (create/update/cancel/list), TTL, cleanup +โ”œโ”€โ”€ taskExecution.ts # Generic task executor with state management +โ”œโ”€โ”€ streaming.ts # SSE stream formatting, heartbeat, chunk/completion events +โ”œโ”€โ”€ routingLogger.ts # Routing decision logger (stats, history, retention) +โ””โ”€โ”€ skills/ + โ”œโ”€โ”€ smartRouting.ts # Smart routing skill (routes via /v1/chat/completions) + โ””โ”€โ”€ quotaManagement.ts # Quota management skill (natural-language quota queries) + +src/app/a2a/ +โ””โ”€โ”€ route.ts # Next.js API route handler (JSON-RPC 2.0 dispatch) + +open-sse/mcp-server/ +โ””โ”€โ”€ schemas/a2a.ts # Zod schemas (AgentCard, Task, JSON-RPC, SSE events) +``` + +--- + +## Comparison: MCP vs A2A + +| Feature | MCP Server | A2A Server | +| ----------------- | ---------------------------- | ------------------------------------------------- | +| **Protocol** | Model Context Protocol | Agent-to-Agent Protocol v0.3 | +| **Transport** | stdio / HTTP | HTTP (JSON-RPC 2.0) | +| **Discovery** | Tool listing via MCP | `/.well-known/agent.json` | +| **Granularity** | 16 individual tools | 2 high-level skills | +| **Best for** | IDE agents (Cursor, VS Code) | Multi-agent systems (LangChain, CrewAI) | +| **Streaming** | Not supported | SSE via `message/stream` | +| **Task tracking** | No | Full lifecycle (submitted โ†’ completed) | +| **Observability** | Audit log per tool call | Cost envelope + resilience trace + policy verdict | + +--- + +## ใƒฉใ‚คใ‚ปใƒณใ‚น + +Part of [OmniRoute](https://github.com/diegosouzapw/OmniRoute) โ€” MIT License. diff --git a/docs/i18n/ko/A2A-SERVER.md b/docs/i18n/ko/A2A-SERVER.md deleted file mode 100644 index 01531ff482..0000000000 --- a/docs/i18n/ko/A2A-SERVER.md +++ /dev/null @@ -1,200 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/A2A-SERVER.md) - ---- - -# OmniRoute A2A Server Documentation - -> Agent-to-Agent Protocol v0.3 โ€” OmniRoute as an intelligent routing agent - -## Agent Discovery - -```bash -curl http://localhost:20128/.well-known/agent.json -``` - -Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements. - ---- - -## Authentication - -All `/a2a` requests require an API key via the `Authorization` header: - -``` -Authorization: Bearer YOUR_OMNIROUTE_API_KEY -``` - -If no API key is configured on the server, authentication is bypassed. - ---- - -## JSON-RPC 2.0 Methods - -### `message/send` โ€” Synchronous Execution - -Sends a message to a skill and waits for the complete response. - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{ - "jsonrpc": "2.0", - "id": "1", - "method": "message/send", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Write a hello world in Python"}], - "metadata": {"model": "auto", "combo": "fast-coding"} - } - }' -``` - -**Response:** - -```json -{ - "jsonrpc": "2.0", - "id": "1", - "result": { - "task": { "id": "uuid", "state": "completed" }, - "artifacts": [{ "type": "text", "content": "..." }], - "metadata": { - "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)", - "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, - "resilience_trace": [ - { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." } - ], - "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } - } - } -} -``` - -### `message/stream` โ€” SSE Streaming - -Same as `message/send` but returns Server-Sent Events for real-time streaming. - -```bash -curl -N -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{ - "jsonrpc": "2.0", - "id": "1", - "method": "message/stream", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Explain quantum computing"}] - } - }' -``` - -**SSE Events:** - -``` -data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}} - -: heartbeat 2026-03-03T17:00:00Z - -data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} -``` - -### `tasks/get` โ€” Query Task Status - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' -``` - -### `tasks/cancel` โ€” Cancel a Task - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' -``` - ---- - -## Available Skills - -| Skill | Description | -| :----------------- | :------------------------------------------------------------------------------------------------------------------------------ | -| `smart-routing` | Routes prompts through OmniRoute's intelligent pipeline. Returns response with routing explanation, cost, and resilience trace. | -| `quota-management` | Answers natural-language queries about provider quotas, suggests free combos, and provides quota rankings. | - ---- - -## Task Lifecycle - -``` -submitted โ†’ working โ†’ completed - โ†’ failed - โ†’ cancelled -``` - -- Tasks expire after 5 minutes (configurable) -- Terminal states: `completed`, `failed`, `cancelled` -- Event log tracks every state transition - ---- - -## Error Codes - -| Code | Meaning | -| :----- | :----------------------------- | -| -32700 | Parse error (invalid JSON) | -| -32600 | Invalid request / Unauthorized | -| -32601 | Method or skill not found | -| -32602 | Invalid params | -| -32603 | Internal error | - ---- - -## Integration Examples - -### Python (requests) - -```python -import requests - -resp = requests.post("http://localhost:20128/a2a", json={ - "jsonrpc": "2.0", "id": "1", - "method": "message/send", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Hello"}] - } -}, headers={"Authorization": "Bearer YOUR_KEY"}) - -result = resp.json()["result"] -print(result["artifacts"][0]["content"]) -print(result["metadata"]["routing_explanation"]) -``` - -### TypeScript (fetch) - -```typescript -const resp = await fetch("http://localhost:20128/a2a", { - method: "POST", - headers: { - "Content-Type": "application/json", - Authorization: "Bearer YOUR_KEY", - }, - body: JSON.stringify({ - jsonrpc: "2.0", - id: "1", - method: "message/send", - params: { - skill: "smart-routing", - messages: [{ role: "user", content: "Hello" }], - }, - }), -}); -const { result } = await resp.json(); -console.log(result.metadata.routing_explanation); -``` diff --git a/docs/i18n/ko/API_REFERENCE.md b/docs/i18n/ko/API_REFERENCE.md deleted file mode 100644 index b878605221..0000000000 --- a/docs/i18n/ko/API_REFERENCE.md +++ /dev/null @@ -1,455 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/API_REFERENCE.md) - ---- - -# API Reference - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/API_REFERENCE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/API_REFERENCE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/API_REFERENCE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/API_REFERENCE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/API_REFERENCE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/API_REFERENCE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/API_REFERENCE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/API_REFERENCE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/API_REFERENCE.md) - -Complete reference for all OmniRoute API endpoints. - ---- - -## Table of Contents - -- [Chat Completions](#chat-completions) -- [Embeddings](#embeddings) -- [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`. - -### ACP Agents - -| Endpoint | Method | Description | -| ----------------- | ------ | -------------------------------------------------------- | -| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | -| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | -| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | - -GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). - -### Resilience & Rate Limits - -| Endpoint | Method | Description | -| ----------------------- | ------- | ------------------------------- | -| `/api/resilience` | 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` diff --git a/docs/i18n/ko/ARCHITECTURE.md b/docs/i18n/ko/ARCHITECTURE.md deleted file mode 100644 index 4ea06a29f2..0000000000 --- a/docs/i18n/ko/ARCHITECTURE.md +++ /dev/null @@ -1,787 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/ARCHITECTURE.md) - ---- - -# OmniRoute Architecture - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/ARCHITECTURE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/ARCHITECTURE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/ARCHITECTURE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/ARCHITECTURE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/ARCHITECTURE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/ARCHITECTURE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/ARCHITECTURE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/ARCHITECTURE.md) - -_Last updated: 2026-03-04_ - -## 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 (`...`) for reasoning models -- Response sanitization for strict OpenAI SDK compatibility -- Role normalization (developerโ†’system, systemโ†’user) for cross-provider compatibility -- Structured output conversion (json_schema โ†’ Gemini responseSchema) -- Local persistence for providers, keys, aliases, combos, settings, pricing -- Usage/cost tracking and request logging -- Optional cloud sync for multi-device/state sync -- IP allowlist/blocklist for API access control -- Thinking budget management (passthrough/auto/custom/adaptive) -- Global system prompt injection -- Session tracking and fingerprinting -- Per-account enhanced rate limiting with provider-specific profiles -- Circuit breaker pattern for provider resilience -- Anti-thundering herd protection with mutex locking -- Signature-based request deduplication cache -- Domain layer: model availability, cost rules, fallback policy, lockout policy -- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) -- Policy engine for centralized request evaluation (lockout โ†’ budget โ†’ fallback) -- Request telemetry with p50/p95/p99 latency aggregation -- Correlation ID (X-Request-Id) for end-to-end tracing -- Compliance audit logging with opt-out per API key -- Eval framework for LLM quality assurance -- Resilience UI dashboard with real-time circuit breaker status -- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) - -Primary runtime model: - -- Next.js 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[(storage.sqlite)] - UDB[(usage tables + log artifacts)] - end - - subgraph Upstreams[Upstream Providers] - P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/Qoder/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/route.ts` (GET) -- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) -- OAuth: `src/app/api/oauth/*` -- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` -- Usage: `src/app/api/usage/*` -- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` -- CLI tooling helpers: `src/app/api/cli-tools/*` -- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) -- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) -- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) -- Sessions: `src/app/api/sessions` (GET) -- Rate limits: `src/app/api/rate-limits` (GET) -- Resilience: `src/app/api/resilience` (GET/PATCH) โ€” provider profiles, circuit breaker, rate limit state -- Resilience reset: `src/app/api/resilience/reset` (POST) โ€” reset breakers + cooldowns -- Cache stats: `src/app/api/cache/stats` (GET/DELETE) -- Model availability: `src/app/api/models/availability` (GET/POST) -- Telemetry: `src/app/api/telemetry/summary` (GET) -- Budget: `src/app/api/usage/budget` (GET/POST) -- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) -- Compliance audit: `src/app/api/compliance/audit-log` (GET) -- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) -- Policies: `src/app/api/policies` (GET/POST) - -## 2) SSE + 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` -- Response sanitization: `open-sse/handlers/responseSanitizer.ts` -- Role normalization: `open-sse/services/roleNormalizer.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`, `qoder.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 (SQLite): - -- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) -- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) -- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) -- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** - -Usage persistence: - -- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) -- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` -- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) -- legacy JSON files are migrated to SQLite by startup migrations when present - -Domain State DB (SQLite): - -- `src/lib/db/domainState.ts` โ€” CRUD operations 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: - -- primary runtime DB: `${DATA_DIR}/storage.sqlite` -- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) -- structured call payload archives: `${DATA_DIR}/call_logs/` -- optional translator/request debug sessions: `/logs/...` - -## Deployment Topology - -```mermaid -flowchart LR - 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[(storage.sqlite)] - UsageDB[(usage tables + log artifacts)] - end - - subgraph External[External Services] - Providers[AI Providers] - SyncCloud[Cloud Sync Service] - end - - CLI --> Next - Browser --> Next - Next --> Core - Next --> MainDB - Core --> MainDB - Core --> UsageDB - Core --> Providers - Next --> SyncCloud -``` - -## Module Mapping (Decision-Critical) - -### Route and API Modules - -- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs -- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) -- `src/app/api/providers*`: provider CRUD, validation, testing -- `src/app/api/provider-nodes*`: custom compatible node management -- `src/app/api/provider-models`: custom model management (CRUD) -- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) -- `src/app/api/oauth/*`: OAuth/device-code flows -- `src/app/api/keys*`: local API key lifecycle -- `src/app/api/models/alias`: alias management -- `src/app/api/combos*`: fallback combo management -- `src/app/api/pricing`: pricing overrides for cost calculation -- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) -- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) -- `src/app/api/usage/*`: usage and logs APIs -- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers -- `src/app/api/cli-tools/*`: local CLI config writers/checkers -- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) -- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) -- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) -- `src/app/api/sessions`: active session listing (GET) -- `src/app/api/rate-limits`: per-account rate limit status (GET) - -### Routing and Execution Core - -- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop -- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup -- `open-sse/executors/*`: provider-specific network and format behavior - -### Translation Registry and Format Converters - -- `open-sse/translator/index.ts`: translator registry and orchestration -- Request translators: `open-sse/translator/request/*` -- Response translators: `open-sse/translator/response/*` -- Format constants: `open-sse/translator/formats.ts` - -### Persistence - -- `src/lib/db/*`: persistent config/state and domain persistence on SQLite -- `src/lib/localDb.ts`: compatibility re-export for DB modules -- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables - -## Provider Executor Coverage (Strategy Pattern) - -Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. - -| Executor | Provider(s) | Special Handling | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | -| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, Qoder, 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 | -| Qoder | openai | OAuth (Basic) | โœ… | โœ… | โœ… | โš ๏ธ Per request | -| OpenRouter | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| GLM/Kimi/MiniMax | claude | API Key | โœ… | โœ… | โŒ | โŒ | -| DeepSeek | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Groq | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| xAI (Grok) | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Mistral | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Perplexity | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Together AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Fireworks AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Cerebras | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Cohere | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| NVIDIA NIM | openai | API Key | โœ… | โœ… | โŒ | โŒ | - -## Format Translation Coverage - -Detected source formats include: - -- `openai` -- `openai-responses` -- `claude` -- `gemini` - -Target formats include: - -- OpenAI chat/Responses -- Claude -- Gemini/Gemini-CLI/Antigravity envelope -- Kiro -- Cursor - -Translations use **OpenAI as the hub format** โ€” all conversions go through OpenAI as intermediate: - -``` -Source Format โ†’ OpenAI (hub) โ†’ Target Format -``` - -Translations are selected dynamically based on source payload shape and provider target format. - -Additional processing layers in the translation pipeline: - -- **Response sanitization** โ€” Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance -- **Role normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI targets; merges `system` โ†’ `user` for models that reject the system role (GLM, ERNIE) -- **Think tag extraction** โ€” Parses `...` blocks from content into `reasoning_content` field -- **Structured output** โ€” Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` - -## Supported API Endpoints - -| 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 `/logs//` 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 - -- SQLite schema migrations and auto-upgrade hooks at startup -- legacy JSON โ†’ SQLite migration compatibility path - -## Observability and Operational Signals - -Runtime visibility sources: - -- console logs from `src/sse/utils/logger.ts` -- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) -- textual request status log in `log.txt` (optional/compat) -- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` -- dashboard usage endpoints (`/api/usage/*`) for UI consumption - -## Security-Sensitive Boundaries - -- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing -- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning -- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format -- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level -- Cloud sync endpoints rely on API key auth + machine id semantics - -## Environment and Runtime Matrix - -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` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. -2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. -3. Request logger writes full headers/body when enabled; treat log directory as sensitive. -4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. -5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. -6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). -7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). -8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). - -## Operational Verification Checklist - -- Build from source: `npm run build` -- Build Docker image: `docker build -t omniroute .` -- Start service and verify: -- `GET /api/settings` -- `GET /api/v1/models` -- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/ko/AUTO-COMBO.md b/docs/i18n/ko/AUTO-COMBO.md deleted file mode 100644 index 2166e41dff..0000000000 --- a/docs/i18n/ko/AUTO-COMBO.md +++ /dev/null @@ -1,67 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/AUTO-COMBO.md) - ---- - -# OmniRoute Auto-Combo Engine - -> Self-managing model chains with adaptive scoring - -## How It Works - -The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**: - -| Factor | Weight | Description | -| :--------- | :----- | :---------------------------------------------- | -| Quota | 0.20 | Remaining capacity [0..1] | -| Health | 0.25 | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 | -| CostInv | 0.20 | Inverse cost (cheaper = higher score) | -| LatencyInv | 0.15 | Inverse p95 latency (faster = higher) | -| TaskFit | 0.10 | Model ร— task type fitness score | -| Stability | 0.10 | Low variance in latency/errors | - -## Mode Packs - -| Pack | Focus | Key Weight | -| :---------------------- | :----------- | :--------------- | -| ๐Ÿš€ **Ship Fast** | Speed | latencyInv: 0.35 | -| ๐Ÿ’ฐ **Cost Saver** | Economy | costInv: 0.40 | -| ๐ŸŽฏ **Quality First** | Best model | taskFit: 0.40 | -| ๐Ÿ“ก **Offline Friendly** | Availability | quota: 0.40 | - -## Self-Healing - -- **Temporary exclusion**: Score < 0.2 โ†’ excluded for 5 min (progressive backoff, max 30 min) -- **Circuit breaker awareness**: OPEN โ†’ auto-excluded; HALF_OPEN โ†’ probe requests -- **Incident mode**: >50% OPEN โ†’ disable exploration, maximize stability -- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout - -## Bandit Exploration - -5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode. - -## API - -```bash -# Create auto-combo -curl -X POST http://localhost:20128/api/combos/auto \ - -H "Content-Type: application/json" \ - -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}' - -# List auto-combos -curl http://localhost:20128/api/combos/auto -``` - -## Task Fitness - -30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` โ†’ high coding score). - -## Files - -| File | Purpose | -| :------------------------------------------- | :------------------------------------ | -| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization | -| `open-sse/services/autoCombo/taskFitness.ts` | Model ร— task fitness lookup | -| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap | -| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode | -| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles | -| `src/app/api/combos/auto/route.ts` | REST API | diff --git a/docs/i18n/ko/CHANGELOG.md b/docs/i18n/ko/CHANGELOG.md index 71c7fdf95b..62f02e3605 100644 --- a/docs/i18n/ko/CHANGELOG.md +++ b/docs/i18n/ko/CHANGELOG.md @@ -1,12 +1,92 @@ # Changelog (ํ•œ๊ตญ์–ด) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CHANGELOG.md) --- - ## [Unreleased] +### ๐Ÿ› ๏ธ Maintenance + +- **AGENTS.md rewrite:** Condensed from 297โ†’153 lines. Added build/lint/test commands (including single-test execution), code style guidelines (Prettier, TypeScript, ESLint, naming, imports, error handling, security), and trimmed verbose architecture tables for AI agent consumption. + +## [3.4.2] - 2026-04-01 + +### ๐Ÿ› Bug Fixes + +- **CI Stabilization:** Fixed failing analytics/settings Playwright selectors and request assertions so GitHub Actions E2E runs pass reliably across localized UIs and switch-based controls. +- **Deterministic Tests:** Removed date-sensitive quota fixtures from Copilot usage tests and aligned idempotency/model catalog tests with the merged runtime behavior. +- **MCP Type Hardening:** Removed zero-budget explicit `any` regressions from the MCP server tool registration path, restoring the `check:any-budget:t11` workflow gate. + +### ๐Ÿ› ๏ธ Maintenance + +- **Release Branch Integration:** Consolidated the active feature branches into `release/v3.4.2` on top of current `main` and validated the branch with lint, unit, coverage, build, and CI-mode E2E runs. + +## [3.4.1] - 2026-03-31 + +> [!WARNING] +> **BREAKING CHANGE: request logging, retention, and logging environment variables have been redesigned.** +> On the first startup after upgrading, OmniRoute archives legacy request logs from `DATA_DIR/logs/`, legacy `DATA_DIR/call_logs/`, and `DATA_DIR/log.txt` into `DATA_DIR/log_archives/*.zip`, then removes the deprecated layout and switches to the new unified artifact format under `DATA_DIR/call_logs/`. + +### โœจ New Features + +- **.ENV Migration Utility:** Included `scripts/migrate-env.mjs` to seamlessly migrate ` Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` - ---- - -## Step 2 โ€” Install CLI Tools - -All npm-based tools require Node.js 18+: - -```bash -# Claude Code (Anthropic) -npm install -g @anthropic-ai/claude-code - -# OpenAI Codex -npm install -g @openai/codex - -# Gemini CLI (Google) -npm install -g @google/gemini-cli - -# OpenCode -npm install -g opencode-ai - -# Cline -npm install -g cline - -# KiloCode -npm install -g kilecode - -# Kiro CLI (Amazon โ€” requires curl + unzip) -apt-get install -y unzip # on Debian/Ubuntu -curl -fsSL https://cli.kiro.dev/install | bash -export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc -``` - -**Verify:** - -```bash -claude --version # 2.x.x -codex --version # 0.x.x -gemini --version # 0.x.x -opencode --version # x.x.x -cline --version # 2.x.x -kilocode --version # x.x.x (or: kilo --version) -kiro-cli --version # 1.x.x -``` - ---- - -## Step 3 โ€” Set Global Environment Variables - -Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`: - -```bash -# OmniRoute Universal Endpoint -export OPENAI_BASE_URL="http://localhost:20128/v1" -export OPENAI_API_KEY="sk-your-omniroute-key" -export ANTHROPIC_BASE_URL="http://localhost:20128/v1" -export ANTHROPIC_API_KEY="sk-your-omniroute-key" -export GEMINI_BASE_URL="http://localhost:20128/v1" -export GEMINI_API_KEY="sk-your-omniroute-key" -``` - -> For a **remote server** replace `localhost:20128` with the server IP or domain, -> e.g. `http://192.168.0.15:20128`. - ---- - -## Step 4 โ€” Configure Each Tool - -### Claude Code - -```bash -# Via CLI: -claude config set --global api-base-url http://localhost:20128/v1 - -# Or create ~/.claude/settings.json: -mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF -{ - "apiBaseUrl": "http://localhost:20128/v1", - "apiKey": "sk-your-omniroute-key" -} -EOF -``` - -**Test:** `claude "say hello"` - ---- - -### OpenAI Codex - -```bash -mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF -model: auto -apiKey: sk-your-omniroute-key -apiBaseUrl: http://localhost:20128/v1 -EOF -``` - -**Test:** `codex "what is 2+2?"` - ---- - -### Gemini CLI - -```bash -mkdir -p ~/.gemini && cat > ~/.gemini/settings.json << EOF -{ - "apiKey": "sk-your-omniroute-key", - "baseUrl": "http://localhost:20128/v1" -} -EOF -``` - -**Test:** `gemini "hello"` - ---- - -### OpenCode - -```bash -mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF -[provider.openai] -base_url = "http://localhost:20128/v1" -api_key = "sk-your-omniroute-key" -EOF -``` - -**Test:** `opencode` - ---- - -### Cline (CLI or VS Code) - -**CLI mode:** - -```bash -mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF -{ - "apiProvider": "openai", - "openAiBaseUrl": "http://localhost:20128/v1", - "openAiApiKey": "sk-your-omniroute-key" -} -EOF -``` - -**VS Code mode:** -Cline extension settings โ†’ API Provider: `OpenAI Compatible` โ†’ Base URL: `http://localhost:20128/v1` - -Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ Cline โ†’ Apply Config**. - ---- - -### KiloCode (CLI or VS Code) - -**CLI mode:** - -```bash -kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key -``` - -**VS Code settings:** - -```json -{ - "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", - "kilo-code.apiKey": "sk-your-omniroute-key" -} -``` - -Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ KiloCode โ†’ Apply Config**. - ---- - -### Continue (VS Code Extension) - -Edit `~/.continue/config.yaml`: - -```yaml -models: - - name: OmniRoute - provider: openai - model: auto - apiBase: http://localhost:20128/v1 - apiKey: sk-your-omniroute-key - default: true -``` - -Restart VS Code after editing. - ---- - -### Kiro CLI (Amazon) - -```bash -# Login to your AWS/Kiro account: -kiro-cli login - -# The CLI uses its own auth โ€” OmniRoute is not needed as backend for Kiro CLI itself. -# Use kiro-cli alongside OmniRoute for other tools. -kiro-cli status -``` - ---- - -### Cursor (Desktop App) - -> **Note:** Cursor routes requests through its cloud. For OmniRoute integration, -> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL. - -Via GUI: **Settings โ†’ Models โ†’ OpenAI API Key** - -- Base URL: `https://your-domain.com/v1` -- API Key: your OmniRoute key - ---- - -## Dashboard Auto-Configuration - -The OmniRoute dashboard automates configuration for most tools: - -1. Go to `http://localhost:20128/dashboard/cli-tools` -2. Expand any tool card -3. Select your API key from the dropdown -4. Click **Apply Config** (if tool is detected as installed) -5. Or copy the generated config snippet manually - ---- - -## Built-in Agents: Droid & OpenClaw - -**Droid** and **OpenClaw** are AI agents built directly into OmniRoute โ€” no installation needed. -They run as internal routes and use OmniRoute's model routing automatically. - -- Access: `http://localhost:20128/dashboard/agents` -- Configure: same combos and providers as all other tools -- No API key or CLI install required - ---- - -## Available API Endpoints - -| Endpoint | Description | Use For | -| -------------------------- | ----------------------------- | --------------------------- | -| `/v1/chat/completions` | Standard chat (all providers) | All modern tools | -| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows | -| `/v1/completions` | Legacy text completions | Older tools using `prompt:` | -| `/v1/embeddings` | Text embeddings | RAG, search | -| `/v1/images/generations` | Image generation | DALL-E, Flux, etc. | -| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS | -| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI | - ---- - -## Troubleshooting - -| Error | Cause | Fix | -| ------------------------- | ----------------------- | ------------------------------------------ | -| `Connection refused` | OmniRoute not running | `pm2 start omniroute` | -| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` | -| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` | -| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` | -| CLI shows "not installed" | Binary not in PATH | Check `which ` | -| `kiro-cli: not found` | Not in PATH | `export PATH="$HOME/.local/bin:$PATH"` | - ---- - -## Quick Setup Script (One Command) - -```bash -# Install all CLIs and configure for OmniRoute (replace with your key and server URL) -OMNIROUTE_URL="http://localhost:20128/v1" -OMNIROUTE_KEY="sk-your-omniroute-key" - -npm install -g @anthropic-ai/claude-code @openai/codex @google/gemini-cli opencode-ai cline kilecode - -# Kiro CLI -apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash - -# Write configs -mkdir -p ~/.claude ~/.codex ~/.gemini ~/.config/opencode ~/.continue - -cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" -cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" -cat > ~/.gemini/settings.json <<< "{\"apiKey\":\"$OMNIROUTE_KEY\",\"baseUrl\":\"$OMNIROUTE_URL\"}" -cat >> ~/.bashrc << EOF -export OPENAI_BASE_URL="$OMNIROUTE_URL" -export OPENAI_API_KEY="$OMNIROUTE_KEY" -export ANTHROPIC_BASE_URL="$OMNIROUTE_URL" -export ANTHROPIC_API_KEY="$OMNIROUTE_KEY" -EOF - -source ~/.bashrc -echo "โœ… All CLIs installed and configured for OmniRoute" -``` diff --git a/docs/i18n/ko/CODEBASE_DOCUMENTATION.md b/docs/i18n/ko/CODEBASE_DOCUMENTATION.md deleted file mode 100644 index e2d7950052..0000000000 --- a/docs/i18n/ko/CODEBASE_DOCUMENTATION.md +++ /dev/null @@ -1,593 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CODEBASE_DOCUMENTATION.md) - ---- - -# omniroute โ€” Codebase Documentation - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) - -> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. - ---- - -## 1. 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
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, Qoder, 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 | -| Qoder | 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"] -``` diff --git a/docs/i18n/ko/CONTRIBUTING.md b/docs/i18n/ko/CONTRIBUTING.md new file mode 100644 index 0000000000..4ff31e341f --- /dev/null +++ b/docs/i18n/ko/CONTRIBUTING.md @@ -0,0 +1,299 @@ +# Contributing to OmniRoute (ํ•œ๊ตญ์–ด) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CONTRIBUTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CONTRIBUTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CONTRIBUTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CONTRIBUTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CONTRIBUTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CONTRIBUTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CONTRIBUTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CONTRIBUTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CONTRIBUTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CONTRIBUTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CONTRIBUTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CONTRIBUTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CONTRIBUTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CONTRIBUTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CONTRIBUTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CONTRIBUTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CONTRIBUTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CONTRIBUTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CONTRIBUTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CONTRIBUTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CONTRIBUTING.md) + +--- + +Thank you for your interest in contributing! This guide covers everything you need to get started. + +--- + +## Development Setup + +### Prerequisites + +- **Node.js** >= 18 < 24 (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` | `20128` | Server port | +| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | Base URL for frontend | +| `JWT_SECRET` | (generate above) | JWT signing secret | +| `INITIAL_PASSWORD` | `CHANGEME` | First login password | +| `APP_LOG_LEVEL` | `info` | Log verbosity level | + +### Dashboard Settings + +The dashboard provides UI toggles for features that can also be configured via environment variables: + +| Setting Location | Toggle | Description | +| ------------------- | ------------------ | ------------------------------ | +| Settings โ†’ Advanced | Debug Mode | Enable debug request logs (UI) | +| Settings โ†’ General | Sidebar Visibility | Show/hide sidebar sections | + +These settings are stored in the database and persist across restarts, overriding env var defaults when set. + +### 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:20128/dashboard` +- **API**: `http://localhost:20128/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`, `mcp`, `a2a`, `memory`, `skills`. + +--- + +## Running Tests + +```bash +# All tests (unit + vitest + ecosystem + e2e) +npm run test:all + +# Single test file (Node.js native test runner โ€” most tests use this) +node --import tsx/esm --test tests/unit/your-file.test.mjs + +# Vitest (MCP server, autoCombo, cache) +npm run test:vitest + +# E2E tests (requires Playwright) +npm run test:e2e + +# Protocol clients E2E (MCP transports, A2A) +npm run test:protocols:e2e + +# Ecosystem compatibility tests +npm run test:ecosystem + +# Coverage (55% min statements/lines/functions; 60% branches) +npm run test:coverage +npm run coverage:report + +# Lint + format check +npm run lint +npm run check +``` + +Coverage notes: + +- `npm run test:coverage` measures source coverage for the main unit test suite, excludes `tests/**`, and includes `open-sse/**` +- `npm run coverage:report` prints the detailed file-by-file report from the latest coverage run +- `npm run test:coverage:legacy` preserves the older metric for historical comparison +- See `docs/COVERAGE_PLAN.md` for the phased coverage improvement roadmap + +Current test status: **122 unit test files** covering: + +- Provider translators and format conversion +- Rate limiting, circuit breaker, and resilience +- Semantic cache, idempotency, progress tracking +- Database operations and schema (21 DB modules) +- OAuth flows and authentication +- API endpoint validation (Zod v4) +- MCP server tools and scope enforcement +- Memory and Skills systems + +--- + +## Code Style + +- **ESLint** โ€” Run `npm run lint` before committing +- **Prettier** โ€” Auto-formatted via `lint-staged` on commit (2 spaces, semicolons, double quotes, 100 char width, es5 trailing commas) +- **TypeScript** โ€” All `src/` code uses `.ts`/`.tsx`; `open-sse/` uses `.ts`/`.js`; document with TSDoc (`@param`, `@returns`, `@throws`) +- **No `eval()`** โ€” ESLint enforces `no-eval`, `no-implied-eval`, `no-new-func` +- **Zod validation** โ€” Use Zod v4 schemas for all API input validation +- **Naming**: Files = camelCase/kebab-case, components = PascalCase, constants = UPPER_SNAKE + +--- + +## Project Structure + +``` +src/ # TypeScript (.ts / .tsx) +โ”œโ”€โ”€ app/ # Next.js 16 App Router +โ”‚ โ”œโ”€โ”€ (dashboard)/ # Dashboard pages (23 sections) +โ”‚ โ”œโ”€โ”€ api/ # API routes (51 directories) +โ”‚ โ””โ”€โ”€ login/ # Auth pages (.tsx) +โ”œโ”€โ”€ domain/ # Policy engine (policyEngine, comboResolver, costRules, etc.) +โ”œโ”€โ”€ lib/ # Core business logic (.ts) +โ”‚ โ”œโ”€โ”€ a2a/ # Agent-to-Agent v0.3 protocol server +โ”‚ โ”œโ”€โ”€ acp/ # Agent Communication Protocol registry +โ”‚ โ”œโ”€โ”€ compliance/ # Compliance policy engine +โ”‚ โ”œโ”€โ”€ db/ # SQLite database layer (21 modules + 16 migrations) +โ”‚ โ”œโ”€โ”€ memory/ # Persistent conversational memory +โ”‚ โ”œโ”€โ”€ oauth/ # OAuth providers, services, and utilities +โ”‚ โ”œโ”€โ”€ skills/ # Extensible skill framework +โ”‚ โ”œโ”€โ”€ usage/ # Usage tracking and cost calculation +โ”‚ โ””โ”€โ”€ localDb.ts # Re-export layer only โ€” never add logic here +โ”œโ”€โ”€ middleware/ # Request middleware (promptInjectionGuard) +โ”œโ”€โ”€ mitm/ # MITM proxy (cert, DNS, target routing) +โ”œโ”€โ”€ shared/ +โ”‚ โ”œโ”€โ”€ components/ # React components (.tsx) +โ”‚ โ”œโ”€โ”€ constants/ # Provider definitions (60+), MCP scopes, routing strategies +โ”‚ โ”œโ”€โ”€ utils/ # Circuit breaker, sanitizer, auth helpers +โ”‚ โ””โ”€โ”€ validation/ # Zod v4 schemas +โ””โ”€โ”€ sse/ # SSE proxy pipeline + +open-sse/ # @omniroute/open-sse workspace +โ”œโ”€โ”€ executors/ # 14 provider-specific request executors +โ”œโ”€โ”€ handlers/ # 11 request handlers (chat, responses, embeddings, images, etc.) +โ”œโ”€โ”€ mcp-server/ # MCP server (25 tools, 3 transports, 10 scopes) +โ”œโ”€โ”€ services/ # 36+ services (combo, autoCombo, rateLimitManager, etc.) +โ”œโ”€โ”€ translator/ # Format translators (OpenAI โ†” Claude โ†” Gemini โ†” Responses โ†” Ollama) +โ”œโ”€โ”€ transformer/ # Responses API transformer +โ””โ”€โ”€ utils/ # 22 utility modules (stream, TLS, proxy, logging) + +electron/ # Electron desktop app (cross-platform) + +tests/ +โ”œโ”€โ”€ unit/ # Node.js test runner (122 test files) +โ”œโ”€โ”€ integration/ # Integration tests +โ”œโ”€โ”€ e2e/ # Playwright tests +โ”œโ”€โ”€ security/ # Security tests +โ”œโ”€โ”€ translator/ # Translator-specific tests +โ””โ”€โ”€ load/ # Load tests + +docs/ # Documentation +โ”œโ”€โ”€ ARCHITECTURE.md # System architecture +โ”œโ”€โ”€ API_REFERENCE.md # All endpoints +โ”œโ”€โ”€ USER_GUIDE.md # Provider setup, CLI integration +โ”œโ”€โ”€ TROUBLESHOOTING.md # Common issues +โ”œโ”€โ”€ MCP-SERVER.md # MCP server (25 tools) +โ”œโ”€โ”€ A2A-SERVER.md # A2A agent protocol +โ”œโ”€โ”€ AUTO-COMBO.md # Auto-combo engine +โ”œโ”€โ”€ CLI-TOOLS.md # CLI tools integration +โ”œโ”€โ”€ COVERAGE_PLAN.md # Test coverage improvement plan +โ”œโ”€โ”€ openapi.yaml # OpenAPI specification +โ””โ”€โ”€ adr/ # Architecture Decision Records +``` + +--- + +## Adding a New Provider + +### Step 1: Register Provider Constants + +Add to `src/shared/constants/providers.ts` โ€” Zod-validated at module load. + +### Step 2: Add Executor (if custom logic needed) + +Create executor in `open-sse/executors/your-provider.ts` extending the base executor. + +### Step 3: Add Translator (if non-OpenAI format) + +Create request/response translators in `open-sse/translator/`. + +### Step 4: Add OAuth Config (if OAuth-based) + +Add OAuth credentials in `src/lib/oauth/constants/oauth.ts` and service in `src/lib/oauth/services/`. + +### Step 5: Register Models + +Add model definitions in `open-sse/config/providerRegistry.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 +- [ ] All inputs validated with Zod schemas +- [ ] CHANGELOG updated (if user-facing change) +- [ ] Documentation updated (if applicable) + +--- + +## Releasing + +Releases are managed via the `/generate-release` workflow. When a new GitHub Release is created, the package is **automatically published to npm** via GitHub Actions. + +--- + +## Getting Help + +- **Architecture**: See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) +- **API Reference**: See [`docs/API_REFERENCE.md`](docs/API_REFERENCE.md) +- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **ADRs**: See `docs/adr/` for architectural decision records diff --git a/docs/i18n/ko/FEATURES.md b/docs/i18n/ko/FEATURES.md deleted file mode 100644 index f6c2cdbbce..0000000000 --- a/docs/i18n/ko/FEATURES.md +++ /dev/null @@ -1,147 +0,0 @@ -# OmniRoute โ€” Dashboard Features Gallery (ํ•œ๊ตญ์–ด) - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) - -> ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../docs/FEATURES.md) - ---- - -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 (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. - -![Providers Dashboard](screenshots/01-providers.png) - ---- - -## ๐ŸŽจ Combos - -Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. - -![Combos Dashboard](screenshots/02-combos.png) - ---- - -## ๐Ÿ“Š Analytics - -Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. - -![Analytics Dashboard](screenshots/03-analytics.png) - ---- - -## ๐Ÿฅ System Health - -Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. - -![Health Dashboard](screenshots/04-health.png) - ---- - -## ๐Ÿ”ง Translator Playground - -Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). - -![Translator Playground](screenshots/05-translator.png) - ---- - -## ๐ŸŽฎ Model Playground _(v2.0.9+)_ - -Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. - ---- - -## ๐ŸŽจ Themes _(v2.0.5+)_ - -Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. - ---- - -## โš™๏ธ Settings - -Comprehensive settings panel with tabs: - -- **General** โ€” System storage, backup management (export/import database) -- **Appearance** โ€” Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls -- **Security** โ€” API endpoint protection, custom provider blocking, IP filtering, session info -- **Routing** โ€” Model aliases, background task degradation -- **Resilience** โ€” Rate limit persistence, circuit breaker tuning -- **Advanced** โ€” Configuration overrides - -![Settings Dashboard](screenshots/06-settings.png) - ---- - -## ๐Ÿ”ง CLI Tools - -One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. - -![CLI Tools Dashboard](screenshots/07-cli-tools.png) - ---- - -## ๐Ÿค– CLI Agents _(v2.0.11+)_ - -Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: - -- **Installation status** โ€” Installed / Not Found with version detection -- **Protocol badges** โ€” stdio, HTTP, etc. -- **Custom agents** โ€” Register any CLI tool via form (name, binary, version command, spawn args) -- **CLI Fingerprint Matching** โ€” Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP - ---- - -## ๐Ÿ–ผ๏ธ Media _(v2.0.3+)_ - -Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. - ---- - -## ๐Ÿ“ Request Logs - -Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. - -![Usage Logs](screenshots/08-usage.png) - ---- - -## ๐ŸŒ API Endpoint - -Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. - -![Endpoint Dashboard](screenshots/09-endpoint.png) - ---- - -## ๐Ÿ”‘ API Key Management - -Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. - ---- - -## ๐Ÿ“‹ Audit Log - -Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. - ---- - -## ๐Ÿ–ฅ๏ธ Desktop Application - -Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. - -Key features: - -- Server readiness polling (no blank screen on cold start) -- System tray with port management -- Content Security Policy -- Single-instance lock -- Auto-update on restart -- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) -- Hardened Electron build packaging โ€” symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+) - -๐Ÿ“– See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/ko/MCP-SERVER.md b/docs/i18n/ko/MCP-SERVER.md deleted file mode 100644 index 829acd30b1..0000000000 --- a/docs/i18n/ko/MCP-SERVER.md +++ /dev/null @@ -1,87 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/MCP-SERVER.md) - ---- - -# OmniRoute MCP Server Documentation - -> Model Context Protocol server with 16 intelligent tools - -## Installation - -OmniRoute MCP is built-in. Start it with: - -```bash -omniroute --mcp -``` - -Or via the open-sse transport: - -```bash -# HTTP streamable transport (port 20130) -omniroute --dev # MCP auto-starts on /mcp endpoint -``` - -## IDE Configuration - -See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup. - ---- - -## Essential Tools (8) - -| Tool | Description | -| :------------------------------ | :--------------------------------------- | -| `omniroute_get_health` | Gateway health, circuit breakers, uptime | -| `omniroute_list_combos` | All configured combos with models | -| `omniroute_get_combo_metrics` | Performance metrics for a specific combo | -| `omniroute_switch_combo` | Switch active combo by ID/name | -| `omniroute_check_quota` | Quota status per provider or all | -| `omniroute_route_request` | Send a chat completion through OmniRoute | -| `omniroute_cost_report` | Cost analytics for a time period | -| `omniroute_list_models_catalog` | Full model catalog with capabilities | - -## Advanced Tools (8) - -| Tool | Description | -| :--------------------------------- | :---------------------------------------------- | -| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | -| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | -| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | -| `omniroute_test_combo` | Live-test all models in a combo | -| `omniroute_get_provider_metrics` | Detailed metrics for one provider | -| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | -| `omniroute_explain_route` | Explain a past routing decision | -| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | - -## Authentication - -MCP tools are authenticated via API key scopes. Each tool requires specific scopes: - -| Scope | Tools | -| :------------- | :----------------------------------------------- | -| `read:health` | get_health, get_provider_metrics | -| `read:combos` | list_combos, get_combo_metrics | -| `write:combos` | switch_combo | -| `read:quota` | check_quota | -| `write:route` | route_request, simulate_route, test_combo | -| `read:usage` | cost_report, get_session_snapshot, explain_route | -| `write:config` | set_budget_guard, set_resilience_profile | -| `read:models` | list_models_catalog, best_combo_for_task | - -## Audit Logging - -Every tool call is logged to `mcp_tool_audit` with: - -- Tool name, arguments, result -- Duration (ms), success/failure -- API key hash, timestamp - -## Files - -| File | Purpose | -| :------------------------------------------- | :------------------------------------------ | -| `open-sse/mcp-server/server.ts` | MCP server creation + 16 tool registrations | -| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport | -| `open-sse/mcp-server/auth.ts` | API key + scope validation | -| `open-sse/mcp-server/audit.ts` | Tool call audit logging | -| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers | diff --git a/docs/i18n/ko/README.md b/docs/i18n/ko/README.md index 5bac782420..a669c168a5 100644 --- a/docs/i18n/ko/README.md +++ b/docs/i18n/ko/README.md @@ -1,12 +1,12 @@ # ๐Ÿš€ OmniRoute โ€” The Free AI Gateway (ํ•œ๊ตญ์–ด) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/README.md) --- ### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback. -_Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._ +_Your universal API proxy โ€” one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._ **Chat Completions โ€ข Embeddings โ€ข Image Generation โ€ข Video โ€ข Music โ€ข Audio โ€ข Reranking โ€ข **Web Search** โ€ข MCP Server โ€ข A2A Protocol โ€ข 100% TypeScript** @@ -46,15 +46,17 @@ _Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now wi > - `APP_LOG_FILE_PATH` > - `APP_LOG_MAX_FILE_SIZE` > - `APP_LOG_RETENTION_DAYS` +> - `APP_LOG_MAX_FILES` > - `APP_LOG_LEVEL` > - `APP_LOG_FORMAT` > - `CALL_LOG_RETENTION_DAYS` +> - `CALL_LOG_MAX_ENTRIES` > > For release details and upgrade notes, see the [CHANGELOG](CHANGELOG.md). --- -## ๐Ÿ†• What's New in v3.0.0 +## ๐Ÿ†• What's New > **Upgrading from v2.9.5?** โ€” See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes. @@ -274,7 +276,7 @@ Developers pay $20โ€“200/month for Claude Pro, Codex Pro, or GitHub Copilot. Eve - **Smart 4-Tier Fallback** โ€” If subscription quota runs out, automatically redirects to API Key โ†’ Cheap โ†’ Free with zero manual intervention - **Real-Time Quota Tracking** โ€” Shows token consumption in real-time with reset countdown (5h, daily, weekly) - **Multi-Account Support** โ€” Multiple accounts per provider with auto round-robin โ€” when one runs out, switches to the next -- **Custom Combos** โ€” Customizable fallback chains with 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Custom Combos** โ€” Customizable fallback chains with 9 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random) - **Codex Business Quotas** โ€” Business/Team workspace quota monitoring directly in the dashboard @@ -286,7 +288,7 @@ OpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If **How OmniRoute solves it:** -- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 67+ providers +- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 60+ providers - **Format Translation** โ€” Automatic and transparent: OpenAI โ†” Claude โ†” Gemini โ†” Responses API - **Response Sanitization** โ€” Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+ - **Role Normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI providers; `system` โ†’ `user` for GLM/ERNIE @@ -372,7 +374,7 @@ Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code.. - **CLI Tools Dashboard** โ€” Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline - **GitHub Copilot Config Generator** โ€” Generates `chatLanguageModels.json` for VS Code with bulk model selection - **Onboarding Wizard** โ€” Guided 4-step setup for first-time users -- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 67+ providers +- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 60+ providers @@ -419,7 +421,7 @@ When a call fails, the dev doesn't know if it was a rate limit, expired token, w - **SQLite Proxy Logs** โ€” Persistent logs that survive server restarts - **Translator Playground** โ€” 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time) - **Request Telemetry** โ€” p50/p95/p99 latency + X-Request-Id tracing -- **File-Based Logging with Rotation** โ€” Console interceptor captures everything to JSON log with size-based rotation +- **File-Based Logging with Rotation** โ€” App logs rotate by size, retention days, and archive count; call log artifacts rotate by retention days and file count - **System Info Report** โ€” `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage. @@ -514,7 +516,7 @@ Developers who want all responses in a specific language, with a specific tone, - **System Prompt Injection** โ€” Global prompt applied to all requests - **Thinking Budget Validation** โ€” Reasoning token allocation control per request (passthrough, auto, custom, adaptive) -- **6 Routing Strategies** โ€” Global strategies that determine how requests are distributed +- **9 Routing Strategies** โ€” Global strategies that determine how requests are distributed - **Wildcard Router** โ€” `provider/*` patterns route dynamically to any provider - **Combo Enable/Disable Toggle** โ€” Toggle combos directly from the dashboard - **Provider Toggle** โ€” Enable/disable all connections for a provider with one click @@ -581,7 +583,7 @@ Different clients should have least-privilege access to tool categories. **How OmniRoute solves it:** -- 9 granular MCP scopes for controlled tool access +- 10 granular MCP scopes for controlled tool access - Scope enforcement and visibility in MCP management UI - Safe default posture for operational tooling @@ -1325,19 +1327,19 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. ### ๐Ÿค– Agent & Protocol Operations (v2.0) -| Feature | What It Does | -| ------------------------------------- | -------------------------------------------------------------------------------------------------- | -| ๐Ÿ”ง **MCP Server (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) | -| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | -| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | -| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | -| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | -| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | -| ๐Ÿ” **MCP Scope Enforcement** | 9 granular scope permissions for controlled tool access | -| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | -| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | -| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | -| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | +| Feature | What It Does | +| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| ๐Ÿ”ง **MCP Server (25 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools | +| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | +| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | +| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | +| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | +| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | +| ๐Ÿ” **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access | +| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | +| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | +| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | +| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | ### ๐Ÿง  Routing & Intelligence @@ -1348,7 +1350,7 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. | ๐Ÿ”„ **Format Translation** | OpenAI โ†” Claude โ†” Gemini โ†” Responses with schema-safe conversions | | ๐Ÿ‘ฅ **Multi-Account Support** | Multiple accounts per provider with intelligent selection | | ๐Ÿ”„ **Auto Token Refresh** | OAuth tokens refresh automatically with retry | -| ๐ŸŽจ **Custom Combos** | 6 balancing strategies + fallback chain control | +| ๐ŸŽจ **Custom Combos** | 9 balancing strategies + fallback chain control | | ๐ŸŒ **Wildcard Router** | `provider/*` dynamic routing | | ๐Ÿง  **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits | | ๐Ÿ”€ **Model Aliases** | Built-in + custom model aliasing and migration safety | @@ -1949,6 +1951,7 @@ opencode - Request artifacts are written to `DATA_DIR/call_logs/` as one JSON file per request - Enable pipeline capture from Dashboard โ†’ Logs โ†’ Request Logs if you need detailed per-stage payloads - Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log` +- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed **Connection test shows "Invalid" for OpenAI-compatible providers** diff --git a/docs/i18n/ko/RELEASE_CHECKLIST.md b/docs/i18n/ko/RELEASE_CHECKLIST.md deleted file mode 100644 index 903e812c3f..0000000000 --- a/docs/i18n/ko/RELEASE_CHECKLIST.md +++ /dev/null @@ -1,37 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/RELEASE_CHECKLIST.md) - ---- - -# Release Checklist - -Use this checklist before tagging or publishing a new OmniRoute release. - -## Version and Changelog - -1. Bump `package.json` version (`x.y.z`) in the release branch. -2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: - - `## [x.y.z] โ€” YYYY-MM-DD` -3. Keep `## [Unreleased]` as the first changelog section for upcoming work. -4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. - -## API Docs - -1. Update `docs/openapi.yaml`: - - `info.version` must equal `package.json` version. -2. Validate endpoint examples if API contracts changed. - -## Runtime Docs - -1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. -2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. -3. Update localized docs if source docs changed significantly. - -## Automated Check - -Run the sync guard locally before opening PR: - -```bash -npm run check:docs-sync -``` - -CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/ko/SECURITY.md b/docs/i18n/ko/SECURITY.md new file mode 100644 index 0000000000..8243c67528 --- /dev/null +++ b/docs/i18n/ko/SECURITY.md @@ -0,0 +1,179 @@ +# Security Policy (ํ•œ๊ตญ์–ด) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../SECURITY.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/SECURITY.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/SECURITY.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/SECURITY.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/SECURITY.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/SECURITY.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/SECURITY.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/SECURITY.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/SECURITY.md) + +--- + +## 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 | +| ------- | -------------- | +| 3.4.x | โœ… Active | +| 3.0.x | โœ… Security | +| < 3.0.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 | +| **MCP Scopes** | 10 granular scopes for MCP tool access control | + +### ๐Ÿ›ก๏ธ 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:::` +- 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** | Allowlist/blocklist IP ranges in dashboard | +| **Rate Limiting** | Per-provider rate limits with automatic backoff | +| **Anti-Thundering Herd** | Mutex + per-connection locking prevents cascading 502s | +| **TLS Fingerprint** | Browser-like TLS fingerprint spoofing to reduce bot detection | +| **CLI Fingerprint** | Per-provider header/body ordering to match native CLI signatures | + +### ๐Ÿ”Œ Resilience & Availability + +| 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 `CALL_LOG_RETENTION_DAYS` | +| **No-Log Opt-out** | Per API key `noLog` flag disables request logging | +| **Audit Log** | Administrative actions tracked in `audit_log` table | +| **MCP Audit** | SQLite-backed audit logging for all MCP tool calls | +| **Zod Validation** | All API inputs validated with Zod v4 schemas at module load | + +--- + +## 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 +- Provider constants validated at module load via Zod (`src/shared/validation/providerSchema.ts`) diff --git a/docs/i18n/ko/TROUBLESHOOTING.md b/docs/i18n/ko/TROUBLESHOOTING.md deleted file mode 100644 index 63c148000a..0000000000 --- a/docs/i18n/ko/TROUBLESHOOTING.md +++ /dev/null @@ -1,258 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/TROUBLESHOOTING.md) - ---- - -# Troubleshooting - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/TROUBLESHOOTING.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/TROUBLESHOOTING.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/TROUBLESHOOTING.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/TROUBLESHOOTING.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/TROUBLESHOOTING.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/TROUBLESHOOTING.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/TROUBLESHOOTING.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/TROUBLESHOOTING.md) - -Common problems and solutions for OmniRoute. - ---- - -## Quick Fixes - -| Problem | Solution | -| ----------------------------- | ------------------------------------------------------------------ | -| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | -| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | -| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | -| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | -| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | - ---- - -## Provider Issues - -### "Language model did not provide messages" - -**Cause:** Provider quota exhausted. - -**Fix:** - -1. 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, Qoder) 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}/storage.sqlite` (providers, combos, aliases, keys, settings) -- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` -- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) - ---- - -## Circuit Breaker Issues - -### Provider stuck in OPEN state - -When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. - -**Fix:** - -1. 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 -- **SDK returns raw string instead of object** โ€” Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures -- **GLM/ERNIE rejects `system` role** โ€” Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models -- **`developer` role not recognized** โ€” Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers -- **`json_schema` not working with Gemini** โ€” Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` - ---- - -## Resilience Settings - -### Auto rate-limit not triggering - -- 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. - ---- - -## Optional RAG / LLM failure taxonomy (16 problems) - -Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. - -In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. - -If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: - -- retrieval drift and broken context boundaries -- empty or stale indexes and vector stores -- embedding versus semantic mismatch -- prompt assembly and context window issues -- logic collapse and overconfident answers -- long chain and agent coordination failures -- multi agent memory and role drift -- deployment and bootstrap ordering problems - -The idea is simple: - -1. When you investigate a bad response, capture: - - user task and request - - route or provider combo in OmniRoute - - any RAG context used downstream (retrieved documents, tool calls, etc) -2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` โ€ฆ `No.16`). -3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. -4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. - -Full text and concrete recipes live here (MIT license, text only): - -[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) - -You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. - ---- - -## Still Stuck? - -- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details -- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints -- **Health Dashboard**: Check **Dashboard โ†’ Health** for real-time system status -- **Translator**: Use **Dashboard โ†’ Translator** to debug format issues diff --git a/docs/i18n/ko/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/ko/VM_DEPLOYMENT_GUIDE.md deleted file mode 100644 index 2f391e72a9..0000000000 --- a/docs/i18n/ko/VM_DEPLOYMENT_GUIDE.md +++ /dev/null @@ -1,401 +0,0 @@ -# OmniRoute โ€” Cloudflare๋ฅผ ์‚ฌ์šฉํ•œ VM ๋ฐฐํฌ ๊ฐ€์ด๋“œ - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](../pt-BR/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](../es/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](../fr/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](../it/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](../ru/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](../zh-CN/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](../de/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](../in/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](../th/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](../uk-UA/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](../ar/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](../ja/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](../vi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](../bg/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](../da/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](../fi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](../he/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](../hu/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](../id/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](../ko/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](../ms/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](../nl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](../no/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](../pt/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](../ro/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](../pl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](../sk/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](../sv/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](../phi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](../cs/VM_DEPLOYMENT_GUIDE.md) - -Cloudflare๋ฅผ ํ†ตํ•ด ๊ด€๋ฆฌ๋˜๋Š” ๋„๋ฉ”์ธ์ด ์žˆ๋Š” VM(VPS)์— OmniRoute๋ฅผ ์„ค์น˜ํ•˜๊ณ  ๊ตฌ์„ฑํ•˜๊ธฐ ์œ„ํ•œ ์ „์ฒด ๊ฐ€์ด๋“œ์ž…๋‹ˆ๋‹ค. - ---- - -## ์ „์ œ์กฐ๊ฑด - -| ์•„์ดํ…œ | ์ตœ์†Œ | ์ถ”์ฒœ | -| ---------- | ------------------- | ---------------- | -| **CPU** | vCPU 1๊ฐœ | vCPU 2๊ฐœ | -| **๋žจ** | 1GB | 2GB | -| **๋””์Šคํฌ** | 10GB SSD | 25GB SSD | -| **OS** | ์šฐ๋ถ„ํˆฌ 22.04 LTS | ์šฐ๋ถ„ํˆฌ 24.04 LTS | -| **๋„๋ฉ”์ธ** | Cloudflare์— ๋“ฑ๋ก๋จ | โ€” | -| **๋„์ปค** | ๋„์ปค ์—”์ง„ 24+ | ๋„์ปค 27+ | - -**ํ…Œ์ŠคํŠธ๋œ ๊ณต๊ธ‰์ž**: Akamai(Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. - ---- - -## 1. VM ๊ตฌ์„ฑ - -### 1.1 ์ธ์Šคํ„ด์Šค ์ƒ์„ฑ - -์„ ํ˜ธํ•˜๋Š” VPS ์ œ๊ณต์—…์ฒด์—์„œ: - -- ์šฐ๋ถ„ํˆฌ 24.04 LTS๋ฅผ ์„ ํƒํ•˜์„ธ์š” -- ์ตœ์†Œ ์š”๊ธˆ์ œ ์„ ํƒ(vCPU 1๊ฐœ / RAM 1GB) -- ๊ฐ•๋ ฅํ•œ ๋ฃจํŠธ ๋น„๋ฐ€๋ฒˆํ˜ธ๋ฅผ ์„ค์ •ํ•˜๊ฑฐ๋‚˜ SSH ํ‚ค๋ฅผ ๊ตฌ์„ฑํ•˜์„ธ์š”. -- **๊ณต์šฉ IP**(์˜ˆ: `203.0.113.10`)๋ฅผ ๊ธฐ๋กํ•ด ๋‘์„ธ์š”. - -### 1.2 SSH๋ฅผ ํ†ตํ•ด ์—ฐ๊ฒฐ - -```bash -ssh root@203.0.113.10 -``` - -### 1.3 ์‹œ์Šคํ…œ ์—…๋ฐ์ดํŠธ - -```bash -apt update && apt upgrade -y -``` - -### 1.4 ๋„์ปค ์„ค์น˜ - -```bash -# Install dependencies -apt install -y ca-certificates curl gnupg - -# Add official Docker repository -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 nginx ์„ค์น˜ - -```bash -apt install -y nginx -``` - -### 1.6 ๋ฐฉํ™”๋ฒฝ ๊ตฌ์„ฑ(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 -``` - -> **ํŒ**: ๋ณด์•ˆ์„ ๊ทน๋Œ€ํ™”ํ•˜๋ ค๋ฉด ํฌํŠธ 80๊ณผ 443์„ Cloudflare IP๋กœ๋งŒ ์ œํ•œํ•˜์„ธ์š”. [Advanced Security](#advanced-security) ์„น์…˜์„ ์ฐธ์กฐํ•˜์„ธ์š”. - ---- - -## 2. OmniRoute ์„ค์น˜ - -### 2.1 ๊ตฌ์„ฑ ๋””๋ ‰ํ„ฐ๋ฆฌ ์ƒ์„ฑ - -```bash -mkdir -p /opt/omniroute -``` - -### 2.2 ํ™˜๊ฒฝ๋ณ€์ˆ˜ ํŒŒ์ผ ์ƒ์„ฑ - -```bash -cat > /opt/omniroute/.env << โ€˜EOFโ€™ -# === Security === -JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY -INITIAL_PASSWORD=YourSecurePassword123! -API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY -STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY -STORAGE_ENCRYPTION_KEY_VERSION=v1 -MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT - -# === 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 (change to your domain) === -BASE_URL=https://llms.seudominio.com -NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com - -# === Cloud Sync (optional) === -# CLOUD_URL=https://cloud.omniroute.online -# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online -EOF -``` - -> โš ๏ธ **์ค‘์š”**: ๊ณ ์œ ํ•œ ๋น„๋ฐ€ ํ‚ค๋ฅผ ์ƒ์„ฑํ•˜์„ธ์š”! ๊ฐ ํ‚ค์— `openssl rand -hex 32`์„ ์‚ฌ์šฉํ•˜์„ธ์š”. - -### 2.3 ์ปจํ…Œ์ด๋„ˆ ์‹œ์ž‘ - -```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 ์‹คํ–‰ ์ค‘์ธ์ง€ ํ™•์ธ - -```bash -docker ps | grep omniroute -docker logs omniroute --tail 20 -``` - -`[DB] SQLite database ready` ๋ฐ `listening on port 20128`์ด ํ‘œ์‹œ๋˜์–ด์•ผ ํ•ฉ๋‹ˆ๋‹ค. - ---- - -## 3. nginx(์—ญ๋ฐฉํ–ฅ ํ”„๋ก์‹œ) ๊ตฌ์„ฑ - -### 3.1 SSL ์ธ์ฆ์„œ ์ƒ์„ฑ(Cloudflare ์›๋ณธ) - -Cloudflare ๋Œ€์‹œ๋ณด๋“œ์—์„œ: - -1. **SSL/TLS โ†’ ์›๋ณธ ์„œ๋ฒ„**๋กœ ์ด๋™ํ•ฉ๋‹ˆ๋‹ค. -2. **์ธ์ฆ์„œ ๋งŒ๋“ค๊ธฐ**๋ฅผ ํด๋ฆญํ•˜์„ธ์š”. -3. ๊ธฐ๋ณธ๊ฐ’(15๋…„, \*.yourdomain.com)์„ ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค. -4. **์›๋ณธ ์ธ์ฆ์„œ** ๋ฐ **๊ฐœ์ธ ํ‚ค**๋ฅผ ๋ณต์‚ฌํ•ฉ๋‹ˆ๋‹ค. - -```bash -mkdir -p /etc/nginx/ssl - -# Paste the certificate -nano /etc/nginx/ssl/origin.crt - -# Paste the private key -nano /etc/nginx/ssl/origin.key - -chmod 600 /etc/nginx/ssl/origin.key -``` - -### 3.2 Nginx ๊ตฌ์„ฑ - -```bash -cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ -# Default server โ€” blocks direct access via 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.yourdomain.com; # Change to your domain - - 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.yourdomain.com; - return 301 https://$server_name$request_uri; -} -NGINX -``` - -### 3.3 ํ™œ์„ฑํ™” ๋ฐ ํ…Œ์ŠคํŠธ - -```bash -# Remove default configuration -rm -f /etc/nginx/sites-enabled/default - -# Enable OmniRoute -ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute - -# Test and reload -nginx -t && systemctl reload nginx -``` - ---- - -## 4. Cloudflare DNS ๊ตฌ์„ฑ - -### 4.1 DNS ๋ ˆ์ฝ”๋“œ ์ถ”๊ฐ€ - -Cloudflare ๋Œ€์‹œ๋ณด๋“œ โ†’ DNS: - -| ์œ ํ˜• | ์ด๋ฆ„ | ๋‚ด์šฉ | ํ”„๋ก์‹œ | -| ---- | ------ | --------------------- | ----------- | -| A | `llms` | `203.0.113.10`(VM IP) | โœ… ํ”„๋ก์‹œ๋จ | - -### 4.2 SSL ๊ตฌ์„ฑ - -**SSL/TLS โ†’ ๊ฐœ์š”**์—์„œ: - -- ๋ชจ๋“œ: **์ „์ฒด(์—„๊ฒฉ)** - -**SSL/TLS โ†’ ์—์ง€ ์ธ์ฆ์„œ**์—์„œ: - -- ํ•ญ์ƒ HTTPS ์‚ฌ์šฉ: โœ… ์ผœ๊ธฐ -- ์ตœ์†Œ TLS ๋ฒ„์ „: TLS 1.2 -- ์ž๋™ HTTPS ์žฌ์ž‘์„ฑ: โœ… ์ผœ์ง - -### 4.3 ํ…Œ์ŠคํŠธ - -```bash -curl -sI https://llms.seudominio.com/health -# Should return HTTP/2 200 -``` - ---- - -## 5. ์šด์˜ ๋ฐ ์œ ์ง€ ๊ด€๋ฆฌ - -### ์ƒˆ ๋ฒ„์ „์œผ๋กœ ์—…๊ทธ๋ ˆ์ด๋“œ - -```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 -``` - -### ๋กœ๊ทธ ๋ณด๊ธฐ - -```bash -docker logs -f omniroute # Real-time stream -docker logs omniroute --tail 50 # Last 50 lines -``` - -### ์ˆ˜๋™ ๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค ๋ฐฑ์—… - -```bash -# Copy data from the volume to the host -docker cp omniroute:/app/data ./backup-$(date +%F) - -# Or compress the entire volume -docker run --rm -v omniroute-data:/data -v $(pwd):/backup \ - alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data -``` - -### ๋ฐฑ์—…์—์„œ ๋ณต์› - -```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. ๊ณ ๊ธ‰ ๋ณด์•ˆ - -### nginx๋ฅผ Cloudflare IP๋กœ ์ œํ•œ - -```bash -cat > /etc/nginx/cloudflare-ips.conf << โ€˜CFโ€™ -# Cloudflare IPv4 ranges โ€” update periodically -# 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 -``` - -`http {}` ๋ธ”๋ก ๋‚ด๋ถ€์˜ `nginx.conf`์— ๋‹ค์Œ์„ ์ถ”๊ฐ€ํ•ฉ๋‹ˆ๋‹ค. - -```nginx -include /etc/nginx/cloudflare-ips.conf; -``` - -### Fail2ban ์„ค์น˜ - -```bash -apt install -y fail2ban -systemctl enable fail2ban -systemctl start fail2ban - -# Check status -fail2ban-client status sshd -``` - -### Docker ํฌํŠธ์— ๋Œ€ํ•œ ์ง์ ‘ ์•ก์„ธ์Šค ์ฐจ๋‹จ - -```bash -# Prevent direct external access to port 20128 -iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP -iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT - -# Persist the rules -apt install -y iptables-persistent -netfilter-persistent save -``` - ---- - -## 7. Cloudflare Workers์— ๋ฐฐํฌ(์„ ํƒ ์‚ฌํ•ญ) - -Cloudflare Workers๋ฅผ ํ†ตํ•œ ์›๊ฒฉ ์•ก์„ธ์Šค์˜ ๊ฒฝ์šฐ(VM์„ ์ง์ ‘ ๋…ธ์ถœํ•˜์ง€ ์•Š๊ณ ): - -```bash -# In the local repository -cd omnirouteCloud -npm install -npx wrangler login -npx wrangler deploy -``` - -[omnirouteCloud/README.md](../omnirouteCloud/README.md)์—์„œ ์ „์ฒด ๋ฌธ์„œ๋ฅผ ์ฐธ์กฐํ•˜์„ธ์š”. - ---- - -## ํฌํŠธ ์š”์•ฝ - -| ํฌํŠธ | ์„œ๋น„์Šค | ์•ก์„ธ์Šค | -| ----- | ----------- | ----------------------------- | -| 22 | SSH | ๊ณต๊ฐœ(fail2ban ํฌํ•จ) | -| 80 | nginx HTTP | ๋ฆฌ๋””๋ ‰์…˜ โ†’ HTTPS | -| 443 | nginx HTTPS | Cloudflare ํ”„๋ก์‹œ๋ฅผ ํ†ตํ•ด | -| 20128 | ์˜ด๋‹ˆ๋ฃจํŠธ | ๋กœ์ปฌํ˜ธ์ŠคํŠธ ์ „์šฉ(nginx๋ฅผ ํ†ตํ•ด) | diff --git a/docs/i18n/ko/docs/A2A-SERVER.md b/docs/i18n/ko/docs/A2A-SERVER.md new file mode 100644 index 0000000000..3e3c346357 --- /dev/null +++ b/docs/i18n/ko/docs/A2A-SERVER.md @@ -0,0 +1,200 @@ +# OmniRoute A2A Server Documentation (ํ•œ๊ตญ์–ด) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/A2A-SERVER.md) + +--- + +> Agent-to-Agent Protocol v0.3 โ€” OmniRoute as an intelligent routing agent + +## Agent Discovery + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements. + +--- + +## Authentication + +All `/a2a` requests require an API key via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server, authentication is bypassed. + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Sends a message to a skill and waits for the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a hello world in Python"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "uuid", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "..." }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}} + +: heartbeat 2026-03-03T17:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Available Skills + +| Skill | Description | +| :----------------- | :------------------------------------------------------------------------------------------------------------------------------ | +| `smart-routing` | Routes prompts through OmniRoute's intelligent pipeline. Returns response with routing explanation, cost, and resilience trace. | +| `quota-management` | Answers natural-language queries about provider quotas, suggests free combos, and provides quota rankings. | + +--- + +## Task Lifecycle + +``` +submitted โ†’ working โ†’ completed + โ†’ failed + โ†’ cancelled +``` + +- Tasks expire after 5 minutes (configurable) +- Terminal states: `completed`, `failed`, `cancelled` +- Event log tracks every state transition + +--- + +## Error Codes + +| Code | Meaning | +| :----- | :----------------------------- | +| -32700 | Parse error (invalid JSON) | +| -32600 | Invalid request / Unauthorized | +| -32601 | Method or skill not found | +| -32602 | Invalid params | +| -32603 | Internal error | + +--- + +## Integration Examples + +### Python (requests) + +```python +import requests + +resp = requests.post("http://localhost:20128/a2a", json={ + "jsonrpc": "2.0", "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Hello"}] + } +}, headers={"Authorization": "Bearer YOUR_KEY"}) + +result = resp.json()["result"] +print(result["artifacts"][0]["content"]) +print(result["metadata"]["routing_explanation"]) +``` + +### TypeScript (fetch) + +```typescript +const resp = await fetch("http://localhost:20128/a2a", { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: "Bearer YOUR_KEY", + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "1", + method: "message/send", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Hello" }], + }, + }), +}); +const { result } = await resp.json(); +console.log(result.metadata.routing_explanation); +``` diff --git a/docs/i18n/ko/docs/API_REFERENCE.md b/docs/i18n/ko/docs/API_REFERENCE.md new file mode 100644 index 0000000000..c7e387c234 --- /dev/null +++ b/docs/i18n/ko/docs/API_REFERENCE.md @@ -0,0 +1,465 @@ +# API Reference (ํ•œ๊ตญ์–ด) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/API_REFERENCE.md) + +--- + +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 | +| `X-Session-Id` | Request | Sticky session key for external session affinity | +| `x_session_id` | Request | Underscore variant also accepted (direct HTTP) | +| `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 | +| `X-OmniRoute-Session-Id` | Response | Effective session ID used by OmniRoute | + +> Nginx note: if you rely on underscore headers (for example `x_session_id`), enable `underscores_in_headers 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/stats + +# Clear all caches +DELETE /api/cache/stats +``` + +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/PATCH | 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 + provider summary (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`) | +| `/api/cache/stats` | 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 | + +### Tunnels + +| Endpoint | Method | Description | +| -------------------------- | ------ | ----------------------------------------------------------------------- | +| `/api/tunnels/cloudflared` | GET | Read Cloudflare Quick Tunnel install/runtime status for the dashboard | +| `/api/tunnels/cloudflared` | POST | Enable or disable the Cloudflare Quick Tunnel (`action=enable/disable`) | + +### 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`. + +### ACP Agents + +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | + +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). + +### Resilience & Rate Limits + +| Endpoint | Method | Description | +| ----------------------- | --------- | ------------------------------- | +| `/api/resilience` | GET/PATCH | 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` diff --git a/docs/i18n/ko/docs/ARCHITECTURE.md b/docs/i18n/ko/docs/ARCHITECTURE.md new file mode 100644 index 0000000000..c846409c8a --- /dev/null +++ b/docs/i18n/ko/docs/ARCHITECTURE.md @@ -0,0 +1,814 @@ +# OmniRoute Architecture (ํ•œ๊ตญ์–ด) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/ARCHITECTURE.md) + +--- + +_Last updated: 2026-03-28_ + +## 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 (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developerโ†’system, systemโ†’user) for cross-provider compatibility +- Structured output conversion (json_schema โ†’ Gemini responseSchema) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) +- Global system prompt injection +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout โ†’ budget โ†’ fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) + +Primary runtime model: + +- Next.js 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.) + +## Dashboard Surface (Current) + +Main pages under `src/app/(dashboard)/dashboard/`: + +- `/dashboard` โ€” quick start + provider overview +- `/dashboard/endpoint` โ€” endpoint proxy + MCP + A2A + API endpoint tabs +- `/dashboard/providers` โ€” provider connections and credentials +- `/dashboard/combos` โ€” combo strategies, templates, model routing rules +- `/dashboard/costs` โ€” cost aggregation and pricing visibility +- `/dashboard/analytics` โ€” usage analytics and evaluations +- `/dashboard/limits` โ€” quota/rate controls +- `/dashboard/cli-tools` โ€” CLI onboarding, runtime detection, config generation +- `/dashboard/agents` โ€” detected ACP agents + custom agent registration +- `/dashboard/media` โ€” image/video/music playground +- `/dashboard/search-tools` โ€” search provider testing and history +- `/dashboard/health` โ€” uptime, circuit breakers, rate limits +- `/dashboard/logs` โ€” request/proxy/audit/console logs +- `/dashboard/settings` โ€” system settings tabs (general, routing, combo defaults, etc.) +- `/dashboard/api-manager` โ€” API key lifecycle and model permissions + +## 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[(storage.sqlite)] + UDB[(usage tables + log artifacts)] + end + + subgraph Upstreams[Upstream Providers] + P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/Qoder/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/route.ts` (GET) +- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- OAuth: `src/app/api/oauth/*` +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` +- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI tooling helpers: `src/app/api/cli-tools/*` +- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) +- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) โ€” provider profiles, circuit breaker, rate limit state +- Resilience reset: `src/app/api/resilience/reset` (POST) โ€” reset breakers + cooldowns +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) +- Telemetry: `src/app/api/telemetry/summary` (GET) +- Budget: `src/app/api/usage/budget` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Policies: `src/app/api/policies` (GET/POST) + +## 2) SSE + 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` +- Response sanitization: `open-sse/handlers/responseSanitizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.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`, `qoder.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 (SQLite): + +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** + +Usage persistence: + +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present + +Domain State DB (SQLite): + +- `src/lib/db/domainState.ts` โ€” CRUD operations 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`, `src/shared/services/modelSyncScheduler.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Periodic task: `src/shared/services/modelSyncScheduler.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. Combo routing adds one extra guard: provider-scoped 400s such as upstream content-block and role-validation failures are treated as model-local failures so later combo targets can still run. + +## 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: + +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` + +## Deployment Topology + +```mermaid +flowchart LR + 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[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] + end + + subgraph External[External Services] + Providers[AI Providers] + SyncCloud[Cloud Sync Service] + end + + CLI --> Next + Browser --> Next + Next --> Core + Next --> MainDB + Core --> MainDB + Core --> UsageDB + Core --> Providers + Next --> SyncCloud +``` + +## Module Mapping (Decision-Critical) + +### Route and API Modules + +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle +- `src/app/api/models/alias`: alias management +- `src/app/api/combos*`: fallback combo management +- `src/app/api/pricing`: pricing overrides for cost calculation +- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers +- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) +- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) +- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) +- `src/app/api/sessions`: active session listing (GET) +- `src/app/api/rate-limits`: per-account rate limit status (GET) + +### Routing and Execution Core + +- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior + +### Translation Registry and Format Converters + +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` +- Format constants: `open-sse/translator/formats.ts` + +### Persistence + +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables + +## Provider Executor Coverage (Strategy Pattern) + +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. + +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, Qoder, 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 | +| Qoder | openai | OAuth (Basic) | โœ… | โœ… | โœ… | โš ๏ธ Per request | +| OpenRouter | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| GLM/Kimi/MiniMax | claude | API Key | โœ… | โœ… | โŒ | โŒ | +| DeepSeek | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Groq | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| xAI (Grok) | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Mistral | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Perplexity | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Together AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Fireworks AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Cerebras | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Cohere | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| NVIDIA NIM | openai | API Key | โœ… | โœ… | โŒ | โŒ | + +## Format Translation Coverage + +Detected source formats include: + +- `openai` +- `openai-responses` +- `claude` +- `gemini` + +Target formats include: + +- OpenAI chat/Responses +- Claude +- Gemini/Gemini-CLI/Antigravity envelope +- Kiro +- Cursor + +Translations use **OpenAI as the hub format** โ€” all conversions go through OpenAI as intermediate: + +``` +Source Format โ†’ OpenAI (hub) โ†’ Target Format +``` + +Translations are selected dynamically based on source payload shape and provider target format. + +Additional processing layers in the translation pipeline: + +- **Response sanitization** โ€” Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI targets; merges `system` โ†’ `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** โ€” Parses `...` blocks from content into `reasoning_content` field +- **Structured output** โ€” Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` + +## Supported API Endpoints + +| 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` | Provider Models | Provider model metadata backing custom and managed available models | + +## 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 `/logs//` 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 + +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON โ†’ SQLite migration compatibility path + +## Observability and Operational Signals + +Runtime visibility sources: + +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- four-stage detailed payload captures in SQLite (`request_detail_logs`) when `settings.detailed_logs_enabled=true` +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption + +Detailed request payload capture stores up to four JSON payload stages per routed call: + +- raw request received from the client +- translated request actually sent upstream +- provider response reconstructed as JSON; streamed responses are compacted to the final summary plus stream metadata +- final client response returned by OmniRoute; streamed responses are stored in the same compact summary form + +## Security-Sensitive Boundaries + +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics + +## Environment and Runtime Matrix + +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` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). + +## Operational Verification Checklist + +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: +- `GET /api/settings` +- `GET /api/v1/models` +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/ko/docs/AUTO-COMBO.md b/docs/i18n/ko/docs/AUTO-COMBO.md new file mode 100644 index 0000000000..ff2237f22f --- /dev/null +++ b/docs/i18n/ko/docs/AUTO-COMBO.md @@ -0,0 +1,67 @@ +# OmniRoute Auto-Combo Engine (ํ•œ๊ตญ์–ด) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/AUTO-COMBO.md) + +--- + +> Self-managing model chains with adaptive scoring + +## How It Works + +The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**: + +| Factor | Weight | Description | +| :--------- | :----- | :---------------------------------------------- | +| Quota | 0.20 | Remaining capacity [0..1] | +| Health | 0.25 | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 | +| CostInv | 0.20 | Inverse cost (cheaper = higher score) | +| LatencyInv | 0.15 | Inverse p95 latency (faster = higher) | +| TaskFit | 0.10 | Model ร— task type fitness score | +| Stability | 0.10 | Low variance in latency/errors | + +## Mode Packs + +| Pack | Focus | Key Weight | +| :---------------------- | :----------- | :--------------- | +| ๐Ÿš€ **Ship Fast** | Speed | latencyInv: 0.35 | +| ๐Ÿ’ฐ **Cost Saver** | Economy | costInv: 0.40 | +| ๐ŸŽฏ **Quality First** | Best model | taskFit: 0.40 | +| ๐Ÿ“ก **Offline Friendly** | Availability | quota: 0.40 | + +## Self-Healing + +- **Temporary exclusion**: Score < 0.2 โ†’ excluded for 5 min (progressive backoff, max 30 min) +- **Circuit breaker awareness**: OPEN โ†’ auto-excluded; HALF_OPEN โ†’ probe requests +- **Incident mode**: >50% OPEN โ†’ disable exploration, maximize stability +- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout + +## Bandit Exploration + +5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode. + +## API + +```bash +# Create auto-combo +curl -X POST http://localhost:20128/api/combos/auto \ + -H "Content-Type: application/json" \ + -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}' + +# List auto-combos +curl http://localhost:20128/api/combos/auto +``` + +## Task Fitness + +30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` โ†’ high coding score). + +## Files + +| File | Purpose | +| :------------------------------------------- | :------------------------------------ | +| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization | +| `open-sse/services/autoCombo/taskFitness.ts` | Model ร— task fitness lookup | +| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap | +| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode | +| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles | +| `src/app/api/combos/auto/route.ts` | REST API | diff --git a/docs/i18n/ko/docs/CLI-TOOLS.md b/docs/i18n/ko/docs/CLI-TOOLS.md new file mode 100644 index 0000000000..92faf71be1 --- /dev/null +++ b/docs/i18n/ko/docs/CLI-TOOLS.md @@ -0,0 +1,348 @@ +# CLI Tools Setup Guide โ€” OmniRoute (ํ•œ๊ตญ์–ด) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CLI-TOOLS.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CLI-TOOLS.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CLI-TOOLS.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CLI-TOOLS.md) + +--- + +This guide explains how to install and configure all supported AI coding CLI tools +to use **OmniRoute** as the unified backend, giving you centralized key management, +cost tracking, model switching, and request logging across every tool. + +--- + +## How It Works + +``` +Claude / Codex / OpenCode / Cline / KiloCode / Continue / Kiro / Cursor / Copilot + โ”‚ + โ–ผ (all point to OmniRoute) + http://YOUR_SERVER:20128/v1 + โ”‚ + โ–ผ (OmniRoute routes to the right provider) + Anthropic / OpenAI / Gemini / DeepSeek / Groq / Mistral / ... +``` + +**Benefits:** + +- One API key to manage all tools +- Cost tracking across all CLIs in the dashboard +- Model switching without reconfiguring every tool +- Works locally and on remote servers (VPS) + +--- + +## Supported Tools (Dashboard Source of Truth) + +The dashboard cards in `/dashboard/cli-tools` are generated from `src/shared/constants/cliTools.ts`. +Current list (v3.0.0-rc.16): + +| Tool | ID | Command | Setup Mode | Install Method | +| ------------------ | ------------- | ---------- | ---------- | -------------- | +| **Claude Code** | `claude` | `claude` | env | npm | +| **OpenAI Codex** | `codex` | `codex` | custom | npm | +| **Factory Droid** | `droid` | `droid` | custom | bundled/CLI | +| **OpenClaw** | `openclaw` | `openclaw` | custom | bundled/CLI | +| **Cursor** | `cursor` | app | guide | desktop app | +| **Cline** | `cline` | `cline` | custom | npm | +| **Kilo Code** | `kilo` | `kilocode` | custom | npm | +| **Continue** | `continue` | extension | guide | VS Code | +| **Antigravity** | `antigravity` | internal | mitm | OmniRoute | +| **GitHub Copilot** | `copilot` | extension | custom | VS Code | +| **OpenCode** | `opencode` | `opencode` | guide | npm | +| **Kiro AI** | `kiro` | app/cli | mitm | desktop/CLI | + +### CLI fingerprint sync (Agents + Settings) + +`/dashboard/agents` and `Settings > CLI Fingerprint` use `src/shared/constants/cliCompatProviders.ts`. +This keeps provider IDs aligned with CLI cards and legacy IDs. + +| CLI ID | Fingerprint Provider ID | +| ---------------------------------------------------------------------------------------------------- | ----------------------- | +| `kilo` | `kilocode` | +| `copilot` | `github` | +| `claude` / `codex` / `antigravity` / `kiro` / `cursor` / `cline` / `opencode` / `droid` / `openclaw` | same ID | + +Legacy IDs still accepted for compatibility: `copilot`, `kimi-coding`, `qwen`. + +--- + +## Step 1 โ€” Get an OmniRoute API Key + +1. Open the OmniRoute dashboard โ†’ **API Manager** (`/dashboard/api-manager`) +2. Click **Create API Key** +3. Give it a name (e.g. `cli-tools`) and select all permissions +4. Copy the key โ€” you'll need it for every CLI below + +> Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` + +--- + +## Step 2 โ€” Install CLI Tools + +All npm-based tools require Node.js 18+: + +```bash +# Claude Code (Anthropic) +npm install -g @anthropic-ai/claude-code + +# OpenAI Codex +npm install -g @openai/codex + +# OpenCode +npm install -g opencode-ai + +# Cline +npm install -g cline + +# KiloCode +npm install -g kilocode + +# Kiro CLI (Amazon โ€” requires curl + unzip) +apt-get install -y unzip # on Debian/Ubuntu +curl -fsSL https://cli.kiro.dev/install | bash +export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc +``` + +**Verify:** + +```bash +claude --version # 2.x.x +codex --version # 0.x.x +opencode --version # x.x.x +cline --version # 2.x.x +kilocode --version # x.x.x (or: kilo --version) +kiro-cli --version # 1.x.x +``` + +--- + +## Step 3 โ€” Set Global Environment Variables + +Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`: + +```bash +# OmniRoute Universal Endpoint +export OPENAI_BASE_URL="http://localhost:20128/v1" +export OPENAI_API_KEY="sk-your-omniroute-key" +export ANTHROPIC_BASE_URL="http://localhost:20128/v1" +export ANTHROPIC_API_KEY="sk-your-omniroute-key" +export GEMINI_BASE_URL="http://localhost:20128/v1" +export GEMINI_API_KEY="sk-your-omniroute-key" +``` + +> For a **remote server** replace `localhost:20128` with the server IP or domain, +> e.g. `http://192.168.0.15:20128`. + +--- + +## Step 4 โ€” Configure Each Tool + +### Claude Code + +```bash +# Via CLI: +claude config set --global api-base-url http://localhost:20128/v1 + +# Or create ~/.claude/settings.json: +mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF +{ + "apiBaseUrl": "http://localhost:20128/v1", + "apiKey": "sk-your-omniroute-key" +} +EOF +``` + +**Test:** `claude "say hello"` + +--- + +### OpenAI Codex + +```bash +mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF +model: auto +apiKey: sk-your-omniroute-key +apiBaseUrl: http://localhost:20128/v1 +EOF +``` + +**Test:** `codex "what is 2+2?"` + +--- + +### OpenCode + +```bash +mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF +[provider.openai] +base_url = "http://localhost:20128/v1" +api_key = "sk-your-omniroute-key" +EOF +``` + +**Test:** `opencode` + +--- + +### Cline (CLI or VS Code) + +**CLI mode:** + +```bash +mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF +{ + "apiProvider": "openai", + "openAiBaseUrl": "http://localhost:20128/v1", + "openAiApiKey": "sk-your-omniroute-key" +} +EOF +``` + +**VS Code mode:** +Cline extension settings โ†’ API Provider: `OpenAI Compatible` โ†’ Base URL: `http://localhost:20128/v1` + +Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ Cline โ†’ Apply Config**. + +--- + +### KiloCode (CLI or VS Code) + +**CLI mode:** + +```bash +kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key +``` + +**VS Code settings:** + +```json +{ + "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", + "kilo-code.apiKey": "sk-your-omniroute-key" +} +``` + +Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ KiloCode โ†’ Apply Config**. + +--- + +### Continue (VS Code Extension) + +Edit `~/.continue/config.yaml`: + +```yaml +models: + - name: OmniRoute + provider: openai + model: auto + apiBase: http://localhost:20128/v1 + apiKey: sk-your-omniroute-key + default: true +``` + +Restart VS Code after editing. + +--- + +### Kiro CLI (Amazon) + +```bash +# Login to your AWS/Kiro account: +kiro-cli login + +# The CLI uses its own auth โ€” OmniRoute is not needed as backend for Kiro CLI itself. +# Use kiro-cli alongside OmniRoute for other tools. +kiro-cli status +``` + +--- + +### Cursor (Desktop App) + +> **Note:** Cursor routes requests through its cloud. For OmniRoute integration, +> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL. + +Via GUI: **Settings โ†’ Models โ†’ OpenAI API Key** + +- Base URL: `https://your-domain.com/v1` +- API Key: your OmniRoute key + +--- + +## Dashboard Auto-Configuration + +The OmniRoute dashboard automates configuration for most tools: + +1. Go to `http://localhost:20128/dashboard/cli-tools` +2. Expand any tool card +3. Select your API key from the dropdown +4. Click **Apply Config** (if tool is detected as installed) +5. Or copy the generated config snippet manually + +--- + +## Built-in Agents: Droid & OpenClaw + +**Droid** and **OpenClaw** are AI agents built directly into OmniRoute โ€” no installation needed. +They run as internal routes and use OmniRoute's model routing automatically. + +- Access: `http://localhost:20128/dashboard/agents` +- Configure: same combos and providers as all other tools +- No API key or CLI install required + +--- + +## Available API Endpoints + +| Endpoint | Description | Use For | +| -------------------------- | ----------------------------- | --------------------------- | +| `/v1/chat/completions` | Standard chat (all providers) | All modern tools | +| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows | +| `/v1/completions` | Legacy text completions | Older tools using `prompt:` | +| `/v1/embeddings` | Text embeddings | RAG, search | +| `/v1/images/generations` | Image generation | DALL-E, Flux, etc. | +| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS | +| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI | + +--- + +## ๋ฌธ์ œ ํ•ด๊ฒฐ + +| Error | Cause | Fix | +| ------------------------- | ----------------------- | ------------------------------------------ | +| `Connection refused` | OmniRoute not running | `pm2 start omniroute` | +| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` | +| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` | +| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` | +| CLI shows "not installed" | Binary not in PATH | Check `which ` | +| `kiro-cli: not found` | Not in PATH | `export PATH="$HOME/.local/bin:$PATH"` | + +--- + +## Quick Setup Script (One Command) + +```bash +# Install all CLIs and configure for OmniRoute (replace with your key and server URL) +OMNIROUTE_URL="http://localhost:20128/v1" +OMNIROUTE_KEY="sk-your-omniroute-key" + +npm install -g @anthropic-ai/claude-code @openai/codex opencode-ai cline kilocode + +# Kiro CLI +apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash + +# Write configs +mkdir -p ~/.claude ~/.codex ~/.config/opencode ~/.continue + +cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" +cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" +cat >> ~/.bashrc << EOF +export OPENAI_BASE_URL="$OMNIROUTE_URL" +export OPENAI_API_KEY="$OMNIROUTE_KEY" +export ANTHROPIC_BASE_URL="$OMNIROUTE_URL" +export ANTHROPIC_API_KEY="$OMNIROUTE_KEY" +EOF + +source ~/.bashrc +echo "โœ… All CLIs installed and configured for OmniRoute" +``` diff --git a/docs/i18n/ko/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/ko/docs/CODEBASE_DOCUMENTATION.md new file mode 100644 index 0000000000..b4767929ca --- /dev/null +++ b/docs/i18n/ko/docs/CODEBASE_DOCUMENTATION.md @@ -0,0 +1,591 @@ +# omniroute โ€” Codebase Documentation (ํ•œ๊ตญ์–ด) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CODEBASE_DOCUMENTATION.md) + +--- + +> 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
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, Qoder, 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. + +#### ์•„ํ‚คํ…์ฒ˜ + +```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 | +| Qoder | 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"] +``` diff --git a/docs/i18n/ko/docs/COVERAGE_PLAN.md b/docs/i18n/ko/docs/COVERAGE_PLAN.md new file mode 100644 index 0000000000..08a3a2d375 --- /dev/null +++ b/docs/i18n/ko/docs/COVERAGE_PLAN.md @@ -0,0 +1,170 @@ +# Test Coverage Plan (ํ•œ๊ตญ์–ด) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/COVERAGE_PLAN.md) + +--- + +Last updated: 2026-03-28 + +## Baseline + +There are multiple coverage numbers depending on how the report is computed. For planning, only one of them is useful. + +| Metric | Scope | Statements / Lines | Branches | Functions | Notes | +| -------------------- | ----------------------------------------------------- | -----------------: | -------: | --------: | --------------------------------------------------- | +| Legacy | Old `npm run test:coverage` | 79.42% | 75.15% | 67.94% | Inflated: counts test files and excludes `open-sse` | +| Diagnostic | Source-only, excluding tests and excluding `open-sse` | 68.16% | 63.55% | 64.06% | Useful only to isolate `src/**` | +| Recommended baseline | Source-only, excluding tests and including `open-sse` | 56.95% | 66.05% | 57.80% | This is the project-wide baseline to improve | + +The recommended baseline is the number to optimize against. + +## Rules + +- Coverage targets apply to source files, not to `tests/**`. +- `open-sse/**` is part of the product and must remain in scope. +- New code should not reduce coverage in touched areas. +- Prefer testing behavior and branch outcomes over implementation details. +- Prefer temp SQLite databases and small fixtures over broad mocks for `src/lib/db/**`. + +## Current command set + +- `npm run test:coverage` + - Main source coverage gate for the unit test suite + - Generates `text-summary`, `html`, `json-summary`, and `lcov` +- `npm run coverage:report` + - Detailed file-by-file report from the latest run +- `npm run test:coverage:legacy` + - Historical comparison only + +## Milestones + +| Phase | Target | Focus | +| ------- | ---------------------: | ------------------------------------------------- | +| Phase 1 | 60% statements / lines | Quick wins and low-risk utility coverage | +| Phase 2 | 65% statements / lines | DB and route foundations | +| Phase 3 | 70% statements / lines | Provider validation and usage analytics | +| Phase 4 | 75% statements / lines | `open-sse` translators and helpers | +| Phase 5 | 80% statements / lines | `open-sse` handlers and executor branches | +| Phase 6 | 85% statements / lines | Harder edge cases, branch debt, regression suites | +| Phase 7 | 90% statements / lines | Final sweep, gap closure, strict ratchet | + +Branches and functions should ratchet upward with each phase, but the primary hard target is statements / lines. + +## Priority hotspots + +These files or areas offer the best return for the next phases: + +1. `open-sse/handlers` + - `chatCore.ts` at 7.57% + - Overall directory at 29.07% +2. `open-sse/translator/request` + - Overall directory at 36.39% + - Many translators are still near single-digit coverage +3. `open-sse/translator/response` + - Overall directory at 8.07% +4. `open-sse/executors` + - Overall directory at 36.62% +5. `src/lib/db` + - `models.ts` at 20.66% + - `registeredKeys.ts` at 34.46% + - `modelComboMappings.ts` at 36.25% + - `settings.ts` at 46.40% + - `webhooks.ts` at 33.33% +6. `src/lib/usage` + - `usageHistory.ts` at 21.12% + - `usageStats.ts` at 9.56% + - `costCalculator.ts` at 30.00% +7. `src/lib/providers` + - `validation.ts` at 41.16% +8. Low-risk utility and API files for early gains + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/api/errorResponse.ts` + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +## Execution checklist + +### Phase 1: 56.95% -> 60% + +- [x] Fix coverage metric so it reflects source code instead of test files +- [x] Keep a legacy coverage script for comparison +- [x] Record the baseline and hotspots in-repo +- [ ] Add focused tests for low-risk utilities: + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/fetchTimeout.ts` + - `src/lib/api/errorResponse.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/display/names.ts` +- [ ] Add route tests for: + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +### Phase 2: 60% -> 65% + +- [ ] Add DB-backed tests for: + - `src/lib/db/modelComboMappings.ts` + - `src/lib/db/settings.ts` + - `src/lib/db/registeredKeys.ts` +- [ ] Cover branch behavior in: + - `src/lib/providers/validation.ts` + - `src/app/api/v1/embeddings/route.ts` + - `src/app/api/v1/moderations/route.ts` + +### Phase 3: 65% -> 70% + +- [ ] Add usage analytics tests for: + - `src/lib/usage/usageHistory.ts` + - `src/lib/usage/usageStats.ts` + - `src/lib/usage/costCalculator.ts` +- [ ] Expand route coverage for proxy management and settings branches + +### Phase 4: 70% -> 75% + +- [ ] Cover translator helpers and central translation paths: + - `open-sse/translator/index.ts` + - `open-sse/translator/helpers/*` + - `open-sse/translator/request/*` + - `open-sse/translator/response/*` + +### Phase 5: 75% -> 80% + +- [ ] Add handler-level tests for: + - `open-sse/handlers/chatCore.ts` + - `open-sse/handlers/responsesHandler.js` + - `open-sse/handlers/imageGeneration.js` + - `open-sse/handlers/embeddings.js` +- [ ] Add executor branch coverage for provider-specific auth, retries, and endpoint overrides + +### Phase 6: 80% -> 85% + +- [ ] Merge more edge-case suites into the main coverage path +- [ ] Increase function coverage for DB modules with weak constructor/helper coverage +- [ ] Close branch gaps in `settings.ts`, `registeredKeys.ts`, `validation.ts`, and translator helpers + +### Phase 7: 85% -> 90% + +- [ ] Treat the remaining low-coverage files as blockers +- [ ] Add regression tests for every uncovered production bug fixed during the push to 90% +- [ ] Raise the coverage gate in CI only after the local baseline is stable for at least two consecutive runs + +## Ratchet policy + +Update `npm run test:coverage` thresholds only after the project actually exceeds the next milestone with a comfortable buffer. + +Recommended ratchet sequence: + +1. 55/60/55 +2. 60/62/58 +3. 65/64/62 +4. 70/66/66 +5. 75/70/72 +6. 80/75/78 +7. 85/80/84 +8. 90/85/88 + +Order is `statements-lines / branches / functions`. + +## Known gap + +The current coverage command measures the main Node unit suite and includes source reached from it, including `open-sse`. It does not yet merge Vitest coverage into a single unified report. That merge is worth doing later, but it is not a blocker for starting the 60% -> 80% climb. diff --git a/docs/i18n/ko/docs/FEATURES.md b/docs/i18n/ko/docs/FEATURES.md index 4d38b2d602..7827fedcd7 100644 --- a/docs/i18n/ko/docs/FEATURES.md +++ b/docs/i18n/ko/docs/FEATURES.md @@ -1,6 +1,6 @@ # OmniRoute โ€” Dashboard Features Gallery (ํ•œ๊ตญ์–ด) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/FEATURES.md) --- @@ -10,7 +10,7 @@ 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). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. ![Providers Dashboard](screenshots/01-providers.png) diff --git a/docs/i18n/bg/MCP-SERVER.md b/docs/i18n/ko/docs/MCP-SERVER.md similarity index 65% rename from docs/i18n/bg/MCP-SERVER.md rename to docs/i18n/ko/docs/MCP-SERVER.md index 829acd30b1..6422214e8b 100644 --- a/docs/i18n/bg/MCP-SERVER.md +++ b/docs/i18n/ko/docs/MCP-SERVER.md @@ -1,12 +1,12 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/MCP-SERVER.md) +# OmniRoute MCP Server Documentation (ํ•œ๊ตญ์–ด) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/MCP-SERVER.md) --- -# OmniRoute MCP Server Documentation - > Model Context Protocol server with 16 intelligent tools -## Installation +## ์„ค์น˜ OmniRoute MCP is built-in. Start it with: @@ -42,16 +42,16 @@ See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, ## Advanced Tools (8) -| Tool | Description | -| :--------------------------------- | :---------------------------------------------- | -| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | -| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | -| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | -| `omniroute_test_combo` | Live-test all models in a combo | -| `omniroute_get_provider_metrics` | Detailed metrics for one provider | -| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | -| `omniroute_explain_route` | Explain a past routing decision | -| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | +| Tool | Description | +| :--------------------------------- | :---------------------------------------------------------- | +| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | +| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | +| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | +| `omniroute_test_combo` | Live-test all models in a combo via a real upstream request | +| `omniroute_get_provider_metrics` | Detailed metrics for one provider | +| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | +| `omniroute_explain_route` | Explain a past routing decision | +| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | ## Authentication diff --git a/docs/i18n/ko/docs/RELEASE_CHECKLIST.md b/docs/i18n/ko/docs/RELEASE_CHECKLIST.md new file mode 100644 index 0000000000..883e92bada --- /dev/null +++ b/docs/i18n/ko/docs/RELEASE_CHECKLIST.md @@ -0,0 +1,37 @@ +# Release Checklist (ํ•œ๊ตญ์–ด) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/RELEASE_CHECKLIST.md) + +--- + +Use this checklist before tagging or publishing a new OmniRoute release. + +## Version and Changelog + +1. Bump `package.json` version (`x.y.z`) in the release branch. +2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: + - `## [x.y.z] โ€” YYYY-MM-DD` +3. Keep `## [Unreleased]` as the first changelog section for upcoming work. +4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. + +## API Docs + +1. Update `docs/openapi.yaml`: + - `info.version` must equal `package.json` version. +2. Validate endpoint examples if API contracts changed. + +## Runtime Docs + +1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. +2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. +3. Update localized docs if source docs changed significantly. + +## Automated Check + +Run the sync guard locally before opening PR: + +```bash +npm run check:docs-sync +``` + +CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/ko/docs/TROUBLESHOOTING.md b/docs/i18n/ko/docs/TROUBLESHOOTING.md new file mode 100644 index 0000000000..a3bfc907a9 --- /dev/null +++ b/docs/i18n/ko/docs/TROUBLESHOOTING.md @@ -0,0 +1,256 @@ +# Troubleshooting (ํ•œ๊ตญ์–ด) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/TROUBLESHOOTING.md) + +--- + +Common problems and solutions for OmniRoute. + +--- + +## Quick Fixes + +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | + +--- + +## Provider Issues + +### "Language model did not provide messages" + +**Cause:** Provider quota exhausted. + +**Fix:** + +1. 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, Qoder) 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}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) + +--- + +## Circuit Breaker Issues + +### Provider stuck in OPEN state + +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. + +**Fix:** + +1. 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 +- **SDK returns raw string instead of object** โ€” Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** โ€” Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** โ€” Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** โ€” Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` + +--- + +## Resilience Settings + +### Auto rate-limit not triggering + +- 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. + +--- + +## Optional RAG / LLM failure taxonomy (16 problems) + +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` โ€ฆ `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard โ†’ Health** for real-time system status +- **Translator**: Use **Dashboard โ†’ Translator** to debug format issues diff --git a/docs/i18n/ko/USER_GUIDE.md b/docs/i18n/ko/docs/USER_GUIDE.md similarity index 82% rename from docs/i18n/ko/USER_GUIDE.md rename to docs/i18n/ko/docs/USER_GUIDE.md index e0bf1d5651..33e525b16d 100644 --- a/docs/i18n/ko/USER_GUIDE.md +++ b/docs/i18n/ko/docs/USER_GUIDE.md @@ -1,8 +1,6 @@ # User Guide (ํ•œ๊ตญ์–ด) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/USER_GUIDE.md) - -> ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/USER_GUIDE.md) --- @@ -320,7 +318,7 @@ Model: cc/claude-opus-4-6 --- -## ๐Ÿš€ Deployment +## ๋ฐฐํฌ ### Global npm install (Recommended) @@ -511,23 +509,26 @@ post_install() { ### Environment Variables -| Variable | Default | Description | -| ------------------------- | ------------------------------------ | ------------------------------------------------------- | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | -| `INITIAL_PASSWORD` | `123456` | First login password | -| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | -| `PORT` | framework default | Service port (`20128` in examples) | -| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | -| `NODE_ENV` | runtime default | Set `production` for deploy | -| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | -| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | -| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | -| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | -| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | -| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | -| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | -| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | +| 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/*` | +| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand | +| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | For the full environment variable reference, see the [README](../README.md). @@ -598,6 +599,11 @@ curl -X POST http://localhost:20128/api/provider-models \ Or use Dashboard: **Providers โ†’ [Provider] โ†’ Custom Models**. +Notes: + +- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers. +- The **Custom Models** section is intended for providers that do not expose managed available-model imports. + ### Dedicated Provider Routes Route requests directly to a specific provider with model validation: @@ -642,6 +648,14 @@ Returns models grouped by provider with types (`chat`, `embedding`, `image`). - Automatic background sync with timeout + fail-fast - Prefer server-side `BASE_URL`/`CLOUD_URL` in production +### Cloudflare Quick Tunnel + +- Available in **Dashboard โ†’ Endpoints** for Docker and other self-hosted deployments +- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint +- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary +- Tunnel URLs are ephemeral and change every time you stop/start the tunnel +- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download + ### LLM Gateway Intelligence (Phase 9) - **Semantic Cache** โ€” Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) @@ -757,11 +771,11 @@ OmniRoute implements provider-level resilience with four components: 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 | +| 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 unless `DISABLE_SQLITE_AUTO_BACKUP=true` | ```bash # API: Export database @@ -787,10 +801,11 @@ curl -X POST http://localhost:20128/api/db-backups/import \ ### Settings Dashboard -The settings page is organized into 5 tabs for easy navigation: +The settings page is organized into 6 tabs for easy navigation: | Tab | Contents | | -------------- | ---------------------------------------------------------------------------------------------- | +| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility | | **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | | **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | | **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | diff --git a/docs/i18n/ko/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/ko/docs/VM_DEPLOYMENT_GUIDE.md new file mode 100644 index 0000000000..76b400c3b6 --- /dev/null +++ b/docs/i18n/ko/docs/VM_DEPLOYMENT_GUIDE.md @@ -0,0 +1,403 @@ +# OmniRoute โ€” Deployment Guide on VM with Cloudflare (ํ•œ๊ตญ์–ด) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/VM_DEPLOYMENT_GUIDE.md) + +--- + +Complete guide to install and configure OmniRoute on a VM (VPS) with domain managed via Cloudflare. + +--- + +## Prerequisites + +| Item | Minimum | Recommended | +| ---------- | ------------------------ | ---------------- | +| **CPU** | 1 vCPU | 2 vCPU | +| **RAM** | 1 GB | 2 GB | +| **Disk** | 10 GB SSD | 25 GB SSD | +| **OS** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS | +| **Domain** | Registered on Cloudflare | โ€” | +| **Docker** | Docker Engine 24+ | Docker 27+ | + +**Tested providers**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. + +--- + +## 1. Configure the VM + +### 1.1 Create the instance + +On your preferred VPS provider: + +- Choose Ubuntu 24.04 LTS +- Select the minimum plan (1 vCPU / 1 GB RAM) +- Set a strong root password or configure SSH key +- Note the **public IP** (e.g., `203.0.113.10`) + +### 1.2 Connect via SSH + +```bash +ssh root@203.0.113.10 +``` + +### 1.3 Update the system + +```bash +apt update && apt upgrade -y +``` + +### 1.4 Install Docker + +```bash +# Install dependencies +apt install -y ca-certificates curl gnupg + +# Add official Docker repository +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 Install nginx + +```bash +apt install -y nginx +``` + +### 1.6 Configure 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 +``` + +> **Tip**: For maximum security, restrict ports 80 and 443 to Cloudflare IPs only. See the [Advanced Security](#advanced-security) section. + +--- + +## 2. Install OmniRoute + +### 2.1 Create configuration directory + +```bash +mkdir -p /opt/omniroute +``` + +### 2.2 Create environment variables file + +```bash +cat > /opt/omniroute/.env << โ€˜EOFโ€™ +# === Security === +JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY +INITIAL_PASSWORD=YourSecurePassword123! +API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY +STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY +STORAGE_ENCRYPTION_KEY_VERSION=v1 +MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT + +# === 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 (change to your domain) === +BASE_URL=https://llms.seudominio.com +NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com + +# === Cloud Sync (optional) === +# CLOUD_URL=https://cloud.omniroute.online +# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online +EOF +``` + +> โš ๏ธ **IMPORTANT**: Generate unique secret keys! Use `openssl rand -hex 32` for each key. + +### 2.3 Start the 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 Verify that it is running + +```bash +docker ps | grep omniroute +docker logs omniroute --tail 20 +``` + +It should display: `[DB] SQLite database ready` and `listening on port 20128`. + +--- + +## 3. Configure nginx (Reverse Proxy) + +### 3.1 Generate SSL certificate (Cloudflare Origin) + +In the Cloudflare dashboard: + +1. Go to **SSL/TLS โ†’ Origin Server** +2. Click **Create Certificate** +3. Keep the defaults (15 years, \*.yourdomain.com) +4. Copy the **Origin Certificate** and the **Private Key** + +```bash +mkdir -p /etc/nginx/ssl + +# Paste the certificate +nano /etc/nginx/ssl/origin.crt + +# Paste the private key +nano /etc/nginx/ssl/origin.key + +chmod 600 /etc/nginx/ssl/origin.key +``` + +### 3.2 Nginx Configuration + +```bash +cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ +# Default server โ€” blocks direct access via 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.yourdomain.com; # Change to your domain + + 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.yourdomain.com; + return 301 https://$server_name$request_uri; +} +NGINX +``` + +### 3.3 Enable and Test + +```bash +# Remove default configuration +rm -f /etc/nginx/sites-enabled/default + +# Enable OmniRoute +ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute + +# Test and reload +nginx -t && systemctl reload nginx +``` + +--- + +## 4. Configure Cloudflare DNS + +### 4.1 Add DNS record + +In the Cloudflare dashboard โ†’ DNS: + +| Type | Name | Content | Proxy | +| ---- | ------ | ---------------------- | ---------- | +| A | `llms` | `203.0.113.10` (VM IP) | โœ… Proxied | + +### 4.2 Configure SSL + +Under **SSL/TLS โ†’ Overview**: + +- Mode: **Full (Strict)** + +Under **SSL/TLS โ†’ Edge Certificates**: + +- Always Use HTTPS: โœ… On +- Minimum TLS Version: TLS 1.2 +- Automatic HTTPS Rewrites: โœ… On + +### 4.3 Testing + +```bash +curl -sI https://llms.seudominio.com/health +# Should return HTTP/2 200 +``` + +--- + +## 5. Operations and Maintenance + +### Upgrade to a new version + +```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 +``` + +### View logs + +```bash +docker logs -f omniroute # Real-time stream +docker logs omniroute --tail 50 # Last 50 lines +``` + +### Manual database backup + +```bash +# Copy data from the volume to the host +docker cp omniroute:/app/data ./backup-$(date +%F) + +# Or compress the entire volume +docker run --rm -v omniroute-data:/data -v $(pwd):/backup \ + alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data +``` + +### Restore from 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. Advanced Security + +### Restrict nginx to Cloudflare IPs + +```bash +cat > /etc/nginx/cloudflare-ips.conf << โ€˜CFโ€™ +# Cloudflare IPv4 ranges โ€” update periodically +# 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 +``` + +Add the following to `nginx.conf` inside the `http {}` block: + +```nginx +include /etc/nginx/cloudflare-ips.conf; +``` + +### Install fail2ban + +```bash +apt install -y fail2ban +systemctl enable fail2ban +systemctl start fail2ban + +# Check status +fail2ban-client status sshd +``` + +### Block direct access to the Docker port + +```bash +# Prevent direct external access to port 20128 +iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP +iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT + +# Persist the rules +apt install -y iptables-persistent +netfilter-persistent save +``` + +--- + +## 7. Deploy to Cloudflare Workers (Optional) + +For remote access via Cloudflare Workers (without exposing the VM directly): + +```bash +# In the local repository +cd omnirouteCloud +npm install +npx wrangler login +npx wrangler deploy +``` + +See the full documentation at [omnirouteCloud/README.md](../omnirouteCloud/README.md). + +--- + +## Port Summary + +| Port | Service | Access | +| ----- | ----------- | -------------------------- | +| 22 | SSH | Public (with fail2ban) | +| 80 | nginx HTTP | Redirect โ†’ HTTPS | +| 443 | nginx HTTPS | Via Cloudflare Proxy | +| 20128 | OmniRoute | Localhost only (via nginx) | diff --git a/docs/i18n/ko/src/lib/a2a/README.md b/docs/i18n/ko/src/lib/a2a/README.md new file mode 100644 index 0000000000..b487966f0a --- /dev/null +++ b/docs/i18n/ko/src/lib/a2a/README.md @@ -0,0 +1,752 @@ +# OmniRoute A2A Server (ํ•œ๊ตญ์–ด) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../../../src/lib/a2a/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../../../es/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../../../fr/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../../../de/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../../../it/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../../../ru/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../../../zh-CN/src/lib/a2a/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../../../ja/src/lib/a2a/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../../../ko/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../../../ar/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../../../in/src/lib/a2a/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../../../th/src/lib/a2a/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../../../vi/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../../../id/src/lib/a2a/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../../../ms/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../../../nl/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../../../pl/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../../../sv/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../../../no/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../../../da/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../../../fi/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../../../pt/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../../../ro/src/lib/a2a/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../../../hu/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../../../bg/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../../../sk/src/lib/a2a/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../../../uk-UA/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../../../he/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../../../phi/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../../../pt-BR/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../../../cs/src/lib/a2a/README.md) + +--- + +> **Agent-to-Agent Protocol v0.3** โ€” Enables any AI agent to use OmniRoute as an intelligent routing agent via JSON-RPC 2.0. + +The A2A Server exposes OmniRoute as a **first-class agent** that other agents can discover, delegate tasks to, and collaborate with using the [A2A Protocol](https://google.github.io/A2A/). + +--- + +## ์•„ํ‚คํ…์ฒ˜ + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Orchestrator Agent โ”‚ +โ”‚ (LangChain, CrewAI, AutoGen, Custom Agent) โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ 1. GET /.well-known/agent.json (discover) + โ”‚ 2. POST /a2a (JSON-RPC 2.0) + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ OmniRoute A2A Server โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Task Manager โ”‚ โ”‚ Skill Engine โ”‚ โ”‚ SSE Streaming โ”‚ โ”‚ +โ”‚ โ”‚ (lifecycle) โ”‚โ”€โ”€โ”‚ (registry) โ”‚โ”€โ”€โ”‚ (real-time) โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ +โ”‚ Skills: โ”‚ โ”‚ +โ”‚ โ”œโ”€ smart-routing โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ””โ”€ quota-management โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ Routing Decision Logger โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ OmniRoute Gateway (internal) + /v1/chat/completions, /api/combos, /api/usage/quota +``` + +--- + +## ๋น ๋ฅธ ์‹œ์ž‘ + +### Agent Discovery + +Every A2A-compatible agent exposes an **Agent Card** at `/.well-known/agent.json`: + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +**Response:** + +```json +{ + "name": "OmniRoute", + "description": "Intelligent AI gateway with auto-routing across 50+ providers", + "url": "http://localhost:20128/a2a", + "version": "1.8.1", + "capabilities": { + "streaming": true, + "pushNotifications": false + }, + "skills": [ + { + "id": "smart-routing", + "name": "Smart Routing", + "description": "Routes prompts through OmniRoute intelligent pipeline", + "tags": ["routing", "llm", "multi-provider", "cost-optimization"], + "examples": [ + "Write a hello world in Python", + "Explain quantum computing using the cheapest provider" + ] + }, + { + "id": "quota-management", + "name": "Quota Management", + "description": "Natural-language queries about provider quotas", + "tags": ["quota", "analytics", "cost"], + "examples": [ + "Which provider has the most quota remaining?", + "Suggest a free combo for coding" + ] + } + ], + "authentication": { + "schemes": ["bearer"], + "apiKeyHeader": "Authorization" + } +} +``` + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Send a message to a skill and receive the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python hello world"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "a1b2c3d4-...", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "print('Hello, World!')" }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.0030)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "2026-03-04T..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"Quantum computing..."}}} + +: heartbeat 2026-03-04T21:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Running Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Skills Reference + +### `smart-routing` + +Routes prompts through OmniRoute's intelligent pipeline with full observability. + +**Parameters (in `metadata`):** + +| Parameter | Type | Default | Description | +| --------- | -------- | ------------ | ---------------------------------------------------------------------------------------- | +| `model` | `string` | `"auto"` | Target model (e.g., `claude-sonnet-4`, `gpt-4o`, `auto`) | +| `combo` | `string` | active combo | Specific combo to route through | +| `budget` | `number` | none | Maximum cost in USD for this request | +| `role` | `string` | none | Task role hint: `coding`, `review`, `planning`, `analysis`, `debugging`, `documentation` | + +**Returns:** + +| Field | Description | +| ------------------------------ | --------------------------------------------------------- | +| `artifacts[].content` | The LLM response text | +| `metadata.routing_explanation` | Human-readable explanation of routing decision | +| `metadata.cost_envelope` | Estimated vs actual cost with currency | +| `metadata.resilience_trace` | Array of events (primary_selected, fallback_needed, etc.) | +| `metadata.policy_verdict` | Whether the request was allowed and why | + +### `quota-management` + +Answers natural-language queries about provider quotas. + +**Query types (inferred from message content):** + +| Query Pattern | Response Type | +| ---------------------------------------------- | -------------------------------------------------------- | +| Contains `"ranking"`, `"most quota"`, `"best"` | Providers ranked by remaining quota | +| Contains `"free"`, `"suggest"` | Lists free combos or suggests free-tier providers | +| Default | Full quota summary with warnings for low-quota providers | + +--- + +## Task Lifecycle + +``` +submitted โ”€โ”€โ†’ working โ”€โ”€โ†’ completed + โ”€โ”€โ†’ failed + โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ†’ cancelled +``` + +| State | Description | +| ----------- | ----------------------------------------------------- | +| `submitted` | Task created, queued for execution | +| `working` | Skill handler is executing | +| `completed` | Execution succeeded, artifacts available | +| `failed` | Execution failed or task expired (TTL: 5 min default) | +| `cancelled` | Cancelled by client via `tasks/cancel` | + +- Terminal states: `completed`, `failed`, `cancelled` (no further transitions) +- Expired tasks in `submitted` or `working` are auto-marked as `failed` +- Tasks are garbage-collected after 2ร— TTL + +--- + +## Client Examples + +### Python โ€” Orchestrator Agent + +```python +""" +A2A Client โ€” Python example. +Discovers OmniRoute agent, sends a task, and processes the result. +""" +import requests +import json + +BASE_URL = "http://localhost:20128" +API_KEY = "your-api-key" +HEADERS = { + "Content-Type": "application/json", + "Authorization": f"Bearer {API_KEY}", +} + +# 1. Discover agent capabilities +agent_card = requests.get(f"{BASE_URL}/.well-known/agent.json").json() +print(f"Agent: {agent_card['name']} v{agent_card['version']}") +print(f"Skills: {[s['id'] for s in agent_card['skills']]}") + +# 2. Send a smart-routing task +response = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python quicksort implementation"}], + "metadata": { + "model": "auto", + "combo": "fast-coding", + "budget": 0.10, + } + } +}) +result = response.json()["result"] +print(f"\n๐Ÿ“ Response: {result['artifacts'][0]['content'][:200]}...") +print(f"๐Ÿ”€ Routing: {result['metadata']['routing_explanation']}") +print(f"๐Ÿ’ฐ Cost: ${result['metadata']['cost_envelope']['actual']}") +print(f"๐Ÿ›ก๏ธ Policy: {result['metadata']['policy_verdict']['reason']}") + +# 3. Query quota status +quota_resp = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-2", + "method": "message/send", + "params": { + "skill": "quota-management", + "messages": [{"role": "user", "content": "Which provider has the most quota remaining?"}], + } +}) +quota_result = quota_resp.json()["result"] +print(f"\n๐Ÿ“Š Quota: {quota_result['artifacts'][0]['content']}") +``` + +### TypeScript โ€” Multi-Agent Orchestrator + +```typescript +/** + * A2A Client โ€” TypeScript example. + * Shows agent discovery, task delegation, and streaming. + */ + +const BASE_URL = "http://localhost:20128"; +const API_KEY = "your-api-key"; + +interface JsonRpcResponse { + jsonrpc: "2.0"; + id: string | number; + result?: T; + error?: { code: number; message: string }; +} + +async function a2aCall(method: string, params: Record): Promise { + const resp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: `${method}-${Date.now()}`, + method, + params, + }), + }); + const json: JsonRpcResponse = await resp.json(); + if (json.error) throw new Error(`[${json.error.code}] ${json.error.message}`); + return json.result!; +} + +// โ”€โ”€ Agent Discovery โ”€โ”€ +const agentCard = await fetch(`${BASE_URL}/.well-known/agent.json`).then((r) => r.json()); +console.log(`Connected to: ${agentCard.name} (${agentCard.skills.length} skills)`); + +// โ”€โ”€ Smart Routing: Send a coding task โ”€โ”€ +const routingResult = await a2aCall("message/send", { + skill: "smart-routing", + messages: [{ role: "user", content: "Implement a Redis cache wrapper in TypeScript" }], + metadata: { model: "claude-sonnet-4", role: "coding" }, +}); +console.log("Response:", routingResult.artifacts[0].content); +console.log("Provider:", routingResult.metadata.routing_explanation); + +// โ”€โ”€ Quota Management: Find free alternatives โ”€โ”€ +const quotaResult = await a2aCall("message/send", { + skill: "quota-management", + messages: [{ role: "user", content: "Suggest free combos for documentation" }], +}); +console.log("Free combos:", quotaResult.artifacts[0].content); + +// โ”€โ”€ Streaming: Real-time response โ”€โ”€ +const streamResp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "stream-1", + method: "message/stream", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Explain microservices architecture" }], + }, + }), +}); + +const reader = streamResp.body!.getReader(); +const decoder = new TextDecoder(); +while (true) { + const { done, value } = await reader.read(); + if (done) break; + const chunk = decoder.decode(value); + for (const line of chunk.split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + if (event.params.chunk) { + process.stdout.write(event.params.chunk.content); + } + if (event.params.task.state === "completed") { + console.log("\nโœ… Stream completed"); + } + } + } +} +``` + +### Python โ€” LangChain A2A Integration + +```python +""" +LangChain integration โ€” Use OmniRoute A2A as a custom LLM. +""" +from langchain.llms.base import BaseLLM +from langchain.schema import LLMResult, Generation +import requests +from typing import List, Optional + +class OmniRouteA2A(BaseLLM): + base_url: str = "http://localhost:20128" + api_key: str = "" + model: str = "auto" + combo: Optional[str] = None + + @property + def _llm_type(self) -> str: + return "omniroute-a2a" + + def _call(self, prompt: str, stop: Optional[List[str]] = None, **kwargs) -> str: + response = requests.post( + f"{self.base_url}/a2a", + headers={ + "Content-Type": "application/json", + "Authorization": f"Bearer {self.api_key}", + }, + json={ + "jsonrpc": "2.0", + "id": "langchain-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": prompt}], + "metadata": { + "model": self.model, + **({"combo": self.combo} if self.combo else {}), + }, + }, + }, + ) + result = response.json()["result"] + return result["artifacts"][0]["content"] + + def _generate(self, prompts: List[str], stop=None, **kwargs) -> LLMResult: + return LLMResult( + generations=[[Generation(text=self._call(p, stop))] for p in prompts] + ) + +# Usage +llm = OmniRouteA2A( + base_url="http://localhost:20128", + api_key="your-key", + model="auto", + combo="fast-coding", +) +result = llm("Write a Python function to merge two sorted lists") +print(result) +``` + +### Go โ€” A2A Client + +```go +package main + +import ( + "bytes" + "encoding/json" + "fmt" + "io" + "net/http" +) + +const baseURL = "http://localhost:20128" +const apiKey = "your-api-key" + +type JsonRpcRequest struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Method string `json:"method"` + Params interface{} `json:"params"` +} + +type JsonRpcResponse struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Result interface{} `json:"result"` + Error *struct { + Code int `json:"code"` + Message string `json:"message"` + } `json:"error"` +} + +func a2aCall(method string, params interface{}) (*JsonRpcResponse, error) { + body, _ := json.Marshal(JsonRpcRequest{ + Jsonrpc: "2.0", + ID: "go-1", + Method: method, + Params: params, + }) + + req, _ := http.NewRequest("POST", baseURL+"/a2a", bytes.NewReader(body)) + req.Header.Set("Content-Type", "application/json") + req.Header.Set("Authorization", "Bearer "+apiKey) + + resp, err := http.DefaultClient.Do(req) + if err != nil { + return nil, err + } + defer resp.Body.Close() + data, _ := io.ReadAll(resp.Body) + + var result JsonRpcResponse + json.Unmarshal(data, &result) + return &result, nil +} + +func main() { + // Discover agent + resp, _ := http.Get(baseURL + "/.well-known/agent.json") + defer resp.Body.Close() + body, _ := io.ReadAll(resp.Body) + fmt.Println("Agent Card:", string(body)) + + // Send smart-routing task + result, _ := a2aCall("message/send", map[string]interface{}{ + "skill": "smart-routing", + "messages": []map[string]string{{"role": "user", "content": "Hello from Go!"}}, + "metadata": map[string]interface{}{"model": "auto"}, + }) + out, _ := json.MarshalIndent(result.Result, "", " ") + fmt.Println("Result:", string(out)) +} +``` + +--- + +## Use Cases + +### ๐Ÿค– Use Case 1: Multi-Agent Coding Pipeline + +An orchestrator agent delegates code generation to OmniRoute, then passes the output to a review agent. + +```python +def coding_pipeline(task: str): + # Step 1: Generate code via OmniRoute A2A + code_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Write production-quality code: {task}"} + ], metadata={"model": "auto", "role": "coding"}) + code = code_result["artifacts"][0]["content"] + + # Step 2: Review the code via OmniRoute A2A (different model) + review_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Review this code for bugs and improvements:\n\n{code}"} + ], metadata={"model": "auto", "role": "review"}) + review = review_result["artifacts"][0]["content"] + + # Step 3: Check costs + print(f"Code cost: ${code_result['metadata']['cost_envelope']['actual']}") + print(f"Review cost: ${review_result['metadata']['cost_envelope']['actual']}") + + return {"code": code, "review": review} +``` + +### ๐Ÿ’ก Use Case 2: Quota-Aware Agent Swarm + +Multiple agents share quota through OmniRoute, using the quota skill to coordinate. + +```python +async def quota_aware_agent(agent_name: str, task: str): + # Check quota before starting + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Which provider has the most quota remaining?"} + ]) + print(f"[{agent_name}] {quota['artifacts'][0]['content']}") + + # Send request with budget constraint + result = a2a_send("smart-routing", [ + {"role": "user", "content": task} + ], metadata={"budget": 0.05}) + + policy = result["metadata"]["policy_verdict"] + if not policy["allowed"]: + print(f"[{agent_name}] โš ๏ธ Budget exceeded: {policy['reason']}") + # Fall back to free combo + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Suggest free combos"} + ]) + print(f"[{agent_name}] Free alternatives: {quota['artifacts'][0]['content']}") + + return result +``` + +### ๐Ÿ“Š Use Case 3: Real-Time Streaming Dashboard + +A monitoring agent streams responses and displays progress in real-time. + +```typescript +async function streamingDashboard(prompt: string) { + const response = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { "Content-Type": "application/json", Authorization: `Bearer ${API_KEY}` }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "dash-1", + method: "message/stream", + params: { skill: "smart-routing", messages: [{ role: "user", content: prompt }] }, + }), + }); + + let totalChunks = 0; + const reader = response.body!.getReader(); + const decoder = new TextDecoder(); + + while (true) { + const { done, value } = await reader.read(); + if (done) break; + + for (const line of decoder.decode(value).split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + const state = event.params.task.state; + + if (state === "working" && event.params.chunk) { + totalChunks++; + process.stdout.write( + `\r[Chunk ${totalChunks}] ${event.params.chunk.content.slice(0, 50)}...` + ); + } + if (state === "completed") { + const meta = event.params.metadata; + console.log( + `\nโœ… Done | Cost: $${meta?.cost_envelope?.actual || 0} | Route: ${meta?.routing_explanation || "N/A"}` + ); + } + if (state === "failed") { + console.error(`\nโŒ Failed: ${event.params.metadata?.error}`); + } + } + } + } +} +``` + +### ๐Ÿ” Use Case 4: Task Polling Pattern + +For long-running tasks, poll the task status instead of waiting synchronously. + +```python +import time + +def poll_task(task_id: str, timeout: int = 60): + """Poll task status until completion or timeout.""" + start = time.time() + while time.time() - start < timeout: + result = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "poll-1", + "method": "tasks/get", + "params": {"taskId": task_id}, + }).json() + + task = result["result"]["task"] + state = task["state"] + print(f" Task {task_id[:8]}... state={state}") + + if state in ("completed", "failed", "cancelled"): + return task + time.sleep(2) + + # Timeout โ€” cancel the task + requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "cancel-1", + "method": "tasks/cancel", + "params": {"taskId": task_id}, + }) + raise TimeoutError(f"Task {task_id} timed out after {timeout}s") +``` + +--- + +## Error Codes + +| Code | Constant | Meaning | +| ------ | ------------------------ | ---------------------------------------- | +| -32700 | โ€” | Parse error (invalid JSON) | +| -32600 | `INVALID_REQUEST` | Invalid JSON-RPC request or unauthorized | +| -32601 | `METHOD_NOT_FOUND` | Unknown method or skill | +| -32602 | `INVALID_PARAMS` | Missing or invalid parameters | +| -32603 | `INTERNAL_ERROR` | Skill execution failed | +| -32001 | `TASK_NOT_FOUND` | Task ID not found | +| -32002 | `TASK_ALREADY_COMPLETED` | Cannot modify a completed task | +| -32003 | `UNAUTHORIZED` | Invalid or missing API key | +| -32004 | `BUDGET_EXCEEDED` | Request exceeds configured budget | +| -32005 | `PROVIDER_UNAVAILABLE` | No available providers | + +--- + +## Authentication + +All `/a2a` requests require a Bearer token via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server (`OMNIROUTE_API_KEY` is empty), authentication is bypassed. + +--- + +## File Structure + +``` +src/lib/a2a/ +โ”œโ”€โ”€ taskManager.ts # Task lifecycle (create/update/cancel/list), TTL, cleanup +โ”œโ”€โ”€ taskExecution.ts # Generic task executor with state management +โ”œโ”€โ”€ streaming.ts # SSE stream formatting, heartbeat, chunk/completion events +โ”œโ”€โ”€ routingLogger.ts # Routing decision logger (stats, history, retention) +โ””โ”€โ”€ skills/ + โ”œโ”€โ”€ smartRouting.ts # Smart routing skill (routes via /v1/chat/completions) + โ””โ”€โ”€ quotaManagement.ts # Quota management skill (natural-language quota queries) + +src/app/a2a/ +โ””โ”€โ”€ route.ts # Next.js API route handler (JSON-RPC 2.0 dispatch) + +open-sse/mcp-server/ +โ””โ”€โ”€ schemas/a2a.ts # Zod schemas (AgentCard, Task, JSON-RPC, SSE events) +``` + +--- + +## Comparison: MCP vs A2A + +| Feature | MCP Server | A2A Server | +| ----------------- | ---------------------------- | ------------------------------------------------- | +| **Protocol** | Model Context Protocol | Agent-to-Agent Protocol v0.3 | +| **Transport** | stdio / HTTP | HTTP (JSON-RPC 2.0) | +| **Discovery** | Tool listing via MCP | `/.well-known/agent.json` | +| **Granularity** | 16 individual tools | 2 high-level skills | +| **Best for** | IDE agents (Cursor, VS Code) | Multi-agent systems (LangChain, CrewAI) | +| **Streaming** | Not supported | SSE via `message/stream` | +| **Task tracking** | No | Full lifecycle (submitted โ†’ completed) | +| **Observability** | Audit log per tool call | Cost envelope + resilience trace + policy verdict | + +--- + +## ๋ผ์ด์„ ์Šค + +Part of [OmniRoute](https://github.com/diegosouzapw/OmniRoute) โ€” MIT License. diff --git a/docs/i18n/ms/A2A-SERVER.md b/docs/i18n/ms/A2A-SERVER.md deleted file mode 100644 index 01531ff482..0000000000 --- a/docs/i18n/ms/A2A-SERVER.md +++ /dev/null @@ -1,200 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/A2A-SERVER.md) - ---- - -# OmniRoute A2A Server Documentation - -> Agent-to-Agent Protocol v0.3 โ€” OmniRoute as an intelligent routing agent - -## Agent Discovery - -```bash -curl http://localhost:20128/.well-known/agent.json -``` - -Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements. - ---- - -## Authentication - -All `/a2a` requests require an API key via the `Authorization` header: - -``` -Authorization: Bearer YOUR_OMNIROUTE_API_KEY -``` - -If no API key is configured on the server, authentication is bypassed. - ---- - -## JSON-RPC 2.0 Methods - -### `message/send` โ€” Synchronous Execution - -Sends a message to a skill and waits for the complete response. - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{ - "jsonrpc": "2.0", - "id": "1", - "method": "message/send", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Write a hello world in Python"}], - "metadata": {"model": "auto", "combo": "fast-coding"} - } - }' -``` - -**Response:** - -```json -{ - "jsonrpc": "2.0", - "id": "1", - "result": { - "task": { "id": "uuid", "state": "completed" }, - "artifacts": [{ "type": "text", "content": "..." }], - "metadata": { - "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)", - "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, - "resilience_trace": [ - { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." } - ], - "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } - } - } -} -``` - -### `message/stream` โ€” SSE Streaming - -Same as `message/send` but returns Server-Sent Events for real-time streaming. - -```bash -curl -N -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{ - "jsonrpc": "2.0", - "id": "1", - "method": "message/stream", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Explain quantum computing"}] - } - }' -``` - -**SSE Events:** - -``` -data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}} - -: heartbeat 2026-03-03T17:00:00Z - -data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} -``` - -### `tasks/get` โ€” Query Task Status - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' -``` - -### `tasks/cancel` โ€” Cancel a Task - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' -``` - ---- - -## Available Skills - -| Skill | Description | -| :----------------- | :------------------------------------------------------------------------------------------------------------------------------ | -| `smart-routing` | Routes prompts through OmniRoute's intelligent pipeline. Returns response with routing explanation, cost, and resilience trace. | -| `quota-management` | Answers natural-language queries about provider quotas, suggests free combos, and provides quota rankings. | - ---- - -## Task Lifecycle - -``` -submitted โ†’ working โ†’ completed - โ†’ failed - โ†’ cancelled -``` - -- Tasks expire after 5 minutes (configurable) -- Terminal states: `completed`, `failed`, `cancelled` -- Event log tracks every state transition - ---- - -## Error Codes - -| Code | Meaning | -| :----- | :----------------------------- | -| -32700 | Parse error (invalid JSON) | -| -32600 | Invalid request / Unauthorized | -| -32601 | Method or skill not found | -| -32602 | Invalid params | -| -32603 | Internal error | - ---- - -## Integration Examples - -### Python (requests) - -```python -import requests - -resp = requests.post("http://localhost:20128/a2a", json={ - "jsonrpc": "2.0", "id": "1", - "method": "message/send", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Hello"}] - } -}, headers={"Authorization": "Bearer YOUR_KEY"}) - -result = resp.json()["result"] -print(result["artifacts"][0]["content"]) -print(result["metadata"]["routing_explanation"]) -``` - -### TypeScript (fetch) - -```typescript -const resp = await fetch("http://localhost:20128/a2a", { - method: "POST", - headers: { - "Content-Type": "application/json", - Authorization: "Bearer YOUR_KEY", - }, - body: JSON.stringify({ - jsonrpc: "2.0", - id: "1", - method: "message/send", - params: { - skill: "smart-routing", - messages: [{ role: "user", content: "Hello" }], - }, - }), -}); -const { result } = await resp.json(); -console.log(result.metadata.routing_explanation); -``` diff --git a/docs/i18n/ms/API_REFERENCE.md b/docs/i18n/ms/API_REFERENCE.md deleted file mode 100644 index b878605221..0000000000 --- a/docs/i18n/ms/API_REFERENCE.md +++ /dev/null @@ -1,455 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/API_REFERENCE.md) - ---- - -# API Reference - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/API_REFERENCE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/API_REFERENCE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/API_REFERENCE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/API_REFERENCE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/API_REFERENCE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/API_REFERENCE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/API_REFERENCE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/API_REFERENCE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/API_REFERENCE.md) - -Complete reference for all OmniRoute API endpoints. - ---- - -## Table of Contents - -- [Chat Completions](#chat-completions) -- [Embeddings](#embeddings) -- [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`. - -### ACP Agents - -| Endpoint | Method | Description | -| ----------------- | ------ | -------------------------------------------------------- | -| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | -| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | -| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | - -GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). - -### Resilience & Rate Limits - -| Endpoint | Method | Description | -| ----------------------- | ------- | ------------------------------- | -| `/api/resilience` | 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` diff --git a/docs/i18n/ms/ARCHITECTURE.md b/docs/i18n/ms/ARCHITECTURE.md deleted file mode 100644 index 4ea06a29f2..0000000000 --- a/docs/i18n/ms/ARCHITECTURE.md +++ /dev/null @@ -1,787 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/ARCHITECTURE.md) - ---- - -# OmniRoute Architecture - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/ARCHITECTURE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/ARCHITECTURE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/ARCHITECTURE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/ARCHITECTURE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/ARCHITECTURE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/ARCHITECTURE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/ARCHITECTURE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/ARCHITECTURE.md) - -_Last updated: 2026-03-04_ - -## 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 (`...`) for reasoning models -- Response sanitization for strict OpenAI SDK compatibility -- Role normalization (developerโ†’system, systemโ†’user) for cross-provider compatibility -- Structured output conversion (json_schema โ†’ Gemini responseSchema) -- Local persistence for providers, keys, aliases, combos, settings, pricing -- Usage/cost tracking and request logging -- Optional cloud sync for multi-device/state sync -- IP allowlist/blocklist for API access control -- Thinking budget management (passthrough/auto/custom/adaptive) -- Global system prompt injection -- Session tracking and fingerprinting -- Per-account enhanced rate limiting with provider-specific profiles -- Circuit breaker pattern for provider resilience -- Anti-thundering herd protection with mutex locking -- Signature-based request deduplication cache -- Domain layer: model availability, cost rules, fallback policy, lockout policy -- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) -- Policy engine for centralized request evaluation (lockout โ†’ budget โ†’ fallback) -- Request telemetry with p50/p95/p99 latency aggregation -- Correlation ID (X-Request-Id) for end-to-end tracing -- Compliance audit logging with opt-out per API key -- Eval framework for LLM quality assurance -- Resilience UI dashboard with real-time circuit breaker status -- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) - -Primary runtime model: - -- Next.js 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[(storage.sqlite)] - UDB[(usage tables + log artifacts)] - end - - subgraph Upstreams[Upstream Providers] - P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/Qoder/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/route.ts` (GET) -- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) -- OAuth: `src/app/api/oauth/*` -- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` -- Usage: `src/app/api/usage/*` -- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` -- CLI tooling helpers: `src/app/api/cli-tools/*` -- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) -- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) -- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) -- Sessions: `src/app/api/sessions` (GET) -- Rate limits: `src/app/api/rate-limits` (GET) -- Resilience: `src/app/api/resilience` (GET/PATCH) โ€” provider profiles, circuit breaker, rate limit state -- Resilience reset: `src/app/api/resilience/reset` (POST) โ€” reset breakers + cooldowns -- Cache stats: `src/app/api/cache/stats` (GET/DELETE) -- Model availability: `src/app/api/models/availability` (GET/POST) -- Telemetry: `src/app/api/telemetry/summary` (GET) -- Budget: `src/app/api/usage/budget` (GET/POST) -- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) -- Compliance audit: `src/app/api/compliance/audit-log` (GET) -- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) -- Policies: `src/app/api/policies` (GET/POST) - -## 2) SSE + 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` -- Response sanitization: `open-sse/handlers/responseSanitizer.ts` -- Role normalization: `open-sse/services/roleNormalizer.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`, `qoder.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 (SQLite): - -- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) -- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) -- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) -- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** - -Usage persistence: - -- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) -- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` -- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) -- legacy JSON files are migrated to SQLite by startup migrations when present - -Domain State DB (SQLite): - -- `src/lib/db/domainState.ts` โ€” CRUD operations 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: - -- primary runtime DB: `${DATA_DIR}/storage.sqlite` -- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) -- structured call payload archives: `${DATA_DIR}/call_logs/` -- optional translator/request debug sessions: `/logs/...` - -## Deployment Topology - -```mermaid -flowchart LR - 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[(storage.sqlite)] - UsageDB[(usage tables + log artifacts)] - end - - subgraph External[External Services] - Providers[AI Providers] - SyncCloud[Cloud Sync Service] - end - - CLI --> Next - Browser --> Next - Next --> Core - Next --> MainDB - Core --> MainDB - Core --> UsageDB - Core --> Providers - Next --> SyncCloud -``` - -## Module Mapping (Decision-Critical) - -### Route and API Modules - -- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs -- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) -- `src/app/api/providers*`: provider CRUD, validation, testing -- `src/app/api/provider-nodes*`: custom compatible node management -- `src/app/api/provider-models`: custom model management (CRUD) -- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) -- `src/app/api/oauth/*`: OAuth/device-code flows -- `src/app/api/keys*`: local API key lifecycle -- `src/app/api/models/alias`: alias management -- `src/app/api/combos*`: fallback combo management -- `src/app/api/pricing`: pricing overrides for cost calculation -- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) -- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) -- `src/app/api/usage/*`: usage and logs APIs -- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers -- `src/app/api/cli-tools/*`: local CLI config writers/checkers -- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) -- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) -- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) -- `src/app/api/sessions`: active session listing (GET) -- `src/app/api/rate-limits`: per-account rate limit status (GET) - -### Routing and Execution Core - -- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop -- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup -- `open-sse/executors/*`: provider-specific network and format behavior - -### Translation Registry and Format Converters - -- `open-sse/translator/index.ts`: translator registry and orchestration -- Request translators: `open-sse/translator/request/*` -- Response translators: `open-sse/translator/response/*` -- Format constants: `open-sse/translator/formats.ts` - -### Persistence - -- `src/lib/db/*`: persistent config/state and domain persistence on SQLite -- `src/lib/localDb.ts`: compatibility re-export for DB modules -- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables - -## Provider Executor Coverage (Strategy Pattern) - -Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. - -| Executor | Provider(s) | Special Handling | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | -| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, Qoder, 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 | -| Qoder | openai | OAuth (Basic) | โœ… | โœ… | โœ… | โš ๏ธ Per request | -| OpenRouter | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| GLM/Kimi/MiniMax | claude | API Key | โœ… | โœ… | โŒ | โŒ | -| DeepSeek | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Groq | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| xAI (Grok) | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Mistral | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Perplexity | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Together AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Fireworks AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Cerebras | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Cohere | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| NVIDIA NIM | openai | API Key | โœ… | โœ… | โŒ | โŒ | - -## Format Translation Coverage - -Detected source formats include: - -- `openai` -- `openai-responses` -- `claude` -- `gemini` - -Target formats include: - -- OpenAI chat/Responses -- Claude -- Gemini/Gemini-CLI/Antigravity envelope -- Kiro -- Cursor - -Translations use **OpenAI as the hub format** โ€” all conversions go through OpenAI as intermediate: - -``` -Source Format โ†’ OpenAI (hub) โ†’ Target Format -``` - -Translations are selected dynamically based on source payload shape and provider target format. - -Additional processing layers in the translation pipeline: - -- **Response sanitization** โ€” Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance -- **Role normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI targets; merges `system` โ†’ `user` for models that reject the system role (GLM, ERNIE) -- **Think tag extraction** โ€” Parses `...` blocks from content into `reasoning_content` field -- **Structured output** โ€” Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` - -## Supported API Endpoints - -| 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 `/logs//` 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 - -- SQLite schema migrations and auto-upgrade hooks at startup -- legacy JSON โ†’ SQLite migration compatibility path - -## Observability and Operational Signals - -Runtime visibility sources: - -- console logs from `src/sse/utils/logger.ts` -- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) -- textual request status log in `log.txt` (optional/compat) -- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` -- dashboard usage endpoints (`/api/usage/*`) for UI consumption - -## Security-Sensitive Boundaries - -- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing -- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning -- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format -- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level -- Cloud sync endpoints rely on API key auth + machine id semantics - -## Environment and Runtime Matrix - -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` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. -2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. -3. Request logger writes full headers/body when enabled; treat log directory as sensitive. -4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. -5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. -6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). -7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). -8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). - -## Operational Verification Checklist - -- Build from source: `npm run build` -- Build Docker image: `docker build -t omniroute .` -- Start service and verify: -- `GET /api/settings` -- `GET /api/v1/models` -- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/ms/AUTO-COMBO.md b/docs/i18n/ms/AUTO-COMBO.md deleted file mode 100644 index 2166e41dff..0000000000 --- a/docs/i18n/ms/AUTO-COMBO.md +++ /dev/null @@ -1,67 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/AUTO-COMBO.md) - ---- - -# OmniRoute Auto-Combo Engine - -> Self-managing model chains with adaptive scoring - -## How It Works - -The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**: - -| Factor | Weight | Description | -| :--------- | :----- | :---------------------------------------------- | -| Quota | 0.20 | Remaining capacity [0..1] | -| Health | 0.25 | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 | -| CostInv | 0.20 | Inverse cost (cheaper = higher score) | -| LatencyInv | 0.15 | Inverse p95 latency (faster = higher) | -| TaskFit | 0.10 | Model ร— task type fitness score | -| Stability | 0.10 | Low variance in latency/errors | - -## Mode Packs - -| Pack | Focus | Key Weight | -| :---------------------- | :----------- | :--------------- | -| ๐Ÿš€ **Ship Fast** | Speed | latencyInv: 0.35 | -| ๐Ÿ’ฐ **Cost Saver** | Economy | costInv: 0.40 | -| ๐ŸŽฏ **Quality First** | Best model | taskFit: 0.40 | -| ๐Ÿ“ก **Offline Friendly** | Availability | quota: 0.40 | - -## Self-Healing - -- **Temporary exclusion**: Score < 0.2 โ†’ excluded for 5 min (progressive backoff, max 30 min) -- **Circuit breaker awareness**: OPEN โ†’ auto-excluded; HALF_OPEN โ†’ probe requests -- **Incident mode**: >50% OPEN โ†’ disable exploration, maximize stability -- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout - -## Bandit Exploration - -5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode. - -## API - -```bash -# Create auto-combo -curl -X POST http://localhost:20128/api/combos/auto \ - -H "Content-Type: application/json" \ - -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}' - -# List auto-combos -curl http://localhost:20128/api/combos/auto -``` - -## Task Fitness - -30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` โ†’ high coding score). - -## Files - -| File | Purpose | -| :------------------------------------------- | :------------------------------------ | -| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization | -| `open-sse/services/autoCombo/taskFitness.ts` | Model ร— task fitness lookup | -| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap | -| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode | -| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles | -| `src/app/api/combos/auto/route.ts` | REST API | diff --git a/docs/i18n/ms/CHANGELOG.md b/docs/i18n/ms/CHANGELOG.md index 02c1cbe37d..292c8ca0b6 100644 --- a/docs/i18n/ms/CHANGELOG.md +++ b/docs/i18n/ms/CHANGELOG.md @@ -1,12 +1,92 @@ # Changelog (Bahasa Melayu) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CHANGELOG.md) --- - ## [Unreleased] +### ๐Ÿ› ๏ธ Maintenance + +- **AGENTS.md rewrite:** Condensed from 297โ†’153 lines. Added build/lint/test commands (including single-test execution), code style guidelines (Prettier, TypeScript, ESLint, naming, imports, error handling, security), and trimmed verbose architecture tables for AI agent consumption. + +## [3.4.2] - 2026-04-01 + +### ๐Ÿ› Bug Fixes + +- **CI Stabilization:** Fixed failing analytics/settings Playwright selectors and request assertions so GitHub Actions E2E runs pass reliably across localized UIs and switch-based controls. +- **Deterministic Tests:** Removed date-sensitive quota fixtures from Copilot usage tests and aligned idempotency/model catalog tests with the merged runtime behavior. +- **MCP Type Hardening:** Removed zero-budget explicit `any` regressions from the MCP server tool registration path, restoring the `check:any-budget:t11` workflow gate. + +### ๐Ÿ› ๏ธ Maintenance + +- **Release Branch Integration:** Consolidated the active feature branches into `release/v3.4.2` on top of current `main` and validated the branch with lint, unit, coverage, build, and CI-mode E2E runs. + +## [3.4.1] - 2026-03-31 + +> [!WARNING] +> **BREAKING CHANGE: request logging, retention, and logging environment variables have been redesigned.** +> On the first startup after upgrading, OmniRoute archives legacy request logs from `DATA_DIR/logs/`, legacy `DATA_DIR/call_logs/`, and `DATA_DIR/log.txt` into `DATA_DIR/log_archives/*.zip`, then removes the deprecated layout and switches to the new unified artifact format under `DATA_DIR/call_logs/`. + +### โœจ New Features + +- **.ENV Migration Utility:** Included `scripts/migrate-env.mjs` to seamlessly migrate ` Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` - ---- - -## Step 2 โ€” Install CLI Tools - -All npm-based tools require Node.js 18+: - -```bash -# Claude Code (Anthropic) -npm install -g @anthropic-ai/claude-code - -# OpenAI Codex -npm install -g @openai/codex - -# Gemini CLI (Google) -npm install -g @google/gemini-cli - -# OpenCode -npm install -g opencode-ai - -# Cline -npm install -g cline - -# KiloCode -npm install -g kilecode - -# Kiro CLI (Amazon โ€” requires curl + unzip) -apt-get install -y unzip # on Debian/Ubuntu -curl -fsSL https://cli.kiro.dev/install | bash -export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc -``` - -**Verify:** - -```bash -claude --version # 2.x.x -codex --version # 0.x.x -gemini --version # 0.x.x -opencode --version # x.x.x -cline --version # 2.x.x -kilocode --version # x.x.x (or: kilo --version) -kiro-cli --version # 1.x.x -``` - ---- - -## Step 3 โ€” Set Global Environment Variables - -Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`: - -```bash -# OmniRoute Universal Endpoint -export OPENAI_BASE_URL="http://localhost:20128/v1" -export OPENAI_API_KEY="sk-your-omniroute-key" -export ANTHROPIC_BASE_URL="http://localhost:20128/v1" -export ANTHROPIC_API_KEY="sk-your-omniroute-key" -export GEMINI_BASE_URL="http://localhost:20128/v1" -export GEMINI_API_KEY="sk-your-omniroute-key" -``` - -> For a **remote server** replace `localhost:20128` with the server IP or domain, -> e.g. `http://192.168.0.15:20128`. - ---- - -## Step 4 โ€” Configure Each Tool - -### Claude Code - -```bash -# Via CLI: -claude config set --global api-base-url http://localhost:20128/v1 - -# Or create ~/.claude/settings.json: -mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF -{ - "apiBaseUrl": "http://localhost:20128/v1", - "apiKey": "sk-your-omniroute-key" -} -EOF -``` - -**Test:** `claude "say hello"` - ---- - -### OpenAI Codex - -```bash -mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF -model: auto -apiKey: sk-your-omniroute-key -apiBaseUrl: http://localhost:20128/v1 -EOF -``` - -**Test:** `codex "what is 2+2?"` - ---- - -### Gemini CLI - -```bash -mkdir -p ~/.gemini && cat > ~/.gemini/settings.json << EOF -{ - "apiKey": "sk-your-omniroute-key", - "baseUrl": "http://localhost:20128/v1" -} -EOF -``` - -**Test:** `gemini "hello"` - ---- - -### OpenCode - -```bash -mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF -[provider.openai] -base_url = "http://localhost:20128/v1" -api_key = "sk-your-omniroute-key" -EOF -``` - -**Test:** `opencode` - ---- - -### Cline (CLI or VS Code) - -**CLI mode:** - -```bash -mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF -{ - "apiProvider": "openai", - "openAiBaseUrl": "http://localhost:20128/v1", - "openAiApiKey": "sk-your-omniroute-key" -} -EOF -``` - -**VS Code mode:** -Cline extension settings โ†’ API Provider: `OpenAI Compatible` โ†’ Base URL: `http://localhost:20128/v1` - -Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ Cline โ†’ Apply Config**. - ---- - -### KiloCode (CLI or VS Code) - -**CLI mode:** - -```bash -kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key -``` - -**VS Code settings:** - -```json -{ - "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", - "kilo-code.apiKey": "sk-your-omniroute-key" -} -``` - -Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ KiloCode โ†’ Apply Config**. - ---- - -### Continue (VS Code Extension) - -Edit `~/.continue/config.yaml`: - -```yaml -models: - - name: OmniRoute - provider: openai - model: auto - apiBase: http://localhost:20128/v1 - apiKey: sk-your-omniroute-key - default: true -``` - -Restart VS Code after editing. - ---- - -### Kiro CLI (Amazon) - -```bash -# Login to your AWS/Kiro account: -kiro-cli login - -# The CLI uses its own auth โ€” OmniRoute is not needed as backend for Kiro CLI itself. -# Use kiro-cli alongside OmniRoute for other tools. -kiro-cli status -``` - ---- - -### Cursor (Desktop App) - -> **Note:** Cursor routes requests through its cloud. For OmniRoute integration, -> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL. - -Via GUI: **Settings โ†’ Models โ†’ OpenAI API Key** - -- Base URL: `https://your-domain.com/v1` -- API Key: your OmniRoute key - ---- - -## Dashboard Auto-Configuration - -The OmniRoute dashboard automates configuration for most tools: - -1. Go to `http://localhost:20128/dashboard/cli-tools` -2. Expand any tool card -3. Select your API key from the dropdown -4. Click **Apply Config** (if tool is detected as installed) -5. Or copy the generated config snippet manually - ---- - -## Built-in Agents: Droid & OpenClaw - -**Droid** and **OpenClaw** are AI agents built directly into OmniRoute โ€” no installation needed. -They run as internal routes and use OmniRoute's model routing automatically. - -- Access: `http://localhost:20128/dashboard/agents` -- Configure: same combos and providers as all other tools -- No API key or CLI install required - ---- - -## Available API Endpoints - -| Endpoint | Description | Use For | -| -------------------------- | ----------------------------- | --------------------------- | -| `/v1/chat/completions` | Standard chat (all providers) | All modern tools | -| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows | -| `/v1/completions` | Legacy text completions | Older tools using `prompt:` | -| `/v1/embeddings` | Text embeddings | RAG, search | -| `/v1/images/generations` | Image generation | DALL-E, Flux, etc. | -| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS | -| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI | - ---- - -## Troubleshooting - -| Error | Cause | Fix | -| ------------------------- | ----------------------- | ------------------------------------------ | -| `Connection refused` | OmniRoute not running | `pm2 start omniroute` | -| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` | -| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` | -| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` | -| CLI shows "not installed" | Binary not in PATH | Check `which ` | -| `kiro-cli: not found` | Not in PATH | `export PATH="$HOME/.local/bin:$PATH"` | - ---- - -## Quick Setup Script (One Command) - -```bash -# Install all CLIs and configure for OmniRoute (replace with your key and server URL) -OMNIROUTE_URL="http://localhost:20128/v1" -OMNIROUTE_KEY="sk-your-omniroute-key" - -npm install -g @anthropic-ai/claude-code @openai/codex @google/gemini-cli opencode-ai cline kilecode - -# Kiro CLI -apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash - -# Write configs -mkdir -p ~/.claude ~/.codex ~/.gemini ~/.config/opencode ~/.continue - -cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" -cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" -cat > ~/.gemini/settings.json <<< "{\"apiKey\":\"$OMNIROUTE_KEY\",\"baseUrl\":\"$OMNIROUTE_URL\"}" -cat >> ~/.bashrc << EOF -export OPENAI_BASE_URL="$OMNIROUTE_URL" -export OPENAI_API_KEY="$OMNIROUTE_KEY" -export ANTHROPIC_BASE_URL="$OMNIROUTE_URL" -export ANTHROPIC_API_KEY="$OMNIROUTE_KEY" -EOF - -source ~/.bashrc -echo "โœ… All CLIs installed and configured for OmniRoute" -``` diff --git a/docs/i18n/ms/CODEBASE_DOCUMENTATION.md b/docs/i18n/ms/CODEBASE_DOCUMENTATION.md deleted file mode 100644 index e2d7950052..0000000000 --- a/docs/i18n/ms/CODEBASE_DOCUMENTATION.md +++ /dev/null @@ -1,593 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CODEBASE_DOCUMENTATION.md) - ---- - -# omniroute โ€” Codebase Documentation - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) - -> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. - ---- - -## 1. 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
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, Qoder, 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 | -| Qoder | 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"] -``` diff --git a/docs/i18n/ms/CONTRIBUTING.md b/docs/i18n/ms/CONTRIBUTING.md new file mode 100644 index 0000000000..80a5562544 --- /dev/null +++ b/docs/i18n/ms/CONTRIBUTING.md @@ -0,0 +1,299 @@ +# Contributing to OmniRoute (Bahasa Melayu) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CONTRIBUTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CONTRIBUTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CONTRIBUTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CONTRIBUTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CONTRIBUTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CONTRIBUTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CONTRIBUTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CONTRIBUTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CONTRIBUTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CONTRIBUTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CONTRIBUTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CONTRIBUTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CONTRIBUTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CONTRIBUTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CONTRIBUTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CONTRIBUTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CONTRIBUTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CONTRIBUTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CONTRIBUTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CONTRIBUTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CONTRIBUTING.md) + +--- + +Thank you for your interest in contributing! This guide covers everything you need to get started. + +--- + +## Development Setup + +### Prerequisites + +- **Node.js** >= 18 < 24 (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` | `20128` | Server port | +| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | Base URL for frontend | +| `JWT_SECRET` | (generate above) | JWT signing secret | +| `INITIAL_PASSWORD` | `CHANGEME` | First login password | +| `APP_LOG_LEVEL` | `info` | Log verbosity level | + +### Dashboard Settings + +The dashboard provides UI toggles for features that can also be configured via environment variables: + +| Setting Location | Toggle | Description | +| ------------------- | ------------------ | ------------------------------ | +| Settings โ†’ Advanced | Debug Mode | Enable debug request logs (UI) | +| Settings โ†’ General | Sidebar Visibility | Show/hide sidebar sections | + +These settings are stored in the database and persist across restarts, overriding env var defaults when set. + +### 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:20128/dashboard` +- **API**: `http://localhost:20128/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`, `mcp`, `a2a`, `memory`, `skills`. + +--- + +## Running Tests + +```bash +# All tests (unit + vitest + ecosystem + e2e) +npm run test:all + +# Single test file (Node.js native test runner โ€” most tests use this) +node --import tsx/esm --test tests/unit/your-file.test.mjs + +# Vitest (MCP server, autoCombo, cache) +npm run test:vitest + +# E2E tests (requires Playwright) +npm run test:e2e + +# Protocol clients E2E (MCP transports, A2A) +npm run test:protocols:e2e + +# Ecosystem compatibility tests +npm run test:ecosystem + +# Coverage (55% min statements/lines/functions; 60% branches) +npm run test:coverage +npm run coverage:report + +# Lint + format check +npm run lint +npm run check +``` + +Coverage notes: + +- `npm run test:coverage` measures source coverage for the main unit test suite, excludes `tests/**`, and includes `open-sse/**` +- `npm run coverage:report` prints the detailed file-by-file report from the latest coverage run +- `npm run test:coverage:legacy` preserves the older metric for historical comparison +- See `docs/COVERAGE_PLAN.md` for the phased coverage improvement roadmap + +Current test status: **122 unit test files** covering: + +- Provider translators and format conversion +- Rate limiting, circuit breaker, and resilience +- Semantic cache, idempotency, progress tracking +- Database operations and schema (21 DB modules) +- OAuth flows and authentication +- API endpoint validation (Zod v4) +- MCP server tools and scope enforcement +- Memory and Skills systems + +--- + +## Code Style + +- **ESLint** โ€” Run `npm run lint` before committing +- **Prettier** โ€” Auto-formatted via `lint-staged` on commit (2 spaces, semicolons, double quotes, 100 char width, es5 trailing commas) +- **TypeScript** โ€” All `src/` code uses `.ts`/`.tsx`; `open-sse/` uses `.ts`/`.js`; document with TSDoc (`@param`, `@returns`, `@throws`) +- **No `eval()`** โ€” ESLint enforces `no-eval`, `no-implied-eval`, `no-new-func` +- **Zod validation** โ€” Use Zod v4 schemas for all API input validation +- **Naming**: Files = camelCase/kebab-case, components = PascalCase, constants = UPPER_SNAKE + +--- + +## Project Structure + +``` +src/ # TypeScript (.ts / .tsx) +โ”œโ”€โ”€ app/ # Next.js 16 App Router +โ”‚ โ”œโ”€โ”€ (dashboard)/ # Dashboard pages (23 sections) +โ”‚ โ”œโ”€โ”€ api/ # API routes (51 directories) +โ”‚ โ””โ”€โ”€ login/ # Auth pages (.tsx) +โ”œโ”€โ”€ domain/ # Policy engine (policyEngine, comboResolver, costRules, etc.) +โ”œโ”€โ”€ lib/ # Core business logic (.ts) +โ”‚ โ”œโ”€โ”€ a2a/ # Agent-to-Agent v0.3 protocol server +โ”‚ โ”œโ”€โ”€ acp/ # Agent Communication Protocol registry +โ”‚ โ”œโ”€โ”€ compliance/ # Compliance policy engine +โ”‚ โ”œโ”€โ”€ db/ # SQLite database layer (21 modules + 16 migrations) +โ”‚ โ”œโ”€โ”€ memory/ # Persistent conversational memory +โ”‚ โ”œโ”€โ”€ oauth/ # OAuth providers, services, and utilities +โ”‚ โ”œโ”€โ”€ skills/ # Extensible skill framework +โ”‚ โ”œโ”€โ”€ usage/ # Usage tracking and cost calculation +โ”‚ โ””โ”€โ”€ localDb.ts # Re-export layer only โ€” never add logic here +โ”œโ”€โ”€ middleware/ # Request middleware (promptInjectionGuard) +โ”œโ”€โ”€ mitm/ # MITM proxy (cert, DNS, target routing) +โ”œโ”€โ”€ shared/ +โ”‚ โ”œโ”€โ”€ components/ # React components (.tsx) +โ”‚ โ”œโ”€โ”€ constants/ # Provider definitions (60+), MCP scopes, routing strategies +โ”‚ โ”œโ”€โ”€ utils/ # Circuit breaker, sanitizer, auth helpers +โ”‚ โ””โ”€โ”€ validation/ # Zod v4 schemas +โ””โ”€โ”€ sse/ # SSE proxy pipeline + +open-sse/ # @omniroute/open-sse workspace +โ”œโ”€โ”€ executors/ # 14 provider-specific request executors +โ”œโ”€โ”€ handlers/ # 11 request handlers (chat, responses, embeddings, images, etc.) +โ”œโ”€โ”€ mcp-server/ # MCP server (25 tools, 3 transports, 10 scopes) +โ”œโ”€โ”€ services/ # 36+ services (combo, autoCombo, rateLimitManager, etc.) +โ”œโ”€โ”€ translator/ # Format translators (OpenAI โ†” Claude โ†” Gemini โ†” Responses โ†” Ollama) +โ”œโ”€โ”€ transformer/ # Responses API transformer +โ””โ”€โ”€ utils/ # 22 utility modules (stream, TLS, proxy, logging) + +electron/ # Electron desktop app (cross-platform) + +tests/ +โ”œโ”€โ”€ unit/ # Node.js test runner (122 test files) +โ”œโ”€โ”€ integration/ # Integration tests +โ”œโ”€โ”€ e2e/ # Playwright tests +โ”œโ”€โ”€ security/ # Security tests +โ”œโ”€โ”€ translator/ # Translator-specific tests +โ””โ”€โ”€ load/ # Load tests + +docs/ # Documentation +โ”œโ”€โ”€ ARCHITECTURE.md # System architecture +โ”œโ”€โ”€ API_REFERENCE.md # All endpoints +โ”œโ”€โ”€ USER_GUIDE.md # Provider setup, CLI integration +โ”œโ”€โ”€ TROUBLESHOOTING.md # Common issues +โ”œโ”€โ”€ MCP-SERVER.md # MCP server (25 tools) +โ”œโ”€โ”€ A2A-SERVER.md # A2A agent protocol +โ”œโ”€โ”€ AUTO-COMBO.md # Auto-combo engine +โ”œโ”€โ”€ CLI-TOOLS.md # CLI tools integration +โ”œโ”€โ”€ COVERAGE_PLAN.md # Test coverage improvement plan +โ”œโ”€โ”€ openapi.yaml # OpenAPI specification +โ””โ”€โ”€ adr/ # Architecture Decision Records +``` + +--- + +## Adding a New Provider + +### Step 1: Register Provider Constants + +Add to `src/shared/constants/providers.ts` โ€” Zod-validated at module load. + +### Step 2: Add Executor (if custom logic needed) + +Create executor in `open-sse/executors/your-provider.ts` extending the base executor. + +### Step 3: Add Translator (if non-OpenAI format) + +Create request/response translators in `open-sse/translator/`. + +### Step 4: Add OAuth Config (if OAuth-based) + +Add OAuth credentials in `src/lib/oauth/constants/oauth.ts` and service in `src/lib/oauth/services/`. + +### Step 5: Register Models + +Add model definitions in `open-sse/config/providerRegistry.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 +- [ ] All inputs validated with Zod schemas +- [ ] CHANGELOG updated (if user-facing change) +- [ ] Documentation updated (if applicable) + +--- + +## Releasing + +Releases are managed via the `/generate-release` workflow. When a new GitHub Release is created, the package is **automatically published to npm** via GitHub Actions. + +--- + +## Getting Help + +- **Architecture**: See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) +- **API Reference**: See [`docs/API_REFERENCE.md`](docs/API_REFERENCE.md) +- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **ADRs**: See `docs/adr/` for architectural decision records diff --git a/docs/i18n/ms/FEATURES.md b/docs/i18n/ms/FEATURES.md deleted file mode 100644 index 1f9f72e562..0000000000 --- a/docs/i18n/ms/FEATURES.md +++ /dev/null @@ -1,147 +0,0 @@ -# OmniRoute โ€” Dashboard Features Gallery (Bahasa Melayu) - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) - -> ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../docs/FEATURES.md) - ---- - -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 (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. - -![Providers Dashboard](screenshots/01-providers.png) - ---- - -## ๐ŸŽจ Combos - -Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. - -![Combos Dashboard](screenshots/02-combos.png) - ---- - -## ๐Ÿ“Š Analytics - -Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. - -![Analytics Dashboard](screenshots/03-analytics.png) - ---- - -## ๐Ÿฅ System Health - -Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. - -![Health Dashboard](screenshots/04-health.png) - ---- - -## ๐Ÿ”ง Translator Playground - -Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). - -![Translator Playground](screenshots/05-translator.png) - ---- - -## ๐ŸŽฎ Model Playground _(v2.0.9+)_ - -Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. - ---- - -## ๐ŸŽจ Themes _(v2.0.5+)_ - -Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. - ---- - -## โš™๏ธ Settings - -Comprehensive settings panel with tabs: - -- **General** โ€” System storage, backup management (export/import database) -- **Appearance** โ€” Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls -- **Security** โ€” API endpoint protection, custom provider blocking, IP filtering, session info -- **Routing** โ€” Model aliases, background task degradation -- **Resilience** โ€” Rate limit persistence, circuit breaker tuning -- **Advanced** โ€” Configuration overrides - -![Settings Dashboard](screenshots/06-settings.png) - ---- - -## ๐Ÿ”ง CLI Tools - -One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. - -![CLI Tools Dashboard](screenshots/07-cli-tools.png) - ---- - -## ๐Ÿค– CLI Agents _(v2.0.11+)_ - -Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: - -- **Installation status** โ€” Installed / Not Found with version detection -- **Protocol badges** โ€” stdio, HTTP, etc. -- **Custom agents** โ€” Register any CLI tool via form (name, binary, version command, spawn args) -- **CLI Fingerprint Matching** โ€” Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP - ---- - -## ๐Ÿ–ผ๏ธ Media _(v2.0.3+)_ - -Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. - ---- - -## ๐Ÿ“ Request Logs - -Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. - -![Usage Logs](screenshots/08-usage.png) - ---- - -## ๐ŸŒ API Endpoint - -Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. - -![Endpoint Dashboard](screenshots/09-endpoint.png) - ---- - -## ๐Ÿ”‘ API Key Management - -Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. - ---- - -## ๐Ÿ“‹ Audit Log - -Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. - ---- - -## ๐Ÿ–ฅ๏ธ Desktop Application - -Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. - -Key features: - -- Server readiness polling (no blank screen on cold start) -- System tray with port management -- Content Security Policy -- Single-instance lock -- Auto-update on restart -- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) -- Hardened Electron build packaging โ€” symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+) - -๐Ÿ“– See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/ms/MCP-SERVER.md b/docs/i18n/ms/MCP-SERVER.md deleted file mode 100644 index 829acd30b1..0000000000 --- a/docs/i18n/ms/MCP-SERVER.md +++ /dev/null @@ -1,87 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/MCP-SERVER.md) - ---- - -# OmniRoute MCP Server Documentation - -> Model Context Protocol server with 16 intelligent tools - -## Installation - -OmniRoute MCP is built-in. Start it with: - -```bash -omniroute --mcp -``` - -Or via the open-sse transport: - -```bash -# HTTP streamable transport (port 20130) -omniroute --dev # MCP auto-starts on /mcp endpoint -``` - -## IDE Configuration - -See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup. - ---- - -## Essential Tools (8) - -| Tool | Description | -| :------------------------------ | :--------------------------------------- | -| `omniroute_get_health` | Gateway health, circuit breakers, uptime | -| `omniroute_list_combos` | All configured combos with models | -| `omniroute_get_combo_metrics` | Performance metrics for a specific combo | -| `omniroute_switch_combo` | Switch active combo by ID/name | -| `omniroute_check_quota` | Quota status per provider or all | -| `omniroute_route_request` | Send a chat completion through OmniRoute | -| `omniroute_cost_report` | Cost analytics for a time period | -| `omniroute_list_models_catalog` | Full model catalog with capabilities | - -## Advanced Tools (8) - -| Tool | Description | -| :--------------------------------- | :---------------------------------------------- | -| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | -| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | -| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | -| `omniroute_test_combo` | Live-test all models in a combo | -| `omniroute_get_provider_metrics` | Detailed metrics for one provider | -| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | -| `omniroute_explain_route` | Explain a past routing decision | -| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | - -## Authentication - -MCP tools are authenticated via API key scopes. Each tool requires specific scopes: - -| Scope | Tools | -| :------------- | :----------------------------------------------- | -| `read:health` | get_health, get_provider_metrics | -| `read:combos` | list_combos, get_combo_metrics | -| `write:combos` | switch_combo | -| `read:quota` | check_quota | -| `write:route` | route_request, simulate_route, test_combo | -| `read:usage` | cost_report, get_session_snapshot, explain_route | -| `write:config` | set_budget_guard, set_resilience_profile | -| `read:models` | list_models_catalog, best_combo_for_task | - -## Audit Logging - -Every tool call is logged to `mcp_tool_audit` with: - -- Tool name, arguments, result -- Duration (ms), success/failure -- API key hash, timestamp - -## Files - -| File | Purpose | -| :------------------------------------------- | :------------------------------------------ | -| `open-sse/mcp-server/server.ts` | MCP server creation + 16 tool registrations | -| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport | -| `open-sse/mcp-server/auth.ts` | API key + scope validation | -| `open-sse/mcp-server/audit.ts` | Tool call audit logging | -| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers | diff --git a/docs/i18n/ms/README.md b/docs/i18n/ms/README.md index 10febbe619..03c8f45e70 100644 --- a/docs/i18n/ms/README.md +++ b/docs/i18n/ms/README.md @@ -1,12 +1,12 @@ # ๐Ÿš€ OmniRoute โ€” The Free AI Gateway (Bahasa Melayu) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/README.md) --- ### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback. -_Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._ +_Your universal API proxy โ€” one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._ **Chat Completions โ€ข Embeddings โ€ข Image Generation โ€ข Video โ€ข Music โ€ข Audio โ€ข Reranking โ€ข **Web Search** โ€ข MCP Server โ€ข A2A Protocol โ€ข 100% TypeScript** @@ -46,15 +46,17 @@ _Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now wi > - `APP_LOG_FILE_PATH` > - `APP_LOG_MAX_FILE_SIZE` > - `APP_LOG_RETENTION_DAYS` +> - `APP_LOG_MAX_FILES` > - `APP_LOG_LEVEL` > - `APP_LOG_FORMAT` > - `CALL_LOG_RETENTION_DAYS` +> - `CALL_LOG_MAX_ENTRIES` > > For release details and upgrade notes, see the [CHANGELOG](CHANGELOG.md). --- -## ๐Ÿ†• What's New in v3.0.0 +## ๐Ÿ†• What's New > **Upgrading from v2.9.5?** โ€” See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes. @@ -274,7 +276,7 @@ Developers pay $20โ€“200/month for Claude Pro, Codex Pro, or GitHub Copilot. Eve - **Smart 4-Tier Fallback** โ€” If subscription quota runs out, automatically redirects to API Key โ†’ Cheap โ†’ Free with zero manual intervention - **Real-Time Quota Tracking** โ€” Shows token consumption in real-time with reset countdown (5h, daily, weekly) - **Multi-Account Support** โ€” Multiple accounts per provider with auto round-robin โ€” when one runs out, switches to the next -- **Custom Combos** โ€” Customizable fallback chains with 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Custom Combos** โ€” Customizable fallback chains with 9 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random) - **Codex Business Quotas** โ€” Business/Team workspace quota monitoring directly in the dashboard @@ -286,7 +288,7 @@ OpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If **How OmniRoute solves it:** -- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 67+ providers +- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 60+ providers - **Format Translation** โ€” Automatic and transparent: OpenAI โ†” Claude โ†” Gemini โ†” Responses API - **Response Sanitization** โ€” Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+ - **Role Normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI providers; `system` โ†’ `user` for GLM/ERNIE @@ -372,7 +374,7 @@ Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code.. - **CLI Tools Dashboard** โ€” Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline - **GitHub Copilot Config Generator** โ€” Generates `chatLanguageModels.json` for VS Code with bulk model selection - **Onboarding Wizard** โ€” Guided 4-step setup for first-time users -- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 67+ providers +- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 60+ providers @@ -419,7 +421,7 @@ When a call fails, the dev doesn't know if it was a rate limit, expired token, w - **SQLite Proxy Logs** โ€” Persistent logs that survive server restarts - **Translator Playground** โ€” 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time) - **Request Telemetry** โ€” p50/p95/p99 latency + X-Request-Id tracing -- **File-Based Logging with Rotation** โ€” Console interceptor captures everything to JSON log with size-based rotation +- **File-Based Logging with Rotation** โ€” App logs rotate by size, retention days, and archive count; call log artifacts rotate by retention days and file count - **System Info Report** โ€” `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage. @@ -514,7 +516,7 @@ Developers who want all responses in a specific language, with a specific tone, - **System Prompt Injection** โ€” Global prompt applied to all requests - **Thinking Budget Validation** โ€” Reasoning token allocation control per request (passthrough, auto, custom, adaptive) -- **6 Routing Strategies** โ€” Global strategies that determine how requests are distributed +- **9 Routing Strategies** โ€” Global strategies that determine how requests are distributed - **Wildcard Router** โ€” `provider/*` patterns route dynamically to any provider - **Combo Enable/Disable Toggle** โ€” Toggle combos directly from the dashboard - **Provider Toggle** โ€” Enable/disable all connections for a provider with one click @@ -581,7 +583,7 @@ Different clients should have least-privilege access to tool categories. **How OmniRoute solves it:** -- 9 granular MCP scopes for controlled tool access +- 10 granular MCP scopes for controlled tool access - Scope enforcement and visibility in MCP management UI - Safe default posture for operational tooling @@ -1325,19 +1327,19 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. ### ๐Ÿค– Agent & Protocol Operations (v2.0) -| Feature | What It Does | -| ------------------------------------- | -------------------------------------------------------------------------------------------------- | -| ๐Ÿ”ง **MCP Server (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) | -| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | -| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | -| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | -| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | -| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | -| ๐Ÿ” **MCP Scope Enforcement** | 9 granular scope permissions for controlled tool access | -| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | -| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | -| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | -| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | +| Feature | What It Does | +| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| ๐Ÿ”ง **MCP Server (25 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools | +| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | +| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | +| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | +| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | +| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | +| ๐Ÿ” **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access | +| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | +| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | +| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | +| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | ### ๐Ÿง  Routing & Intelligence @@ -1348,7 +1350,7 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. | ๐Ÿ”„ **Format Translation** | OpenAI โ†” Claude โ†” Gemini โ†” Responses with schema-safe conversions | | ๐Ÿ‘ฅ **Multi-Account Support** | Multiple accounts per provider with intelligent selection | | ๐Ÿ”„ **Auto Token Refresh** | OAuth tokens refresh automatically with retry | -| ๐ŸŽจ **Custom Combos** | 6 balancing strategies + fallback chain control | +| ๐ŸŽจ **Custom Combos** | 9 balancing strategies + fallback chain control | | ๐ŸŒ **Wildcard Router** | `provider/*` dynamic routing | | ๐Ÿง  **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits | | ๐Ÿ”€ **Model Aliases** | Built-in + custom model aliasing and migration safety | @@ -1949,6 +1951,7 @@ opencode - Request artifacts are written to `DATA_DIR/call_logs/` as one JSON file per request - Enable pipeline capture from Dashboard โ†’ Logs โ†’ Request Logs if you need detailed per-stage payloads - Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log` +- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed **Connection test shows "Invalid" for OpenAI-compatible providers** diff --git a/docs/i18n/ms/RELEASE_CHECKLIST.md b/docs/i18n/ms/RELEASE_CHECKLIST.md deleted file mode 100644 index 903e812c3f..0000000000 --- a/docs/i18n/ms/RELEASE_CHECKLIST.md +++ /dev/null @@ -1,37 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/RELEASE_CHECKLIST.md) - ---- - -# Release Checklist - -Use this checklist before tagging or publishing a new OmniRoute release. - -## Version and Changelog - -1. Bump `package.json` version (`x.y.z`) in the release branch. -2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: - - `## [x.y.z] โ€” YYYY-MM-DD` -3. Keep `## [Unreleased]` as the first changelog section for upcoming work. -4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. - -## API Docs - -1. Update `docs/openapi.yaml`: - - `info.version` must equal `package.json` version. -2. Validate endpoint examples if API contracts changed. - -## Runtime Docs - -1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. -2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. -3. Update localized docs if source docs changed significantly. - -## Automated Check - -Run the sync guard locally before opening PR: - -```bash -npm run check:docs-sync -``` - -CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/ms/SECURITY.md b/docs/i18n/ms/SECURITY.md new file mode 100644 index 0000000000..fc0444896c --- /dev/null +++ b/docs/i18n/ms/SECURITY.md @@ -0,0 +1,179 @@ +# Security Policy (Bahasa Melayu) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../SECURITY.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/SECURITY.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/SECURITY.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/SECURITY.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/SECURITY.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/SECURITY.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/SECURITY.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/SECURITY.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/SECURITY.md) + +--- + +## 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 | +| ------- | -------------- | +| 3.4.x | โœ… Active | +| 3.0.x | โœ… Security | +| < 3.0.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 | +| **MCP Scopes** | 10 granular scopes for MCP tool access control | + +### ๐Ÿ›ก๏ธ 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:::` +- 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** | Allowlist/blocklist IP ranges in dashboard | +| **Rate Limiting** | Per-provider rate limits with automatic backoff | +| **Anti-Thundering Herd** | Mutex + per-connection locking prevents cascading 502s | +| **TLS Fingerprint** | Browser-like TLS fingerprint spoofing to reduce bot detection | +| **CLI Fingerprint** | Per-provider header/body ordering to match native CLI signatures | + +### ๐Ÿ”Œ Resilience & Availability + +| 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 `CALL_LOG_RETENTION_DAYS` | +| **No-Log Opt-out** | Per API key `noLog` flag disables request logging | +| **Audit Log** | Administrative actions tracked in `audit_log` table | +| **MCP Audit** | SQLite-backed audit logging for all MCP tool calls | +| **Zod Validation** | All API inputs validated with Zod v4 schemas at module load | + +--- + +## 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 +- Provider constants validated at module load via Zod (`src/shared/validation/providerSchema.ts`) diff --git a/docs/i18n/ms/TROUBLESHOOTING.md b/docs/i18n/ms/TROUBLESHOOTING.md deleted file mode 100644 index 63c148000a..0000000000 --- a/docs/i18n/ms/TROUBLESHOOTING.md +++ /dev/null @@ -1,258 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/TROUBLESHOOTING.md) - ---- - -# Troubleshooting - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/TROUBLESHOOTING.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/TROUBLESHOOTING.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/TROUBLESHOOTING.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/TROUBLESHOOTING.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/TROUBLESHOOTING.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/TROUBLESHOOTING.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/TROUBLESHOOTING.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/TROUBLESHOOTING.md) - -Common problems and solutions for OmniRoute. - ---- - -## Quick Fixes - -| Problem | Solution | -| ----------------------------- | ------------------------------------------------------------------ | -| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | -| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | -| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | -| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | -| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | - ---- - -## Provider Issues - -### "Language model did not provide messages" - -**Cause:** Provider quota exhausted. - -**Fix:** - -1. 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, Qoder) 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}/storage.sqlite` (providers, combos, aliases, keys, settings) -- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` -- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) - ---- - -## Circuit Breaker Issues - -### Provider stuck in OPEN state - -When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. - -**Fix:** - -1. 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 -- **SDK returns raw string instead of object** โ€” Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures -- **GLM/ERNIE rejects `system` role** โ€” Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models -- **`developer` role not recognized** โ€” Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers -- **`json_schema` not working with Gemini** โ€” Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` - ---- - -## Resilience Settings - -### Auto rate-limit not triggering - -- 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. - ---- - -## Optional RAG / LLM failure taxonomy (16 problems) - -Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. - -In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. - -If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: - -- retrieval drift and broken context boundaries -- empty or stale indexes and vector stores -- embedding versus semantic mismatch -- prompt assembly and context window issues -- logic collapse and overconfident answers -- long chain and agent coordination failures -- multi agent memory and role drift -- deployment and bootstrap ordering problems - -The idea is simple: - -1. When you investigate a bad response, capture: - - user task and request - - route or provider combo in OmniRoute - - any RAG context used downstream (retrieved documents, tool calls, etc) -2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` โ€ฆ `No.16`). -3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. -4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. - -Full text and concrete recipes live here (MIT license, text only): - -[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) - -You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. - ---- - -## Still Stuck? - -- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details -- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints -- **Health Dashboard**: Check **Dashboard โ†’ Health** for real-time system status -- **Translator**: Use **Dashboard โ†’ Translator** to debug format issues diff --git a/docs/i18n/ms/docs/A2A-SERVER.md b/docs/i18n/ms/docs/A2A-SERVER.md new file mode 100644 index 0000000000..e91af8ae8c --- /dev/null +++ b/docs/i18n/ms/docs/A2A-SERVER.md @@ -0,0 +1,200 @@ +# OmniRoute A2A Server Documentation (Bahasa Melayu) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/A2A-SERVER.md) + +--- + +> Agent-to-Agent Protocol v0.3 โ€” OmniRoute as an intelligent routing agent + +## Agent Discovery + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements. + +--- + +## Authentication + +All `/a2a` requests require an API key via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server, authentication is bypassed. + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Sends a message to a skill and waits for the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a hello world in Python"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "uuid", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "..." }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}} + +: heartbeat 2026-03-03T17:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Available Skills + +| Skill | Description | +| :----------------- | :------------------------------------------------------------------------------------------------------------------------------ | +| `smart-routing` | Routes prompts through OmniRoute's intelligent pipeline. Returns response with routing explanation, cost, and resilience trace. | +| `quota-management` | Answers natural-language queries about provider quotas, suggests free combos, and provides quota rankings. | + +--- + +## Task Lifecycle + +``` +submitted โ†’ working โ†’ completed + โ†’ failed + โ†’ cancelled +``` + +- Tasks expire after 5 minutes (configurable) +- Terminal states: `completed`, `failed`, `cancelled` +- Event log tracks every state transition + +--- + +## Error Codes + +| Code | Meaning | +| :----- | :----------------------------- | +| -32700 | Parse error (invalid JSON) | +| -32600 | Invalid request / Unauthorized | +| -32601 | Method or skill not found | +| -32602 | Invalid params | +| -32603 | Internal error | + +--- + +## Integration Examples + +### Python (requests) + +```python +import requests + +resp = requests.post("http://localhost:20128/a2a", json={ + "jsonrpc": "2.0", "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Hello"}] + } +}, headers={"Authorization": "Bearer YOUR_KEY"}) + +result = resp.json()["result"] +print(result["artifacts"][0]["content"]) +print(result["metadata"]["routing_explanation"]) +``` + +### TypeScript (fetch) + +```typescript +const resp = await fetch("http://localhost:20128/a2a", { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: "Bearer YOUR_KEY", + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "1", + method: "message/send", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Hello" }], + }, + }), +}); +const { result } = await resp.json(); +console.log(result.metadata.routing_explanation); +``` diff --git a/docs/i18n/ms/docs/API_REFERENCE.md b/docs/i18n/ms/docs/API_REFERENCE.md new file mode 100644 index 0000000000..1e27fabdb6 --- /dev/null +++ b/docs/i18n/ms/docs/API_REFERENCE.md @@ -0,0 +1,465 @@ +# API Reference (Bahasa Melayu) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/API_REFERENCE.md) + +--- + +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 | +| `X-Session-Id` | Request | Sticky session key for external session affinity | +| `x_session_id` | Request | Underscore variant also accepted (direct HTTP) | +| `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 | +| `X-OmniRoute-Session-Id` | Response | Effective session ID used by OmniRoute | + +> Nginx note: if you rely on underscore headers (for example `x_session_id`), enable `underscores_in_headers 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/stats + +# Clear all caches +DELETE /api/cache/stats +``` + +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/PATCH | 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 + provider summary (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`) | +| `/api/cache/stats` | 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 | + +### Tunnels + +| Endpoint | Method | Description | +| -------------------------- | ------ | ----------------------------------------------------------------------- | +| `/api/tunnels/cloudflared` | GET | Read Cloudflare Quick Tunnel install/runtime status for the dashboard | +| `/api/tunnels/cloudflared` | POST | Enable or disable the Cloudflare Quick Tunnel (`action=enable/disable`) | + +### 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`. + +### ACP Agents + +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | + +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). + +### Resilience & Rate Limits + +| Endpoint | Method | Description | +| ----------------------- | --------- | ------------------------------- | +| `/api/resilience` | GET/PATCH | 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` diff --git a/docs/i18n/ms/docs/ARCHITECTURE.md b/docs/i18n/ms/docs/ARCHITECTURE.md new file mode 100644 index 0000000000..4b42344852 --- /dev/null +++ b/docs/i18n/ms/docs/ARCHITECTURE.md @@ -0,0 +1,814 @@ +# OmniRoute Architecture (Bahasa Melayu) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/ARCHITECTURE.md) + +--- + +_Last updated: 2026-03-28_ + +## 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 (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developerโ†’system, systemโ†’user) for cross-provider compatibility +- Structured output conversion (json_schema โ†’ Gemini responseSchema) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) +- Global system prompt injection +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout โ†’ budget โ†’ fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) + +Primary runtime model: + +- Next.js 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.) + +## Dashboard Surface (Current) + +Main pages under `src/app/(dashboard)/dashboard/`: + +- `/dashboard` โ€” quick start + provider overview +- `/dashboard/endpoint` โ€” endpoint proxy + MCP + A2A + API endpoint tabs +- `/dashboard/providers` โ€” provider connections and credentials +- `/dashboard/combos` โ€” combo strategies, templates, model routing rules +- `/dashboard/costs` โ€” cost aggregation and pricing visibility +- `/dashboard/analytics` โ€” usage analytics and evaluations +- `/dashboard/limits` โ€” quota/rate controls +- `/dashboard/cli-tools` โ€” CLI onboarding, runtime detection, config generation +- `/dashboard/agents` โ€” detected ACP agents + custom agent registration +- `/dashboard/media` โ€” image/video/music playground +- `/dashboard/search-tools` โ€” search provider testing and history +- `/dashboard/health` โ€” uptime, circuit breakers, rate limits +- `/dashboard/logs` โ€” request/proxy/audit/console logs +- `/dashboard/settings` โ€” system settings tabs (general, routing, combo defaults, etc.) +- `/dashboard/api-manager` โ€” API key lifecycle and model permissions + +## 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[(storage.sqlite)] + UDB[(usage tables + log artifacts)] + end + + subgraph Upstreams[Upstream Providers] + P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/Qoder/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/route.ts` (GET) +- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- OAuth: `src/app/api/oauth/*` +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` +- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI tooling helpers: `src/app/api/cli-tools/*` +- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) +- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) โ€” provider profiles, circuit breaker, rate limit state +- Resilience reset: `src/app/api/resilience/reset` (POST) โ€” reset breakers + cooldowns +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) +- Telemetry: `src/app/api/telemetry/summary` (GET) +- Budget: `src/app/api/usage/budget` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Policies: `src/app/api/policies` (GET/POST) + +## 2) SSE + 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` +- Response sanitization: `open-sse/handlers/responseSanitizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.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`, `qoder.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 (SQLite): + +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** + +Usage persistence: + +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present + +Domain State DB (SQLite): + +- `src/lib/db/domainState.ts` โ€” CRUD operations 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`, `src/shared/services/modelSyncScheduler.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Periodic task: `src/shared/services/modelSyncScheduler.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. Combo routing adds one extra guard: provider-scoped 400s such as upstream content-block and role-validation failures are treated as model-local failures so later combo targets can still run. + +## 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: + +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` + +## Deployment Topology + +```mermaid +flowchart LR + 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[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] + end + + subgraph External[External Services] + Providers[AI Providers] + SyncCloud[Cloud Sync Service] + end + + CLI --> Next + Browser --> Next + Next --> Core + Next --> MainDB + Core --> MainDB + Core --> UsageDB + Core --> Providers + Next --> SyncCloud +``` + +## Module Mapping (Decision-Critical) + +### Route and API Modules + +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle +- `src/app/api/models/alias`: alias management +- `src/app/api/combos*`: fallback combo management +- `src/app/api/pricing`: pricing overrides for cost calculation +- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers +- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) +- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) +- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) +- `src/app/api/sessions`: active session listing (GET) +- `src/app/api/rate-limits`: per-account rate limit status (GET) + +### Routing and Execution Core + +- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior + +### Translation Registry and Format Converters + +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` +- Format constants: `open-sse/translator/formats.ts` + +### Persistence + +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables + +## Provider Executor Coverage (Strategy Pattern) + +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. + +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, Qoder, 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 | +| Qoder | openai | OAuth (Basic) | โœ… | โœ… | โœ… | โš ๏ธ Per request | +| OpenRouter | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| GLM/Kimi/MiniMax | claude | API Key | โœ… | โœ… | โŒ | โŒ | +| DeepSeek | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Groq | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| xAI (Grok) | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Mistral | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Perplexity | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Together AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Fireworks AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Cerebras | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Cohere | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| NVIDIA NIM | openai | API Key | โœ… | โœ… | โŒ | โŒ | + +## Format Translation Coverage + +Detected source formats include: + +- `openai` +- `openai-responses` +- `claude` +- `gemini` + +Target formats include: + +- OpenAI chat/Responses +- Claude +- Gemini/Gemini-CLI/Antigravity envelope +- Kiro +- Cursor + +Translations use **OpenAI as the hub format** โ€” all conversions go through OpenAI as intermediate: + +``` +Source Format โ†’ OpenAI (hub) โ†’ Target Format +``` + +Translations are selected dynamically based on source payload shape and provider target format. + +Additional processing layers in the translation pipeline: + +- **Response sanitization** โ€” Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI targets; merges `system` โ†’ `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** โ€” Parses `...` blocks from content into `reasoning_content` field +- **Structured output** โ€” Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` + +## Supported API Endpoints + +| 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` | Provider Models | Provider model metadata backing custom and managed available models | + +## 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 `/logs//` 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 + +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON โ†’ SQLite migration compatibility path + +## Observability and Operational Signals + +Runtime visibility sources: + +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- four-stage detailed payload captures in SQLite (`request_detail_logs`) when `settings.detailed_logs_enabled=true` +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption + +Detailed request payload capture stores up to four JSON payload stages per routed call: + +- raw request received from the client +- translated request actually sent upstream +- provider response reconstructed as JSON; streamed responses are compacted to the final summary plus stream metadata +- final client response returned by OmniRoute; streamed responses are stored in the same compact summary form + +## Security-Sensitive Boundaries + +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics + +## Environment and Runtime Matrix + +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` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). + +## Operational Verification Checklist + +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: +- `GET /api/settings` +- `GET /api/v1/models` +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/ms/docs/AUTO-COMBO.md b/docs/i18n/ms/docs/AUTO-COMBO.md new file mode 100644 index 0000000000..5447be3a5c --- /dev/null +++ b/docs/i18n/ms/docs/AUTO-COMBO.md @@ -0,0 +1,67 @@ +# OmniRoute Auto-Combo Engine (Bahasa Melayu) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/AUTO-COMBO.md) + +--- + +> Self-managing model chains with adaptive scoring + +## How It Works + +The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**: + +| Factor | Weight | Description | +| :--------- | :----- | :---------------------------------------------- | +| Quota | 0.20 | Remaining capacity [0..1] | +| Health | 0.25 | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 | +| CostInv | 0.20 | Inverse cost (cheaper = higher score) | +| LatencyInv | 0.15 | Inverse p95 latency (faster = higher) | +| TaskFit | 0.10 | Model ร— task type fitness score | +| Stability | 0.10 | Low variance in latency/errors | + +## Mode Packs + +| Pack | Focus | Key Weight | +| :---------------------- | :----------- | :--------------- | +| ๐Ÿš€ **Ship Fast** | Speed | latencyInv: 0.35 | +| ๐Ÿ’ฐ **Cost Saver** | Economy | costInv: 0.40 | +| ๐ŸŽฏ **Quality First** | Best model | taskFit: 0.40 | +| ๐Ÿ“ก **Offline Friendly** | Availability | quota: 0.40 | + +## Self-Healing + +- **Temporary exclusion**: Score < 0.2 โ†’ excluded for 5 min (progressive backoff, max 30 min) +- **Circuit breaker awareness**: OPEN โ†’ auto-excluded; HALF_OPEN โ†’ probe requests +- **Incident mode**: >50% OPEN โ†’ disable exploration, maximize stability +- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout + +## Bandit Exploration + +5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode. + +## API + +```bash +# Create auto-combo +curl -X POST http://localhost:20128/api/combos/auto \ + -H "Content-Type: application/json" \ + -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}' + +# List auto-combos +curl http://localhost:20128/api/combos/auto +``` + +## Task Fitness + +30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` โ†’ high coding score). + +## Files + +| File | Purpose | +| :------------------------------------------- | :------------------------------------ | +| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization | +| `open-sse/services/autoCombo/taskFitness.ts` | Model ร— task fitness lookup | +| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap | +| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode | +| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles | +| `src/app/api/combos/auto/route.ts` | REST API | diff --git a/docs/i18n/ms/docs/CLI-TOOLS.md b/docs/i18n/ms/docs/CLI-TOOLS.md new file mode 100644 index 0000000000..fdf2400ac0 --- /dev/null +++ b/docs/i18n/ms/docs/CLI-TOOLS.md @@ -0,0 +1,348 @@ +# CLI Tools Setup Guide โ€” OmniRoute (Bahasa Melayu) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CLI-TOOLS.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CLI-TOOLS.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CLI-TOOLS.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CLI-TOOLS.md) + +--- + +This guide explains how to install and configure all supported AI coding CLI tools +to use **OmniRoute** as the unified backend, giving you centralized key management, +cost tracking, model switching, and request logging across every tool. + +--- + +## How It Works + +``` +Claude / Codex / OpenCode / Cline / KiloCode / Continue / Kiro / Cursor / Copilot + โ”‚ + โ–ผ (all point to OmniRoute) + http://YOUR_SERVER:20128/v1 + โ”‚ + โ–ผ (OmniRoute routes to the right provider) + Anthropic / OpenAI / Gemini / DeepSeek / Groq / Mistral / ... +``` + +**Benefits:** + +- One API key to manage all tools +- Cost tracking across all CLIs in the dashboard +- Model switching without reconfiguring every tool +- Works locally and on remote servers (VPS) + +--- + +## Supported Tools (Dashboard Source of Truth) + +The dashboard cards in `/dashboard/cli-tools` are generated from `src/shared/constants/cliTools.ts`. +Current list (v3.0.0-rc.16): + +| Tool | ID | Command | Setup Mode | Install Method | +| ------------------ | ------------- | ---------- | ---------- | -------------- | +| **Claude Code** | `claude` | `claude` | env | npm | +| **OpenAI Codex** | `codex` | `codex` | custom | npm | +| **Factory Droid** | `droid` | `droid` | custom | bundled/CLI | +| **OpenClaw** | `openclaw` | `openclaw` | custom | bundled/CLI | +| **Cursor** | `cursor` | app | guide | desktop app | +| **Cline** | `cline` | `cline` | custom | npm | +| **Kilo Code** | `kilo` | `kilocode` | custom | npm | +| **Continue** | `continue` | extension | guide | VS Code | +| **Antigravity** | `antigravity` | internal | mitm | OmniRoute | +| **GitHub Copilot** | `copilot` | extension | custom | VS Code | +| **OpenCode** | `opencode` | `opencode` | guide | npm | +| **Kiro AI** | `kiro` | app/cli | mitm | desktop/CLI | + +### CLI fingerprint sync (Agents + Settings) + +`/dashboard/agents` and `Settings > CLI Fingerprint` use `src/shared/constants/cliCompatProviders.ts`. +This keeps provider IDs aligned with CLI cards and legacy IDs. + +| CLI ID | Fingerprint Provider ID | +| ---------------------------------------------------------------------------------------------------- | ----------------------- | +| `kilo` | `kilocode` | +| `copilot` | `github` | +| `claude` / `codex` / `antigravity` / `kiro` / `cursor` / `cline` / `opencode` / `droid` / `openclaw` | same ID | + +Legacy IDs still accepted for compatibility: `copilot`, `kimi-coding`, `qwen`. + +--- + +## Step 1 โ€” Get an OmniRoute API Key + +1. Open the OmniRoute dashboard โ†’ **API Manager** (`/dashboard/api-manager`) +2. Click **Create API Key** +3. Give it a name (e.g. `cli-tools`) and select all permissions +4. Copy the key โ€” you'll need it for every CLI below + +> Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` + +--- + +## Step 2 โ€” Install CLI Tools + +All npm-based tools require Node.js 18+: + +```bash +# Claude Code (Anthropic) +npm install -g @anthropic-ai/claude-code + +# OpenAI Codex +npm install -g @openai/codex + +# OpenCode +npm install -g opencode-ai + +# Cline +npm install -g cline + +# KiloCode +npm install -g kilocode + +# Kiro CLI (Amazon โ€” requires curl + unzip) +apt-get install -y unzip # on Debian/Ubuntu +curl -fsSL https://cli.kiro.dev/install | bash +export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc +``` + +**Verify:** + +```bash +claude --version # 2.x.x +codex --version # 0.x.x +opencode --version # x.x.x +cline --version # 2.x.x +kilocode --version # x.x.x (or: kilo --version) +kiro-cli --version # 1.x.x +``` + +--- + +## Step 3 โ€” Set Global Environment Variables + +Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`: + +```bash +# OmniRoute Universal Endpoint +export OPENAI_BASE_URL="http://localhost:20128/v1" +export OPENAI_API_KEY="sk-your-omniroute-key" +export ANTHROPIC_BASE_URL="http://localhost:20128/v1" +export ANTHROPIC_API_KEY="sk-your-omniroute-key" +export GEMINI_BASE_URL="http://localhost:20128/v1" +export GEMINI_API_KEY="sk-your-omniroute-key" +``` + +> For a **remote server** replace `localhost:20128` with the server IP or domain, +> e.g. `http://192.168.0.15:20128`. + +--- + +## Step 4 โ€” Configure Each Tool + +### Claude Code + +```bash +# Via CLI: +claude config set --global api-base-url http://localhost:20128/v1 + +# Or create ~/.claude/settings.json: +mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF +{ + "apiBaseUrl": "http://localhost:20128/v1", + "apiKey": "sk-your-omniroute-key" +} +EOF +``` + +**Test:** `claude "say hello"` + +--- + +### OpenAI Codex + +```bash +mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF +model: auto +apiKey: sk-your-omniroute-key +apiBaseUrl: http://localhost:20128/v1 +EOF +``` + +**Test:** `codex "what is 2+2?"` + +--- + +### OpenCode + +```bash +mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF +[provider.openai] +base_url = "http://localhost:20128/v1" +api_key = "sk-your-omniroute-key" +EOF +``` + +**Test:** `opencode` + +--- + +### Cline (CLI or VS Code) + +**CLI mode:** + +```bash +mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF +{ + "apiProvider": "openai", + "openAiBaseUrl": "http://localhost:20128/v1", + "openAiApiKey": "sk-your-omniroute-key" +} +EOF +``` + +**VS Code mode:** +Cline extension settings โ†’ API Provider: `OpenAI Compatible` โ†’ Base URL: `http://localhost:20128/v1` + +Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ Cline โ†’ Apply Config**. + +--- + +### KiloCode (CLI or VS Code) + +**CLI mode:** + +```bash +kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key +``` + +**VS Code settings:** + +```json +{ + "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", + "kilo-code.apiKey": "sk-your-omniroute-key" +} +``` + +Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ KiloCode โ†’ Apply Config**. + +--- + +### Continue (VS Code Extension) + +Edit `~/.continue/config.yaml`: + +```yaml +models: + - name: OmniRoute + provider: openai + model: auto + apiBase: http://localhost:20128/v1 + apiKey: sk-your-omniroute-key + default: true +``` + +Restart VS Code after editing. + +--- + +### Kiro CLI (Amazon) + +```bash +# Login to your AWS/Kiro account: +kiro-cli login + +# The CLI uses its own auth โ€” OmniRoute is not needed as backend for Kiro CLI itself. +# Use kiro-cli alongside OmniRoute for other tools. +kiro-cli status +``` + +--- + +### Cursor (Desktop App) + +> **Note:** Cursor routes requests through its cloud. For OmniRoute integration, +> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL. + +Via GUI: **Settings โ†’ Models โ†’ OpenAI API Key** + +- Base URL: `https://your-domain.com/v1` +- API Key: your OmniRoute key + +--- + +## Dashboard Auto-Configuration + +The OmniRoute dashboard automates configuration for most tools: + +1. Go to `http://localhost:20128/dashboard/cli-tools` +2. Expand any tool card +3. Select your API key from the dropdown +4. Click **Apply Config** (if tool is detected as installed) +5. Or copy the generated config snippet manually + +--- + +## Built-in Agents: Droid & OpenClaw + +**Droid** and **OpenClaw** are AI agents built directly into OmniRoute โ€” no installation needed. +They run as internal routes and use OmniRoute's model routing automatically. + +- Access: `http://localhost:20128/dashboard/agents` +- Configure: same combos and providers as all other tools +- No API key or CLI install required + +--- + +## Available API Endpoints + +| Endpoint | Description | Use For | +| -------------------------- | ----------------------------- | --------------------------- | +| `/v1/chat/completions` | Standard chat (all providers) | All modern tools | +| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows | +| `/v1/completions` | Legacy text completions | Older tools using `prompt:` | +| `/v1/embeddings` | Text embeddings | RAG, search | +| `/v1/images/generations` | Image generation | DALL-E, Flux, etc. | +| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS | +| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI | + +--- + +## Penyelesaian Masalah + +| Error | Cause | Fix | +| ------------------------- | ----------------------- | ------------------------------------------ | +| `Connection refused` | OmniRoute not running | `pm2 start omniroute` | +| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` | +| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` | +| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` | +| CLI shows "not installed" | Binary not in PATH | Check `which ` | +| `kiro-cli: not found` | Not in PATH | `export PATH="$HOME/.local/bin:$PATH"` | + +--- + +## Quick Setup Script (One Command) + +```bash +# Install all CLIs and configure for OmniRoute (replace with your key and server URL) +OMNIROUTE_URL="http://localhost:20128/v1" +OMNIROUTE_KEY="sk-your-omniroute-key" + +npm install -g @anthropic-ai/claude-code @openai/codex opencode-ai cline kilocode + +# Kiro CLI +apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash + +# Write configs +mkdir -p ~/.claude ~/.codex ~/.config/opencode ~/.continue + +cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" +cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" +cat >> ~/.bashrc << EOF +export OPENAI_BASE_URL="$OMNIROUTE_URL" +export OPENAI_API_KEY="$OMNIROUTE_KEY" +export ANTHROPIC_BASE_URL="$OMNIROUTE_URL" +export ANTHROPIC_API_KEY="$OMNIROUTE_KEY" +EOF + +source ~/.bashrc +echo "โœ… All CLIs installed and configured for OmniRoute" +``` diff --git a/docs/i18n/ms/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/ms/docs/CODEBASE_DOCUMENTATION.md new file mode 100644 index 0000000000..f978b9aabb --- /dev/null +++ b/docs/i18n/ms/docs/CODEBASE_DOCUMENTATION.md @@ -0,0 +1,591 @@ +# omniroute โ€” Codebase Documentation (Bahasa Melayu) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CODEBASE_DOCUMENTATION.md) + +--- + +> 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
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, Qoder, 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. + +#### Seni Bina + +```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 | +| Qoder | 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"] +``` diff --git a/docs/i18n/ms/docs/COVERAGE_PLAN.md b/docs/i18n/ms/docs/COVERAGE_PLAN.md new file mode 100644 index 0000000000..0fd1f8d9c9 --- /dev/null +++ b/docs/i18n/ms/docs/COVERAGE_PLAN.md @@ -0,0 +1,170 @@ +# Test Coverage Plan (Bahasa Melayu) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/COVERAGE_PLAN.md) + +--- + +Last updated: 2026-03-28 + +## Baseline + +There are multiple coverage numbers depending on how the report is computed. For planning, only one of them is useful. + +| Metric | Scope | Statements / Lines | Branches | Functions | Notes | +| -------------------- | ----------------------------------------------------- | -----------------: | -------: | --------: | --------------------------------------------------- | +| Legacy | Old `npm run test:coverage` | 79.42% | 75.15% | 67.94% | Inflated: counts test files and excludes `open-sse` | +| Diagnostic | Source-only, excluding tests and excluding `open-sse` | 68.16% | 63.55% | 64.06% | Useful only to isolate `src/**` | +| Recommended baseline | Source-only, excluding tests and including `open-sse` | 56.95% | 66.05% | 57.80% | This is the project-wide baseline to improve | + +The recommended baseline is the number to optimize against. + +## Rules + +- Coverage targets apply to source files, not to `tests/**`. +- `open-sse/**` is part of the product and must remain in scope. +- New code should not reduce coverage in touched areas. +- Prefer testing behavior and branch outcomes over implementation details. +- Prefer temp SQLite databases and small fixtures over broad mocks for `src/lib/db/**`. + +## Current command set + +- `npm run test:coverage` + - Main source coverage gate for the unit test suite + - Generates `text-summary`, `html`, `json-summary`, and `lcov` +- `npm run coverage:report` + - Detailed file-by-file report from the latest run +- `npm run test:coverage:legacy` + - Historical comparison only + +## Milestones + +| Phase | Target | Focus | +| ------- | ---------------------: | ------------------------------------------------- | +| Phase 1 | 60% statements / lines | Quick wins and low-risk utility coverage | +| Phase 2 | 65% statements / lines | DB and route foundations | +| Phase 3 | 70% statements / lines | Provider validation and usage analytics | +| Phase 4 | 75% statements / lines | `open-sse` translators and helpers | +| Phase 5 | 80% statements / lines | `open-sse` handlers and executor branches | +| Phase 6 | 85% statements / lines | Harder edge cases, branch debt, regression suites | +| Phase 7 | 90% statements / lines | Final sweep, gap closure, strict ratchet | + +Branches and functions should ratchet upward with each phase, but the primary hard target is statements / lines. + +## Priority hotspots + +These files or areas offer the best return for the next phases: + +1. `open-sse/handlers` + - `chatCore.ts` at 7.57% + - Overall directory at 29.07% +2. `open-sse/translator/request` + - Overall directory at 36.39% + - Many translators are still near single-digit coverage +3. `open-sse/translator/response` + - Overall directory at 8.07% +4. `open-sse/executors` + - Overall directory at 36.62% +5. `src/lib/db` + - `models.ts` at 20.66% + - `registeredKeys.ts` at 34.46% + - `modelComboMappings.ts` at 36.25% + - `settings.ts` at 46.40% + - `webhooks.ts` at 33.33% +6. `src/lib/usage` + - `usageHistory.ts` at 21.12% + - `usageStats.ts` at 9.56% + - `costCalculator.ts` at 30.00% +7. `src/lib/providers` + - `validation.ts` at 41.16% +8. Low-risk utility and API files for early gains + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/api/errorResponse.ts` + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +## Execution checklist + +### Phase 1: 56.95% -> 60% + +- [x] Fix coverage metric so it reflects source code instead of test files +- [x] Keep a legacy coverage script for comparison +- [x] Record the baseline and hotspots in-repo +- [ ] Add focused tests for low-risk utilities: + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/fetchTimeout.ts` + - `src/lib/api/errorResponse.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/display/names.ts` +- [ ] Add route tests for: + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +### Phase 2: 60% -> 65% + +- [ ] Add DB-backed tests for: + - `src/lib/db/modelComboMappings.ts` + - `src/lib/db/settings.ts` + - `src/lib/db/registeredKeys.ts` +- [ ] Cover branch behavior in: + - `src/lib/providers/validation.ts` + - `src/app/api/v1/embeddings/route.ts` + - `src/app/api/v1/moderations/route.ts` + +### Phase 3: 65% -> 70% + +- [ ] Add usage analytics tests for: + - `src/lib/usage/usageHistory.ts` + - `src/lib/usage/usageStats.ts` + - `src/lib/usage/costCalculator.ts` +- [ ] Expand route coverage for proxy management and settings branches + +### Phase 4: 70% -> 75% + +- [ ] Cover translator helpers and central translation paths: + - `open-sse/translator/index.ts` + - `open-sse/translator/helpers/*` + - `open-sse/translator/request/*` + - `open-sse/translator/response/*` + +### Phase 5: 75% -> 80% + +- [ ] Add handler-level tests for: + - `open-sse/handlers/chatCore.ts` + - `open-sse/handlers/responsesHandler.js` + - `open-sse/handlers/imageGeneration.js` + - `open-sse/handlers/embeddings.js` +- [ ] Add executor branch coverage for provider-specific auth, retries, and endpoint overrides + +### Phase 6: 80% -> 85% + +- [ ] Merge more edge-case suites into the main coverage path +- [ ] Increase function coverage for DB modules with weak constructor/helper coverage +- [ ] Close branch gaps in `settings.ts`, `registeredKeys.ts`, `validation.ts`, and translator helpers + +### Phase 7: 85% -> 90% + +- [ ] Treat the remaining low-coverage files as blockers +- [ ] Add regression tests for every uncovered production bug fixed during the push to 90% +- [ ] Raise the coverage gate in CI only after the local baseline is stable for at least two consecutive runs + +## Ratchet policy + +Update `npm run test:coverage` thresholds only after the project actually exceeds the next milestone with a comfortable buffer. + +Recommended ratchet sequence: + +1. 55/60/55 +2. 60/62/58 +3. 65/64/62 +4. 70/66/66 +5. 75/70/72 +6. 80/75/78 +7. 85/80/84 +8. 90/85/88 + +Order is `statements-lines / branches / functions`. + +## Known gap + +The current coverage command measures the main Node unit suite and includes source reached from it, including `open-sse`. It does not yet merge Vitest coverage into a single unified report. That merge is worth doing later, but it is not a blocker for starting the 60% -> 80% climb. diff --git a/docs/i18n/ms/docs/FEATURES.md b/docs/i18n/ms/docs/FEATURES.md index e429f21df4..131a0056cc 100644 --- a/docs/i18n/ms/docs/FEATURES.md +++ b/docs/i18n/ms/docs/FEATURES.md @@ -1,6 +1,6 @@ # OmniRoute โ€” Dashboard Features Gallery (Bahasa Melayu) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/FEATURES.md) --- @@ -10,7 +10,7 @@ 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). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. ![Providers Dashboard](screenshots/01-providers.png) diff --git a/docs/i18n/ms/docs/MCP-SERVER.md b/docs/i18n/ms/docs/MCP-SERVER.md new file mode 100644 index 0000000000..978adce1df --- /dev/null +++ b/docs/i18n/ms/docs/MCP-SERVER.md @@ -0,0 +1,87 @@ +# OmniRoute MCP Server Documentation (Bahasa Melayu) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/MCP-SERVER.md) + +--- + +> Model Context Protocol server with 16 intelligent tools + +## Pasang + +OmniRoute MCP is built-in. Start it with: + +```bash +omniroute --mcp +``` + +Or via the open-sse transport: + +```bash +# HTTP streamable transport (port 20130) +omniroute --dev # MCP auto-starts on /mcp endpoint +``` + +## IDE Configuration + +See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup. + +--- + +## Essential Tools (8) + +| Tool | Description | +| :------------------------------ | :--------------------------------------- | +| `omniroute_get_health` | Gateway health, circuit breakers, uptime | +| `omniroute_list_combos` | All configured combos with models | +| `omniroute_get_combo_metrics` | Performance metrics for a specific combo | +| `omniroute_switch_combo` | Switch active combo by ID/name | +| `omniroute_check_quota` | Quota status per provider or all | +| `omniroute_route_request` | Send a chat completion through OmniRoute | +| `omniroute_cost_report` | Cost analytics for a time period | +| `omniroute_list_models_catalog` | Full model catalog with capabilities | + +## Advanced Tools (8) + +| Tool | Description | +| :--------------------------------- | :---------------------------------------------------------- | +| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | +| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | +| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | +| `omniroute_test_combo` | Live-test all models in a combo via a real upstream request | +| `omniroute_get_provider_metrics` | Detailed metrics for one provider | +| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | +| `omniroute_explain_route` | Explain a past routing decision | +| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | + +## Authentication + +MCP tools are authenticated via API key scopes. Each tool requires specific scopes: + +| Scope | Tools | +| :------------- | :----------------------------------------------- | +| `read:health` | get_health, get_provider_metrics | +| `read:combos` | list_combos, get_combo_metrics | +| `write:combos` | switch_combo | +| `read:quota` | check_quota | +| `write:route` | route_request, simulate_route, test_combo | +| `read:usage` | cost_report, get_session_snapshot, explain_route | +| `write:config` | set_budget_guard, set_resilience_profile | +| `read:models` | list_models_catalog, best_combo_for_task | + +## Audit Logging + +Every tool call is logged to `mcp_tool_audit` with: + +- Tool name, arguments, result +- Duration (ms), success/failure +- API key hash, timestamp + +## Files + +| File | Purpose | +| :------------------------------------------- | :------------------------------------------ | +| `open-sse/mcp-server/server.ts` | MCP server creation + 16 tool registrations | +| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport | +| `open-sse/mcp-server/auth.ts` | API key + scope validation | +| `open-sse/mcp-server/audit.ts` | Tool call audit logging | +| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers | diff --git a/docs/i18n/ms/docs/RELEASE_CHECKLIST.md b/docs/i18n/ms/docs/RELEASE_CHECKLIST.md new file mode 100644 index 0000000000..2b14ce5f34 --- /dev/null +++ b/docs/i18n/ms/docs/RELEASE_CHECKLIST.md @@ -0,0 +1,37 @@ +# Release Checklist (Bahasa Melayu) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/RELEASE_CHECKLIST.md) + +--- + +Use this checklist before tagging or publishing a new OmniRoute release. + +## Version and Changelog + +1. Bump `package.json` version (`x.y.z`) in the release branch. +2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: + - `## [x.y.z] โ€” YYYY-MM-DD` +3. Keep `## [Unreleased]` as the first changelog section for upcoming work. +4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. + +## API Docs + +1. Update `docs/openapi.yaml`: + - `info.version` must equal `package.json` version. +2. Validate endpoint examples if API contracts changed. + +## Runtime Docs + +1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. +2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. +3. Update localized docs if source docs changed significantly. + +## Automated Check + +Run the sync guard locally before opening PR: + +```bash +npm run check:docs-sync +``` + +CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/ms/docs/TROUBLESHOOTING.md b/docs/i18n/ms/docs/TROUBLESHOOTING.md new file mode 100644 index 0000000000..ae4fec9944 --- /dev/null +++ b/docs/i18n/ms/docs/TROUBLESHOOTING.md @@ -0,0 +1,256 @@ +# Troubleshooting (Bahasa Melayu) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/TROUBLESHOOTING.md) + +--- + +Common problems and solutions for OmniRoute. + +--- + +## Quick Fixes + +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | + +--- + +## Provider Issues + +### "Language model did not provide messages" + +**Cause:** Provider quota exhausted. + +**Fix:** + +1. 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, Qoder) 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}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) + +--- + +## Circuit Breaker Issues + +### Provider stuck in OPEN state + +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. + +**Fix:** + +1. 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 +- **SDK returns raw string instead of object** โ€” Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** โ€” Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** โ€” Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** โ€” Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` + +--- + +## Resilience Settings + +### Auto rate-limit not triggering + +- 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. + +--- + +## Optional RAG / LLM failure taxonomy (16 problems) + +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` โ€ฆ `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard โ†’ Health** for real-time system status +- **Translator**: Use **Dashboard โ†’ Translator** to debug format issues diff --git a/docs/i18n/ms/USER_GUIDE.md b/docs/i18n/ms/docs/USER_GUIDE.md similarity index 82% rename from docs/i18n/ms/USER_GUIDE.md rename to docs/i18n/ms/docs/USER_GUIDE.md index 2211ee1ff1..2c889675e8 100644 --- a/docs/i18n/ms/USER_GUIDE.md +++ b/docs/i18n/ms/docs/USER_GUIDE.md @@ -1,8 +1,6 @@ # User Guide (Bahasa Melayu) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/USER_GUIDE.md) - -> ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/USER_GUIDE.md) --- @@ -320,7 +318,7 @@ Model: cc/claude-opus-4-6 --- -## ๐Ÿš€ Deployment +## Penempatan ### Global npm install (Recommended) @@ -511,23 +509,26 @@ post_install() { ### Environment Variables -| Variable | Default | Description | -| ------------------------- | ------------------------------------ | ------------------------------------------------------- | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | -| `INITIAL_PASSWORD` | `123456` | First login password | -| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | -| `PORT` | framework default | Service port (`20128` in examples) | -| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | -| `NODE_ENV` | runtime default | Set `production` for deploy | -| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | -| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | -| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | -| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | -| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | -| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | -| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | -| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | +| 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/*` | +| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand | +| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | For the full environment variable reference, see the [README](../README.md). @@ -598,6 +599,11 @@ curl -X POST http://localhost:20128/api/provider-models \ Or use Dashboard: **Providers โ†’ [Provider] โ†’ Custom Models**. +Notes: + +- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers. +- The **Custom Models** section is intended for providers that do not expose managed available-model imports. + ### Dedicated Provider Routes Route requests directly to a specific provider with model validation: @@ -642,6 +648,14 @@ Returns models grouped by provider with types (`chat`, `embedding`, `image`). - Automatic background sync with timeout + fail-fast - Prefer server-side `BASE_URL`/`CLOUD_URL` in production +### Cloudflare Quick Tunnel + +- Available in **Dashboard โ†’ Endpoints** for Docker and other self-hosted deployments +- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint +- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary +- Tunnel URLs are ephemeral and change every time you stop/start the tunnel +- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download + ### LLM Gateway Intelligence (Phase 9) - **Semantic Cache** โ€” Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) @@ -757,11 +771,11 @@ OmniRoute implements provider-level resilience with four components: 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 | +| 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 unless `DISABLE_SQLITE_AUTO_BACKUP=true` | ```bash # API: Export database @@ -787,10 +801,11 @@ curl -X POST http://localhost:20128/api/db-backups/import \ ### Settings Dashboard -The settings page is organized into 5 tabs for easy navigation: +The settings page is organized into 6 tabs for easy navigation: | Tab | Contents | | -------------- | ---------------------------------------------------------------------------------------------- | +| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility | | **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | | **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | | **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | diff --git a/docs/i18n/ms/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/ms/docs/VM_DEPLOYMENT_GUIDE.md new file mode 100644 index 0000000000..559cdc3089 --- /dev/null +++ b/docs/i18n/ms/docs/VM_DEPLOYMENT_GUIDE.md @@ -0,0 +1,403 @@ +# OmniRoute โ€” Deployment Guide on VM with Cloudflare (Bahasa Melayu) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/VM_DEPLOYMENT_GUIDE.md) + +--- + +Complete guide to install and configure OmniRoute on a VM (VPS) with domain managed via Cloudflare. + +--- + +## Prerequisites + +| Item | Minimum | Recommended | +| ---------- | ------------------------ | ---------------- | +| **CPU** | 1 vCPU | 2 vCPU | +| **RAM** | 1 GB | 2 GB | +| **Disk** | 10 GB SSD | 25 GB SSD | +| **OS** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS | +| **Domain** | Registered on Cloudflare | โ€” | +| **Docker** | Docker Engine 24+ | Docker 27+ | + +**Tested providers**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. + +--- + +## 1. Configure the VM + +### 1.1 Create the instance + +On your preferred VPS provider: + +- Choose Ubuntu 24.04 LTS +- Select the minimum plan (1 vCPU / 1 GB RAM) +- Set a strong root password or configure SSH key +- Note the **public IP** (e.g., `203.0.113.10`) + +### 1.2 Connect via SSH + +```bash +ssh root@203.0.113.10 +``` + +### 1.3 Update the system + +```bash +apt update && apt upgrade -y +``` + +### 1.4 Install Docker + +```bash +# Install dependencies +apt install -y ca-certificates curl gnupg + +# Add official Docker repository +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 Install nginx + +```bash +apt install -y nginx +``` + +### 1.6 Configure 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 +``` + +> **Tip**: For maximum security, restrict ports 80 and 443 to Cloudflare IPs only. See the [Advanced Security](#advanced-security) section. + +--- + +## 2. Install OmniRoute + +### 2.1 Create configuration directory + +```bash +mkdir -p /opt/omniroute +``` + +### 2.2 Create environment variables file + +```bash +cat > /opt/omniroute/.env << โ€˜EOFโ€™ +# === Security === +JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY +INITIAL_PASSWORD=YourSecurePassword123! +API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY +STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY +STORAGE_ENCRYPTION_KEY_VERSION=v1 +MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT + +# === 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 (change to your domain) === +BASE_URL=https://llms.seudominio.com +NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com + +# === Cloud Sync (optional) === +# CLOUD_URL=https://cloud.omniroute.online +# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online +EOF +``` + +> โš ๏ธ **IMPORTANT**: Generate unique secret keys! Use `openssl rand -hex 32` for each key. + +### 2.3 Start the 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 Verify that it is running + +```bash +docker ps | grep omniroute +docker logs omniroute --tail 20 +``` + +It should display: `[DB] SQLite database ready` and `listening on port 20128`. + +--- + +## 3. Configure nginx (Reverse Proxy) + +### 3.1 Generate SSL certificate (Cloudflare Origin) + +In the Cloudflare dashboard: + +1. Go to **SSL/TLS โ†’ Origin Server** +2. Click **Create Certificate** +3. Keep the defaults (15 years, \*.yourdomain.com) +4. Copy the **Origin Certificate** and the **Private Key** + +```bash +mkdir -p /etc/nginx/ssl + +# Paste the certificate +nano /etc/nginx/ssl/origin.crt + +# Paste the private key +nano /etc/nginx/ssl/origin.key + +chmod 600 /etc/nginx/ssl/origin.key +``` + +### 3.2 Nginx Configuration + +```bash +cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ +# Default server โ€” blocks direct access via 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.yourdomain.com; # Change to your domain + + 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.yourdomain.com; + return 301 https://$server_name$request_uri; +} +NGINX +``` + +### 3.3 Enable and Test + +```bash +# Remove default configuration +rm -f /etc/nginx/sites-enabled/default + +# Enable OmniRoute +ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute + +# Test and reload +nginx -t && systemctl reload nginx +``` + +--- + +## 4. Configure Cloudflare DNS + +### 4.1 Add DNS record + +In the Cloudflare dashboard โ†’ DNS: + +| Type | Name | Content | Proxy | +| ---- | ------ | ---------------------- | ---------- | +| A | `llms` | `203.0.113.10` (VM IP) | โœ… Proxied | + +### 4.2 Configure SSL + +Under **SSL/TLS โ†’ Overview**: + +- Mode: **Full (Strict)** + +Under **SSL/TLS โ†’ Edge Certificates**: + +- Always Use HTTPS: โœ… On +- Minimum TLS Version: TLS 1.2 +- Automatic HTTPS Rewrites: โœ… On + +### 4.3 Testing + +```bash +curl -sI https://llms.seudominio.com/health +# Should return HTTP/2 200 +``` + +--- + +## 5. Operations and Maintenance + +### Upgrade to a new version + +```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 +``` + +### View logs + +```bash +docker logs -f omniroute # Real-time stream +docker logs omniroute --tail 50 # Last 50 lines +``` + +### Manual database backup + +```bash +# Copy data from the volume to the host +docker cp omniroute:/app/data ./backup-$(date +%F) + +# Or compress the entire volume +docker run --rm -v omniroute-data:/data -v $(pwd):/backup \ + alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data +``` + +### Restore from 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. Advanced Security + +### Restrict nginx to Cloudflare IPs + +```bash +cat > /etc/nginx/cloudflare-ips.conf << โ€˜CFโ€™ +# Cloudflare IPv4 ranges โ€” update periodically +# 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 +``` + +Add the following to `nginx.conf` inside the `http {}` block: + +```nginx +include /etc/nginx/cloudflare-ips.conf; +``` + +### Install fail2ban + +```bash +apt install -y fail2ban +systemctl enable fail2ban +systemctl start fail2ban + +# Check status +fail2ban-client status sshd +``` + +### Block direct access to the Docker port + +```bash +# Prevent direct external access to port 20128 +iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP +iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT + +# Persist the rules +apt install -y iptables-persistent +netfilter-persistent save +``` + +--- + +## 7. Deploy to Cloudflare Workers (Optional) + +For remote access via Cloudflare Workers (without exposing the VM directly): + +```bash +# In the local repository +cd omnirouteCloud +npm install +npx wrangler login +npx wrangler deploy +``` + +See the full documentation at [omnirouteCloud/README.md](../omnirouteCloud/README.md). + +--- + +## Port Summary + +| Port | Service | Access | +| ----- | ----------- | -------------------------- | +| 22 | SSH | Public (with fail2ban) | +| 80 | nginx HTTP | Redirect โ†’ HTTPS | +| 443 | nginx HTTPS | Via Cloudflare Proxy | +| 20128 | OmniRoute | Localhost only (via nginx) | diff --git a/docs/i18n/ms/src/lib/a2a/README.md b/docs/i18n/ms/src/lib/a2a/README.md new file mode 100644 index 0000000000..664b6d9716 --- /dev/null +++ b/docs/i18n/ms/src/lib/a2a/README.md @@ -0,0 +1,752 @@ +# OmniRoute A2A Server (Bahasa Melayu) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../../../src/lib/a2a/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../../../es/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../../../fr/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../../../de/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../../../it/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../../../ru/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../../../zh-CN/src/lib/a2a/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../../../ja/src/lib/a2a/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../../../ko/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../../../ar/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../../../in/src/lib/a2a/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../../../th/src/lib/a2a/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../../../vi/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../../../id/src/lib/a2a/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../../../ms/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../../../nl/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../../../pl/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../../../sv/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../../../no/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../../../da/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../../../fi/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../../../pt/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../../../ro/src/lib/a2a/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../../../hu/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../../../bg/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../../../sk/src/lib/a2a/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../../../uk-UA/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../../../he/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../../../phi/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../../../pt-BR/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../../../cs/src/lib/a2a/README.md) + +--- + +> **Agent-to-Agent Protocol v0.3** โ€” Enables any AI agent to use OmniRoute as an intelligent routing agent via JSON-RPC 2.0. + +The A2A Server exposes OmniRoute as a **first-class agent** that other agents can discover, delegate tasks to, and collaborate with using the [A2A Protocol](https://google.github.io/A2A/). + +--- + +## Seni Bina + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Orchestrator Agent โ”‚ +โ”‚ (LangChain, CrewAI, AutoGen, Custom Agent) โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ 1. GET /.well-known/agent.json (discover) + โ”‚ 2. POST /a2a (JSON-RPC 2.0) + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ OmniRoute A2A Server โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Task Manager โ”‚ โ”‚ Skill Engine โ”‚ โ”‚ SSE Streaming โ”‚ โ”‚ +โ”‚ โ”‚ (lifecycle) โ”‚โ”€โ”€โ”‚ (registry) โ”‚โ”€โ”€โ”‚ (real-time) โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ +โ”‚ Skills: โ”‚ โ”‚ +โ”‚ โ”œโ”€ smart-routing โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ””โ”€ quota-management โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ Routing Decision Logger โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ OmniRoute Gateway (internal) + /v1/chat/completions, /api/combos, /api/usage/quota +``` + +--- + +## Mula Pantas + +### Agent Discovery + +Every A2A-compatible agent exposes an **Agent Card** at `/.well-known/agent.json`: + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +**Response:** + +```json +{ + "name": "OmniRoute", + "description": "Intelligent AI gateway with auto-routing across 50+ providers", + "url": "http://localhost:20128/a2a", + "version": "1.8.1", + "capabilities": { + "streaming": true, + "pushNotifications": false + }, + "skills": [ + { + "id": "smart-routing", + "name": "Smart Routing", + "description": "Routes prompts through OmniRoute intelligent pipeline", + "tags": ["routing", "llm", "multi-provider", "cost-optimization"], + "examples": [ + "Write a hello world in Python", + "Explain quantum computing using the cheapest provider" + ] + }, + { + "id": "quota-management", + "name": "Quota Management", + "description": "Natural-language queries about provider quotas", + "tags": ["quota", "analytics", "cost"], + "examples": [ + "Which provider has the most quota remaining?", + "Suggest a free combo for coding" + ] + } + ], + "authentication": { + "schemes": ["bearer"], + "apiKeyHeader": "Authorization" + } +} +``` + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Send a message to a skill and receive the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python hello world"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "a1b2c3d4-...", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "print('Hello, World!')" }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.0030)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "2026-03-04T..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"Quantum computing..."}}} + +: heartbeat 2026-03-04T21:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Running Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Skills Reference + +### `smart-routing` + +Routes prompts through OmniRoute's intelligent pipeline with full observability. + +**Parameters (in `metadata`):** + +| Parameter | Type | Default | Description | +| --------- | -------- | ------------ | ---------------------------------------------------------------------------------------- | +| `model` | `string` | `"auto"` | Target model (e.g., `claude-sonnet-4`, `gpt-4o`, `auto`) | +| `combo` | `string` | active combo | Specific combo to route through | +| `budget` | `number` | none | Maximum cost in USD for this request | +| `role` | `string` | none | Task role hint: `coding`, `review`, `planning`, `analysis`, `debugging`, `documentation` | + +**Returns:** + +| Field | Description | +| ------------------------------ | --------------------------------------------------------- | +| `artifacts[].content` | The LLM response text | +| `metadata.routing_explanation` | Human-readable explanation of routing decision | +| `metadata.cost_envelope` | Estimated vs actual cost with currency | +| `metadata.resilience_trace` | Array of events (primary_selected, fallback_needed, etc.) | +| `metadata.policy_verdict` | Whether the request was allowed and why | + +### `quota-management` + +Answers natural-language queries about provider quotas. + +**Query types (inferred from message content):** + +| Query Pattern | Response Type | +| ---------------------------------------------- | -------------------------------------------------------- | +| Contains `"ranking"`, `"most quota"`, `"best"` | Providers ranked by remaining quota | +| Contains `"free"`, `"suggest"` | Lists free combos or suggests free-tier providers | +| Default | Full quota summary with warnings for low-quota providers | + +--- + +## Task Lifecycle + +``` +submitted โ”€โ”€โ†’ working โ”€โ”€โ†’ completed + โ”€โ”€โ†’ failed + โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ†’ cancelled +``` + +| State | Description | +| ----------- | ----------------------------------------------------- | +| `submitted` | Task created, queued for execution | +| `working` | Skill handler is executing | +| `completed` | Execution succeeded, artifacts available | +| `failed` | Execution failed or task expired (TTL: 5 min default) | +| `cancelled` | Cancelled by client via `tasks/cancel` | + +- Terminal states: `completed`, `failed`, `cancelled` (no further transitions) +- Expired tasks in `submitted` or `working` are auto-marked as `failed` +- Tasks are garbage-collected after 2ร— TTL + +--- + +## Client Examples + +### Python โ€” Orchestrator Agent + +```python +""" +A2A Client โ€” Python example. +Discovers OmniRoute agent, sends a task, and processes the result. +""" +import requests +import json + +BASE_URL = "http://localhost:20128" +API_KEY = "your-api-key" +HEADERS = { + "Content-Type": "application/json", + "Authorization": f"Bearer {API_KEY}", +} + +# 1. Discover agent capabilities +agent_card = requests.get(f"{BASE_URL}/.well-known/agent.json").json() +print(f"Agent: {agent_card['name']} v{agent_card['version']}") +print(f"Skills: {[s['id'] for s in agent_card['skills']]}") + +# 2. Send a smart-routing task +response = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python quicksort implementation"}], + "metadata": { + "model": "auto", + "combo": "fast-coding", + "budget": 0.10, + } + } +}) +result = response.json()["result"] +print(f"\n๐Ÿ“ Response: {result['artifacts'][0]['content'][:200]}...") +print(f"๐Ÿ”€ Routing: {result['metadata']['routing_explanation']}") +print(f"๐Ÿ’ฐ Cost: ${result['metadata']['cost_envelope']['actual']}") +print(f"๐Ÿ›ก๏ธ Policy: {result['metadata']['policy_verdict']['reason']}") + +# 3. Query quota status +quota_resp = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-2", + "method": "message/send", + "params": { + "skill": "quota-management", + "messages": [{"role": "user", "content": "Which provider has the most quota remaining?"}], + } +}) +quota_result = quota_resp.json()["result"] +print(f"\n๐Ÿ“Š Quota: {quota_result['artifacts'][0]['content']}") +``` + +### TypeScript โ€” Multi-Agent Orchestrator + +```typescript +/** + * A2A Client โ€” TypeScript example. + * Shows agent discovery, task delegation, and streaming. + */ + +const BASE_URL = "http://localhost:20128"; +const API_KEY = "your-api-key"; + +interface JsonRpcResponse { + jsonrpc: "2.0"; + id: string | number; + result?: T; + error?: { code: number; message: string }; +} + +async function a2aCall(method: string, params: Record): Promise { + const resp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: `${method}-${Date.now()}`, + method, + params, + }), + }); + const json: JsonRpcResponse = await resp.json(); + if (json.error) throw new Error(`[${json.error.code}] ${json.error.message}`); + return json.result!; +} + +// โ”€โ”€ Agent Discovery โ”€โ”€ +const agentCard = await fetch(`${BASE_URL}/.well-known/agent.json`).then((r) => r.json()); +console.log(`Connected to: ${agentCard.name} (${agentCard.skills.length} skills)`); + +// โ”€โ”€ Smart Routing: Send a coding task โ”€โ”€ +const routingResult = await a2aCall("message/send", { + skill: "smart-routing", + messages: [{ role: "user", content: "Implement a Redis cache wrapper in TypeScript" }], + metadata: { model: "claude-sonnet-4", role: "coding" }, +}); +console.log("Response:", routingResult.artifacts[0].content); +console.log("Provider:", routingResult.metadata.routing_explanation); + +// โ”€โ”€ Quota Management: Find free alternatives โ”€โ”€ +const quotaResult = await a2aCall("message/send", { + skill: "quota-management", + messages: [{ role: "user", content: "Suggest free combos for documentation" }], +}); +console.log("Free combos:", quotaResult.artifacts[0].content); + +// โ”€โ”€ Streaming: Real-time response โ”€โ”€ +const streamResp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "stream-1", + method: "message/stream", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Explain microservices architecture" }], + }, + }), +}); + +const reader = streamResp.body!.getReader(); +const decoder = new TextDecoder(); +while (true) { + const { done, value } = await reader.read(); + if (done) break; + const chunk = decoder.decode(value); + for (const line of chunk.split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + if (event.params.chunk) { + process.stdout.write(event.params.chunk.content); + } + if (event.params.task.state === "completed") { + console.log("\nโœ… Stream completed"); + } + } + } +} +``` + +### Python โ€” LangChain A2A Integration + +```python +""" +LangChain integration โ€” Use OmniRoute A2A as a custom LLM. +""" +from langchain.llms.base import BaseLLM +from langchain.schema import LLMResult, Generation +import requests +from typing import List, Optional + +class OmniRouteA2A(BaseLLM): + base_url: str = "http://localhost:20128" + api_key: str = "" + model: str = "auto" + combo: Optional[str] = None + + @property + def _llm_type(self) -> str: + return "omniroute-a2a" + + def _call(self, prompt: str, stop: Optional[List[str]] = None, **kwargs) -> str: + response = requests.post( + f"{self.base_url}/a2a", + headers={ + "Content-Type": "application/json", + "Authorization": f"Bearer {self.api_key}", + }, + json={ + "jsonrpc": "2.0", + "id": "langchain-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": prompt}], + "metadata": { + "model": self.model, + **({"combo": self.combo} if self.combo else {}), + }, + }, + }, + ) + result = response.json()["result"] + return result["artifacts"][0]["content"] + + def _generate(self, prompts: List[str], stop=None, **kwargs) -> LLMResult: + return LLMResult( + generations=[[Generation(text=self._call(p, stop))] for p in prompts] + ) + +# Usage +llm = OmniRouteA2A( + base_url="http://localhost:20128", + api_key="your-key", + model="auto", + combo="fast-coding", +) +result = llm("Write a Python function to merge two sorted lists") +print(result) +``` + +### Go โ€” A2A Client + +```go +package main + +import ( + "bytes" + "encoding/json" + "fmt" + "io" + "net/http" +) + +const baseURL = "http://localhost:20128" +const apiKey = "your-api-key" + +type JsonRpcRequest struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Method string `json:"method"` + Params interface{} `json:"params"` +} + +type JsonRpcResponse struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Result interface{} `json:"result"` + Error *struct { + Code int `json:"code"` + Message string `json:"message"` + } `json:"error"` +} + +func a2aCall(method string, params interface{}) (*JsonRpcResponse, error) { + body, _ := json.Marshal(JsonRpcRequest{ + Jsonrpc: "2.0", + ID: "go-1", + Method: method, + Params: params, + }) + + req, _ := http.NewRequest("POST", baseURL+"/a2a", bytes.NewReader(body)) + req.Header.Set("Content-Type", "application/json") + req.Header.Set("Authorization", "Bearer "+apiKey) + + resp, err := http.DefaultClient.Do(req) + if err != nil { + return nil, err + } + defer resp.Body.Close() + data, _ := io.ReadAll(resp.Body) + + var result JsonRpcResponse + json.Unmarshal(data, &result) + return &result, nil +} + +func main() { + // Discover agent + resp, _ := http.Get(baseURL + "/.well-known/agent.json") + defer resp.Body.Close() + body, _ := io.ReadAll(resp.Body) + fmt.Println("Agent Card:", string(body)) + + // Send smart-routing task + result, _ := a2aCall("message/send", map[string]interface{}{ + "skill": "smart-routing", + "messages": []map[string]string{{"role": "user", "content": "Hello from Go!"}}, + "metadata": map[string]interface{}{"model": "auto"}, + }) + out, _ := json.MarshalIndent(result.Result, "", " ") + fmt.Println("Result:", string(out)) +} +``` + +--- + +## Use Cases + +### ๐Ÿค– Use Case 1: Multi-Agent Coding Pipeline + +An orchestrator agent delegates code generation to OmniRoute, then passes the output to a review agent. + +```python +def coding_pipeline(task: str): + # Step 1: Generate code via OmniRoute A2A + code_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Write production-quality code: {task}"} + ], metadata={"model": "auto", "role": "coding"}) + code = code_result["artifacts"][0]["content"] + + # Step 2: Review the code via OmniRoute A2A (different model) + review_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Review this code for bugs and improvements:\n\n{code}"} + ], metadata={"model": "auto", "role": "review"}) + review = review_result["artifacts"][0]["content"] + + # Step 3: Check costs + print(f"Code cost: ${code_result['metadata']['cost_envelope']['actual']}") + print(f"Review cost: ${review_result['metadata']['cost_envelope']['actual']}") + + return {"code": code, "review": review} +``` + +### ๐Ÿ’ก Use Case 2: Quota-Aware Agent Swarm + +Multiple agents share quota through OmniRoute, using the quota skill to coordinate. + +```python +async def quota_aware_agent(agent_name: str, task: str): + # Check quota before starting + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Which provider has the most quota remaining?"} + ]) + print(f"[{agent_name}] {quota['artifacts'][0]['content']}") + + # Send request with budget constraint + result = a2a_send("smart-routing", [ + {"role": "user", "content": task} + ], metadata={"budget": 0.05}) + + policy = result["metadata"]["policy_verdict"] + if not policy["allowed"]: + print(f"[{agent_name}] โš ๏ธ Budget exceeded: {policy['reason']}") + # Fall back to free combo + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Suggest free combos"} + ]) + print(f"[{agent_name}] Free alternatives: {quota['artifacts'][0]['content']}") + + return result +``` + +### ๐Ÿ“Š Use Case 3: Real-Time Streaming Dashboard + +A monitoring agent streams responses and displays progress in real-time. + +```typescript +async function streamingDashboard(prompt: string) { + const response = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { "Content-Type": "application/json", Authorization: `Bearer ${API_KEY}` }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "dash-1", + method: "message/stream", + params: { skill: "smart-routing", messages: [{ role: "user", content: prompt }] }, + }), + }); + + let totalChunks = 0; + const reader = response.body!.getReader(); + const decoder = new TextDecoder(); + + while (true) { + const { done, value } = await reader.read(); + if (done) break; + + for (const line of decoder.decode(value).split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + const state = event.params.task.state; + + if (state === "working" && event.params.chunk) { + totalChunks++; + process.stdout.write( + `\r[Chunk ${totalChunks}] ${event.params.chunk.content.slice(0, 50)}...` + ); + } + if (state === "completed") { + const meta = event.params.metadata; + console.log( + `\nโœ… Done | Cost: $${meta?.cost_envelope?.actual || 0} | Route: ${meta?.routing_explanation || "N/A"}` + ); + } + if (state === "failed") { + console.error(`\nโŒ Failed: ${event.params.metadata?.error}`); + } + } + } + } +} +``` + +### ๐Ÿ” Use Case 4: Task Polling Pattern + +For long-running tasks, poll the task status instead of waiting synchronously. + +```python +import time + +def poll_task(task_id: str, timeout: int = 60): + """Poll task status until completion or timeout.""" + start = time.time() + while time.time() - start < timeout: + result = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "poll-1", + "method": "tasks/get", + "params": {"taskId": task_id}, + }).json() + + task = result["result"]["task"] + state = task["state"] + print(f" Task {task_id[:8]}... state={state}") + + if state in ("completed", "failed", "cancelled"): + return task + time.sleep(2) + + # Timeout โ€” cancel the task + requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "cancel-1", + "method": "tasks/cancel", + "params": {"taskId": task_id}, + }) + raise TimeoutError(f"Task {task_id} timed out after {timeout}s") +``` + +--- + +## Error Codes + +| Code | Constant | Meaning | +| ------ | ------------------------ | ---------------------------------------- | +| -32700 | โ€” | Parse error (invalid JSON) | +| -32600 | `INVALID_REQUEST` | Invalid JSON-RPC request or unauthorized | +| -32601 | `METHOD_NOT_FOUND` | Unknown method or skill | +| -32602 | `INVALID_PARAMS` | Missing or invalid parameters | +| -32603 | `INTERNAL_ERROR` | Skill execution failed | +| -32001 | `TASK_NOT_FOUND` | Task ID not found | +| -32002 | `TASK_ALREADY_COMPLETED` | Cannot modify a completed task | +| -32003 | `UNAUTHORIZED` | Invalid or missing API key | +| -32004 | `BUDGET_EXCEEDED` | Request exceeds configured budget | +| -32005 | `PROVIDER_UNAVAILABLE` | No available providers | + +--- + +## Authentication + +All `/a2a` requests require a Bearer token via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server (`OMNIROUTE_API_KEY` is empty), authentication is bypassed. + +--- + +## File Structure + +``` +src/lib/a2a/ +โ”œโ”€โ”€ taskManager.ts # Task lifecycle (create/update/cancel/list), TTL, cleanup +โ”œโ”€โ”€ taskExecution.ts # Generic task executor with state management +โ”œโ”€โ”€ streaming.ts # SSE stream formatting, heartbeat, chunk/completion events +โ”œโ”€โ”€ routingLogger.ts # Routing decision logger (stats, history, retention) +โ””โ”€โ”€ skills/ + โ”œโ”€โ”€ smartRouting.ts # Smart routing skill (routes via /v1/chat/completions) + โ””โ”€โ”€ quotaManagement.ts # Quota management skill (natural-language quota queries) + +src/app/a2a/ +โ””โ”€โ”€ route.ts # Next.js API route handler (JSON-RPC 2.0 dispatch) + +open-sse/mcp-server/ +โ””โ”€โ”€ schemas/a2a.ts # Zod schemas (AgentCard, Task, JSON-RPC, SSE events) +``` + +--- + +## Comparison: MCP vs A2A + +| Feature | MCP Server | A2A Server | +| ----------------- | ---------------------------- | ------------------------------------------------- | +| **Protocol** | Model Context Protocol | Agent-to-Agent Protocol v0.3 | +| **Transport** | stdio / HTTP | HTTP (JSON-RPC 2.0) | +| **Discovery** | Tool listing via MCP | `/.well-known/agent.json` | +| **Granularity** | 16 individual tools | 2 high-level skills | +| **Best for** | IDE agents (Cursor, VS Code) | Multi-agent systems (LangChain, CrewAI) | +| **Streaming** | Not supported | SSE via `message/stream` | +| **Task tracking** | No | Full lifecycle (submitted โ†’ completed) | +| **Observability** | Audit log per tool call | Cost envelope + resilience trace + policy verdict | + +--- + +## Lesen + +Part of [OmniRoute](https://github.com/diegosouzapw/OmniRoute) โ€” MIT License. diff --git a/docs/i18n/nl/A2A-SERVER.md b/docs/i18n/nl/A2A-SERVER.md deleted file mode 100644 index 01531ff482..0000000000 --- a/docs/i18n/nl/A2A-SERVER.md +++ /dev/null @@ -1,200 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/A2A-SERVER.md) - ---- - -# OmniRoute A2A Server Documentation - -> Agent-to-Agent Protocol v0.3 โ€” OmniRoute as an intelligent routing agent - -## Agent Discovery - -```bash -curl http://localhost:20128/.well-known/agent.json -``` - -Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements. - ---- - -## Authentication - -All `/a2a` requests require an API key via the `Authorization` header: - -``` -Authorization: Bearer YOUR_OMNIROUTE_API_KEY -``` - -If no API key is configured on the server, authentication is bypassed. - ---- - -## JSON-RPC 2.0 Methods - -### `message/send` โ€” Synchronous Execution - -Sends a message to a skill and waits for the complete response. - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{ - "jsonrpc": "2.0", - "id": "1", - "method": "message/send", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Write a hello world in Python"}], - "metadata": {"model": "auto", "combo": "fast-coding"} - } - }' -``` - -**Response:** - -```json -{ - "jsonrpc": "2.0", - "id": "1", - "result": { - "task": { "id": "uuid", "state": "completed" }, - "artifacts": [{ "type": "text", "content": "..." }], - "metadata": { - "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)", - "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, - "resilience_trace": [ - { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." } - ], - "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } - } - } -} -``` - -### `message/stream` โ€” SSE Streaming - -Same as `message/send` but returns Server-Sent Events for real-time streaming. - -```bash -curl -N -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{ - "jsonrpc": "2.0", - "id": "1", - "method": "message/stream", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Explain quantum computing"}] - } - }' -``` - -**SSE Events:** - -``` -data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}} - -: heartbeat 2026-03-03T17:00:00Z - -data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} -``` - -### `tasks/get` โ€” Query Task Status - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' -``` - -### `tasks/cancel` โ€” Cancel a Task - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' -``` - ---- - -## Available Skills - -| Skill | Description | -| :----------------- | :------------------------------------------------------------------------------------------------------------------------------ | -| `smart-routing` | Routes prompts through OmniRoute's intelligent pipeline. Returns response with routing explanation, cost, and resilience trace. | -| `quota-management` | Answers natural-language queries about provider quotas, suggests free combos, and provides quota rankings. | - ---- - -## Task Lifecycle - -``` -submitted โ†’ working โ†’ completed - โ†’ failed - โ†’ cancelled -``` - -- Tasks expire after 5 minutes (configurable) -- Terminal states: `completed`, `failed`, `cancelled` -- Event log tracks every state transition - ---- - -## Error Codes - -| Code | Meaning | -| :----- | :----------------------------- | -| -32700 | Parse error (invalid JSON) | -| -32600 | Invalid request / Unauthorized | -| -32601 | Method or skill not found | -| -32602 | Invalid params | -| -32603 | Internal error | - ---- - -## Integration Examples - -### Python (requests) - -```python -import requests - -resp = requests.post("http://localhost:20128/a2a", json={ - "jsonrpc": "2.0", "id": "1", - "method": "message/send", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Hello"}] - } -}, headers={"Authorization": "Bearer YOUR_KEY"}) - -result = resp.json()["result"] -print(result["artifacts"][0]["content"]) -print(result["metadata"]["routing_explanation"]) -``` - -### TypeScript (fetch) - -```typescript -const resp = await fetch("http://localhost:20128/a2a", { - method: "POST", - headers: { - "Content-Type": "application/json", - Authorization: "Bearer YOUR_KEY", - }, - body: JSON.stringify({ - jsonrpc: "2.0", - id: "1", - method: "message/send", - params: { - skill: "smart-routing", - messages: [{ role: "user", content: "Hello" }], - }, - }), -}); -const { result } = await resp.json(); -console.log(result.metadata.routing_explanation); -``` diff --git a/docs/i18n/nl/API_REFERENCE.md b/docs/i18n/nl/API_REFERENCE.md deleted file mode 100644 index b878605221..0000000000 --- a/docs/i18n/nl/API_REFERENCE.md +++ /dev/null @@ -1,455 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/API_REFERENCE.md) - ---- - -# API Reference - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/API_REFERENCE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/API_REFERENCE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/API_REFERENCE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/API_REFERENCE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/API_REFERENCE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/API_REFERENCE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/API_REFERENCE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/API_REFERENCE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/API_REFERENCE.md) - -Complete reference for all OmniRoute API endpoints. - ---- - -## Table of Contents - -- [Chat Completions](#chat-completions) -- [Embeddings](#embeddings) -- [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`. - -### ACP Agents - -| Endpoint | Method | Description | -| ----------------- | ------ | -------------------------------------------------------- | -| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | -| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | -| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | - -GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). - -### Resilience & Rate Limits - -| Endpoint | Method | Description | -| ----------------------- | ------- | ------------------------------- | -| `/api/resilience` | 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` diff --git a/docs/i18n/nl/ARCHITECTURE.md b/docs/i18n/nl/ARCHITECTURE.md deleted file mode 100644 index 4ea06a29f2..0000000000 --- a/docs/i18n/nl/ARCHITECTURE.md +++ /dev/null @@ -1,787 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/ARCHITECTURE.md) - ---- - -# OmniRoute Architecture - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/ARCHITECTURE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/ARCHITECTURE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/ARCHITECTURE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/ARCHITECTURE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/ARCHITECTURE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/ARCHITECTURE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/ARCHITECTURE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/ARCHITECTURE.md) - -_Last updated: 2026-03-04_ - -## 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 (`...`) for reasoning models -- Response sanitization for strict OpenAI SDK compatibility -- Role normalization (developerโ†’system, systemโ†’user) for cross-provider compatibility -- Structured output conversion (json_schema โ†’ Gemini responseSchema) -- Local persistence for providers, keys, aliases, combos, settings, pricing -- Usage/cost tracking and request logging -- Optional cloud sync for multi-device/state sync -- IP allowlist/blocklist for API access control -- Thinking budget management (passthrough/auto/custom/adaptive) -- Global system prompt injection -- Session tracking and fingerprinting -- Per-account enhanced rate limiting with provider-specific profiles -- Circuit breaker pattern for provider resilience -- Anti-thundering herd protection with mutex locking -- Signature-based request deduplication cache -- Domain layer: model availability, cost rules, fallback policy, lockout policy -- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) -- Policy engine for centralized request evaluation (lockout โ†’ budget โ†’ fallback) -- Request telemetry with p50/p95/p99 latency aggregation -- Correlation ID (X-Request-Id) for end-to-end tracing -- Compliance audit logging with opt-out per API key -- Eval framework for LLM quality assurance -- Resilience UI dashboard with real-time circuit breaker status -- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) - -Primary runtime model: - -- Next.js 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[(storage.sqlite)] - UDB[(usage tables + log artifacts)] - end - - subgraph Upstreams[Upstream Providers] - P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/Qoder/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/route.ts` (GET) -- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) -- OAuth: `src/app/api/oauth/*` -- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` -- Usage: `src/app/api/usage/*` -- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` -- CLI tooling helpers: `src/app/api/cli-tools/*` -- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) -- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) -- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) -- Sessions: `src/app/api/sessions` (GET) -- Rate limits: `src/app/api/rate-limits` (GET) -- Resilience: `src/app/api/resilience` (GET/PATCH) โ€” provider profiles, circuit breaker, rate limit state -- Resilience reset: `src/app/api/resilience/reset` (POST) โ€” reset breakers + cooldowns -- Cache stats: `src/app/api/cache/stats` (GET/DELETE) -- Model availability: `src/app/api/models/availability` (GET/POST) -- Telemetry: `src/app/api/telemetry/summary` (GET) -- Budget: `src/app/api/usage/budget` (GET/POST) -- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) -- Compliance audit: `src/app/api/compliance/audit-log` (GET) -- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) -- Policies: `src/app/api/policies` (GET/POST) - -## 2) SSE + 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` -- Response sanitization: `open-sse/handlers/responseSanitizer.ts` -- Role normalization: `open-sse/services/roleNormalizer.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`, `qoder.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 (SQLite): - -- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) -- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) -- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) -- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** - -Usage persistence: - -- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) -- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` -- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) -- legacy JSON files are migrated to SQLite by startup migrations when present - -Domain State DB (SQLite): - -- `src/lib/db/domainState.ts` โ€” CRUD operations 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: - -- primary runtime DB: `${DATA_DIR}/storage.sqlite` -- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) -- structured call payload archives: `${DATA_DIR}/call_logs/` -- optional translator/request debug sessions: `/logs/...` - -## Deployment Topology - -```mermaid -flowchart LR - 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[(storage.sqlite)] - UsageDB[(usage tables + log artifacts)] - end - - subgraph External[External Services] - Providers[AI Providers] - SyncCloud[Cloud Sync Service] - end - - CLI --> Next - Browser --> Next - Next --> Core - Next --> MainDB - Core --> MainDB - Core --> UsageDB - Core --> Providers - Next --> SyncCloud -``` - -## Module Mapping (Decision-Critical) - -### Route and API Modules - -- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs -- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) -- `src/app/api/providers*`: provider CRUD, validation, testing -- `src/app/api/provider-nodes*`: custom compatible node management -- `src/app/api/provider-models`: custom model management (CRUD) -- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) -- `src/app/api/oauth/*`: OAuth/device-code flows -- `src/app/api/keys*`: local API key lifecycle -- `src/app/api/models/alias`: alias management -- `src/app/api/combos*`: fallback combo management -- `src/app/api/pricing`: pricing overrides for cost calculation -- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) -- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) -- `src/app/api/usage/*`: usage and logs APIs -- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers -- `src/app/api/cli-tools/*`: local CLI config writers/checkers -- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) -- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) -- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) -- `src/app/api/sessions`: active session listing (GET) -- `src/app/api/rate-limits`: per-account rate limit status (GET) - -### Routing and Execution Core - -- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop -- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup -- `open-sse/executors/*`: provider-specific network and format behavior - -### Translation Registry and Format Converters - -- `open-sse/translator/index.ts`: translator registry and orchestration -- Request translators: `open-sse/translator/request/*` -- Response translators: `open-sse/translator/response/*` -- Format constants: `open-sse/translator/formats.ts` - -### Persistence - -- `src/lib/db/*`: persistent config/state and domain persistence on SQLite -- `src/lib/localDb.ts`: compatibility re-export for DB modules -- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables - -## Provider Executor Coverage (Strategy Pattern) - -Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. - -| Executor | Provider(s) | Special Handling | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | -| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, Qoder, 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 | -| Qoder | openai | OAuth (Basic) | โœ… | โœ… | โœ… | โš ๏ธ Per request | -| OpenRouter | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| GLM/Kimi/MiniMax | claude | API Key | โœ… | โœ… | โŒ | โŒ | -| DeepSeek | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Groq | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| xAI (Grok) | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Mistral | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Perplexity | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Together AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Fireworks AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Cerebras | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Cohere | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| NVIDIA NIM | openai | API Key | โœ… | โœ… | โŒ | โŒ | - -## Format Translation Coverage - -Detected source formats include: - -- `openai` -- `openai-responses` -- `claude` -- `gemini` - -Target formats include: - -- OpenAI chat/Responses -- Claude -- Gemini/Gemini-CLI/Antigravity envelope -- Kiro -- Cursor - -Translations use **OpenAI as the hub format** โ€” all conversions go through OpenAI as intermediate: - -``` -Source Format โ†’ OpenAI (hub) โ†’ Target Format -``` - -Translations are selected dynamically based on source payload shape and provider target format. - -Additional processing layers in the translation pipeline: - -- **Response sanitization** โ€” Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance -- **Role normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI targets; merges `system` โ†’ `user` for models that reject the system role (GLM, ERNIE) -- **Think tag extraction** โ€” Parses `...` blocks from content into `reasoning_content` field -- **Structured output** โ€” Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` - -## Supported API Endpoints - -| 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 `/logs//` 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 - -- SQLite schema migrations and auto-upgrade hooks at startup -- legacy JSON โ†’ SQLite migration compatibility path - -## Observability and Operational Signals - -Runtime visibility sources: - -- console logs from `src/sse/utils/logger.ts` -- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) -- textual request status log in `log.txt` (optional/compat) -- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` -- dashboard usage endpoints (`/api/usage/*`) for UI consumption - -## Security-Sensitive Boundaries - -- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing -- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning -- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format -- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level -- Cloud sync endpoints rely on API key auth + machine id semantics - -## Environment and Runtime Matrix - -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` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. -2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. -3. Request logger writes full headers/body when enabled; treat log directory as sensitive. -4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. -5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. -6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). -7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). -8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). - -## Operational Verification Checklist - -- Build from source: `npm run build` -- Build Docker image: `docker build -t omniroute .` -- Start service and verify: -- `GET /api/settings` -- `GET /api/v1/models` -- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/nl/AUTO-COMBO.md b/docs/i18n/nl/AUTO-COMBO.md deleted file mode 100644 index 2166e41dff..0000000000 --- a/docs/i18n/nl/AUTO-COMBO.md +++ /dev/null @@ -1,67 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/AUTO-COMBO.md) - ---- - -# OmniRoute Auto-Combo Engine - -> Self-managing model chains with adaptive scoring - -## How It Works - -The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**: - -| Factor | Weight | Description | -| :--------- | :----- | :---------------------------------------------- | -| Quota | 0.20 | Remaining capacity [0..1] | -| Health | 0.25 | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 | -| CostInv | 0.20 | Inverse cost (cheaper = higher score) | -| LatencyInv | 0.15 | Inverse p95 latency (faster = higher) | -| TaskFit | 0.10 | Model ร— task type fitness score | -| Stability | 0.10 | Low variance in latency/errors | - -## Mode Packs - -| Pack | Focus | Key Weight | -| :---------------------- | :----------- | :--------------- | -| ๐Ÿš€ **Ship Fast** | Speed | latencyInv: 0.35 | -| ๐Ÿ’ฐ **Cost Saver** | Economy | costInv: 0.40 | -| ๐ŸŽฏ **Quality First** | Best model | taskFit: 0.40 | -| ๐Ÿ“ก **Offline Friendly** | Availability | quota: 0.40 | - -## Self-Healing - -- **Temporary exclusion**: Score < 0.2 โ†’ excluded for 5 min (progressive backoff, max 30 min) -- **Circuit breaker awareness**: OPEN โ†’ auto-excluded; HALF_OPEN โ†’ probe requests -- **Incident mode**: >50% OPEN โ†’ disable exploration, maximize stability -- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout - -## Bandit Exploration - -5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode. - -## API - -```bash -# Create auto-combo -curl -X POST http://localhost:20128/api/combos/auto \ - -H "Content-Type: application/json" \ - -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}' - -# List auto-combos -curl http://localhost:20128/api/combos/auto -``` - -## Task Fitness - -30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` โ†’ high coding score). - -## Files - -| File | Purpose | -| :------------------------------------------- | :------------------------------------ | -| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization | -| `open-sse/services/autoCombo/taskFitness.ts` | Model ร— task fitness lookup | -| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap | -| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode | -| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles | -| `src/app/api/combos/auto/route.ts` | REST API | diff --git a/docs/i18n/nl/CHANGELOG.md b/docs/i18n/nl/CHANGELOG.md index 9f21698378..927c5d5054 100644 --- a/docs/i18n/nl/CHANGELOG.md +++ b/docs/i18n/nl/CHANGELOG.md @@ -1,12 +1,92 @@ # Changelog (Nederlands) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CHANGELOG.md) --- - ## [Unreleased] +### ๐Ÿ› ๏ธ Maintenance + +- **AGENTS.md rewrite:** Condensed from 297โ†’153 lines. Added build/lint/test commands (including single-test execution), code style guidelines (Prettier, TypeScript, ESLint, naming, imports, error handling, security), and trimmed verbose architecture tables for AI agent consumption. + +## [3.4.2] - 2026-04-01 + +### ๐Ÿ› Bug Fixes + +- **CI Stabilization:** Fixed failing analytics/settings Playwright selectors and request assertions so GitHub Actions E2E runs pass reliably across localized UIs and switch-based controls. +- **Deterministic Tests:** Removed date-sensitive quota fixtures from Copilot usage tests and aligned idempotency/model catalog tests with the merged runtime behavior. +- **MCP Type Hardening:** Removed zero-budget explicit `any` regressions from the MCP server tool registration path, restoring the `check:any-budget:t11` workflow gate. + +### ๐Ÿ› ๏ธ Maintenance + +- **Release Branch Integration:** Consolidated the active feature branches into `release/v3.4.2` on top of current `main` and validated the branch with lint, unit, coverage, build, and CI-mode E2E runs. + +## [3.4.1] - 2026-03-31 + +> [!WARNING] +> **BREAKING CHANGE: request logging, retention, and logging environment variables have been redesigned.** +> On the first startup after upgrading, OmniRoute archives legacy request logs from `DATA_DIR/logs/`, legacy `DATA_DIR/call_logs/`, and `DATA_DIR/log.txt` into `DATA_DIR/log_archives/*.zip`, then removes the deprecated layout and switches to the new unified artifact format under `DATA_DIR/call_logs/`. + +### โœจ New Features + +- **.ENV Migration Utility:** Included `scripts/migrate-env.mjs` to seamlessly migrate ` Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` - ---- - -## Step 2 โ€” Install CLI Tools - -All npm-based tools require Node.js 18+: - -```bash -# Claude Code (Anthropic) -npm install -g @anthropic-ai/claude-code - -# OpenAI Codex -npm install -g @openai/codex - -# Gemini CLI (Google) -npm install -g @google/gemini-cli - -# OpenCode -npm install -g opencode-ai - -# Cline -npm install -g cline - -# KiloCode -npm install -g kilecode - -# Kiro CLI (Amazon โ€” requires curl + unzip) -apt-get install -y unzip # on Debian/Ubuntu -curl -fsSL https://cli.kiro.dev/install | bash -export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc -``` - -**Verify:** - -```bash -claude --version # 2.x.x -codex --version # 0.x.x -gemini --version # 0.x.x -opencode --version # x.x.x -cline --version # 2.x.x -kilocode --version # x.x.x (or: kilo --version) -kiro-cli --version # 1.x.x -``` - ---- - -## Step 3 โ€” Set Global Environment Variables - -Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`: - -```bash -# OmniRoute Universal Endpoint -export OPENAI_BASE_URL="http://localhost:20128/v1" -export OPENAI_API_KEY="sk-your-omniroute-key" -export ANTHROPIC_BASE_URL="http://localhost:20128/v1" -export ANTHROPIC_API_KEY="sk-your-omniroute-key" -export GEMINI_BASE_URL="http://localhost:20128/v1" -export GEMINI_API_KEY="sk-your-omniroute-key" -``` - -> For a **remote server** replace `localhost:20128` with the server IP or domain, -> e.g. `http://192.168.0.15:20128`. - ---- - -## Step 4 โ€” Configure Each Tool - -### Claude Code - -```bash -# Via CLI: -claude config set --global api-base-url http://localhost:20128/v1 - -# Or create ~/.claude/settings.json: -mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF -{ - "apiBaseUrl": "http://localhost:20128/v1", - "apiKey": "sk-your-omniroute-key" -} -EOF -``` - -**Test:** `claude "say hello"` - ---- - -### OpenAI Codex - -```bash -mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF -model: auto -apiKey: sk-your-omniroute-key -apiBaseUrl: http://localhost:20128/v1 -EOF -``` - -**Test:** `codex "what is 2+2?"` - ---- - -### Gemini CLI - -```bash -mkdir -p ~/.gemini && cat > ~/.gemini/settings.json << EOF -{ - "apiKey": "sk-your-omniroute-key", - "baseUrl": "http://localhost:20128/v1" -} -EOF -``` - -**Test:** `gemini "hello"` - ---- - -### OpenCode - -```bash -mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF -[provider.openai] -base_url = "http://localhost:20128/v1" -api_key = "sk-your-omniroute-key" -EOF -``` - -**Test:** `opencode` - ---- - -### Cline (CLI or VS Code) - -**CLI mode:** - -```bash -mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF -{ - "apiProvider": "openai", - "openAiBaseUrl": "http://localhost:20128/v1", - "openAiApiKey": "sk-your-omniroute-key" -} -EOF -``` - -**VS Code mode:** -Cline extension settings โ†’ API Provider: `OpenAI Compatible` โ†’ Base URL: `http://localhost:20128/v1` - -Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ Cline โ†’ Apply Config**. - ---- - -### KiloCode (CLI or VS Code) - -**CLI mode:** - -```bash -kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key -``` - -**VS Code settings:** - -```json -{ - "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", - "kilo-code.apiKey": "sk-your-omniroute-key" -} -``` - -Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ KiloCode โ†’ Apply Config**. - ---- - -### Continue (VS Code Extension) - -Edit `~/.continue/config.yaml`: - -```yaml -models: - - name: OmniRoute - provider: openai - model: auto - apiBase: http://localhost:20128/v1 - apiKey: sk-your-omniroute-key - default: true -``` - -Restart VS Code after editing. - ---- - -### Kiro CLI (Amazon) - -```bash -# Login to your AWS/Kiro account: -kiro-cli login - -# The CLI uses its own auth โ€” OmniRoute is not needed as backend for Kiro CLI itself. -# Use kiro-cli alongside OmniRoute for other tools. -kiro-cli status -``` - ---- - -### Cursor (Desktop App) - -> **Note:** Cursor routes requests through its cloud. For OmniRoute integration, -> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL. - -Via GUI: **Settings โ†’ Models โ†’ OpenAI API Key** - -- Base URL: `https://your-domain.com/v1` -- API Key: your OmniRoute key - ---- - -## Dashboard Auto-Configuration - -The OmniRoute dashboard automates configuration for most tools: - -1. Go to `http://localhost:20128/dashboard/cli-tools` -2. Expand any tool card -3. Select your API key from the dropdown -4. Click **Apply Config** (if tool is detected as installed) -5. Or copy the generated config snippet manually - ---- - -## Built-in Agents: Droid & OpenClaw - -**Droid** and **OpenClaw** are AI agents built directly into OmniRoute โ€” no installation needed. -They run as internal routes and use OmniRoute's model routing automatically. - -- Access: `http://localhost:20128/dashboard/agents` -- Configure: same combos and providers as all other tools -- No API key or CLI install required - ---- - -## Available API Endpoints - -| Endpoint | Description | Use For | -| -------------------------- | ----------------------------- | --------------------------- | -| `/v1/chat/completions` | Standard chat (all providers) | All modern tools | -| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows | -| `/v1/completions` | Legacy text completions | Older tools using `prompt:` | -| `/v1/embeddings` | Text embeddings | RAG, search | -| `/v1/images/generations` | Image generation | DALL-E, Flux, etc. | -| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS | -| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI | - ---- - -## Troubleshooting - -| Error | Cause | Fix | -| ------------------------- | ----------------------- | ------------------------------------------ | -| `Connection refused` | OmniRoute not running | `pm2 start omniroute` | -| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` | -| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` | -| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` | -| CLI shows "not installed" | Binary not in PATH | Check `which ` | -| `kiro-cli: not found` | Not in PATH | `export PATH="$HOME/.local/bin:$PATH"` | - ---- - -## Quick Setup Script (One Command) - -```bash -# Install all CLIs and configure for OmniRoute (replace with your key and server URL) -OMNIROUTE_URL="http://localhost:20128/v1" -OMNIROUTE_KEY="sk-your-omniroute-key" - -npm install -g @anthropic-ai/claude-code @openai/codex @google/gemini-cli opencode-ai cline kilecode - -# Kiro CLI -apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash - -# Write configs -mkdir -p ~/.claude ~/.codex ~/.gemini ~/.config/opencode ~/.continue - -cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" -cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" -cat > ~/.gemini/settings.json <<< "{\"apiKey\":\"$OMNIROUTE_KEY\",\"baseUrl\":\"$OMNIROUTE_URL\"}" -cat >> ~/.bashrc << EOF -export OPENAI_BASE_URL="$OMNIROUTE_URL" -export OPENAI_API_KEY="$OMNIROUTE_KEY" -export ANTHROPIC_BASE_URL="$OMNIROUTE_URL" -export ANTHROPIC_API_KEY="$OMNIROUTE_KEY" -EOF - -source ~/.bashrc -echo "โœ… All CLIs installed and configured for OmniRoute" -``` diff --git a/docs/i18n/nl/CODEBASE_DOCUMENTATION.md b/docs/i18n/nl/CODEBASE_DOCUMENTATION.md deleted file mode 100644 index e2d7950052..0000000000 --- a/docs/i18n/nl/CODEBASE_DOCUMENTATION.md +++ /dev/null @@ -1,593 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CODEBASE_DOCUMENTATION.md) - ---- - -# omniroute โ€” Codebase Documentation - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) - -> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. - ---- - -## 1. 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
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, Qoder, 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 | -| Qoder | 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"] -``` diff --git a/docs/i18n/nl/CONTRIBUTING.md b/docs/i18n/nl/CONTRIBUTING.md new file mode 100644 index 0000000000..b082496cb3 --- /dev/null +++ b/docs/i18n/nl/CONTRIBUTING.md @@ -0,0 +1,299 @@ +# Contributing to OmniRoute (Nederlands) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CONTRIBUTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CONTRIBUTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CONTRIBUTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CONTRIBUTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CONTRIBUTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CONTRIBUTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CONTRIBUTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CONTRIBUTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CONTRIBUTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CONTRIBUTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CONTRIBUTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CONTRIBUTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CONTRIBUTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CONTRIBUTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CONTRIBUTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CONTRIBUTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CONTRIBUTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CONTRIBUTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CONTRIBUTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CONTRIBUTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CONTRIBUTING.md) + +--- + +Thank you for your interest in contributing! This guide covers everything you need to get started. + +--- + +## Development Setup + +### Prerequisites + +- **Node.js** >= 18 < 24 (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` | `20128` | Server port | +| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | Base URL for frontend | +| `JWT_SECRET` | (generate above) | JWT signing secret | +| `INITIAL_PASSWORD` | `CHANGEME` | First login password | +| `APP_LOG_LEVEL` | `info` | Log verbosity level | + +### Dashboard Settings + +The dashboard provides UI toggles for features that can also be configured via environment variables: + +| Setting Location | Toggle | Description | +| ------------------- | ------------------ | ------------------------------ | +| Settings โ†’ Advanced | Debug Mode | Enable debug request logs (UI) | +| Settings โ†’ General | Sidebar Visibility | Show/hide sidebar sections | + +These settings are stored in the database and persist across restarts, overriding env var defaults when set. + +### 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:20128/dashboard` +- **API**: `http://localhost:20128/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`, `mcp`, `a2a`, `memory`, `skills`. + +--- + +## Running Tests + +```bash +# All tests (unit + vitest + ecosystem + e2e) +npm run test:all + +# Single test file (Node.js native test runner โ€” most tests use this) +node --import tsx/esm --test tests/unit/your-file.test.mjs + +# Vitest (MCP server, autoCombo, cache) +npm run test:vitest + +# E2E tests (requires Playwright) +npm run test:e2e + +# Protocol clients E2E (MCP transports, A2A) +npm run test:protocols:e2e + +# Ecosystem compatibility tests +npm run test:ecosystem + +# Coverage (55% min statements/lines/functions; 60% branches) +npm run test:coverage +npm run coverage:report + +# Lint + format check +npm run lint +npm run check +``` + +Coverage notes: + +- `npm run test:coverage` measures source coverage for the main unit test suite, excludes `tests/**`, and includes `open-sse/**` +- `npm run coverage:report` prints the detailed file-by-file report from the latest coverage run +- `npm run test:coverage:legacy` preserves the older metric for historical comparison +- See `docs/COVERAGE_PLAN.md` for the phased coverage improvement roadmap + +Current test status: **122 unit test files** covering: + +- Provider translators and format conversion +- Rate limiting, circuit breaker, and resilience +- Semantic cache, idempotency, progress tracking +- Database operations and schema (21 DB modules) +- OAuth flows and authentication +- API endpoint validation (Zod v4) +- MCP server tools and scope enforcement +- Memory and Skills systems + +--- + +## Code Style + +- **ESLint** โ€” Run `npm run lint` before committing +- **Prettier** โ€” Auto-formatted via `lint-staged` on commit (2 spaces, semicolons, double quotes, 100 char width, es5 trailing commas) +- **TypeScript** โ€” All `src/` code uses `.ts`/`.tsx`; `open-sse/` uses `.ts`/`.js`; document with TSDoc (`@param`, `@returns`, `@throws`) +- **No `eval()`** โ€” ESLint enforces `no-eval`, `no-implied-eval`, `no-new-func` +- **Zod validation** โ€” Use Zod v4 schemas for all API input validation +- **Naming**: Files = camelCase/kebab-case, components = PascalCase, constants = UPPER_SNAKE + +--- + +## Project Structure + +``` +src/ # TypeScript (.ts / .tsx) +โ”œโ”€โ”€ app/ # Next.js 16 App Router +โ”‚ โ”œโ”€โ”€ (dashboard)/ # Dashboard pages (23 sections) +โ”‚ โ”œโ”€โ”€ api/ # API routes (51 directories) +โ”‚ โ””โ”€โ”€ login/ # Auth pages (.tsx) +โ”œโ”€โ”€ domain/ # Policy engine (policyEngine, comboResolver, costRules, etc.) +โ”œโ”€โ”€ lib/ # Core business logic (.ts) +โ”‚ โ”œโ”€โ”€ a2a/ # Agent-to-Agent v0.3 protocol server +โ”‚ โ”œโ”€โ”€ acp/ # Agent Communication Protocol registry +โ”‚ โ”œโ”€โ”€ compliance/ # Compliance policy engine +โ”‚ โ”œโ”€โ”€ db/ # SQLite database layer (21 modules + 16 migrations) +โ”‚ โ”œโ”€โ”€ memory/ # Persistent conversational memory +โ”‚ โ”œโ”€โ”€ oauth/ # OAuth providers, services, and utilities +โ”‚ โ”œโ”€โ”€ skills/ # Extensible skill framework +โ”‚ โ”œโ”€โ”€ usage/ # Usage tracking and cost calculation +โ”‚ โ””โ”€โ”€ localDb.ts # Re-export layer only โ€” never add logic here +โ”œโ”€โ”€ middleware/ # Request middleware (promptInjectionGuard) +โ”œโ”€โ”€ mitm/ # MITM proxy (cert, DNS, target routing) +โ”œโ”€โ”€ shared/ +โ”‚ โ”œโ”€โ”€ components/ # React components (.tsx) +โ”‚ โ”œโ”€โ”€ constants/ # Provider definitions (60+), MCP scopes, routing strategies +โ”‚ โ”œโ”€โ”€ utils/ # Circuit breaker, sanitizer, auth helpers +โ”‚ โ””โ”€โ”€ validation/ # Zod v4 schemas +โ””โ”€โ”€ sse/ # SSE proxy pipeline + +open-sse/ # @omniroute/open-sse workspace +โ”œโ”€โ”€ executors/ # 14 provider-specific request executors +โ”œโ”€โ”€ handlers/ # 11 request handlers (chat, responses, embeddings, images, etc.) +โ”œโ”€โ”€ mcp-server/ # MCP server (25 tools, 3 transports, 10 scopes) +โ”œโ”€โ”€ services/ # 36+ services (combo, autoCombo, rateLimitManager, etc.) +โ”œโ”€โ”€ translator/ # Format translators (OpenAI โ†” Claude โ†” Gemini โ†” Responses โ†” Ollama) +โ”œโ”€โ”€ transformer/ # Responses API transformer +โ””โ”€โ”€ utils/ # 22 utility modules (stream, TLS, proxy, logging) + +electron/ # Electron desktop app (cross-platform) + +tests/ +โ”œโ”€โ”€ unit/ # Node.js test runner (122 test files) +โ”œโ”€โ”€ integration/ # Integration tests +โ”œโ”€โ”€ e2e/ # Playwright tests +โ”œโ”€โ”€ security/ # Security tests +โ”œโ”€โ”€ translator/ # Translator-specific tests +โ””โ”€โ”€ load/ # Load tests + +docs/ # Documentation +โ”œโ”€โ”€ ARCHITECTURE.md # System architecture +โ”œโ”€โ”€ API_REFERENCE.md # All endpoints +โ”œโ”€โ”€ USER_GUIDE.md # Provider setup, CLI integration +โ”œโ”€โ”€ TROUBLESHOOTING.md # Common issues +โ”œโ”€โ”€ MCP-SERVER.md # MCP server (25 tools) +โ”œโ”€โ”€ A2A-SERVER.md # A2A agent protocol +โ”œโ”€โ”€ AUTO-COMBO.md # Auto-combo engine +โ”œโ”€โ”€ CLI-TOOLS.md # CLI tools integration +โ”œโ”€โ”€ COVERAGE_PLAN.md # Test coverage improvement plan +โ”œโ”€โ”€ openapi.yaml # OpenAPI specification +โ””โ”€โ”€ adr/ # Architecture Decision Records +``` + +--- + +## Adding a New Provider + +### Step 1: Register Provider Constants + +Add to `src/shared/constants/providers.ts` โ€” Zod-validated at module load. + +### Step 2: Add Executor (if custom logic needed) + +Create executor in `open-sse/executors/your-provider.ts` extending the base executor. + +### Step 3: Add Translator (if non-OpenAI format) + +Create request/response translators in `open-sse/translator/`. + +### Step 4: Add OAuth Config (if OAuth-based) + +Add OAuth credentials in `src/lib/oauth/constants/oauth.ts` and service in `src/lib/oauth/services/`. + +### Step 5: Register Models + +Add model definitions in `open-sse/config/providerRegistry.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 +- [ ] All inputs validated with Zod schemas +- [ ] CHANGELOG updated (if user-facing change) +- [ ] Documentation updated (if applicable) + +--- + +## Releasing + +Releases are managed via the `/generate-release` workflow. When a new GitHub Release is created, the package is **automatically published to npm** via GitHub Actions. + +--- + +## Getting Help + +- **Architecture**: See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) +- **API Reference**: See [`docs/API_REFERENCE.md`](docs/API_REFERENCE.md) +- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **ADRs**: See `docs/adr/` for architectural decision records diff --git a/docs/i18n/nl/FEATURES.md b/docs/i18n/nl/FEATURES.md deleted file mode 100644 index 98af59014e..0000000000 --- a/docs/i18n/nl/FEATURES.md +++ /dev/null @@ -1,147 +0,0 @@ -# OmniRoute โ€” Dashboard Features Gallery (Nederlands) - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) - -> ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../docs/FEATURES.md) - ---- - -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 (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. - -![Providers Dashboard](screenshots/01-providers.png) - ---- - -## ๐ŸŽจ Combos - -Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. - -![Combos Dashboard](screenshots/02-combos.png) - ---- - -## ๐Ÿ“Š Analytics - -Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. - -![Analytics Dashboard](screenshots/03-analytics.png) - ---- - -## ๐Ÿฅ System Health - -Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. - -![Health Dashboard](screenshots/04-health.png) - ---- - -## ๐Ÿ”ง Translator Playground - -Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). - -![Translator Playground](screenshots/05-translator.png) - ---- - -## ๐ŸŽฎ Model Playground _(v2.0.9+)_ - -Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. - ---- - -## ๐ŸŽจ Themes _(v2.0.5+)_ - -Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. - ---- - -## โš™๏ธ Settings - -Comprehensive settings panel with tabs: - -- **General** โ€” System storage, backup management (export/import database) -- **Appearance** โ€” Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls -- **Security** โ€” API endpoint protection, custom provider blocking, IP filtering, session info -- **Routing** โ€” Model aliases, background task degradation -- **Resilience** โ€” Rate limit persistence, circuit breaker tuning -- **Advanced** โ€” Configuration overrides - -![Settings Dashboard](screenshots/06-settings.png) - ---- - -## ๐Ÿ”ง CLI Tools - -One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. - -![CLI Tools Dashboard](screenshots/07-cli-tools.png) - ---- - -## ๐Ÿค– CLI Agents _(v2.0.11+)_ - -Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: - -- **Installation status** โ€” Installed / Not Found with version detection -- **Protocol badges** โ€” stdio, HTTP, etc. -- **Custom agents** โ€” Register any CLI tool via form (name, binary, version command, spawn args) -- **CLI Fingerprint Matching** โ€” Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP - ---- - -## ๐Ÿ–ผ๏ธ Media _(v2.0.3+)_ - -Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. - ---- - -## ๐Ÿ“ Request Logs - -Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. - -![Usage Logs](screenshots/08-usage.png) - ---- - -## ๐ŸŒ API Endpoint - -Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. - -![Endpoint Dashboard](screenshots/09-endpoint.png) - ---- - -## ๐Ÿ”‘ API Key Management - -Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. - ---- - -## ๐Ÿ“‹ Audit Log - -Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. - ---- - -## ๐Ÿ–ฅ๏ธ Desktop Application - -Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. - -Key features: - -- Server readiness polling (no blank screen on cold start) -- System tray with port management -- Content Security Policy -- Single-instance lock -- Auto-update on restart -- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) -- Hardened Electron build packaging โ€” symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+) - -๐Ÿ“– See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/nl/MCP-SERVER.md b/docs/i18n/nl/MCP-SERVER.md deleted file mode 100644 index 829acd30b1..0000000000 --- a/docs/i18n/nl/MCP-SERVER.md +++ /dev/null @@ -1,87 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/MCP-SERVER.md) - ---- - -# OmniRoute MCP Server Documentation - -> Model Context Protocol server with 16 intelligent tools - -## Installation - -OmniRoute MCP is built-in. Start it with: - -```bash -omniroute --mcp -``` - -Or via the open-sse transport: - -```bash -# HTTP streamable transport (port 20130) -omniroute --dev # MCP auto-starts on /mcp endpoint -``` - -## IDE Configuration - -See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup. - ---- - -## Essential Tools (8) - -| Tool | Description | -| :------------------------------ | :--------------------------------------- | -| `omniroute_get_health` | Gateway health, circuit breakers, uptime | -| `omniroute_list_combos` | All configured combos with models | -| `omniroute_get_combo_metrics` | Performance metrics for a specific combo | -| `omniroute_switch_combo` | Switch active combo by ID/name | -| `omniroute_check_quota` | Quota status per provider or all | -| `omniroute_route_request` | Send a chat completion through OmniRoute | -| `omniroute_cost_report` | Cost analytics for a time period | -| `omniroute_list_models_catalog` | Full model catalog with capabilities | - -## Advanced Tools (8) - -| Tool | Description | -| :--------------------------------- | :---------------------------------------------- | -| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | -| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | -| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | -| `omniroute_test_combo` | Live-test all models in a combo | -| `omniroute_get_provider_metrics` | Detailed metrics for one provider | -| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | -| `omniroute_explain_route` | Explain a past routing decision | -| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | - -## Authentication - -MCP tools are authenticated via API key scopes. Each tool requires specific scopes: - -| Scope | Tools | -| :------------- | :----------------------------------------------- | -| `read:health` | get_health, get_provider_metrics | -| `read:combos` | list_combos, get_combo_metrics | -| `write:combos` | switch_combo | -| `read:quota` | check_quota | -| `write:route` | route_request, simulate_route, test_combo | -| `read:usage` | cost_report, get_session_snapshot, explain_route | -| `write:config` | set_budget_guard, set_resilience_profile | -| `read:models` | list_models_catalog, best_combo_for_task | - -## Audit Logging - -Every tool call is logged to `mcp_tool_audit` with: - -- Tool name, arguments, result -- Duration (ms), success/failure -- API key hash, timestamp - -## Files - -| File | Purpose | -| :------------------------------------------- | :------------------------------------------ | -| `open-sse/mcp-server/server.ts` | MCP server creation + 16 tool registrations | -| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport | -| `open-sse/mcp-server/auth.ts` | API key + scope validation | -| `open-sse/mcp-server/audit.ts` | Tool call audit logging | -| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers | diff --git a/docs/i18n/nl/README.md b/docs/i18n/nl/README.md index a2c4a2b985..ee8366735e 100644 --- a/docs/i18n/nl/README.md +++ b/docs/i18n/nl/README.md @@ -1,12 +1,12 @@ # ๐Ÿš€ OmniRoute โ€” The Free AI Gateway (Nederlands) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/README.md) --- ### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback. -_Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._ +_Your universal API proxy โ€” one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._ **Chat Completions โ€ข Embeddings โ€ข Image Generation โ€ข Video โ€ข Music โ€ข Audio โ€ข Reranking โ€ข **Web Search** โ€ข MCP Server โ€ข A2A Protocol โ€ข 100% TypeScript** @@ -46,15 +46,17 @@ _Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now wi > - `APP_LOG_FILE_PATH` > - `APP_LOG_MAX_FILE_SIZE` > - `APP_LOG_RETENTION_DAYS` +> - `APP_LOG_MAX_FILES` > - `APP_LOG_LEVEL` > - `APP_LOG_FORMAT` > - `CALL_LOG_RETENTION_DAYS` +> - `CALL_LOG_MAX_ENTRIES` > > For release details and upgrade notes, see the [CHANGELOG](CHANGELOG.md). --- -## ๐Ÿ†• What's New in v3.0.0 +## ๐Ÿ†• What's New > **Upgrading from v2.9.5?** โ€” See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes. @@ -274,7 +276,7 @@ Developers pay $20โ€“200/month for Claude Pro, Codex Pro, or GitHub Copilot. Eve - **Smart 4-Tier Fallback** โ€” If subscription quota runs out, automatically redirects to API Key โ†’ Cheap โ†’ Free with zero manual intervention - **Real-Time Quota Tracking** โ€” Shows token consumption in real-time with reset countdown (5h, daily, weekly) - **Multi-Account Support** โ€” Multiple accounts per provider with auto round-robin โ€” when one runs out, switches to the next -- **Custom Combos** โ€” Customizable fallback chains with 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Custom Combos** โ€” Customizable fallback chains with 9 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random) - **Codex Business Quotas** โ€” Business/Team workspace quota monitoring directly in the dashboard @@ -286,7 +288,7 @@ OpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If **How OmniRoute solves it:** -- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 67+ providers +- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 60+ providers - **Format Translation** โ€” Automatic and transparent: OpenAI โ†” Claude โ†” Gemini โ†” Responses API - **Response Sanitization** โ€” Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+ - **Role Normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI providers; `system` โ†’ `user` for GLM/ERNIE @@ -372,7 +374,7 @@ Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code.. - **CLI Tools Dashboard** โ€” Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline - **GitHub Copilot Config Generator** โ€” Generates `chatLanguageModels.json` for VS Code with bulk model selection - **Onboarding Wizard** โ€” Guided 4-step setup for first-time users -- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 67+ providers +- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 60+ providers @@ -419,7 +421,7 @@ When a call fails, the dev doesn't know if it was a rate limit, expired token, w - **SQLite Proxy Logs** โ€” Persistent logs that survive server restarts - **Translator Playground** โ€” 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time) - **Request Telemetry** โ€” p50/p95/p99 latency + X-Request-Id tracing -- **File-Based Logging with Rotation** โ€” Console interceptor captures everything to JSON log with size-based rotation +- **File-Based Logging with Rotation** โ€” App logs rotate by size, retention days, and archive count; call log artifacts rotate by retention days and file count - **System Info Report** โ€” `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage. @@ -514,7 +516,7 @@ Developers who want all responses in a specific language, with a specific tone, - **System Prompt Injection** โ€” Global prompt applied to all requests - **Thinking Budget Validation** โ€” Reasoning token allocation control per request (passthrough, auto, custom, adaptive) -- **6 Routing Strategies** โ€” Global strategies that determine how requests are distributed +- **9 Routing Strategies** โ€” Global strategies that determine how requests are distributed - **Wildcard Router** โ€” `provider/*` patterns route dynamically to any provider - **Combo Enable/Disable Toggle** โ€” Toggle combos directly from the dashboard - **Provider Toggle** โ€” Enable/disable all connections for a provider with one click @@ -581,7 +583,7 @@ Different clients should have least-privilege access to tool categories. **How OmniRoute solves it:** -- 9 granular MCP scopes for controlled tool access +- 10 granular MCP scopes for controlled tool access - Scope enforcement and visibility in MCP management UI - Safe default posture for operational tooling @@ -1325,19 +1327,19 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. ### ๐Ÿค– Agent & Protocol Operations (v2.0) -| Feature | What It Does | -| ------------------------------------- | -------------------------------------------------------------------------------------------------- | -| ๐Ÿ”ง **MCP Server (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) | -| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | -| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | -| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | -| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | -| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | -| ๐Ÿ” **MCP Scope Enforcement** | 9 granular scope permissions for controlled tool access | -| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | -| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | -| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | -| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | +| Feature | What It Does | +| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| ๐Ÿ”ง **MCP Server (25 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools | +| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | +| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | +| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | +| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | +| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | +| ๐Ÿ” **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access | +| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | +| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | +| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | +| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | ### ๐Ÿง  Routing & Intelligence @@ -1348,7 +1350,7 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. | ๐Ÿ”„ **Format Translation** | OpenAI โ†” Claude โ†” Gemini โ†” Responses with schema-safe conversions | | ๐Ÿ‘ฅ **Multi-Account Support** | Multiple accounts per provider with intelligent selection | | ๐Ÿ”„ **Auto Token Refresh** | OAuth tokens refresh automatically with retry | -| ๐ŸŽจ **Custom Combos** | 6 balancing strategies + fallback chain control | +| ๐ŸŽจ **Custom Combos** | 9 balancing strategies + fallback chain control | | ๐ŸŒ **Wildcard Router** | `provider/*` dynamic routing | | ๐Ÿง  **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits | | ๐Ÿ”€ **Model Aliases** | Built-in + custom model aliasing and migration safety | @@ -1949,6 +1951,7 @@ opencode - Request artifacts are written to `DATA_DIR/call_logs/` as one JSON file per request - Enable pipeline capture from Dashboard โ†’ Logs โ†’ Request Logs if you need detailed per-stage payloads - Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log` +- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed **Connection test shows "Invalid" for OpenAI-compatible providers** diff --git a/docs/i18n/nl/RELEASE_CHECKLIST.md b/docs/i18n/nl/RELEASE_CHECKLIST.md deleted file mode 100644 index 903e812c3f..0000000000 --- a/docs/i18n/nl/RELEASE_CHECKLIST.md +++ /dev/null @@ -1,37 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/RELEASE_CHECKLIST.md) - ---- - -# Release Checklist - -Use this checklist before tagging or publishing a new OmniRoute release. - -## Version and Changelog - -1. Bump `package.json` version (`x.y.z`) in the release branch. -2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: - - `## [x.y.z] โ€” YYYY-MM-DD` -3. Keep `## [Unreleased]` as the first changelog section for upcoming work. -4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. - -## API Docs - -1. Update `docs/openapi.yaml`: - - `info.version` must equal `package.json` version. -2. Validate endpoint examples if API contracts changed. - -## Runtime Docs - -1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. -2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. -3. Update localized docs if source docs changed significantly. - -## Automated Check - -Run the sync guard locally before opening PR: - -```bash -npm run check:docs-sync -``` - -CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/nl/SECURITY.md b/docs/i18n/nl/SECURITY.md new file mode 100644 index 0000000000..9135536583 --- /dev/null +++ b/docs/i18n/nl/SECURITY.md @@ -0,0 +1,179 @@ +# Security Policy (Nederlands) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../SECURITY.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/SECURITY.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/SECURITY.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/SECURITY.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/SECURITY.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/SECURITY.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/SECURITY.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/SECURITY.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/SECURITY.md) + +--- + +## 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 | +| ------- | -------------- | +| 3.4.x | โœ… Active | +| 3.0.x | โœ… Security | +| < 3.0.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 | +| **MCP Scopes** | 10 granular scopes for MCP tool access control | + +### ๐Ÿ›ก๏ธ 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:::` +- 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** | Allowlist/blocklist IP ranges in dashboard | +| **Rate Limiting** | Per-provider rate limits with automatic backoff | +| **Anti-Thundering Herd** | Mutex + per-connection locking prevents cascading 502s | +| **TLS Fingerprint** | Browser-like TLS fingerprint spoofing to reduce bot detection | +| **CLI Fingerprint** | Per-provider header/body ordering to match native CLI signatures | + +### ๐Ÿ”Œ Resilience & Availability + +| 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 `CALL_LOG_RETENTION_DAYS` | +| **No-Log Opt-out** | Per API key `noLog` flag disables request logging | +| **Audit Log** | Administrative actions tracked in `audit_log` table | +| **MCP Audit** | SQLite-backed audit logging for all MCP tool calls | +| **Zod Validation** | All API inputs validated with Zod v4 schemas at module load | + +--- + +## 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 +- Provider constants validated at module load via Zod (`src/shared/validation/providerSchema.ts`) diff --git a/docs/i18n/nl/TROUBLESHOOTING.md b/docs/i18n/nl/TROUBLESHOOTING.md deleted file mode 100644 index 63c148000a..0000000000 --- a/docs/i18n/nl/TROUBLESHOOTING.md +++ /dev/null @@ -1,258 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/TROUBLESHOOTING.md) - ---- - -# Troubleshooting - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/TROUBLESHOOTING.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/TROUBLESHOOTING.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/TROUBLESHOOTING.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/TROUBLESHOOTING.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/TROUBLESHOOTING.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/TROUBLESHOOTING.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/TROUBLESHOOTING.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/TROUBLESHOOTING.md) - -Common problems and solutions for OmniRoute. - ---- - -## Quick Fixes - -| Problem | Solution | -| ----------------------------- | ------------------------------------------------------------------ | -| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | -| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | -| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | -| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | -| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | - ---- - -## Provider Issues - -### "Language model did not provide messages" - -**Cause:** Provider quota exhausted. - -**Fix:** - -1. 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, Qoder) 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}/storage.sqlite` (providers, combos, aliases, keys, settings) -- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` -- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) - ---- - -## Circuit Breaker Issues - -### Provider stuck in OPEN state - -When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. - -**Fix:** - -1. 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 -- **SDK returns raw string instead of object** โ€” Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures -- **GLM/ERNIE rejects `system` role** โ€” Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models -- **`developer` role not recognized** โ€” Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers -- **`json_schema` not working with Gemini** โ€” Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` - ---- - -## Resilience Settings - -### Auto rate-limit not triggering - -- 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. - ---- - -## Optional RAG / LLM failure taxonomy (16 problems) - -Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. - -In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. - -If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: - -- retrieval drift and broken context boundaries -- empty or stale indexes and vector stores -- embedding versus semantic mismatch -- prompt assembly and context window issues -- logic collapse and overconfident answers -- long chain and agent coordination failures -- multi agent memory and role drift -- deployment and bootstrap ordering problems - -The idea is simple: - -1. When you investigate a bad response, capture: - - user task and request - - route or provider combo in OmniRoute - - any RAG context used downstream (retrieved documents, tool calls, etc) -2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` โ€ฆ `No.16`). -3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. -4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. - -Full text and concrete recipes live here (MIT license, text only): - -[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) - -You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. - ---- - -## Still Stuck? - -- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details -- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints -- **Health Dashboard**: Check **Dashboard โ†’ Health** for real-time system status -- **Translator**: Use **Dashboard โ†’ Translator** to debug format issues diff --git a/docs/i18n/nl/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/nl/VM_DEPLOYMENT_GUIDE.md deleted file mode 100644 index 3436af2522..0000000000 --- a/docs/i18n/nl/VM_DEPLOYMENT_GUIDE.md +++ /dev/null @@ -1,401 +0,0 @@ -# OmniRoute โ€” Implementatiehandleiding op VM met Cloudflare - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](../pt-BR/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](../es/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](../fr/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](../it/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](../ru/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](../zh-CN/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](../de/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](../in/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](../th/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](../uk-UA/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](../ar/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](../ja/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](../vi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](../bg/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](../da/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](../fi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](../he/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](../hu/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](../id/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](../ko/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](../ms/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](../nl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](../no/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](../pt/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](../ro/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](../pl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](../sk/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](../sv/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](../phi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](../cs/VM_DEPLOYMENT_GUIDE.md) - -Volledige gids voor het installeren en configureren van OmniRoute op een VM (VPS) met een domein beheerd via Cloudflare. - ---- - -## Vereisten - -| Artikel | Minimaal | Aanbevolen | -| --------------------- | --------------------------- | --------------- | -| **CPU** | 1 vCPU | 2 vCPU | -| **RAM** | 1 GB | 2 GB | -| **Schijf** | 10 GB SSD | 25 GB SSD | -| **Besturingssysteem** | Ubuntu 22.04LTS | Ubuntu 24.04LTS | -| **Domein** | Geregistreerd op Cloudflare | โ€” | -| **Dokker** | Docker-engine 24+ | Dokwerker 27+ | - -**Geteste providers**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. - ---- - -## 1. Configureer de VM - -### 1.1 Maak het exemplaar - -Op uw favoriete VPS-provider: - -- Kies Ubuntu 24.04 LTS -- Selecteer het minimale abonnement (1 vCPU / 1 GB RAM) -- Stel een sterk rootwachtwoord in of configureer de SSH-sleutel -- Noteer het **openbare IP** (bijvoorbeeld `203.0.113.10`) - -### 1.2 Verbinding maken via SSH - -```bash -ssh root@203.0.113.10 -``` - -### 1.3 Update het systeem - -```bash -apt update && apt upgrade -y -``` - -### 1.4 Docker installeren - -```bash -# Install dependencies -apt install -y ca-certificates curl gnupg - -# Add official Docker repository -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 Installeer nginx - -```bash -apt install -y nginx -``` - -### 1.6 Firewall configureren (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 -``` - -> **Tip**: Voor maximale veiligheid beperkt u poort 80 en 443 alleen tot Cloudflare IP's. Zie de sectie [Advanced Security](#advanced-security). - ---- - -## 2. Installeer OmniRoute - -### 2.1 Maak een configuratiedirectory - -```bash -mkdir -p /opt/omniroute -``` - -### 2.2 Maak een bestand met omgevingsvariabelen - -```bash -cat > /opt/omniroute/.env << โ€˜EOFโ€™ -# === Security === -JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY -INITIAL_PASSWORD=YourSecurePassword123! -API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY -STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY -STORAGE_ENCRYPTION_KEY_VERSION=v1 -MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT - -# === 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 (change to your domain) === -BASE_URL=https://llms.seudominio.com -NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com - -# === Cloud Sync (optional) === -# CLOUD_URL=https://cloud.omniroute.online -# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online -EOF -``` - -> โš ๏ธ **BELANGRIJK**: Genereer unieke geheime sleutels! Gebruik `openssl rand -hex 32` voor elke sleutel. - -### 2.3 Start de 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 Controleer of het actief is - -```bash -docker ps | grep omniroute -docker logs omniroute --tail 20 -``` - -Het zou moeten verschijnen: `[DB] SQLite database ready` en `listening on port 20128`. - ---- - -## 3. Nginx configureren (Reverse Proxy) - -### 3.1 SSL-certificaat genereren (Cloudflare Origin) - -In het Cloudflare-dashboard: - -1. Ga naar **SSL/TLS โ†’ Origin Server** -2. Klik op **Certificaat maken** -3. Behoud de standaardwaarden (15 jaar, \*.uwdomein.com) -4. Kopieer het **Oorsprongscertificaat** en de **Privรฉsleutel** - -```bash -mkdir -p /etc/nginx/ssl - -# Paste the certificate -nano /etc/nginx/ssl/origin.crt - -# Paste the private key -nano /etc/nginx/ssl/origin.key - -chmod 600 /etc/nginx/ssl/origin.key -``` - -### 3.2 Nginx-configuratie - -```bash -cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ -# Default server โ€” blocks direct access via 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.yourdomain.com; # Change to your domain - - 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.yourdomain.com; - return 301 https://$server_name$request_uri; -} -NGINX -``` - -### 3.3 Inschakelen en testen - -```bash -# Remove default configuration -rm -f /etc/nginx/sites-enabled/default - -# Enable OmniRoute -ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute - -# Test and reload -nginx -t && systemctl reload nginx -``` - ---- - -## 4. Configureer Cloudflare DNS - -### 4.1 DNS-record toevoegen - -In het Cloudflare-dashboard โ†’ DNS: - -| Typ | Naam | Inhoud | Proxy | -| --- | ------ | ---------------------- | ---------------- | -| Een | `llms` | `203.0.113.10` (VM-IP) | โœ… Gevolmachtigd | - -### 4.2 SSL configureren - -Onder **SSL/TLS โ†’ Overzicht**: - -- Modus: **Volledig (streng)** - -Onder **SSL/TLS โ†’ Edge-certificaten**: - -- Gebruik altijd HTTPS: โœ… Aan -- Minimale TLS-versie: TLS 1.2 -- Automatische HTTPS-herschrijvingen: โœ… Aan - -### 4.3 Testen - -```bash -curl -sI https://llms.seudominio.com/health -# Should return HTTP/2 200 -``` - ---- - -## 5. Bediening en onderhoud - -### Upgrade naar een nieuwe versie - -```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 -``` - -### Logboeken bekijken - -```bash -docker logs -f omniroute # Real-time stream -docker logs omniroute --tail 50 # Last 50 lines -``` - -### Handmatige databaseback-up - -```bash -# Copy data from the volume to the host -docker cp omniroute:/app/data ./backup-$(date +%F) - -# Or compress the entire volume -docker run --rm -v omniroute-data:/data -v $(pwd):/backup \ - alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data -``` - -### Herstellen vanaf back-up - -```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. Geavanceerde beveiliging - -### Beperk nginx tot Cloudflare IP's - -```bash -cat > /etc/nginx/cloudflare-ips.conf << โ€˜CFโ€™ -# Cloudflare IPv4 ranges โ€” update periodically -# 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 -``` - -Voeg het volgende toe aan `nginx.conf` in het blok `http {}`: - -```nginx -include /etc/nginx/cloudflare-ips.conf; -``` - -### Installeer fail2ban - -```bash -apt install -y fail2ban -systemctl enable fail2ban -systemctl start fail2ban - -# Check status -fail2ban-client status sshd -``` - -### Blokkeer directe toegang tot de Docker-poort - -```bash -# Prevent direct external access to port 20128 -iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP -iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT - -# Persist the rules -apt install -y iptables-persistent -netfilter-persistent save -``` - ---- - -## 7. Implementeren naar Cloudflare-werknemers (optioneel) - -Voor externe toegang via Cloudflare Workers (zonder de VM rechtstreeks bloot te leggen): - -```bash -# In the local repository -cd omnirouteCloud -npm install -npx wrangler login -npx wrangler deploy -``` - -Bekijk de volledige documentatie op [omnirouteCloud/README.md](../omnirouteCloud/README.md). - ---- - -## Poortsamenvatting - -| Haven | Dienst | Toegang | -| ----- | ----------- | ---------------------------- | -| 22 | SSH | Openbaar (met fail2ban) | -| 80 | nginx-HTTP | Omleiding โ†’ HTTPS | -| 443 | nginx-HTTPS | Via Cloudflare Proxy | -| 20128 | OmniRoute | Alleen Localhost (via nginx) | diff --git a/docs/i18n/nl/docs/A2A-SERVER.md b/docs/i18n/nl/docs/A2A-SERVER.md new file mode 100644 index 0000000000..4b8f43c669 --- /dev/null +++ b/docs/i18n/nl/docs/A2A-SERVER.md @@ -0,0 +1,200 @@ +# OmniRoute A2A Server Documentation (Nederlands) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/A2A-SERVER.md) + +--- + +> Agent-to-Agent Protocol v0.3 โ€” OmniRoute as an intelligent routing agent + +## Agent Discovery + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements. + +--- + +## Authentication + +All `/a2a` requests require an API key via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server, authentication is bypassed. + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Sends a message to a skill and waits for the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a hello world in Python"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "uuid", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "..." }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}} + +: heartbeat 2026-03-03T17:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Available Skills + +| Skill | Description | +| :----------------- | :------------------------------------------------------------------------------------------------------------------------------ | +| `smart-routing` | Routes prompts through OmniRoute's intelligent pipeline. Returns response with routing explanation, cost, and resilience trace. | +| `quota-management` | Answers natural-language queries about provider quotas, suggests free combos, and provides quota rankings. | + +--- + +## Task Lifecycle + +``` +submitted โ†’ working โ†’ completed + โ†’ failed + โ†’ cancelled +``` + +- Tasks expire after 5 minutes (configurable) +- Terminal states: `completed`, `failed`, `cancelled` +- Event log tracks every state transition + +--- + +## Error Codes + +| Code | Meaning | +| :----- | :----------------------------- | +| -32700 | Parse error (invalid JSON) | +| -32600 | Invalid request / Unauthorized | +| -32601 | Method or skill not found | +| -32602 | Invalid params | +| -32603 | Internal error | + +--- + +## Integration Examples + +### Python (requests) + +```python +import requests + +resp = requests.post("http://localhost:20128/a2a", json={ + "jsonrpc": "2.0", "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Hello"}] + } +}, headers={"Authorization": "Bearer YOUR_KEY"}) + +result = resp.json()["result"] +print(result["artifacts"][0]["content"]) +print(result["metadata"]["routing_explanation"]) +``` + +### TypeScript (fetch) + +```typescript +const resp = await fetch("http://localhost:20128/a2a", { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: "Bearer YOUR_KEY", + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "1", + method: "message/send", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Hello" }], + }, + }), +}); +const { result } = await resp.json(); +console.log(result.metadata.routing_explanation); +``` diff --git a/docs/i18n/nl/docs/API_REFERENCE.md b/docs/i18n/nl/docs/API_REFERENCE.md new file mode 100644 index 0000000000..42678fd74d --- /dev/null +++ b/docs/i18n/nl/docs/API_REFERENCE.md @@ -0,0 +1,465 @@ +# API Reference (Nederlands) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/API_REFERENCE.md) + +--- + +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 | +| `X-Session-Id` | Request | Sticky session key for external session affinity | +| `x_session_id` | Request | Underscore variant also accepted (direct HTTP) | +| `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 | +| `X-OmniRoute-Session-Id` | Response | Effective session ID used by OmniRoute | + +> Nginx note: if you rely on underscore headers (for example `x_session_id`), enable `underscores_in_headers 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/stats + +# Clear all caches +DELETE /api/cache/stats +``` + +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/PATCH | 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 + provider summary (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`) | +| `/api/cache/stats` | 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 | + +### Tunnels + +| Endpoint | Method | Description | +| -------------------------- | ------ | ----------------------------------------------------------------------- | +| `/api/tunnels/cloudflared` | GET | Read Cloudflare Quick Tunnel install/runtime status for the dashboard | +| `/api/tunnels/cloudflared` | POST | Enable or disable the Cloudflare Quick Tunnel (`action=enable/disable`) | + +### 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`. + +### ACP Agents + +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | + +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). + +### Resilience & Rate Limits + +| Endpoint | Method | Description | +| ----------------------- | --------- | ------------------------------- | +| `/api/resilience` | GET/PATCH | 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` diff --git a/docs/i18n/nl/docs/ARCHITECTURE.md b/docs/i18n/nl/docs/ARCHITECTURE.md new file mode 100644 index 0000000000..e4c347f704 --- /dev/null +++ b/docs/i18n/nl/docs/ARCHITECTURE.md @@ -0,0 +1,814 @@ +# OmniRoute Architecture (Nederlands) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/ARCHITECTURE.md) + +--- + +_Last updated: 2026-03-28_ + +## 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 (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developerโ†’system, systemโ†’user) for cross-provider compatibility +- Structured output conversion (json_schema โ†’ Gemini responseSchema) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) +- Global system prompt injection +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout โ†’ budget โ†’ fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) + +Primary runtime model: + +- Next.js 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.) + +## Dashboard Surface (Current) + +Main pages under `src/app/(dashboard)/dashboard/`: + +- `/dashboard` โ€” quick start + provider overview +- `/dashboard/endpoint` โ€” endpoint proxy + MCP + A2A + API endpoint tabs +- `/dashboard/providers` โ€” provider connections and credentials +- `/dashboard/combos` โ€” combo strategies, templates, model routing rules +- `/dashboard/costs` โ€” cost aggregation and pricing visibility +- `/dashboard/analytics` โ€” usage analytics and evaluations +- `/dashboard/limits` โ€” quota/rate controls +- `/dashboard/cli-tools` โ€” CLI onboarding, runtime detection, config generation +- `/dashboard/agents` โ€” detected ACP agents + custom agent registration +- `/dashboard/media` โ€” image/video/music playground +- `/dashboard/search-tools` โ€” search provider testing and history +- `/dashboard/health` โ€” uptime, circuit breakers, rate limits +- `/dashboard/logs` โ€” request/proxy/audit/console logs +- `/dashboard/settings` โ€” system settings tabs (general, routing, combo defaults, etc.) +- `/dashboard/api-manager` โ€” API key lifecycle and model permissions + +## 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[(storage.sqlite)] + UDB[(usage tables + log artifacts)] + end + + subgraph Upstreams[Upstream Providers] + P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/Qoder/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/route.ts` (GET) +- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- OAuth: `src/app/api/oauth/*` +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` +- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI tooling helpers: `src/app/api/cli-tools/*` +- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) +- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) โ€” provider profiles, circuit breaker, rate limit state +- Resilience reset: `src/app/api/resilience/reset` (POST) โ€” reset breakers + cooldowns +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) +- Telemetry: `src/app/api/telemetry/summary` (GET) +- Budget: `src/app/api/usage/budget` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Policies: `src/app/api/policies` (GET/POST) + +## 2) SSE + 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` +- Response sanitization: `open-sse/handlers/responseSanitizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.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`, `qoder.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 (SQLite): + +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** + +Usage persistence: + +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present + +Domain State DB (SQLite): + +- `src/lib/db/domainState.ts` โ€” CRUD operations 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`, `src/shared/services/modelSyncScheduler.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Periodic task: `src/shared/services/modelSyncScheduler.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. Combo routing adds one extra guard: provider-scoped 400s such as upstream content-block and role-validation failures are treated as model-local failures so later combo targets can still run. + +## 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: + +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` + +## Deployment Topology + +```mermaid +flowchart LR + 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[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] + end + + subgraph External[External Services] + Providers[AI Providers] + SyncCloud[Cloud Sync Service] + end + + CLI --> Next + Browser --> Next + Next --> Core + Next --> MainDB + Core --> MainDB + Core --> UsageDB + Core --> Providers + Next --> SyncCloud +``` + +## Module Mapping (Decision-Critical) + +### Route and API Modules + +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle +- `src/app/api/models/alias`: alias management +- `src/app/api/combos*`: fallback combo management +- `src/app/api/pricing`: pricing overrides for cost calculation +- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers +- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) +- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) +- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) +- `src/app/api/sessions`: active session listing (GET) +- `src/app/api/rate-limits`: per-account rate limit status (GET) + +### Routing and Execution Core + +- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior + +### Translation Registry and Format Converters + +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` +- Format constants: `open-sse/translator/formats.ts` + +### Persistence + +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables + +## Provider Executor Coverage (Strategy Pattern) + +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. + +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, Qoder, 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 | +| Qoder | openai | OAuth (Basic) | โœ… | โœ… | โœ… | โš ๏ธ Per request | +| OpenRouter | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| GLM/Kimi/MiniMax | claude | API Key | โœ… | โœ… | โŒ | โŒ | +| DeepSeek | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Groq | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| xAI (Grok) | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Mistral | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Perplexity | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Together AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Fireworks AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Cerebras | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Cohere | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| NVIDIA NIM | openai | API Key | โœ… | โœ… | โŒ | โŒ | + +## Format Translation Coverage + +Detected source formats include: + +- `openai` +- `openai-responses` +- `claude` +- `gemini` + +Target formats include: + +- OpenAI chat/Responses +- Claude +- Gemini/Gemini-CLI/Antigravity envelope +- Kiro +- Cursor + +Translations use **OpenAI as the hub format** โ€” all conversions go through OpenAI as intermediate: + +``` +Source Format โ†’ OpenAI (hub) โ†’ Target Format +``` + +Translations are selected dynamically based on source payload shape and provider target format. + +Additional processing layers in the translation pipeline: + +- **Response sanitization** โ€” Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI targets; merges `system` โ†’ `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** โ€” Parses `...` blocks from content into `reasoning_content` field +- **Structured output** โ€” Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` + +## Supported API Endpoints + +| 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` | Provider Models | Provider model metadata backing custom and managed available models | + +## 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 `/logs//` 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 + +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON โ†’ SQLite migration compatibility path + +## Observability and Operational Signals + +Runtime visibility sources: + +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- four-stage detailed payload captures in SQLite (`request_detail_logs`) when `settings.detailed_logs_enabled=true` +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption + +Detailed request payload capture stores up to four JSON payload stages per routed call: + +- raw request received from the client +- translated request actually sent upstream +- provider response reconstructed as JSON; streamed responses are compacted to the final summary plus stream metadata +- final client response returned by OmniRoute; streamed responses are stored in the same compact summary form + +## Security-Sensitive Boundaries + +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics + +## Environment and Runtime Matrix + +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` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). + +## Operational Verification Checklist + +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: +- `GET /api/settings` +- `GET /api/v1/models` +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/nl/docs/AUTO-COMBO.md b/docs/i18n/nl/docs/AUTO-COMBO.md new file mode 100644 index 0000000000..dbc66c9d1f --- /dev/null +++ b/docs/i18n/nl/docs/AUTO-COMBO.md @@ -0,0 +1,67 @@ +# OmniRoute Auto-Combo Engine (Nederlands) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/AUTO-COMBO.md) + +--- + +> Self-managing model chains with adaptive scoring + +## How It Works + +The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**: + +| Factor | Weight | Description | +| :--------- | :----- | :---------------------------------------------- | +| Quota | 0.20 | Remaining capacity [0..1] | +| Health | 0.25 | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 | +| CostInv | 0.20 | Inverse cost (cheaper = higher score) | +| LatencyInv | 0.15 | Inverse p95 latency (faster = higher) | +| TaskFit | 0.10 | Model ร— task type fitness score | +| Stability | 0.10 | Low variance in latency/errors | + +## Mode Packs + +| Pack | Focus | Key Weight | +| :---------------------- | :----------- | :--------------- | +| ๐Ÿš€ **Ship Fast** | Speed | latencyInv: 0.35 | +| ๐Ÿ’ฐ **Cost Saver** | Economy | costInv: 0.40 | +| ๐ŸŽฏ **Quality First** | Best model | taskFit: 0.40 | +| ๐Ÿ“ก **Offline Friendly** | Availability | quota: 0.40 | + +## Self-Healing + +- **Temporary exclusion**: Score < 0.2 โ†’ excluded for 5 min (progressive backoff, max 30 min) +- **Circuit breaker awareness**: OPEN โ†’ auto-excluded; HALF_OPEN โ†’ probe requests +- **Incident mode**: >50% OPEN โ†’ disable exploration, maximize stability +- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout + +## Bandit Exploration + +5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode. + +## API + +```bash +# Create auto-combo +curl -X POST http://localhost:20128/api/combos/auto \ + -H "Content-Type: application/json" \ + -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}' + +# List auto-combos +curl http://localhost:20128/api/combos/auto +``` + +## Task Fitness + +30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` โ†’ high coding score). + +## Files + +| File | Purpose | +| :------------------------------------------- | :------------------------------------ | +| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization | +| `open-sse/services/autoCombo/taskFitness.ts` | Model ร— task fitness lookup | +| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap | +| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode | +| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles | +| `src/app/api/combos/auto/route.ts` | REST API | diff --git a/docs/i18n/nl/docs/CLI-TOOLS.md b/docs/i18n/nl/docs/CLI-TOOLS.md new file mode 100644 index 0000000000..9a298733db --- /dev/null +++ b/docs/i18n/nl/docs/CLI-TOOLS.md @@ -0,0 +1,348 @@ +# CLI Tools Setup Guide โ€” OmniRoute (Nederlands) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CLI-TOOLS.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CLI-TOOLS.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CLI-TOOLS.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CLI-TOOLS.md) + +--- + +This guide explains how to install and configure all supported AI coding CLI tools +to use **OmniRoute** as the unified backend, giving you centralized key management, +cost tracking, model switching, and request logging across every tool. + +--- + +## How It Works + +``` +Claude / Codex / OpenCode / Cline / KiloCode / Continue / Kiro / Cursor / Copilot + โ”‚ + โ–ผ (all point to OmniRoute) + http://YOUR_SERVER:20128/v1 + โ”‚ + โ–ผ (OmniRoute routes to the right provider) + Anthropic / OpenAI / Gemini / DeepSeek / Groq / Mistral / ... +``` + +**Benefits:** + +- One API key to manage all tools +- Cost tracking across all CLIs in the dashboard +- Model switching without reconfiguring every tool +- Works locally and on remote servers (VPS) + +--- + +## Supported Tools (Dashboard Source of Truth) + +The dashboard cards in `/dashboard/cli-tools` are generated from `src/shared/constants/cliTools.ts`. +Current list (v3.0.0-rc.16): + +| Tool | ID | Command | Setup Mode | Install Method | +| ------------------ | ------------- | ---------- | ---------- | -------------- | +| **Claude Code** | `claude` | `claude` | env | npm | +| **OpenAI Codex** | `codex` | `codex` | custom | npm | +| **Factory Droid** | `droid` | `droid` | custom | bundled/CLI | +| **OpenClaw** | `openclaw` | `openclaw` | custom | bundled/CLI | +| **Cursor** | `cursor` | app | guide | desktop app | +| **Cline** | `cline` | `cline` | custom | npm | +| **Kilo Code** | `kilo` | `kilocode` | custom | npm | +| **Continue** | `continue` | extension | guide | VS Code | +| **Antigravity** | `antigravity` | internal | mitm | OmniRoute | +| **GitHub Copilot** | `copilot` | extension | custom | VS Code | +| **OpenCode** | `opencode` | `opencode` | guide | npm | +| **Kiro AI** | `kiro` | app/cli | mitm | desktop/CLI | + +### CLI fingerprint sync (Agents + Settings) + +`/dashboard/agents` and `Settings > CLI Fingerprint` use `src/shared/constants/cliCompatProviders.ts`. +This keeps provider IDs aligned with CLI cards and legacy IDs. + +| CLI ID | Fingerprint Provider ID | +| ---------------------------------------------------------------------------------------------------- | ----------------------- | +| `kilo` | `kilocode` | +| `copilot` | `github` | +| `claude` / `codex` / `antigravity` / `kiro` / `cursor` / `cline` / `opencode` / `droid` / `openclaw` | same ID | + +Legacy IDs still accepted for compatibility: `copilot`, `kimi-coding`, `qwen`. + +--- + +## Step 1 โ€” Get an OmniRoute API Key + +1. Open the OmniRoute dashboard โ†’ **API Manager** (`/dashboard/api-manager`) +2. Click **Create API Key** +3. Give it a name (e.g. `cli-tools`) and select all permissions +4. Copy the key โ€” you'll need it for every CLI below + +> Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` + +--- + +## Step 2 โ€” Install CLI Tools + +All npm-based tools require Node.js 18+: + +```bash +# Claude Code (Anthropic) +npm install -g @anthropic-ai/claude-code + +# OpenAI Codex +npm install -g @openai/codex + +# OpenCode +npm install -g opencode-ai + +# Cline +npm install -g cline + +# KiloCode +npm install -g kilocode + +# Kiro CLI (Amazon โ€” requires curl + unzip) +apt-get install -y unzip # on Debian/Ubuntu +curl -fsSL https://cli.kiro.dev/install | bash +export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc +``` + +**Verify:** + +```bash +claude --version # 2.x.x +codex --version # 0.x.x +opencode --version # x.x.x +cline --version # 2.x.x +kilocode --version # x.x.x (or: kilo --version) +kiro-cli --version # 1.x.x +``` + +--- + +## Step 3 โ€” Set Global Environment Variables + +Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`: + +```bash +# OmniRoute Universal Endpoint +export OPENAI_BASE_URL="http://localhost:20128/v1" +export OPENAI_API_KEY="sk-your-omniroute-key" +export ANTHROPIC_BASE_URL="http://localhost:20128/v1" +export ANTHROPIC_API_KEY="sk-your-omniroute-key" +export GEMINI_BASE_URL="http://localhost:20128/v1" +export GEMINI_API_KEY="sk-your-omniroute-key" +``` + +> For a **remote server** replace `localhost:20128` with the server IP or domain, +> e.g. `http://192.168.0.15:20128`. + +--- + +## Step 4 โ€” Configure Each Tool + +### Claude Code + +```bash +# Via CLI: +claude config set --global api-base-url http://localhost:20128/v1 + +# Or create ~/.claude/settings.json: +mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF +{ + "apiBaseUrl": "http://localhost:20128/v1", + "apiKey": "sk-your-omniroute-key" +} +EOF +``` + +**Test:** `claude "say hello"` + +--- + +### OpenAI Codex + +```bash +mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF +model: auto +apiKey: sk-your-omniroute-key +apiBaseUrl: http://localhost:20128/v1 +EOF +``` + +**Test:** `codex "what is 2+2?"` + +--- + +### OpenCode + +```bash +mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF +[provider.openai] +base_url = "http://localhost:20128/v1" +api_key = "sk-your-omniroute-key" +EOF +``` + +**Test:** `opencode` + +--- + +### Cline (CLI or VS Code) + +**CLI mode:** + +```bash +mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF +{ + "apiProvider": "openai", + "openAiBaseUrl": "http://localhost:20128/v1", + "openAiApiKey": "sk-your-omniroute-key" +} +EOF +``` + +**VS Code mode:** +Cline extension settings โ†’ API Provider: `OpenAI Compatible` โ†’ Base URL: `http://localhost:20128/v1` + +Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ Cline โ†’ Apply Config**. + +--- + +### KiloCode (CLI or VS Code) + +**CLI mode:** + +```bash +kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key +``` + +**VS Code settings:** + +```json +{ + "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", + "kilo-code.apiKey": "sk-your-omniroute-key" +} +``` + +Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ KiloCode โ†’ Apply Config**. + +--- + +### Continue (VS Code Extension) + +Edit `~/.continue/config.yaml`: + +```yaml +models: + - name: OmniRoute + provider: openai + model: auto + apiBase: http://localhost:20128/v1 + apiKey: sk-your-omniroute-key + default: true +``` + +Restart VS Code after editing. + +--- + +### Kiro CLI (Amazon) + +```bash +# Login to your AWS/Kiro account: +kiro-cli login + +# The CLI uses its own auth โ€” OmniRoute is not needed as backend for Kiro CLI itself. +# Use kiro-cli alongside OmniRoute for other tools. +kiro-cli status +``` + +--- + +### Cursor (Desktop App) + +> **Note:** Cursor routes requests through its cloud. For OmniRoute integration, +> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL. + +Via GUI: **Settings โ†’ Models โ†’ OpenAI API Key** + +- Base URL: `https://your-domain.com/v1` +- API Key: your OmniRoute key + +--- + +## Dashboard Auto-Configuration + +The OmniRoute dashboard automates configuration for most tools: + +1. Go to `http://localhost:20128/dashboard/cli-tools` +2. Expand any tool card +3. Select your API key from the dropdown +4. Click **Apply Config** (if tool is detected as installed) +5. Or copy the generated config snippet manually + +--- + +## Built-in Agents: Droid & OpenClaw + +**Droid** and **OpenClaw** are AI agents built directly into OmniRoute โ€” no installation needed. +They run as internal routes and use OmniRoute's model routing automatically. + +- Access: `http://localhost:20128/dashboard/agents` +- Configure: same combos and providers as all other tools +- No API key or CLI install required + +--- + +## Available API Endpoints + +| Endpoint | Description | Use For | +| -------------------------- | ----------------------------- | --------------------------- | +| `/v1/chat/completions` | Standard chat (all providers) | All modern tools | +| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows | +| `/v1/completions` | Legacy text completions | Older tools using `prompt:` | +| `/v1/embeddings` | Text embeddings | RAG, search | +| `/v1/images/generations` | Image generation | DALL-E, Flux, etc. | +| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS | +| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI | + +--- + +## Probleemoplossing + +| Error | Cause | Fix | +| ------------------------- | ----------------------- | ------------------------------------------ | +| `Connection refused` | OmniRoute not running | `pm2 start omniroute` | +| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` | +| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` | +| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` | +| CLI shows "not installed" | Binary not in PATH | Check `which ` | +| `kiro-cli: not found` | Not in PATH | `export PATH="$HOME/.local/bin:$PATH"` | + +--- + +## Quick Setup Script (One Command) + +```bash +# Install all CLIs and configure for OmniRoute (replace with your key and server URL) +OMNIROUTE_URL="http://localhost:20128/v1" +OMNIROUTE_KEY="sk-your-omniroute-key" + +npm install -g @anthropic-ai/claude-code @openai/codex opencode-ai cline kilocode + +# Kiro CLI +apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash + +# Write configs +mkdir -p ~/.claude ~/.codex ~/.config/opencode ~/.continue + +cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" +cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" +cat >> ~/.bashrc << EOF +export OPENAI_BASE_URL="$OMNIROUTE_URL" +export OPENAI_API_KEY="$OMNIROUTE_KEY" +export ANTHROPIC_BASE_URL="$OMNIROUTE_URL" +export ANTHROPIC_API_KEY="$OMNIROUTE_KEY" +EOF + +source ~/.bashrc +echo "โœ… All CLIs installed and configured for OmniRoute" +``` diff --git a/docs/i18n/nl/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/nl/docs/CODEBASE_DOCUMENTATION.md new file mode 100644 index 0000000000..c05e1933d3 --- /dev/null +++ b/docs/i18n/nl/docs/CODEBASE_DOCUMENTATION.md @@ -0,0 +1,591 @@ +# omniroute โ€” Codebase Documentation (Nederlands) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CODEBASE_DOCUMENTATION.md) + +--- + +> 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
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, Qoder, 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. + +#### Architectuur + +```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 | +| Qoder | 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"] +``` diff --git a/docs/i18n/nl/docs/COVERAGE_PLAN.md b/docs/i18n/nl/docs/COVERAGE_PLAN.md new file mode 100644 index 0000000000..da87d7a05d --- /dev/null +++ b/docs/i18n/nl/docs/COVERAGE_PLAN.md @@ -0,0 +1,170 @@ +# Test Coverage Plan (Nederlands) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/COVERAGE_PLAN.md) + +--- + +Last updated: 2026-03-28 + +## Baseline + +There are multiple coverage numbers depending on how the report is computed. For planning, only one of them is useful. + +| Metric | Scope | Statements / Lines | Branches | Functions | Notes | +| -------------------- | ----------------------------------------------------- | -----------------: | -------: | --------: | --------------------------------------------------- | +| Legacy | Old `npm run test:coverage` | 79.42% | 75.15% | 67.94% | Inflated: counts test files and excludes `open-sse` | +| Diagnostic | Source-only, excluding tests and excluding `open-sse` | 68.16% | 63.55% | 64.06% | Useful only to isolate `src/**` | +| Recommended baseline | Source-only, excluding tests and including `open-sse` | 56.95% | 66.05% | 57.80% | This is the project-wide baseline to improve | + +The recommended baseline is the number to optimize against. + +## Rules + +- Coverage targets apply to source files, not to `tests/**`. +- `open-sse/**` is part of the product and must remain in scope. +- New code should not reduce coverage in touched areas. +- Prefer testing behavior and branch outcomes over implementation details. +- Prefer temp SQLite databases and small fixtures over broad mocks for `src/lib/db/**`. + +## Current command set + +- `npm run test:coverage` + - Main source coverage gate for the unit test suite + - Generates `text-summary`, `html`, `json-summary`, and `lcov` +- `npm run coverage:report` + - Detailed file-by-file report from the latest run +- `npm run test:coverage:legacy` + - Historical comparison only + +## Milestones + +| Phase | Target | Focus | +| ------- | ---------------------: | ------------------------------------------------- | +| Phase 1 | 60% statements / lines | Quick wins and low-risk utility coverage | +| Phase 2 | 65% statements / lines | DB and route foundations | +| Phase 3 | 70% statements / lines | Provider validation and usage analytics | +| Phase 4 | 75% statements / lines | `open-sse` translators and helpers | +| Phase 5 | 80% statements / lines | `open-sse` handlers and executor branches | +| Phase 6 | 85% statements / lines | Harder edge cases, branch debt, regression suites | +| Phase 7 | 90% statements / lines | Final sweep, gap closure, strict ratchet | + +Branches and functions should ratchet upward with each phase, but the primary hard target is statements / lines. + +## Priority hotspots + +These files or areas offer the best return for the next phases: + +1. `open-sse/handlers` + - `chatCore.ts` at 7.57% + - Overall directory at 29.07% +2. `open-sse/translator/request` + - Overall directory at 36.39% + - Many translators are still near single-digit coverage +3. `open-sse/translator/response` + - Overall directory at 8.07% +4. `open-sse/executors` + - Overall directory at 36.62% +5. `src/lib/db` + - `models.ts` at 20.66% + - `registeredKeys.ts` at 34.46% + - `modelComboMappings.ts` at 36.25% + - `settings.ts` at 46.40% + - `webhooks.ts` at 33.33% +6. `src/lib/usage` + - `usageHistory.ts` at 21.12% + - `usageStats.ts` at 9.56% + - `costCalculator.ts` at 30.00% +7. `src/lib/providers` + - `validation.ts` at 41.16% +8. Low-risk utility and API files for early gains + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/api/errorResponse.ts` + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +## Execution checklist + +### Phase 1: 56.95% -> 60% + +- [x] Fix coverage metric so it reflects source code instead of test files +- [x] Keep a legacy coverage script for comparison +- [x] Record the baseline and hotspots in-repo +- [ ] Add focused tests for low-risk utilities: + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/fetchTimeout.ts` + - `src/lib/api/errorResponse.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/display/names.ts` +- [ ] Add route tests for: + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +### Phase 2: 60% -> 65% + +- [ ] Add DB-backed tests for: + - `src/lib/db/modelComboMappings.ts` + - `src/lib/db/settings.ts` + - `src/lib/db/registeredKeys.ts` +- [ ] Cover branch behavior in: + - `src/lib/providers/validation.ts` + - `src/app/api/v1/embeddings/route.ts` + - `src/app/api/v1/moderations/route.ts` + +### Phase 3: 65% -> 70% + +- [ ] Add usage analytics tests for: + - `src/lib/usage/usageHistory.ts` + - `src/lib/usage/usageStats.ts` + - `src/lib/usage/costCalculator.ts` +- [ ] Expand route coverage for proxy management and settings branches + +### Phase 4: 70% -> 75% + +- [ ] Cover translator helpers and central translation paths: + - `open-sse/translator/index.ts` + - `open-sse/translator/helpers/*` + - `open-sse/translator/request/*` + - `open-sse/translator/response/*` + +### Phase 5: 75% -> 80% + +- [ ] Add handler-level tests for: + - `open-sse/handlers/chatCore.ts` + - `open-sse/handlers/responsesHandler.js` + - `open-sse/handlers/imageGeneration.js` + - `open-sse/handlers/embeddings.js` +- [ ] Add executor branch coverage for provider-specific auth, retries, and endpoint overrides + +### Phase 6: 80% -> 85% + +- [ ] Merge more edge-case suites into the main coverage path +- [ ] Increase function coverage for DB modules with weak constructor/helper coverage +- [ ] Close branch gaps in `settings.ts`, `registeredKeys.ts`, `validation.ts`, and translator helpers + +### Phase 7: 85% -> 90% + +- [ ] Treat the remaining low-coverage files as blockers +- [ ] Add regression tests for every uncovered production bug fixed during the push to 90% +- [ ] Raise the coverage gate in CI only after the local baseline is stable for at least two consecutive runs + +## Ratchet policy + +Update `npm run test:coverage` thresholds only after the project actually exceeds the next milestone with a comfortable buffer. + +Recommended ratchet sequence: + +1. 55/60/55 +2. 60/62/58 +3. 65/64/62 +4. 70/66/66 +5. 75/70/72 +6. 80/75/78 +7. 85/80/84 +8. 90/85/88 + +Order is `statements-lines / branches / functions`. + +## Known gap + +The current coverage command measures the main Node unit suite and includes source reached from it, including `open-sse`. It does not yet merge Vitest coverage into a single unified report. That merge is worth doing later, but it is not a blocker for starting the 60% -> 80% climb. diff --git a/docs/i18n/nl/docs/FEATURES.md b/docs/i18n/nl/docs/FEATURES.md index 288dbfe74f..ee7a4f2674 100644 --- a/docs/i18n/nl/docs/FEATURES.md +++ b/docs/i18n/nl/docs/FEATURES.md @@ -1,6 +1,6 @@ # OmniRoute โ€” Dashboard Features Gallery (Nederlands) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/FEATURES.md) --- @@ -10,7 +10,7 @@ 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). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. ![Providers Dashboard](screenshots/01-providers.png) diff --git a/docs/i18n/nl/docs/MCP-SERVER.md b/docs/i18n/nl/docs/MCP-SERVER.md new file mode 100644 index 0000000000..ad84d765f4 --- /dev/null +++ b/docs/i18n/nl/docs/MCP-SERVER.md @@ -0,0 +1,87 @@ +# OmniRoute MCP Server Documentation (Nederlands) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/MCP-SERVER.md) + +--- + +> Model Context Protocol server with 16 intelligent tools + +## Installeren + +OmniRoute MCP is built-in. Start it with: + +```bash +omniroute --mcp +``` + +Or via the open-sse transport: + +```bash +# HTTP streamable transport (port 20130) +omniroute --dev # MCP auto-starts on /mcp endpoint +``` + +## IDE Configuration + +See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup. + +--- + +## Essential Tools (8) + +| Tool | Description | +| :------------------------------ | :--------------------------------------- | +| `omniroute_get_health` | Gateway health, circuit breakers, uptime | +| `omniroute_list_combos` | All configured combos with models | +| `omniroute_get_combo_metrics` | Performance metrics for a specific combo | +| `omniroute_switch_combo` | Switch active combo by ID/name | +| `omniroute_check_quota` | Quota status per provider or all | +| `omniroute_route_request` | Send a chat completion through OmniRoute | +| `omniroute_cost_report` | Cost analytics for a time period | +| `omniroute_list_models_catalog` | Full model catalog with capabilities | + +## Advanced Tools (8) + +| Tool | Description | +| :--------------------------------- | :---------------------------------------------------------- | +| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | +| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | +| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | +| `omniroute_test_combo` | Live-test all models in a combo via a real upstream request | +| `omniroute_get_provider_metrics` | Detailed metrics for one provider | +| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | +| `omniroute_explain_route` | Explain a past routing decision | +| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | + +## Authentication + +MCP tools are authenticated via API key scopes. Each tool requires specific scopes: + +| Scope | Tools | +| :------------- | :----------------------------------------------- | +| `read:health` | get_health, get_provider_metrics | +| `read:combos` | list_combos, get_combo_metrics | +| `write:combos` | switch_combo | +| `read:quota` | check_quota | +| `write:route` | route_request, simulate_route, test_combo | +| `read:usage` | cost_report, get_session_snapshot, explain_route | +| `write:config` | set_budget_guard, set_resilience_profile | +| `read:models` | list_models_catalog, best_combo_for_task | + +## Audit Logging + +Every tool call is logged to `mcp_tool_audit` with: + +- Tool name, arguments, result +- Duration (ms), success/failure +- API key hash, timestamp + +## Files + +| File | Purpose | +| :------------------------------------------- | :------------------------------------------ | +| `open-sse/mcp-server/server.ts` | MCP server creation + 16 tool registrations | +| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport | +| `open-sse/mcp-server/auth.ts` | API key + scope validation | +| `open-sse/mcp-server/audit.ts` | Tool call audit logging | +| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers | diff --git a/docs/i18n/nl/docs/RELEASE_CHECKLIST.md b/docs/i18n/nl/docs/RELEASE_CHECKLIST.md new file mode 100644 index 0000000000..63f02e0e5a --- /dev/null +++ b/docs/i18n/nl/docs/RELEASE_CHECKLIST.md @@ -0,0 +1,37 @@ +# Release Checklist (Nederlands) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/RELEASE_CHECKLIST.md) + +--- + +Use this checklist before tagging or publishing a new OmniRoute release. + +## Version and Changelog + +1. Bump `package.json` version (`x.y.z`) in the release branch. +2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: + - `## [x.y.z] โ€” YYYY-MM-DD` +3. Keep `## [Unreleased]` as the first changelog section for upcoming work. +4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. + +## API Docs + +1. Update `docs/openapi.yaml`: + - `info.version` must equal `package.json` version. +2. Validate endpoint examples if API contracts changed. + +## Runtime Docs + +1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. +2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. +3. Update localized docs if source docs changed significantly. + +## Automated Check + +Run the sync guard locally before opening PR: + +```bash +npm run check:docs-sync +``` + +CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/nl/docs/TROUBLESHOOTING.md b/docs/i18n/nl/docs/TROUBLESHOOTING.md new file mode 100644 index 0000000000..ce4c77cf5e --- /dev/null +++ b/docs/i18n/nl/docs/TROUBLESHOOTING.md @@ -0,0 +1,256 @@ +# Troubleshooting (Nederlands) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/TROUBLESHOOTING.md) + +--- + +Common problems and solutions for OmniRoute. + +--- + +## Quick Fixes + +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | + +--- + +## Provider Issues + +### "Language model did not provide messages" + +**Cause:** Provider quota exhausted. + +**Fix:** + +1. 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, Qoder) 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}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) + +--- + +## Circuit Breaker Issues + +### Provider stuck in OPEN state + +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. + +**Fix:** + +1. 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 +- **SDK returns raw string instead of object** โ€” Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** โ€” Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** โ€” Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** โ€” Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` + +--- + +## Resilience Settings + +### Auto rate-limit not triggering + +- 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. + +--- + +## Optional RAG / LLM failure taxonomy (16 problems) + +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` โ€ฆ `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard โ†’ Health** for real-time system status +- **Translator**: Use **Dashboard โ†’ Translator** to debug format issues diff --git a/docs/i18n/nl/USER_GUIDE.md b/docs/i18n/nl/docs/USER_GUIDE.md similarity index 82% rename from docs/i18n/nl/USER_GUIDE.md rename to docs/i18n/nl/docs/USER_GUIDE.md index 351ce09434..4088758429 100644 --- a/docs/i18n/nl/USER_GUIDE.md +++ b/docs/i18n/nl/docs/USER_GUIDE.md @@ -1,8 +1,6 @@ # User Guide (Nederlands) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/USER_GUIDE.md) - -> ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/USER_GUIDE.md) --- @@ -320,7 +318,7 @@ Model: cc/claude-opus-4-6 --- -## ๐Ÿš€ Deployment +## Implementatie ### Global npm install (Recommended) @@ -511,23 +509,26 @@ post_install() { ### Environment Variables -| Variable | Default | Description | -| ------------------------- | ------------------------------------ | ------------------------------------------------------- | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | -| `INITIAL_PASSWORD` | `123456` | First login password | -| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | -| `PORT` | framework default | Service port (`20128` in examples) | -| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | -| `NODE_ENV` | runtime default | Set `production` for deploy | -| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | -| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | -| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | -| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | -| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | -| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | -| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | -| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | +| 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/*` | +| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand | +| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | For the full environment variable reference, see the [README](../README.md). @@ -598,6 +599,11 @@ curl -X POST http://localhost:20128/api/provider-models \ Or use Dashboard: **Providers โ†’ [Provider] โ†’ Custom Models**. +Notes: + +- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers. +- The **Custom Models** section is intended for providers that do not expose managed available-model imports. + ### Dedicated Provider Routes Route requests directly to a specific provider with model validation: @@ -642,6 +648,14 @@ Returns models grouped by provider with types (`chat`, `embedding`, `image`). - Automatic background sync with timeout + fail-fast - Prefer server-side `BASE_URL`/`CLOUD_URL` in production +### Cloudflare Quick Tunnel + +- Available in **Dashboard โ†’ Endpoints** for Docker and other self-hosted deployments +- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint +- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary +- Tunnel URLs are ephemeral and change every time you stop/start the tunnel +- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download + ### LLM Gateway Intelligence (Phase 9) - **Semantic Cache** โ€” Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) @@ -757,11 +771,11 @@ OmniRoute implements provider-level resilience with four components: 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 | +| 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 unless `DISABLE_SQLITE_AUTO_BACKUP=true` | ```bash # API: Export database @@ -787,10 +801,11 @@ curl -X POST http://localhost:20128/api/db-backups/import \ ### Settings Dashboard -The settings page is organized into 5 tabs for easy navigation: +The settings page is organized into 6 tabs for easy navigation: | Tab | Contents | | -------------- | ---------------------------------------------------------------------------------------------- | +| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility | | **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | | **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | | **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | diff --git a/docs/i18n/nl/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/nl/docs/VM_DEPLOYMENT_GUIDE.md new file mode 100644 index 0000000000..7ab2f7716a --- /dev/null +++ b/docs/i18n/nl/docs/VM_DEPLOYMENT_GUIDE.md @@ -0,0 +1,403 @@ +# OmniRoute โ€” Deployment Guide on VM with Cloudflare (Nederlands) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/VM_DEPLOYMENT_GUIDE.md) + +--- + +Complete guide to install and configure OmniRoute on a VM (VPS) with domain managed via Cloudflare. + +--- + +## Prerequisites + +| Item | Minimum | Recommended | +| ---------- | ------------------------ | ---------------- | +| **CPU** | 1 vCPU | 2 vCPU | +| **RAM** | 1 GB | 2 GB | +| **Disk** | 10 GB SSD | 25 GB SSD | +| **OS** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS | +| **Domain** | Registered on Cloudflare | โ€” | +| **Docker** | Docker Engine 24+ | Docker 27+ | + +**Tested providers**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. + +--- + +## 1. Configure the VM + +### 1.1 Create the instance + +On your preferred VPS provider: + +- Choose Ubuntu 24.04 LTS +- Select the minimum plan (1 vCPU / 1 GB RAM) +- Set a strong root password or configure SSH key +- Note the **public IP** (e.g., `203.0.113.10`) + +### 1.2 Connect via SSH + +```bash +ssh root@203.0.113.10 +``` + +### 1.3 Update the system + +```bash +apt update && apt upgrade -y +``` + +### 1.4 Install Docker + +```bash +# Install dependencies +apt install -y ca-certificates curl gnupg + +# Add official Docker repository +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 Install nginx + +```bash +apt install -y nginx +``` + +### 1.6 Configure 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 +``` + +> **Tip**: For maximum security, restrict ports 80 and 443 to Cloudflare IPs only. See the [Advanced Security](#advanced-security) section. + +--- + +## 2. Install OmniRoute + +### 2.1 Create configuration directory + +```bash +mkdir -p /opt/omniroute +``` + +### 2.2 Create environment variables file + +```bash +cat > /opt/omniroute/.env << โ€˜EOFโ€™ +# === Security === +JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY +INITIAL_PASSWORD=YourSecurePassword123! +API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY +STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY +STORAGE_ENCRYPTION_KEY_VERSION=v1 +MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT + +# === 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 (change to your domain) === +BASE_URL=https://llms.seudominio.com +NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com + +# === Cloud Sync (optional) === +# CLOUD_URL=https://cloud.omniroute.online +# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online +EOF +``` + +> โš ๏ธ **IMPORTANT**: Generate unique secret keys! Use `openssl rand -hex 32` for each key. + +### 2.3 Start the 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 Verify that it is running + +```bash +docker ps | grep omniroute +docker logs omniroute --tail 20 +``` + +It should display: `[DB] SQLite database ready` and `listening on port 20128`. + +--- + +## 3. Configure nginx (Reverse Proxy) + +### 3.1 Generate SSL certificate (Cloudflare Origin) + +In the Cloudflare dashboard: + +1. Go to **SSL/TLS โ†’ Origin Server** +2. Click **Create Certificate** +3. Keep the defaults (15 years, \*.yourdomain.com) +4. Copy the **Origin Certificate** and the **Private Key** + +```bash +mkdir -p /etc/nginx/ssl + +# Paste the certificate +nano /etc/nginx/ssl/origin.crt + +# Paste the private key +nano /etc/nginx/ssl/origin.key + +chmod 600 /etc/nginx/ssl/origin.key +``` + +### 3.2 Nginx Configuration + +```bash +cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ +# Default server โ€” blocks direct access via 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.yourdomain.com; # Change to your domain + + 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.yourdomain.com; + return 301 https://$server_name$request_uri; +} +NGINX +``` + +### 3.3 Enable and Test + +```bash +# Remove default configuration +rm -f /etc/nginx/sites-enabled/default + +# Enable OmniRoute +ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute + +# Test and reload +nginx -t && systemctl reload nginx +``` + +--- + +## 4. Configure Cloudflare DNS + +### 4.1 Add DNS record + +In the Cloudflare dashboard โ†’ DNS: + +| Type | Name | Content | Proxy | +| ---- | ------ | ---------------------- | ---------- | +| A | `llms` | `203.0.113.10` (VM IP) | โœ… Proxied | + +### 4.2 Configure SSL + +Under **SSL/TLS โ†’ Overview**: + +- Mode: **Full (Strict)** + +Under **SSL/TLS โ†’ Edge Certificates**: + +- Always Use HTTPS: โœ… On +- Minimum TLS Version: TLS 1.2 +- Automatic HTTPS Rewrites: โœ… On + +### 4.3 Testing + +```bash +curl -sI https://llms.seudominio.com/health +# Should return HTTP/2 200 +``` + +--- + +## 5. Operations and Maintenance + +### Upgrade to a new version + +```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 +``` + +### View logs + +```bash +docker logs -f omniroute # Real-time stream +docker logs omniroute --tail 50 # Last 50 lines +``` + +### Manual database backup + +```bash +# Copy data from the volume to the host +docker cp omniroute:/app/data ./backup-$(date +%F) + +# Or compress the entire volume +docker run --rm -v omniroute-data:/data -v $(pwd):/backup \ + alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data +``` + +### Restore from 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. Advanced Security + +### Restrict nginx to Cloudflare IPs + +```bash +cat > /etc/nginx/cloudflare-ips.conf << โ€˜CFโ€™ +# Cloudflare IPv4 ranges โ€” update periodically +# 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 +``` + +Add the following to `nginx.conf` inside the `http {}` block: + +```nginx +include /etc/nginx/cloudflare-ips.conf; +``` + +### Install fail2ban + +```bash +apt install -y fail2ban +systemctl enable fail2ban +systemctl start fail2ban + +# Check status +fail2ban-client status sshd +``` + +### Block direct access to the Docker port + +```bash +# Prevent direct external access to port 20128 +iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP +iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT + +# Persist the rules +apt install -y iptables-persistent +netfilter-persistent save +``` + +--- + +## 7. Deploy to Cloudflare Workers (Optional) + +For remote access via Cloudflare Workers (without exposing the VM directly): + +```bash +# In the local repository +cd omnirouteCloud +npm install +npx wrangler login +npx wrangler deploy +``` + +See the full documentation at [omnirouteCloud/README.md](../omnirouteCloud/README.md). + +--- + +## Port Summary + +| Port | Service | Access | +| ----- | ----------- | -------------------------- | +| 22 | SSH | Public (with fail2ban) | +| 80 | nginx HTTP | Redirect โ†’ HTTPS | +| 443 | nginx HTTPS | Via Cloudflare Proxy | +| 20128 | OmniRoute | Localhost only (via nginx) | diff --git a/docs/i18n/nl/src/lib/a2a/README.md b/docs/i18n/nl/src/lib/a2a/README.md new file mode 100644 index 0000000000..643a3e8802 --- /dev/null +++ b/docs/i18n/nl/src/lib/a2a/README.md @@ -0,0 +1,752 @@ +# OmniRoute A2A Server (Nederlands) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../../../src/lib/a2a/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../../../es/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../../../fr/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../../../de/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../../../it/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../../../ru/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../../../zh-CN/src/lib/a2a/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../../../ja/src/lib/a2a/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../../../ko/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../../../ar/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../../../in/src/lib/a2a/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../../../th/src/lib/a2a/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../../../vi/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../../../id/src/lib/a2a/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../../../ms/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../../../nl/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../../../pl/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../../../sv/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../../../no/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../../../da/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../../../fi/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../../../pt/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../../../ro/src/lib/a2a/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../../../hu/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../../../bg/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../../../sk/src/lib/a2a/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../../../uk-UA/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../../../he/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../../../phi/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../../../pt-BR/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../../../cs/src/lib/a2a/README.md) + +--- + +> **Agent-to-Agent Protocol v0.3** โ€” Enables any AI agent to use OmniRoute as an intelligent routing agent via JSON-RPC 2.0. + +The A2A Server exposes OmniRoute as a **first-class agent** that other agents can discover, delegate tasks to, and collaborate with using the [A2A Protocol](https://google.github.io/A2A/). + +--- + +## Architectuur + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Orchestrator Agent โ”‚ +โ”‚ (LangChain, CrewAI, AutoGen, Custom Agent) โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ 1. GET /.well-known/agent.json (discover) + โ”‚ 2. POST /a2a (JSON-RPC 2.0) + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ OmniRoute A2A Server โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Task Manager โ”‚ โ”‚ Skill Engine โ”‚ โ”‚ SSE Streaming โ”‚ โ”‚ +โ”‚ โ”‚ (lifecycle) โ”‚โ”€โ”€โ”‚ (registry) โ”‚โ”€โ”€โ”‚ (real-time) โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ +โ”‚ Skills: โ”‚ โ”‚ +โ”‚ โ”œโ”€ smart-routing โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ””โ”€ quota-management โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ Routing Decision Logger โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ OmniRoute Gateway (internal) + /v1/chat/completions, /api/combos, /api/usage/quota +``` + +--- + +## Snel starten + +### Agent Discovery + +Every A2A-compatible agent exposes an **Agent Card** at `/.well-known/agent.json`: + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +**Response:** + +```json +{ + "name": "OmniRoute", + "description": "Intelligent AI gateway with auto-routing across 50+ providers", + "url": "http://localhost:20128/a2a", + "version": "1.8.1", + "capabilities": { + "streaming": true, + "pushNotifications": false + }, + "skills": [ + { + "id": "smart-routing", + "name": "Smart Routing", + "description": "Routes prompts through OmniRoute intelligent pipeline", + "tags": ["routing", "llm", "multi-provider", "cost-optimization"], + "examples": [ + "Write a hello world in Python", + "Explain quantum computing using the cheapest provider" + ] + }, + { + "id": "quota-management", + "name": "Quota Management", + "description": "Natural-language queries about provider quotas", + "tags": ["quota", "analytics", "cost"], + "examples": [ + "Which provider has the most quota remaining?", + "Suggest a free combo for coding" + ] + } + ], + "authentication": { + "schemes": ["bearer"], + "apiKeyHeader": "Authorization" + } +} +``` + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Send a message to a skill and receive the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python hello world"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "a1b2c3d4-...", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "print('Hello, World!')" }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.0030)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "2026-03-04T..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"Quantum computing..."}}} + +: heartbeat 2026-03-04T21:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Running Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Skills Reference + +### `smart-routing` + +Routes prompts through OmniRoute's intelligent pipeline with full observability. + +**Parameters (in `metadata`):** + +| Parameter | Type | Default | Description | +| --------- | -------- | ------------ | ---------------------------------------------------------------------------------------- | +| `model` | `string` | `"auto"` | Target model (e.g., `claude-sonnet-4`, `gpt-4o`, `auto`) | +| `combo` | `string` | active combo | Specific combo to route through | +| `budget` | `number` | none | Maximum cost in USD for this request | +| `role` | `string` | none | Task role hint: `coding`, `review`, `planning`, `analysis`, `debugging`, `documentation` | + +**Returns:** + +| Field | Description | +| ------------------------------ | --------------------------------------------------------- | +| `artifacts[].content` | The LLM response text | +| `metadata.routing_explanation` | Human-readable explanation of routing decision | +| `metadata.cost_envelope` | Estimated vs actual cost with currency | +| `metadata.resilience_trace` | Array of events (primary_selected, fallback_needed, etc.) | +| `metadata.policy_verdict` | Whether the request was allowed and why | + +### `quota-management` + +Answers natural-language queries about provider quotas. + +**Query types (inferred from message content):** + +| Query Pattern | Response Type | +| ---------------------------------------------- | -------------------------------------------------------- | +| Contains `"ranking"`, `"most quota"`, `"best"` | Providers ranked by remaining quota | +| Contains `"free"`, `"suggest"` | Lists free combos or suggests free-tier providers | +| Default | Full quota summary with warnings for low-quota providers | + +--- + +## Task Lifecycle + +``` +submitted โ”€โ”€โ†’ working โ”€โ”€โ†’ completed + โ”€โ”€โ†’ failed + โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ†’ cancelled +``` + +| State | Description | +| ----------- | ----------------------------------------------------- | +| `submitted` | Task created, queued for execution | +| `working` | Skill handler is executing | +| `completed` | Execution succeeded, artifacts available | +| `failed` | Execution failed or task expired (TTL: 5 min default) | +| `cancelled` | Cancelled by client via `tasks/cancel` | + +- Terminal states: `completed`, `failed`, `cancelled` (no further transitions) +- Expired tasks in `submitted` or `working` are auto-marked as `failed` +- Tasks are garbage-collected after 2ร— TTL + +--- + +## Client Examples + +### Python โ€” Orchestrator Agent + +```python +""" +A2A Client โ€” Python example. +Discovers OmniRoute agent, sends a task, and processes the result. +""" +import requests +import json + +BASE_URL = "http://localhost:20128" +API_KEY = "your-api-key" +HEADERS = { + "Content-Type": "application/json", + "Authorization": f"Bearer {API_KEY}", +} + +# 1. Discover agent capabilities +agent_card = requests.get(f"{BASE_URL}/.well-known/agent.json").json() +print(f"Agent: {agent_card['name']} v{agent_card['version']}") +print(f"Skills: {[s['id'] for s in agent_card['skills']]}") + +# 2. Send a smart-routing task +response = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python quicksort implementation"}], + "metadata": { + "model": "auto", + "combo": "fast-coding", + "budget": 0.10, + } + } +}) +result = response.json()["result"] +print(f"\n๐Ÿ“ Response: {result['artifacts'][0]['content'][:200]}...") +print(f"๐Ÿ”€ Routing: {result['metadata']['routing_explanation']}") +print(f"๐Ÿ’ฐ Cost: ${result['metadata']['cost_envelope']['actual']}") +print(f"๐Ÿ›ก๏ธ Policy: {result['metadata']['policy_verdict']['reason']}") + +# 3. Query quota status +quota_resp = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-2", + "method": "message/send", + "params": { + "skill": "quota-management", + "messages": [{"role": "user", "content": "Which provider has the most quota remaining?"}], + } +}) +quota_result = quota_resp.json()["result"] +print(f"\n๐Ÿ“Š Quota: {quota_result['artifacts'][0]['content']}") +``` + +### TypeScript โ€” Multi-Agent Orchestrator + +```typescript +/** + * A2A Client โ€” TypeScript example. + * Shows agent discovery, task delegation, and streaming. + */ + +const BASE_URL = "http://localhost:20128"; +const API_KEY = "your-api-key"; + +interface JsonRpcResponse { + jsonrpc: "2.0"; + id: string | number; + result?: T; + error?: { code: number; message: string }; +} + +async function a2aCall(method: string, params: Record): Promise { + const resp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: `${method}-${Date.now()}`, + method, + params, + }), + }); + const json: JsonRpcResponse = await resp.json(); + if (json.error) throw new Error(`[${json.error.code}] ${json.error.message}`); + return json.result!; +} + +// โ”€โ”€ Agent Discovery โ”€โ”€ +const agentCard = await fetch(`${BASE_URL}/.well-known/agent.json`).then((r) => r.json()); +console.log(`Connected to: ${agentCard.name} (${agentCard.skills.length} skills)`); + +// โ”€โ”€ Smart Routing: Send a coding task โ”€โ”€ +const routingResult = await a2aCall("message/send", { + skill: "smart-routing", + messages: [{ role: "user", content: "Implement a Redis cache wrapper in TypeScript" }], + metadata: { model: "claude-sonnet-4", role: "coding" }, +}); +console.log("Response:", routingResult.artifacts[0].content); +console.log("Provider:", routingResult.metadata.routing_explanation); + +// โ”€โ”€ Quota Management: Find free alternatives โ”€โ”€ +const quotaResult = await a2aCall("message/send", { + skill: "quota-management", + messages: [{ role: "user", content: "Suggest free combos for documentation" }], +}); +console.log("Free combos:", quotaResult.artifacts[0].content); + +// โ”€โ”€ Streaming: Real-time response โ”€โ”€ +const streamResp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "stream-1", + method: "message/stream", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Explain microservices architecture" }], + }, + }), +}); + +const reader = streamResp.body!.getReader(); +const decoder = new TextDecoder(); +while (true) { + const { done, value } = await reader.read(); + if (done) break; + const chunk = decoder.decode(value); + for (const line of chunk.split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + if (event.params.chunk) { + process.stdout.write(event.params.chunk.content); + } + if (event.params.task.state === "completed") { + console.log("\nโœ… Stream completed"); + } + } + } +} +``` + +### Python โ€” LangChain A2A Integration + +```python +""" +LangChain integration โ€” Use OmniRoute A2A as a custom LLM. +""" +from langchain.llms.base import BaseLLM +from langchain.schema import LLMResult, Generation +import requests +from typing import List, Optional + +class OmniRouteA2A(BaseLLM): + base_url: str = "http://localhost:20128" + api_key: str = "" + model: str = "auto" + combo: Optional[str] = None + + @property + def _llm_type(self) -> str: + return "omniroute-a2a" + + def _call(self, prompt: str, stop: Optional[List[str]] = None, **kwargs) -> str: + response = requests.post( + f"{self.base_url}/a2a", + headers={ + "Content-Type": "application/json", + "Authorization": f"Bearer {self.api_key}", + }, + json={ + "jsonrpc": "2.0", + "id": "langchain-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": prompt}], + "metadata": { + "model": self.model, + **({"combo": self.combo} if self.combo else {}), + }, + }, + }, + ) + result = response.json()["result"] + return result["artifacts"][0]["content"] + + def _generate(self, prompts: List[str], stop=None, **kwargs) -> LLMResult: + return LLMResult( + generations=[[Generation(text=self._call(p, stop))] for p in prompts] + ) + +# Usage +llm = OmniRouteA2A( + base_url="http://localhost:20128", + api_key="your-key", + model="auto", + combo="fast-coding", +) +result = llm("Write a Python function to merge two sorted lists") +print(result) +``` + +### Go โ€” A2A Client + +```go +package main + +import ( + "bytes" + "encoding/json" + "fmt" + "io" + "net/http" +) + +const baseURL = "http://localhost:20128" +const apiKey = "your-api-key" + +type JsonRpcRequest struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Method string `json:"method"` + Params interface{} `json:"params"` +} + +type JsonRpcResponse struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Result interface{} `json:"result"` + Error *struct { + Code int `json:"code"` + Message string `json:"message"` + } `json:"error"` +} + +func a2aCall(method string, params interface{}) (*JsonRpcResponse, error) { + body, _ := json.Marshal(JsonRpcRequest{ + Jsonrpc: "2.0", + ID: "go-1", + Method: method, + Params: params, + }) + + req, _ := http.NewRequest("POST", baseURL+"/a2a", bytes.NewReader(body)) + req.Header.Set("Content-Type", "application/json") + req.Header.Set("Authorization", "Bearer "+apiKey) + + resp, err := http.DefaultClient.Do(req) + if err != nil { + return nil, err + } + defer resp.Body.Close() + data, _ := io.ReadAll(resp.Body) + + var result JsonRpcResponse + json.Unmarshal(data, &result) + return &result, nil +} + +func main() { + // Discover agent + resp, _ := http.Get(baseURL + "/.well-known/agent.json") + defer resp.Body.Close() + body, _ := io.ReadAll(resp.Body) + fmt.Println("Agent Card:", string(body)) + + // Send smart-routing task + result, _ := a2aCall("message/send", map[string]interface{}{ + "skill": "smart-routing", + "messages": []map[string]string{{"role": "user", "content": "Hello from Go!"}}, + "metadata": map[string]interface{}{"model": "auto"}, + }) + out, _ := json.MarshalIndent(result.Result, "", " ") + fmt.Println("Result:", string(out)) +} +``` + +--- + +## Use Cases + +### ๐Ÿค– Use Case 1: Multi-Agent Coding Pipeline + +An orchestrator agent delegates code generation to OmniRoute, then passes the output to a review agent. + +```python +def coding_pipeline(task: str): + # Step 1: Generate code via OmniRoute A2A + code_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Write production-quality code: {task}"} + ], metadata={"model": "auto", "role": "coding"}) + code = code_result["artifacts"][0]["content"] + + # Step 2: Review the code via OmniRoute A2A (different model) + review_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Review this code for bugs and improvements:\n\n{code}"} + ], metadata={"model": "auto", "role": "review"}) + review = review_result["artifacts"][0]["content"] + + # Step 3: Check costs + print(f"Code cost: ${code_result['metadata']['cost_envelope']['actual']}") + print(f"Review cost: ${review_result['metadata']['cost_envelope']['actual']}") + + return {"code": code, "review": review} +``` + +### ๐Ÿ’ก Use Case 2: Quota-Aware Agent Swarm + +Multiple agents share quota through OmniRoute, using the quota skill to coordinate. + +```python +async def quota_aware_agent(agent_name: str, task: str): + # Check quota before starting + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Which provider has the most quota remaining?"} + ]) + print(f"[{agent_name}] {quota['artifacts'][0]['content']}") + + # Send request with budget constraint + result = a2a_send("smart-routing", [ + {"role": "user", "content": task} + ], metadata={"budget": 0.05}) + + policy = result["metadata"]["policy_verdict"] + if not policy["allowed"]: + print(f"[{agent_name}] โš ๏ธ Budget exceeded: {policy['reason']}") + # Fall back to free combo + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Suggest free combos"} + ]) + print(f"[{agent_name}] Free alternatives: {quota['artifacts'][0]['content']}") + + return result +``` + +### ๐Ÿ“Š Use Case 3: Real-Time Streaming Dashboard + +A monitoring agent streams responses and displays progress in real-time. + +```typescript +async function streamingDashboard(prompt: string) { + const response = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { "Content-Type": "application/json", Authorization: `Bearer ${API_KEY}` }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "dash-1", + method: "message/stream", + params: { skill: "smart-routing", messages: [{ role: "user", content: prompt }] }, + }), + }); + + let totalChunks = 0; + const reader = response.body!.getReader(); + const decoder = new TextDecoder(); + + while (true) { + const { done, value } = await reader.read(); + if (done) break; + + for (const line of decoder.decode(value).split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + const state = event.params.task.state; + + if (state === "working" && event.params.chunk) { + totalChunks++; + process.stdout.write( + `\r[Chunk ${totalChunks}] ${event.params.chunk.content.slice(0, 50)}...` + ); + } + if (state === "completed") { + const meta = event.params.metadata; + console.log( + `\nโœ… Done | Cost: $${meta?.cost_envelope?.actual || 0} | Route: ${meta?.routing_explanation || "N/A"}` + ); + } + if (state === "failed") { + console.error(`\nโŒ Failed: ${event.params.metadata?.error}`); + } + } + } + } +} +``` + +### ๐Ÿ” Use Case 4: Task Polling Pattern + +For long-running tasks, poll the task status instead of waiting synchronously. + +```python +import time + +def poll_task(task_id: str, timeout: int = 60): + """Poll task status until completion or timeout.""" + start = time.time() + while time.time() - start < timeout: + result = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "poll-1", + "method": "tasks/get", + "params": {"taskId": task_id}, + }).json() + + task = result["result"]["task"] + state = task["state"] + print(f" Task {task_id[:8]}... state={state}") + + if state in ("completed", "failed", "cancelled"): + return task + time.sleep(2) + + # Timeout โ€” cancel the task + requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "cancel-1", + "method": "tasks/cancel", + "params": {"taskId": task_id}, + }) + raise TimeoutError(f"Task {task_id} timed out after {timeout}s") +``` + +--- + +## Error Codes + +| Code | Constant | Meaning | +| ------ | ------------------------ | ---------------------------------------- | +| -32700 | โ€” | Parse error (invalid JSON) | +| -32600 | `INVALID_REQUEST` | Invalid JSON-RPC request or unauthorized | +| -32601 | `METHOD_NOT_FOUND` | Unknown method or skill | +| -32602 | `INVALID_PARAMS` | Missing or invalid parameters | +| -32603 | `INTERNAL_ERROR` | Skill execution failed | +| -32001 | `TASK_NOT_FOUND` | Task ID not found | +| -32002 | `TASK_ALREADY_COMPLETED` | Cannot modify a completed task | +| -32003 | `UNAUTHORIZED` | Invalid or missing API key | +| -32004 | `BUDGET_EXCEEDED` | Request exceeds configured budget | +| -32005 | `PROVIDER_UNAVAILABLE` | No available providers | + +--- + +## Authentication + +All `/a2a` requests require a Bearer token via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server (`OMNIROUTE_API_KEY` is empty), authentication is bypassed. + +--- + +## File Structure + +``` +src/lib/a2a/ +โ”œโ”€โ”€ taskManager.ts # Task lifecycle (create/update/cancel/list), TTL, cleanup +โ”œโ”€โ”€ taskExecution.ts # Generic task executor with state management +โ”œโ”€โ”€ streaming.ts # SSE stream formatting, heartbeat, chunk/completion events +โ”œโ”€โ”€ routingLogger.ts # Routing decision logger (stats, history, retention) +โ””โ”€โ”€ skills/ + โ”œโ”€โ”€ smartRouting.ts # Smart routing skill (routes via /v1/chat/completions) + โ””โ”€โ”€ quotaManagement.ts # Quota management skill (natural-language quota queries) + +src/app/a2a/ +โ””โ”€โ”€ route.ts # Next.js API route handler (JSON-RPC 2.0 dispatch) + +open-sse/mcp-server/ +โ””โ”€โ”€ schemas/a2a.ts # Zod schemas (AgentCard, Task, JSON-RPC, SSE events) +``` + +--- + +## Comparison: MCP vs A2A + +| Feature | MCP Server | A2A Server | +| ----------------- | ---------------------------- | ------------------------------------------------- | +| **Protocol** | Model Context Protocol | Agent-to-Agent Protocol v0.3 | +| **Transport** | stdio / HTTP | HTTP (JSON-RPC 2.0) | +| **Discovery** | Tool listing via MCP | `/.well-known/agent.json` | +| **Granularity** | 16 individual tools | 2 high-level skills | +| **Best for** | IDE agents (Cursor, VS Code) | Multi-agent systems (LangChain, CrewAI) | +| **Streaming** | Not supported | SSE via `message/stream` | +| **Task tracking** | No | Full lifecycle (submitted โ†’ completed) | +| **Observability** | Audit log per tool call | Cost envelope + resilience trace + policy verdict | + +--- + +## Licentie + +Part of [OmniRoute](https://github.com/diegosouzapw/OmniRoute) โ€” MIT License. diff --git a/docs/i18n/no/A2A-SERVER.md b/docs/i18n/no/A2A-SERVER.md deleted file mode 100644 index 01531ff482..0000000000 --- a/docs/i18n/no/A2A-SERVER.md +++ /dev/null @@ -1,200 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/A2A-SERVER.md) - ---- - -# OmniRoute A2A Server Documentation - -> Agent-to-Agent Protocol v0.3 โ€” OmniRoute as an intelligent routing agent - -## Agent Discovery - -```bash -curl http://localhost:20128/.well-known/agent.json -``` - -Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements. - ---- - -## Authentication - -All `/a2a` requests require an API key via the `Authorization` header: - -``` -Authorization: Bearer YOUR_OMNIROUTE_API_KEY -``` - -If no API key is configured on the server, authentication is bypassed. - ---- - -## JSON-RPC 2.0 Methods - -### `message/send` โ€” Synchronous Execution - -Sends a message to a skill and waits for the complete response. - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{ - "jsonrpc": "2.0", - "id": "1", - "method": "message/send", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Write a hello world in Python"}], - "metadata": {"model": "auto", "combo": "fast-coding"} - } - }' -``` - -**Response:** - -```json -{ - "jsonrpc": "2.0", - "id": "1", - "result": { - "task": { "id": "uuid", "state": "completed" }, - "artifacts": [{ "type": "text", "content": "..." }], - "metadata": { - "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)", - "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, - "resilience_trace": [ - { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." } - ], - "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } - } - } -} -``` - -### `message/stream` โ€” SSE Streaming - -Same as `message/send` but returns Server-Sent Events for real-time streaming. - -```bash -curl -N -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{ - "jsonrpc": "2.0", - "id": "1", - "method": "message/stream", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Explain quantum computing"}] - } - }' -``` - -**SSE Events:** - -``` -data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}} - -: heartbeat 2026-03-03T17:00:00Z - -data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} -``` - -### `tasks/get` โ€” Query Task Status - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' -``` - -### `tasks/cancel` โ€” Cancel a Task - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' -``` - ---- - -## Available Skills - -| Skill | Description | -| :----------------- | :------------------------------------------------------------------------------------------------------------------------------ | -| `smart-routing` | Routes prompts through OmniRoute's intelligent pipeline. Returns response with routing explanation, cost, and resilience trace. | -| `quota-management` | Answers natural-language queries about provider quotas, suggests free combos, and provides quota rankings. | - ---- - -## Task Lifecycle - -``` -submitted โ†’ working โ†’ completed - โ†’ failed - โ†’ cancelled -``` - -- Tasks expire after 5 minutes (configurable) -- Terminal states: `completed`, `failed`, `cancelled` -- Event log tracks every state transition - ---- - -## Error Codes - -| Code | Meaning | -| :----- | :----------------------------- | -| -32700 | Parse error (invalid JSON) | -| -32600 | Invalid request / Unauthorized | -| -32601 | Method or skill not found | -| -32602 | Invalid params | -| -32603 | Internal error | - ---- - -## Integration Examples - -### Python (requests) - -```python -import requests - -resp = requests.post("http://localhost:20128/a2a", json={ - "jsonrpc": "2.0", "id": "1", - "method": "message/send", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Hello"}] - } -}, headers={"Authorization": "Bearer YOUR_KEY"}) - -result = resp.json()["result"] -print(result["artifacts"][0]["content"]) -print(result["metadata"]["routing_explanation"]) -``` - -### TypeScript (fetch) - -```typescript -const resp = await fetch("http://localhost:20128/a2a", { - method: "POST", - headers: { - "Content-Type": "application/json", - Authorization: "Bearer YOUR_KEY", - }, - body: JSON.stringify({ - jsonrpc: "2.0", - id: "1", - method: "message/send", - params: { - skill: "smart-routing", - messages: [{ role: "user", content: "Hello" }], - }, - }), -}); -const { result } = await resp.json(); -console.log(result.metadata.routing_explanation); -``` diff --git a/docs/i18n/no/API_REFERENCE.md b/docs/i18n/no/API_REFERENCE.md deleted file mode 100644 index b878605221..0000000000 --- a/docs/i18n/no/API_REFERENCE.md +++ /dev/null @@ -1,455 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/API_REFERENCE.md) - ---- - -# API Reference - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/API_REFERENCE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/API_REFERENCE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/API_REFERENCE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/API_REFERENCE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/API_REFERENCE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/API_REFERENCE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/API_REFERENCE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/API_REFERENCE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/API_REFERENCE.md) - -Complete reference for all OmniRoute API endpoints. - ---- - -## Table of Contents - -- [Chat Completions](#chat-completions) -- [Embeddings](#embeddings) -- [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`. - -### ACP Agents - -| Endpoint | Method | Description | -| ----------------- | ------ | -------------------------------------------------------- | -| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | -| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | -| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | - -GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). - -### Resilience & Rate Limits - -| Endpoint | Method | Description | -| ----------------------- | ------- | ------------------------------- | -| `/api/resilience` | 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` diff --git a/docs/i18n/no/ARCHITECTURE.md b/docs/i18n/no/ARCHITECTURE.md deleted file mode 100644 index 4ea06a29f2..0000000000 --- a/docs/i18n/no/ARCHITECTURE.md +++ /dev/null @@ -1,787 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/ARCHITECTURE.md) - ---- - -# OmniRoute Architecture - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/ARCHITECTURE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/ARCHITECTURE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/ARCHITECTURE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/ARCHITECTURE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/ARCHITECTURE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/ARCHITECTURE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/ARCHITECTURE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/ARCHITECTURE.md) - -_Last updated: 2026-03-04_ - -## 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 (`...`) for reasoning models -- Response sanitization for strict OpenAI SDK compatibility -- Role normalization (developerโ†’system, systemโ†’user) for cross-provider compatibility -- Structured output conversion (json_schema โ†’ Gemini responseSchema) -- Local persistence for providers, keys, aliases, combos, settings, pricing -- Usage/cost tracking and request logging -- Optional cloud sync for multi-device/state sync -- IP allowlist/blocklist for API access control -- Thinking budget management (passthrough/auto/custom/adaptive) -- Global system prompt injection -- Session tracking and fingerprinting -- Per-account enhanced rate limiting with provider-specific profiles -- Circuit breaker pattern for provider resilience -- Anti-thundering herd protection with mutex locking -- Signature-based request deduplication cache -- Domain layer: model availability, cost rules, fallback policy, lockout policy -- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) -- Policy engine for centralized request evaluation (lockout โ†’ budget โ†’ fallback) -- Request telemetry with p50/p95/p99 latency aggregation -- Correlation ID (X-Request-Id) for end-to-end tracing -- Compliance audit logging with opt-out per API key -- Eval framework for LLM quality assurance -- Resilience UI dashboard with real-time circuit breaker status -- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) - -Primary runtime model: - -- Next.js 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[(storage.sqlite)] - UDB[(usage tables + log artifacts)] - end - - subgraph Upstreams[Upstream Providers] - P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/Qoder/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/route.ts` (GET) -- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) -- OAuth: `src/app/api/oauth/*` -- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` -- Usage: `src/app/api/usage/*` -- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` -- CLI tooling helpers: `src/app/api/cli-tools/*` -- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) -- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) -- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) -- Sessions: `src/app/api/sessions` (GET) -- Rate limits: `src/app/api/rate-limits` (GET) -- Resilience: `src/app/api/resilience` (GET/PATCH) โ€” provider profiles, circuit breaker, rate limit state -- Resilience reset: `src/app/api/resilience/reset` (POST) โ€” reset breakers + cooldowns -- Cache stats: `src/app/api/cache/stats` (GET/DELETE) -- Model availability: `src/app/api/models/availability` (GET/POST) -- Telemetry: `src/app/api/telemetry/summary` (GET) -- Budget: `src/app/api/usage/budget` (GET/POST) -- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) -- Compliance audit: `src/app/api/compliance/audit-log` (GET) -- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) -- Policies: `src/app/api/policies` (GET/POST) - -## 2) SSE + 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` -- Response sanitization: `open-sse/handlers/responseSanitizer.ts` -- Role normalization: `open-sse/services/roleNormalizer.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`, `qoder.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 (SQLite): - -- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) -- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) -- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) -- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** - -Usage persistence: - -- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) -- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` -- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) -- legacy JSON files are migrated to SQLite by startup migrations when present - -Domain State DB (SQLite): - -- `src/lib/db/domainState.ts` โ€” CRUD operations 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: - -- primary runtime DB: `${DATA_DIR}/storage.sqlite` -- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) -- structured call payload archives: `${DATA_DIR}/call_logs/` -- optional translator/request debug sessions: `/logs/...` - -## Deployment Topology - -```mermaid -flowchart LR - 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[(storage.sqlite)] - UsageDB[(usage tables + log artifacts)] - end - - subgraph External[External Services] - Providers[AI Providers] - SyncCloud[Cloud Sync Service] - end - - CLI --> Next - Browser --> Next - Next --> Core - Next --> MainDB - Core --> MainDB - Core --> UsageDB - Core --> Providers - Next --> SyncCloud -``` - -## Module Mapping (Decision-Critical) - -### Route and API Modules - -- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs -- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) -- `src/app/api/providers*`: provider CRUD, validation, testing -- `src/app/api/provider-nodes*`: custom compatible node management -- `src/app/api/provider-models`: custom model management (CRUD) -- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) -- `src/app/api/oauth/*`: OAuth/device-code flows -- `src/app/api/keys*`: local API key lifecycle -- `src/app/api/models/alias`: alias management -- `src/app/api/combos*`: fallback combo management -- `src/app/api/pricing`: pricing overrides for cost calculation -- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) -- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) -- `src/app/api/usage/*`: usage and logs APIs -- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers -- `src/app/api/cli-tools/*`: local CLI config writers/checkers -- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) -- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) -- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) -- `src/app/api/sessions`: active session listing (GET) -- `src/app/api/rate-limits`: per-account rate limit status (GET) - -### Routing and Execution Core - -- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop -- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup -- `open-sse/executors/*`: provider-specific network and format behavior - -### Translation Registry and Format Converters - -- `open-sse/translator/index.ts`: translator registry and orchestration -- Request translators: `open-sse/translator/request/*` -- Response translators: `open-sse/translator/response/*` -- Format constants: `open-sse/translator/formats.ts` - -### Persistence - -- `src/lib/db/*`: persistent config/state and domain persistence on SQLite -- `src/lib/localDb.ts`: compatibility re-export for DB modules -- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables - -## Provider Executor Coverage (Strategy Pattern) - -Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. - -| Executor | Provider(s) | Special Handling | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | -| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, Qoder, 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 | -| Qoder | openai | OAuth (Basic) | โœ… | โœ… | โœ… | โš ๏ธ Per request | -| OpenRouter | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| GLM/Kimi/MiniMax | claude | API Key | โœ… | โœ… | โŒ | โŒ | -| DeepSeek | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Groq | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| xAI (Grok) | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Mistral | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Perplexity | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Together AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Fireworks AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Cerebras | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Cohere | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| NVIDIA NIM | openai | API Key | โœ… | โœ… | โŒ | โŒ | - -## Format Translation Coverage - -Detected source formats include: - -- `openai` -- `openai-responses` -- `claude` -- `gemini` - -Target formats include: - -- OpenAI chat/Responses -- Claude -- Gemini/Gemini-CLI/Antigravity envelope -- Kiro -- Cursor - -Translations use **OpenAI as the hub format** โ€” all conversions go through OpenAI as intermediate: - -``` -Source Format โ†’ OpenAI (hub) โ†’ Target Format -``` - -Translations are selected dynamically based on source payload shape and provider target format. - -Additional processing layers in the translation pipeline: - -- **Response sanitization** โ€” Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance -- **Role normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI targets; merges `system` โ†’ `user` for models that reject the system role (GLM, ERNIE) -- **Think tag extraction** โ€” Parses `...` blocks from content into `reasoning_content` field -- **Structured output** โ€” Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` - -## Supported API Endpoints - -| 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 `/logs//` 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 - -- SQLite schema migrations and auto-upgrade hooks at startup -- legacy JSON โ†’ SQLite migration compatibility path - -## Observability and Operational Signals - -Runtime visibility sources: - -- console logs from `src/sse/utils/logger.ts` -- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) -- textual request status log in `log.txt` (optional/compat) -- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` -- dashboard usage endpoints (`/api/usage/*`) for UI consumption - -## Security-Sensitive Boundaries - -- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing -- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning -- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format -- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level -- Cloud sync endpoints rely on API key auth + machine id semantics - -## Environment and Runtime Matrix - -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` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. -2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. -3. Request logger writes full headers/body when enabled; treat log directory as sensitive. -4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. -5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. -6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). -7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). -8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). - -## Operational Verification Checklist - -- Build from source: `npm run build` -- Build Docker image: `docker build -t omniroute .` -- Start service and verify: -- `GET /api/settings` -- `GET /api/v1/models` -- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/no/AUTO-COMBO.md b/docs/i18n/no/AUTO-COMBO.md deleted file mode 100644 index 2166e41dff..0000000000 --- a/docs/i18n/no/AUTO-COMBO.md +++ /dev/null @@ -1,67 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/AUTO-COMBO.md) - ---- - -# OmniRoute Auto-Combo Engine - -> Self-managing model chains with adaptive scoring - -## How It Works - -The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**: - -| Factor | Weight | Description | -| :--------- | :----- | :---------------------------------------------- | -| Quota | 0.20 | Remaining capacity [0..1] | -| Health | 0.25 | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 | -| CostInv | 0.20 | Inverse cost (cheaper = higher score) | -| LatencyInv | 0.15 | Inverse p95 latency (faster = higher) | -| TaskFit | 0.10 | Model ร— task type fitness score | -| Stability | 0.10 | Low variance in latency/errors | - -## Mode Packs - -| Pack | Focus | Key Weight | -| :---------------------- | :----------- | :--------------- | -| ๐Ÿš€ **Ship Fast** | Speed | latencyInv: 0.35 | -| ๐Ÿ’ฐ **Cost Saver** | Economy | costInv: 0.40 | -| ๐ŸŽฏ **Quality First** | Best model | taskFit: 0.40 | -| ๐Ÿ“ก **Offline Friendly** | Availability | quota: 0.40 | - -## Self-Healing - -- **Temporary exclusion**: Score < 0.2 โ†’ excluded for 5 min (progressive backoff, max 30 min) -- **Circuit breaker awareness**: OPEN โ†’ auto-excluded; HALF_OPEN โ†’ probe requests -- **Incident mode**: >50% OPEN โ†’ disable exploration, maximize stability -- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout - -## Bandit Exploration - -5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode. - -## API - -```bash -# Create auto-combo -curl -X POST http://localhost:20128/api/combos/auto \ - -H "Content-Type: application/json" \ - -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}' - -# List auto-combos -curl http://localhost:20128/api/combos/auto -``` - -## Task Fitness - -30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` โ†’ high coding score). - -## Files - -| File | Purpose | -| :------------------------------------------- | :------------------------------------ | -| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization | -| `open-sse/services/autoCombo/taskFitness.ts` | Model ร— task fitness lookup | -| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap | -| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode | -| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles | -| `src/app/api/combos/auto/route.ts` | REST API | diff --git a/docs/i18n/no/CHANGELOG.md b/docs/i18n/no/CHANGELOG.md index bc30969e2b..e548302520 100644 --- a/docs/i18n/no/CHANGELOG.md +++ b/docs/i18n/no/CHANGELOG.md @@ -1,12 +1,92 @@ # Changelog (Norsk) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CHANGELOG.md) --- - ## [Unreleased] +### ๐Ÿ› ๏ธ Maintenance + +- **AGENTS.md rewrite:** Condensed from 297โ†’153 lines. Added build/lint/test commands (including single-test execution), code style guidelines (Prettier, TypeScript, ESLint, naming, imports, error handling, security), and trimmed verbose architecture tables for AI agent consumption. + +## [3.4.2] - 2026-04-01 + +### ๐Ÿ› Bug Fixes + +- **CI Stabilization:** Fixed failing analytics/settings Playwright selectors and request assertions so GitHub Actions E2E runs pass reliably across localized UIs and switch-based controls. +- **Deterministic Tests:** Removed date-sensitive quota fixtures from Copilot usage tests and aligned idempotency/model catalog tests with the merged runtime behavior. +- **MCP Type Hardening:** Removed zero-budget explicit `any` regressions from the MCP server tool registration path, restoring the `check:any-budget:t11` workflow gate. + +### ๐Ÿ› ๏ธ Maintenance + +- **Release Branch Integration:** Consolidated the active feature branches into `release/v3.4.2` on top of current `main` and validated the branch with lint, unit, coverage, build, and CI-mode E2E runs. + +## [3.4.1] - 2026-03-31 + +> [!WARNING] +> **BREAKING CHANGE: request logging, retention, and logging environment variables have been redesigned.** +> On the first startup after upgrading, OmniRoute archives legacy request logs from `DATA_DIR/logs/`, legacy `DATA_DIR/call_logs/`, and `DATA_DIR/log.txt` into `DATA_DIR/log_archives/*.zip`, then removes the deprecated layout and switches to the new unified artifact format under `DATA_DIR/call_logs/`. + +### โœจ New Features + +- **.ENV Migration Utility:** Included `scripts/migrate-env.mjs` to seamlessly migrate ` Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` - ---- - -## Step 2 โ€” Install CLI Tools - -All npm-based tools require Node.js 18+: - -```bash -# Claude Code (Anthropic) -npm install -g @anthropic-ai/claude-code - -# OpenAI Codex -npm install -g @openai/codex - -# Gemini CLI (Google) -npm install -g @google/gemini-cli - -# OpenCode -npm install -g opencode-ai - -# Cline -npm install -g cline - -# KiloCode -npm install -g kilecode - -# Kiro CLI (Amazon โ€” requires curl + unzip) -apt-get install -y unzip # on Debian/Ubuntu -curl -fsSL https://cli.kiro.dev/install | bash -export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc -``` - -**Verify:** - -```bash -claude --version # 2.x.x -codex --version # 0.x.x -gemini --version # 0.x.x -opencode --version # x.x.x -cline --version # 2.x.x -kilocode --version # x.x.x (or: kilo --version) -kiro-cli --version # 1.x.x -``` - ---- - -## Step 3 โ€” Set Global Environment Variables - -Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`: - -```bash -# OmniRoute Universal Endpoint -export OPENAI_BASE_URL="http://localhost:20128/v1" -export OPENAI_API_KEY="sk-your-omniroute-key" -export ANTHROPIC_BASE_URL="http://localhost:20128/v1" -export ANTHROPIC_API_KEY="sk-your-omniroute-key" -export GEMINI_BASE_URL="http://localhost:20128/v1" -export GEMINI_API_KEY="sk-your-omniroute-key" -``` - -> For a **remote server** replace `localhost:20128` with the server IP or domain, -> e.g. `http://192.168.0.15:20128`. - ---- - -## Step 4 โ€” Configure Each Tool - -### Claude Code - -```bash -# Via CLI: -claude config set --global api-base-url http://localhost:20128/v1 - -# Or create ~/.claude/settings.json: -mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF -{ - "apiBaseUrl": "http://localhost:20128/v1", - "apiKey": "sk-your-omniroute-key" -} -EOF -``` - -**Test:** `claude "say hello"` - ---- - -### OpenAI Codex - -```bash -mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF -model: auto -apiKey: sk-your-omniroute-key -apiBaseUrl: http://localhost:20128/v1 -EOF -``` - -**Test:** `codex "what is 2+2?"` - ---- - -### Gemini CLI - -```bash -mkdir -p ~/.gemini && cat > ~/.gemini/settings.json << EOF -{ - "apiKey": "sk-your-omniroute-key", - "baseUrl": "http://localhost:20128/v1" -} -EOF -``` - -**Test:** `gemini "hello"` - ---- - -### OpenCode - -```bash -mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF -[provider.openai] -base_url = "http://localhost:20128/v1" -api_key = "sk-your-omniroute-key" -EOF -``` - -**Test:** `opencode` - ---- - -### Cline (CLI or VS Code) - -**CLI mode:** - -```bash -mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF -{ - "apiProvider": "openai", - "openAiBaseUrl": "http://localhost:20128/v1", - "openAiApiKey": "sk-your-omniroute-key" -} -EOF -``` - -**VS Code mode:** -Cline extension settings โ†’ API Provider: `OpenAI Compatible` โ†’ Base URL: `http://localhost:20128/v1` - -Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ Cline โ†’ Apply Config**. - ---- - -### KiloCode (CLI or VS Code) - -**CLI mode:** - -```bash -kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key -``` - -**VS Code settings:** - -```json -{ - "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", - "kilo-code.apiKey": "sk-your-omniroute-key" -} -``` - -Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ KiloCode โ†’ Apply Config**. - ---- - -### Continue (VS Code Extension) - -Edit `~/.continue/config.yaml`: - -```yaml -models: - - name: OmniRoute - provider: openai - model: auto - apiBase: http://localhost:20128/v1 - apiKey: sk-your-omniroute-key - default: true -``` - -Restart VS Code after editing. - ---- - -### Kiro CLI (Amazon) - -```bash -# Login to your AWS/Kiro account: -kiro-cli login - -# The CLI uses its own auth โ€” OmniRoute is not needed as backend for Kiro CLI itself. -# Use kiro-cli alongside OmniRoute for other tools. -kiro-cli status -``` - ---- - -### Cursor (Desktop App) - -> **Note:** Cursor routes requests through its cloud. For OmniRoute integration, -> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL. - -Via GUI: **Settings โ†’ Models โ†’ OpenAI API Key** - -- Base URL: `https://your-domain.com/v1` -- API Key: your OmniRoute key - ---- - -## Dashboard Auto-Configuration - -The OmniRoute dashboard automates configuration for most tools: - -1. Go to `http://localhost:20128/dashboard/cli-tools` -2. Expand any tool card -3. Select your API key from the dropdown -4. Click **Apply Config** (if tool is detected as installed) -5. Or copy the generated config snippet manually - ---- - -## Built-in Agents: Droid & OpenClaw - -**Droid** and **OpenClaw** are AI agents built directly into OmniRoute โ€” no installation needed. -They run as internal routes and use OmniRoute's model routing automatically. - -- Access: `http://localhost:20128/dashboard/agents` -- Configure: same combos and providers as all other tools -- No API key or CLI install required - ---- - -## Available API Endpoints - -| Endpoint | Description | Use For | -| -------------------------- | ----------------------------- | --------------------------- | -| `/v1/chat/completions` | Standard chat (all providers) | All modern tools | -| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows | -| `/v1/completions` | Legacy text completions | Older tools using `prompt:` | -| `/v1/embeddings` | Text embeddings | RAG, search | -| `/v1/images/generations` | Image generation | DALL-E, Flux, etc. | -| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS | -| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI | - ---- - -## Troubleshooting - -| Error | Cause | Fix | -| ------------------------- | ----------------------- | ------------------------------------------ | -| `Connection refused` | OmniRoute not running | `pm2 start omniroute` | -| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` | -| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` | -| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` | -| CLI shows "not installed" | Binary not in PATH | Check `which ` | -| `kiro-cli: not found` | Not in PATH | `export PATH="$HOME/.local/bin:$PATH"` | - ---- - -## Quick Setup Script (One Command) - -```bash -# Install all CLIs and configure for OmniRoute (replace with your key and server URL) -OMNIROUTE_URL="http://localhost:20128/v1" -OMNIROUTE_KEY="sk-your-omniroute-key" - -npm install -g @anthropic-ai/claude-code @openai/codex @google/gemini-cli opencode-ai cline kilecode - -# Kiro CLI -apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash - -# Write configs -mkdir -p ~/.claude ~/.codex ~/.gemini ~/.config/opencode ~/.continue - -cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" -cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" -cat > ~/.gemini/settings.json <<< "{\"apiKey\":\"$OMNIROUTE_KEY\",\"baseUrl\":\"$OMNIROUTE_URL\"}" -cat >> ~/.bashrc << EOF -export OPENAI_BASE_URL="$OMNIROUTE_URL" -export OPENAI_API_KEY="$OMNIROUTE_KEY" -export ANTHROPIC_BASE_URL="$OMNIROUTE_URL" -export ANTHROPIC_API_KEY="$OMNIROUTE_KEY" -EOF - -source ~/.bashrc -echo "โœ… All CLIs installed and configured for OmniRoute" -``` diff --git a/docs/i18n/no/CODEBASE_DOCUMENTATION.md b/docs/i18n/no/CODEBASE_DOCUMENTATION.md deleted file mode 100644 index e2d7950052..0000000000 --- a/docs/i18n/no/CODEBASE_DOCUMENTATION.md +++ /dev/null @@ -1,593 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CODEBASE_DOCUMENTATION.md) - ---- - -# omniroute โ€” Codebase Documentation - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) - -> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. - ---- - -## 1. 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
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, Qoder, 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 | -| Qoder | 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"] -``` diff --git a/docs/i18n/no/CONTRIBUTING.md b/docs/i18n/no/CONTRIBUTING.md new file mode 100644 index 0000000000..7e392eb497 --- /dev/null +++ b/docs/i18n/no/CONTRIBUTING.md @@ -0,0 +1,299 @@ +# Contributing to OmniRoute (Norsk) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CONTRIBUTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CONTRIBUTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CONTRIBUTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CONTRIBUTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CONTRIBUTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CONTRIBUTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CONTRIBUTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CONTRIBUTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CONTRIBUTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CONTRIBUTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CONTRIBUTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CONTRIBUTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CONTRIBUTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CONTRIBUTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CONTRIBUTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CONTRIBUTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CONTRIBUTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CONTRIBUTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CONTRIBUTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CONTRIBUTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CONTRIBUTING.md) + +--- + +Thank you for your interest in contributing! This guide covers everything you need to get started. + +--- + +## Development Setup + +### Prerequisites + +- **Node.js** >= 18 < 24 (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` | `20128` | Server port | +| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | Base URL for frontend | +| `JWT_SECRET` | (generate above) | JWT signing secret | +| `INITIAL_PASSWORD` | `CHANGEME` | First login password | +| `APP_LOG_LEVEL` | `info` | Log verbosity level | + +### Dashboard Settings + +The dashboard provides UI toggles for features that can also be configured via environment variables: + +| Setting Location | Toggle | Description | +| ------------------- | ------------------ | ------------------------------ | +| Settings โ†’ Advanced | Debug Mode | Enable debug request logs (UI) | +| Settings โ†’ General | Sidebar Visibility | Show/hide sidebar sections | + +These settings are stored in the database and persist across restarts, overriding env var defaults when set. + +### 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:20128/dashboard` +- **API**: `http://localhost:20128/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`, `mcp`, `a2a`, `memory`, `skills`. + +--- + +## Running Tests + +```bash +# All tests (unit + vitest + ecosystem + e2e) +npm run test:all + +# Single test file (Node.js native test runner โ€” most tests use this) +node --import tsx/esm --test tests/unit/your-file.test.mjs + +# Vitest (MCP server, autoCombo, cache) +npm run test:vitest + +# E2E tests (requires Playwright) +npm run test:e2e + +# Protocol clients E2E (MCP transports, A2A) +npm run test:protocols:e2e + +# Ecosystem compatibility tests +npm run test:ecosystem + +# Coverage (55% min statements/lines/functions; 60% branches) +npm run test:coverage +npm run coverage:report + +# Lint + format check +npm run lint +npm run check +``` + +Coverage notes: + +- `npm run test:coverage` measures source coverage for the main unit test suite, excludes `tests/**`, and includes `open-sse/**` +- `npm run coverage:report` prints the detailed file-by-file report from the latest coverage run +- `npm run test:coverage:legacy` preserves the older metric for historical comparison +- See `docs/COVERAGE_PLAN.md` for the phased coverage improvement roadmap + +Current test status: **122 unit test files** covering: + +- Provider translators and format conversion +- Rate limiting, circuit breaker, and resilience +- Semantic cache, idempotency, progress tracking +- Database operations and schema (21 DB modules) +- OAuth flows and authentication +- API endpoint validation (Zod v4) +- MCP server tools and scope enforcement +- Memory and Skills systems + +--- + +## Code Style + +- **ESLint** โ€” Run `npm run lint` before committing +- **Prettier** โ€” Auto-formatted via `lint-staged` on commit (2 spaces, semicolons, double quotes, 100 char width, es5 trailing commas) +- **TypeScript** โ€” All `src/` code uses `.ts`/`.tsx`; `open-sse/` uses `.ts`/`.js`; document with TSDoc (`@param`, `@returns`, `@throws`) +- **No `eval()`** โ€” ESLint enforces `no-eval`, `no-implied-eval`, `no-new-func` +- **Zod validation** โ€” Use Zod v4 schemas for all API input validation +- **Naming**: Files = camelCase/kebab-case, components = PascalCase, constants = UPPER_SNAKE + +--- + +## Project Structure + +``` +src/ # TypeScript (.ts / .tsx) +โ”œโ”€โ”€ app/ # Next.js 16 App Router +โ”‚ โ”œโ”€โ”€ (dashboard)/ # Dashboard pages (23 sections) +โ”‚ โ”œโ”€โ”€ api/ # API routes (51 directories) +โ”‚ โ””โ”€โ”€ login/ # Auth pages (.tsx) +โ”œโ”€โ”€ domain/ # Policy engine (policyEngine, comboResolver, costRules, etc.) +โ”œโ”€โ”€ lib/ # Core business logic (.ts) +โ”‚ โ”œโ”€โ”€ a2a/ # Agent-to-Agent v0.3 protocol server +โ”‚ โ”œโ”€โ”€ acp/ # Agent Communication Protocol registry +โ”‚ โ”œโ”€โ”€ compliance/ # Compliance policy engine +โ”‚ โ”œโ”€โ”€ db/ # SQLite database layer (21 modules + 16 migrations) +โ”‚ โ”œโ”€โ”€ memory/ # Persistent conversational memory +โ”‚ โ”œโ”€โ”€ oauth/ # OAuth providers, services, and utilities +โ”‚ โ”œโ”€โ”€ skills/ # Extensible skill framework +โ”‚ โ”œโ”€โ”€ usage/ # Usage tracking and cost calculation +โ”‚ โ””โ”€โ”€ localDb.ts # Re-export layer only โ€” never add logic here +โ”œโ”€โ”€ middleware/ # Request middleware (promptInjectionGuard) +โ”œโ”€โ”€ mitm/ # MITM proxy (cert, DNS, target routing) +โ”œโ”€โ”€ shared/ +โ”‚ โ”œโ”€โ”€ components/ # React components (.tsx) +โ”‚ โ”œโ”€โ”€ constants/ # Provider definitions (60+), MCP scopes, routing strategies +โ”‚ โ”œโ”€โ”€ utils/ # Circuit breaker, sanitizer, auth helpers +โ”‚ โ””โ”€โ”€ validation/ # Zod v4 schemas +โ””โ”€โ”€ sse/ # SSE proxy pipeline + +open-sse/ # @omniroute/open-sse workspace +โ”œโ”€โ”€ executors/ # 14 provider-specific request executors +โ”œโ”€โ”€ handlers/ # 11 request handlers (chat, responses, embeddings, images, etc.) +โ”œโ”€โ”€ mcp-server/ # MCP server (25 tools, 3 transports, 10 scopes) +โ”œโ”€โ”€ services/ # 36+ services (combo, autoCombo, rateLimitManager, etc.) +โ”œโ”€โ”€ translator/ # Format translators (OpenAI โ†” Claude โ†” Gemini โ†” Responses โ†” Ollama) +โ”œโ”€โ”€ transformer/ # Responses API transformer +โ””โ”€โ”€ utils/ # 22 utility modules (stream, TLS, proxy, logging) + +electron/ # Electron desktop app (cross-platform) + +tests/ +โ”œโ”€โ”€ unit/ # Node.js test runner (122 test files) +โ”œโ”€โ”€ integration/ # Integration tests +โ”œโ”€โ”€ e2e/ # Playwright tests +โ”œโ”€โ”€ security/ # Security tests +โ”œโ”€โ”€ translator/ # Translator-specific tests +โ””โ”€โ”€ load/ # Load tests + +docs/ # Documentation +โ”œโ”€โ”€ ARCHITECTURE.md # System architecture +โ”œโ”€โ”€ API_REFERENCE.md # All endpoints +โ”œโ”€โ”€ USER_GUIDE.md # Provider setup, CLI integration +โ”œโ”€โ”€ TROUBLESHOOTING.md # Common issues +โ”œโ”€โ”€ MCP-SERVER.md # MCP server (25 tools) +โ”œโ”€โ”€ A2A-SERVER.md # A2A agent protocol +โ”œโ”€โ”€ AUTO-COMBO.md # Auto-combo engine +โ”œโ”€โ”€ CLI-TOOLS.md # CLI tools integration +โ”œโ”€โ”€ COVERAGE_PLAN.md # Test coverage improvement plan +โ”œโ”€โ”€ openapi.yaml # OpenAPI specification +โ””โ”€โ”€ adr/ # Architecture Decision Records +``` + +--- + +## Adding a New Provider + +### Step 1: Register Provider Constants + +Add to `src/shared/constants/providers.ts` โ€” Zod-validated at module load. + +### Step 2: Add Executor (if custom logic needed) + +Create executor in `open-sse/executors/your-provider.ts` extending the base executor. + +### Step 3: Add Translator (if non-OpenAI format) + +Create request/response translators in `open-sse/translator/`. + +### Step 4: Add OAuth Config (if OAuth-based) + +Add OAuth credentials in `src/lib/oauth/constants/oauth.ts` and service in `src/lib/oauth/services/`. + +### Step 5: Register Models + +Add model definitions in `open-sse/config/providerRegistry.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 +- [ ] All inputs validated with Zod schemas +- [ ] CHANGELOG updated (if user-facing change) +- [ ] Documentation updated (if applicable) + +--- + +## Releasing + +Releases are managed via the `/generate-release` workflow. When a new GitHub Release is created, the package is **automatically published to npm** via GitHub Actions. + +--- + +## Getting Help + +- **Architecture**: See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) +- **API Reference**: See [`docs/API_REFERENCE.md`](docs/API_REFERENCE.md) +- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **ADRs**: See `docs/adr/` for architectural decision records diff --git a/docs/i18n/no/FEATURES.md b/docs/i18n/no/FEATURES.md deleted file mode 100644 index 248c3f5883..0000000000 --- a/docs/i18n/no/FEATURES.md +++ /dev/null @@ -1,147 +0,0 @@ -# OmniRoute โ€” Dashboard Features Gallery (Norsk) - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) - -> ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../docs/FEATURES.md) - ---- - -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 (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. - -![Providers Dashboard](screenshots/01-providers.png) - ---- - -## ๐ŸŽจ Combos - -Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. - -![Combos Dashboard](screenshots/02-combos.png) - ---- - -## ๐Ÿ“Š Analytics - -Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. - -![Analytics Dashboard](screenshots/03-analytics.png) - ---- - -## ๐Ÿฅ System Health - -Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. - -![Health Dashboard](screenshots/04-health.png) - ---- - -## ๐Ÿ”ง Translator Playground - -Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). - -![Translator Playground](screenshots/05-translator.png) - ---- - -## ๐ŸŽฎ Model Playground _(v2.0.9+)_ - -Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. - ---- - -## ๐ŸŽจ Themes _(v2.0.5+)_ - -Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. - ---- - -## โš™๏ธ Settings - -Comprehensive settings panel with tabs: - -- **General** โ€” System storage, backup management (export/import database) -- **Appearance** โ€” Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls -- **Security** โ€” API endpoint protection, custom provider blocking, IP filtering, session info -- **Routing** โ€” Model aliases, background task degradation -- **Resilience** โ€” Rate limit persistence, circuit breaker tuning -- **Advanced** โ€” Configuration overrides - -![Settings Dashboard](screenshots/06-settings.png) - ---- - -## ๐Ÿ”ง CLI Tools - -One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. - -![CLI Tools Dashboard](screenshots/07-cli-tools.png) - ---- - -## ๐Ÿค– CLI Agents _(v2.0.11+)_ - -Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: - -- **Installation status** โ€” Installed / Not Found with version detection -- **Protocol badges** โ€” stdio, HTTP, etc. -- **Custom agents** โ€” Register any CLI tool via form (name, binary, version command, spawn args) -- **CLI Fingerprint Matching** โ€” Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP - ---- - -## ๐Ÿ–ผ๏ธ Media _(v2.0.3+)_ - -Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. - ---- - -## ๐Ÿ“ Request Logs - -Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. - -![Usage Logs](screenshots/08-usage.png) - ---- - -## ๐ŸŒ API Endpoint - -Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. - -![Endpoint Dashboard](screenshots/09-endpoint.png) - ---- - -## ๐Ÿ”‘ API Key Management - -Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. - ---- - -## ๐Ÿ“‹ Audit Log - -Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. - ---- - -## ๐Ÿ–ฅ๏ธ Desktop Application - -Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. - -Key features: - -- Server readiness polling (no blank screen on cold start) -- System tray with port management -- Content Security Policy -- Single-instance lock -- Auto-update on restart -- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) -- Hardened Electron build packaging โ€” symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+) - -๐Ÿ“– See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/no/MCP-SERVER.md b/docs/i18n/no/MCP-SERVER.md deleted file mode 100644 index 829acd30b1..0000000000 --- a/docs/i18n/no/MCP-SERVER.md +++ /dev/null @@ -1,87 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/MCP-SERVER.md) - ---- - -# OmniRoute MCP Server Documentation - -> Model Context Protocol server with 16 intelligent tools - -## Installation - -OmniRoute MCP is built-in. Start it with: - -```bash -omniroute --mcp -``` - -Or via the open-sse transport: - -```bash -# HTTP streamable transport (port 20130) -omniroute --dev # MCP auto-starts on /mcp endpoint -``` - -## IDE Configuration - -See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup. - ---- - -## Essential Tools (8) - -| Tool | Description | -| :------------------------------ | :--------------------------------------- | -| `omniroute_get_health` | Gateway health, circuit breakers, uptime | -| `omniroute_list_combos` | All configured combos with models | -| `omniroute_get_combo_metrics` | Performance metrics for a specific combo | -| `omniroute_switch_combo` | Switch active combo by ID/name | -| `omniroute_check_quota` | Quota status per provider or all | -| `omniroute_route_request` | Send a chat completion through OmniRoute | -| `omniroute_cost_report` | Cost analytics for a time period | -| `omniroute_list_models_catalog` | Full model catalog with capabilities | - -## Advanced Tools (8) - -| Tool | Description | -| :--------------------------------- | :---------------------------------------------- | -| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | -| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | -| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | -| `omniroute_test_combo` | Live-test all models in a combo | -| `omniroute_get_provider_metrics` | Detailed metrics for one provider | -| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | -| `omniroute_explain_route` | Explain a past routing decision | -| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | - -## Authentication - -MCP tools are authenticated via API key scopes. Each tool requires specific scopes: - -| Scope | Tools | -| :------------- | :----------------------------------------------- | -| `read:health` | get_health, get_provider_metrics | -| `read:combos` | list_combos, get_combo_metrics | -| `write:combos` | switch_combo | -| `read:quota` | check_quota | -| `write:route` | route_request, simulate_route, test_combo | -| `read:usage` | cost_report, get_session_snapshot, explain_route | -| `write:config` | set_budget_guard, set_resilience_profile | -| `read:models` | list_models_catalog, best_combo_for_task | - -## Audit Logging - -Every tool call is logged to `mcp_tool_audit` with: - -- Tool name, arguments, result -- Duration (ms), success/failure -- API key hash, timestamp - -## Files - -| File | Purpose | -| :------------------------------------------- | :------------------------------------------ | -| `open-sse/mcp-server/server.ts` | MCP server creation + 16 tool registrations | -| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport | -| `open-sse/mcp-server/auth.ts` | API key + scope validation | -| `open-sse/mcp-server/audit.ts` | Tool call audit logging | -| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers | diff --git a/docs/i18n/no/README.md b/docs/i18n/no/README.md index 80513a83ef..2be0f184b2 100644 --- a/docs/i18n/no/README.md +++ b/docs/i18n/no/README.md @@ -1,12 +1,12 @@ # ๐Ÿš€ OmniRoute โ€” The Free AI Gateway (Norsk) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/README.md) --- ### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback. -_Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._ +_Your universal API proxy โ€” one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._ **Chat Completions โ€ข Embeddings โ€ข Image Generation โ€ข Video โ€ข Music โ€ข Audio โ€ข Reranking โ€ข **Web Search** โ€ข MCP Server โ€ข A2A Protocol โ€ข 100% TypeScript** @@ -46,15 +46,17 @@ _Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now wi > - `APP_LOG_FILE_PATH` > - `APP_LOG_MAX_FILE_SIZE` > - `APP_LOG_RETENTION_DAYS` +> - `APP_LOG_MAX_FILES` > - `APP_LOG_LEVEL` > - `APP_LOG_FORMAT` > - `CALL_LOG_RETENTION_DAYS` +> - `CALL_LOG_MAX_ENTRIES` > > For release details and upgrade notes, see the [CHANGELOG](CHANGELOG.md). --- -## ๐Ÿ†• What's New in v3.0.0 +## ๐Ÿ†• What's New > **Upgrading from v2.9.5?** โ€” See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes. @@ -274,7 +276,7 @@ Developers pay $20โ€“200/month for Claude Pro, Codex Pro, or GitHub Copilot. Eve - **Smart 4-Tier Fallback** โ€” If subscription quota runs out, automatically redirects to API Key โ†’ Cheap โ†’ Free with zero manual intervention - **Real-Time Quota Tracking** โ€” Shows token consumption in real-time with reset countdown (5h, daily, weekly) - **Multi-Account Support** โ€” Multiple accounts per provider with auto round-robin โ€” when one runs out, switches to the next -- **Custom Combos** โ€” Customizable fallback chains with 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Custom Combos** โ€” Customizable fallback chains with 9 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random) - **Codex Business Quotas** โ€” Business/Team workspace quota monitoring directly in the dashboard @@ -286,7 +288,7 @@ OpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If **How OmniRoute solves it:** -- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 67+ providers +- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 60+ providers - **Format Translation** โ€” Automatic and transparent: OpenAI โ†” Claude โ†” Gemini โ†” Responses API - **Response Sanitization** โ€” Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+ - **Role Normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI providers; `system` โ†’ `user` for GLM/ERNIE @@ -372,7 +374,7 @@ Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code.. - **CLI Tools Dashboard** โ€” Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline - **GitHub Copilot Config Generator** โ€” Generates `chatLanguageModels.json` for VS Code with bulk model selection - **Onboarding Wizard** โ€” Guided 4-step setup for first-time users -- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 67+ providers +- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 60+ providers @@ -419,7 +421,7 @@ When a call fails, the dev doesn't know if it was a rate limit, expired token, w - **SQLite Proxy Logs** โ€” Persistent logs that survive server restarts - **Translator Playground** โ€” 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time) - **Request Telemetry** โ€” p50/p95/p99 latency + X-Request-Id tracing -- **File-Based Logging with Rotation** โ€” Console interceptor captures everything to JSON log with size-based rotation +- **File-Based Logging with Rotation** โ€” App logs rotate by size, retention days, and archive count; call log artifacts rotate by retention days and file count - **System Info Report** โ€” `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage. @@ -514,7 +516,7 @@ Developers who want all responses in a specific language, with a specific tone, - **System Prompt Injection** โ€” Global prompt applied to all requests - **Thinking Budget Validation** โ€” Reasoning token allocation control per request (passthrough, auto, custom, adaptive) -- **6 Routing Strategies** โ€” Global strategies that determine how requests are distributed +- **9 Routing Strategies** โ€” Global strategies that determine how requests are distributed - **Wildcard Router** โ€” `provider/*` patterns route dynamically to any provider - **Combo Enable/Disable Toggle** โ€” Toggle combos directly from the dashboard - **Provider Toggle** โ€” Enable/disable all connections for a provider with one click @@ -581,7 +583,7 @@ Different clients should have least-privilege access to tool categories. **How OmniRoute solves it:** -- 9 granular MCP scopes for controlled tool access +- 10 granular MCP scopes for controlled tool access - Scope enforcement and visibility in MCP management UI - Safe default posture for operational tooling @@ -1325,19 +1327,19 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. ### ๐Ÿค– Agent & Protocol Operations (v2.0) -| Feature | What It Does | -| ------------------------------------- | -------------------------------------------------------------------------------------------------- | -| ๐Ÿ”ง **MCP Server (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) | -| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | -| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | -| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | -| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | -| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | -| ๐Ÿ” **MCP Scope Enforcement** | 9 granular scope permissions for controlled tool access | -| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | -| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | -| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | -| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | +| Feature | What It Does | +| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| ๐Ÿ”ง **MCP Server (25 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools | +| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | +| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | +| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | +| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | +| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | +| ๐Ÿ” **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access | +| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | +| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | +| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | +| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | ### ๐Ÿง  Routing & Intelligence @@ -1348,7 +1350,7 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. | ๐Ÿ”„ **Format Translation** | OpenAI โ†” Claude โ†” Gemini โ†” Responses with schema-safe conversions | | ๐Ÿ‘ฅ **Multi-Account Support** | Multiple accounts per provider with intelligent selection | | ๐Ÿ”„ **Auto Token Refresh** | OAuth tokens refresh automatically with retry | -| ๐ŸŽจ **Custom Combos** | 6 balancing strategies + fallback chain control | +| ๐ŸŽจ **Custom Combos** | 9 balancing strategies + fallback chain control | | ๐ŸŒ **Wildcard Router** | `provider/*` dynamic routing | | ๐Ÿง  **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits | | ๐Ÿ”€ **Model Aliases** | Built-in + custom model aliasing and migration safety | @@ -1949,6 +1951,7 @@ opencode - Request artifacts are written to `DATA_DIR/call_logs/` as one JSON file per request - Enable pipeline capture from Dashboard โ†’ Logs โ†’ Request Logs if you need detailed per-stage payloads - Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log` +- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed **Connection test shows "Invalid" for OpenAI-compatible providers** diff --git a/docs/i18n/no/RELEASE_CHECKLIST.md b/docs/i18n/no/RELEASE_CHECKLIST.md deleted file mode 100644 index 903e812c3f..0000000000 --- a/docs/i18n/no/RELEASE_CHECKLIST.md +++ /dev/null @@ -1,37 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/RELEASE_CHECKLIST.md) - ---- - -# Release Checklist - -Use this checklist before tagging or publishing a new OmniRoute release. - -## Version and Changelog - -1. Bump `package.json` version (`x.y.z`) in the release branch. -2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: - - `## [x.y.z] โ€” YYYY-MM-DD` -3. Keep `## [Unreleased]` as the first changelog section for upcoming work. -4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. - -## API Docs - -1. Update `docs/openapi.yaml`: - - `info.version` must equal `package.json` version. -2. Validate endpoint examples if API contracts changed. - -## Runtime Docs - -1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. -2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. -3. Update localized docs if source docs changed significantly. - -## Automated Check - -Run the sync guard locally before opening PR: - -```bash -npm run check:docs-sync -``` - -CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/no/SECURITY.md b/docs/i18n/no/SECURITY.md new file mode 100644 index 0000000000..4cce6967e7 --- /dev/null +++ b/docs/i18n/no/SECURITY.md @@ -0,0 +1,179 @@ +# Security Policy (Norsk) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../SECURITY.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/SECURITY.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/SECURITY.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/SECURITY.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/SECURITY.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/SECURITY.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/SECURITY.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/SECURITY.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/SECURITY.md) + +--- + +## 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 | +| ------- | -------------- | +| 3.4.x | โœ… Active | +| 3.0.x | โœ… Security | +| < 3.0.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 | +| **MCP Scopes** | 10 granular scopes for MCP tool access control | + +### ๐Ÿ›ก๏ธ 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:::` +- 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** | Allowlist/blocklist IP ranges in dashboard | +| **Rate Limiting** | Per-provider rate limits with automatic backoff | +| **Anti-Thundering Herd** | Mutex + per-connection locking prevents cascading 502s | +| **TLS Fingerprint** | Browser-like TLS fingerprint spoofing to reduce bot detection | +| **CLI Fingerprint** | Per-provider header/body ordering to match native CLI signatures | + +### ๐Ÿ”Œ Resilience & Availability + +| 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 `CALL_LOG_RETENTION_DAYS` | +| **No-Log Opt-out** | Per API key `noLog` flag disables request logging | +| **Audit Log** | Administrative actions tracked in `audit_log` table | +| **MCP Audit** | SQLite-backed audit logging for all MCP tool calls | +| **Zod Validation** | All API inputs validated with Zod v4 schemas at module load | + +--- + +## 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 +- Provider constants validated at module load via Zod (`src/shared/validation/providerSchema.ts`) diff --git a/docs/i18n/no/TROUBLESHOOTING.md b/docs/i18n/no/TROUBLESHOOTING.md deleted file mode 100644 index 63c148000a..0000000000 --- a/docs/i18n/no/TROUBLESHOOTING.md +++ /dev/null @@ -1,258 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/TROUBLESHOOTING.md) - ---- - -# Troubleshooting - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/TROUBLESHOOTING.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/TROUBLESHOOTING.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/TROUBLESHOOTING.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/TROUBLESHOOTING.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/TROUBLESHOOTING.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/TROUBLESHOOTING.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/TROUBLESHOOTING.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/TROUBLESHOOTING.md) - -Common problems and solutions for OmniRoute. - ---- - -## Quick Fixes - -| Problem | Solution | -| ----------------------------- | ------------------------------------------------------------------ | -| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | -| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | -| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | -| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | -| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | - ---- - -## Provider Issues - -### "Language model did not provide messages" - -**Cause:** Provider quota exhausted. - -**Fix:** - -1. 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, Qoder) 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}/storage.sqlite` (providers, combos, aliases, keys, settings) -- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` -- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) - ---- - -## Circuit Breaker Issues - -### Provider stuck in OPEN state - -When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. - -**Fix:** - -1. 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 -- **SDK returns raw string instead of object** โ€” Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures -- **GLM/ERNIE rejects `system` role** โ€” Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models -- **`developer` role not recognized** โ€” Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers -- **`json_schema` not working with Gemini** โ€” Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` - ---- - -## Resilience Settings - -### Auto rate-limit not triggering - -- 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. - ---- - -## Optional RAG / LLM failure taxonomy (16 problems) - -Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. - -In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. - -If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: - -- retrieval drift and broken context boundaries -- empty or stale indexes and vector stores -- embedding versus semantic mismatch -- prompt assembly and context window issues -- logic collapse and overconfident answers -- long chain and agent coordination failures -- multi agent memory and role drift -- deployment and bootstrap ordering problems - -The idea is simple: - -1. When you investigate a bad response, capture: - - user task and request - - route or provider combo in OmniRoute - - any RAG context used downstream (retrieved documents, tool calls, etc) -2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` โ€ฆ `No.16`). -3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. -4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. - -Full text and concrete recipes live here (MIT license, text only): - -[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) - -You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. - ---- - -## Still Stuck? - -- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details -- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints -- **Health Dashboard**: Check **Dashboard โ†’ Health** for real-time system status -- **Translator**: Use **Dashboard โ†’ Translator** to debug format issues diff --git a/docs/i18n/bg/A2A-SERVER.md b/docs/i18n/no/docs/A2A-SERVER.md similarity index 77% rename from docs/i18n/bg/A2A-SERVER.md rename to docs/i18n/no/docs/A2A-SERVER.md index 01531ff482..4c4ae8ce1e 100644 --- a/docs/i18n/bg/A2A-SERVER.md +++ b/docs/i18n/no/docs/A2A-SERVER.md @@ -1,9 +1,9 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/A2A-SERVER.md) +# OmniRoute A2A Server Documentation (Norsk) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/A2A-SERVER.md) --- -# OmniRoute A2A Server Documentation - > Agent-to-Agent Protocol v0.3 โ€” OmniRoute as an intelligent routing agent ## Agent Discovery diff --git a/docs/i18n/de/API_REFERENCE.md b/docs/i18n/no/docs/API_REFERENCE.md similarity index 74% rename from docs/i18n/de/API_REFERENCE.md rename to docs/i18n/no/docs/API_REFERENCE.md index b878605221..81fe5b5a27 100644 --- a/docs/i18n/de/API_REFERENCE.md +++ b/docs/i18n/no/docs/API_REFERENCE.md @@ -1,11 +1,9 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/API_REFERENCE.md) +# API Reference (Norsk) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/API_REFERENCE.md) --- -# API Reference - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/API_REFERENCE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/API_REFERENCE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/API_REFERENCE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/API_REFERENCE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/API_REFERENCE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/API_REFERENCE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/API_REFERENCE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/API_REFERENCE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/API_REFERENCE.md) - Complete reference for all OmniRoute API endpoints. --- @@ -42,15 +40,20 @@ Content-Type: application/json ### 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 | +| Header | Direction | Description | +| ------------------------ | --------- | ------------------------------------------------ | +| `X-OmniRoute-No-Cache` | Request | Set to `true` to bypass cache | +| `X-OmniRoute-Progress` | Request | Set to `true` for progress events | +| `X-Session-Id` | Request | Sticky session key for external session affinity | +| `x_session_id` | Request | Underscore variant also accepted (direct HTTP) | +| `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 | +| `X-OmniRoute-Session-Id` | Response | Effective session ID used by OmniRoute | + +> Nginx note: if you rely on underscore headers (for example `x_session_id`), enable `underscores_in_headers on;`. --- @@ -141,10 +144,10 @@ The provider prefix is auto-added if missing. Mismatched models return `400`. ```bash # Get cache stats -GET /api/cache +GET /api/cache/stats # Clear all caches -DELETE /api/cache +DELETE /api/cache/stats ``` Response example: @@ -215,23 +218,23 @@ Response example: ### 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 | +| Endpoint | Method | Description | +| ------------------------------- | ------------- | ---------------------- | +| `/api/settings` | GET/PUT/PATCH | 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 | +| Endpoint | Method | Description | +| ------------------------ | ---------- | ---------------------------------------------------------------------------------------------------- | +| `/api/sessions` | GET | Active session tracking | +| `/api/rate-limits` | GET | Per-account rate limits | +| `/api/monitoring/health` | GET | Health check + provider summary (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`) | +| `/api/cache/stats` | GET/DELETE | Cache stats / clear | ### Backup & Export/Import @@ -252,6 +255,13 @@ Response example: | `/api/sync/initialize` | POST | Initialize sync | | `/api/cloud/*` | Various | Cloud management | +### Tunnels + +| Endpoint | Method | Description | +| -------------------------- | ------ | ----------------------------------------------------------------------- | +| `/api/tunnels/cloudflared` | GET | Read Cloudflare Quick Tunnel install/runtime status for the dashboard | +| `/api/tunnels/cloudflared` | POST | Enable or disable the Cloudflare Quick Tunnel (`action=enable/disable`) | + ### CLI Tools | Endpoint | Method | Description | @@ -276,12 +286,12 @@ GET response includes `agents[]` (id, name, binary, version, installed, protocol ### 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 | +| Endpoint | Method | Description | +| ----------------------- | --------- | ------------------------------- | +| `/api/resilience` | GET/PATCH | 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 diff --git a/docs/i18n/da/ARCHITECTURE.md b/docs/i18n/no/docs/ARCHITECTURE.md similarity index 89% rename from docs/i18n/da/ARCHITECTURE.md rename to docs/i18n/no/docs/ARCHITECTURE.md index 4ea06a29f2..97cab9d95b 100644 --- a/docs/i18n/da/ARCHITECTURE.md +++ b/docs/i18n/no/docs/ARCHITECTURE.md @@ -1,12 +1,10 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/ARCHITECTURE.md) +# OmniRoute Architecture (Norsk) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/ARCHITECTURE.md) --- -# OmniRoute Architecture - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/ARCHITECTURE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/ARCHITECTURE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/ARCHITECTURE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/ARCHITECTURE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/ARCHITECTURE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/ARCHITECTURE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/ARCHITECTURE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/ARCHITECTURE.md) - -_Last updated: 2026-03-04_ +_Last updated: 2026-03-28_ ## Executive Summary @@ -69,6 +67,26 @@ Primary runtime model: - Provider SLA/control plane outside local process - External CLI binaries themselves (Claude CLI, Codex CLI, etc.) +## Dashboard Surface (Current) + +Main pages under `src/app/(dashboard)/dashboard/`: + +- `/dashboard` โ€” quick start + provider overview +- `/dashboard/endpoint` โ€” endpoint proxy + MCP + A2A + API endpoint tabs +- `/dashboard/providers` โ€” provider connections and credentials +- `/dashboard/combos` โ€” combo strategies, templates, model routing rules +- `/dashboard/costs` โ€” cost aggregation and pricing visibility +- `/dashboard/analytics` โ€” usage analytics and evaluations +- `/dashboard/limits` โ€” quota/rate controls +- `/dashboard/cli-tools` โ€” CLI onboarding, runtime detection, config generation +- `/dashboard/agents` โ€” detected ACP agents + custom agent registration +- `/dashboard/media` โ€” image/video/music playground +- `/dashboard/search-tools` โ€” search provider testing and history +- `/dashboard/health` โ€” uptime, circuit breakers, rate limits +- `/dashboard/logs` โ€” request/proxy/audit/console logs +- `/dashboard/settings` โ€” system settings tabs (general, routing, combo defaults, etc.) +- `/dashboard/api-manager` โ€” API key lifecycle and model permissions + ## High-Level System Context ```mermaid @@ -258,8 +276,9 @@ Domain State DB (SQLite): ## 5) Cloud Sync -- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts` +- Scheduler init: `src/lib/initCloudSync.ts`, `src/shared/services/initializeCloudSync.ts`, `src/shared/services/modelSyncScheduler.ts` - Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Periodic task: `src/shared/services/modelSyncScheduler.ts` - Control route: `src/app/api/sync/cloud/route.ts` ## Request Lifecycle (`/v1/chat/completions`) @@ -339,7 +358,7 @@ flowchart TD Q -- No --> R[Return all unavailable] ``` -Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics. +Fallback decisions are driven by `open-sse/services/accountFallback.ts` using status codes and error-message heuristics. Combo routing adds one extra guard: provider-scoped 400s such as upstream content-block and role-validation failures are treated as model-local failures so later combo targets can still run. ## OAuth Onboarding and Token Refresh Lifecycle @@ -669,25 +688,25 @@ Additional processing layers in the translation pipeline: ## 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 | +| 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` | Provider Models | Provider model metadata backing custom and managed available models | ## Bypass Handler @@ -739,10 +758,18 @@ Runtime visibility sources: - console logs from `src/sse/utils/logger.ts` - per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- four-stage detailed payload captures in SQLite (`request_detail_logs`) when `settings.detailed_logs_enabled=true` - textual request status log in `log.txt` (optional/compat) - optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` - dashboard usage endpoints (`/api/usage/*`) for UI consumption +Detailed request payload capture stores up to four JSON payload stages per routed call: + +- raw request received from the client +- translated request actually sent upstream +- provider response reconstructed as JSON; streamed responses are compacted to the final summary plus stream metadata +- final client response returned by OmniRoute; streamed responses are stored in the same compact summary form + ## Security-Sensitive Boundaries - JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing diff --git a/docs/i18n/ar/AUTO-COMBO.md b/docs/i18n/no/docs/AUTO-COMBO.md similarity index 65% rename from docs/i18n/ar/AUTO-COMBO.md rename to docs/i18n/no/docs/AUTO-COMBO.md index 2166e41dff..3b83d1d845 100644 --- a/docs/i18n/ar/AUTO-COMBO.md +++ b/docs/i18n/no/docs/AUTO-COMBO.md @@ -1,9 +1,9 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/AUTO-COMBO.md) +# OmniRoute Auto-Combo Engine (Norsk) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/AUTO-COMBO.md) --- -# OmniRoute Auto-Combo Engine - > Self-managing model chains with adaptive scoring ## How It Works diff --git a/docs/i18n/bg/CLI-TOOLS.md b/docs/i18n/no/docs/CLI-TOOLS.md similarity index 66% rename from docs/i18n/bg/CLI-TOOLS.md rename to docs/i18n/no/docs/CLI-TOOLS.md index f24fc575fe..fea6cc47c4 100644 --- a/docs/i18n/bg/CLI-TOOLS.md +++ b/docs/i18n/no/docs/CLI-TOOLS.md @@ -1,8 +1,8 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CLI-TOOLS.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CLI-TOOLS.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CLI-TOOLS.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CLI-TOOLS.md) +# CLI Tools Setup Guide โ€” OmniRoute (Norsk) -# ะ ัŠะบะพะฒะพะดัั‚ะฒะพ ะทะฐ ะฝะฐัั‚ั€ะพะนะบะฐ ะฝะฐ CLI ะธะฝัั‚ั€ัƒะผะตะฝั‚ะธ โ€” OmniRoute +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CLI-TOOLS.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CLI-TOOLS.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CLI-TOOLS.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CLI-TOOLS.md) -ะขะพะฒะฐ ั€ัŠะบะพะฒะพะดัั‚ะฒะพ ะพะฑััะฝัะฒะฐ ะบะฐะบ ะดะฐ ะธะฝัั‚ะฐะปะธั€ะฐั‚ะต ะธ ะบะพะฝั„ะธะณัƒั€ะธั€ะฐั‚ะต ะฒัะธั‡ะบะธ ะฟะพะดะดัŠั€ะถะฐะฝะธ AI CLI ะธะฝัั‚ั€ัƒะผะตะฝั‚ะธ ะทะฐ ะธะทะฟะพะปะทะฒะฐะฝะต ะฝะฐ **OmniRoute** ะบะฐั‚ะพ ัƒะฝะธั„ะธั†ะธั€ะฐะฝ ะฑะตะบะตะฝะด. +--- This guide explains how to install and configure all supported AI coding CLI tools to use **OmniRoute** as the unified backend, giving you centralized key management, @@ -13,7 +13,7 @@ cost tracking, model switching, and request logging across every tool. ## How It Works ``` -Claude / Codex / Gemini CLI / OpenCode / Cline / KiloCode / Continue / Kiro CLI +Claude / Codex / OpenCode / Cline / KiloCode / Continue / Kiro / Cursor / Copilot โ”‚ โ–ผ (all point to OmniRoute) http://YOUR_SERVER:20128/v1 @@ -31,21 +31,38 @@ Claude / Codex / Gemini CLI / OpenCode / Cline / KiloCode / Continue / Kiro CLI --- -## Supported Tools +## Supported Tools (Dashboard Source of Truth) -| Tool | Command | Type | Install Method | -| ---------------- | ------------------- | ----------------- | -------------- | -| **Claude Code** | `claude` | CLI | npm | -| **OpenAI Codex** | `codex` | CLI | npm | -| **Gemini CLI** | `gemini` | CLI | npm | -| **OpenCode** | `opencode` | CLI | npm | -| **Cline** | `cline` | CLI + VS Code ext | npm | -| **KiloCode** | `kilocode` / `kilo` | CLI + VS Code ext | npm | -| **Continue** | guide-based | VS Code ext | VS Code | -| **Kiro CLI** | `kiro-cli` | CLI | curl installer | -| **Cursor** | `cursor` | Desktop app | Download | -| **Droid** | web-based | Built-in agent | OmniRoute | -| **OpenClaw** | web-based | Built-in agent | OmniRoute | +The dashboard cards in `/dashboard/cli-tools` are generated from `src/shared/constants/cliTools.ts`. +Current list (v3.0.0-rc.16): + +| Tool | ID | Command | Setup Mode | Install Method | +| ------------------ | ------------- | ---------- | ---------- | -------------- | +| **Claude Code** | `claude` | `claude` | env | npm | +| **OpenAI Codex** | `codex` | `codex` | custom | npm | +| **Factory Droid** | `droid` | `droid` | custom | bundled/CLI | +| **OpenClaw** | `openclaw` | `openclaw` | custom | bundled/CLI | +| **Cursor** | `cursor` | app | guide | desktop app | +| **Cline** | `cline` | `cline` | custom | npm | +| **Kilo Code** | `kilo` | `kilocode` | custom | npm | +| **Continue** | `continue` | extension | guide | VS Code | +| **Antigravity** | `antigravity` | internal | mitm | OmniRoute | +| **GitHub Copilot** | `copilot` | extension | custom | VS Code | +| **OpenCode** | `opencode` | `opencode` | guide | npm | +| **Kiro AI** | `kiro` | app/cli | mitm | desktop/CLI | + +### CLI fingerprint sync (Agents + Settings) + +`/dashboard/agents` and `Settings > CLI Fingerprint` use `src/shared/constants/cliCompatProviders.ts`. +This keeps provider IDs aligned with CLI cards and legacy IDs. + +| CLI ID | Fingerprint Provider ID | +| ---------------------------------------------------------------------------------------------------- | ----------------------- | +| `kilo` | `kilocode` | +| `copilot` | `github` | +| `claude` / `codex` / `antigravity` / `kiro` / `cursor` / `cline` / `opencode` / `droid` / `openclaw` | same ID | + +Legacy IDs still accepted for compatibility: `copilot`, `kimi-coding`, `qwen`. --- @@ -71,9 +88,6 @@ npm install -g @anthropic-ai/claude-code # OpenAI Codex npm install -g @openai/codex -# Gemini CLI (Google) -npm install -g @google/gemini-cli - # OpenCode npm install -g opencode-ai @@ -81,7 +95,7 @@ npm install -g opencode-ai npm install -g cline # KiloCode -npm install -g kilecode +npm install -g kilocode # Kiro CLI (Amazon โ€” requires curl + unzip) apt-get install -y unzip # on Debian/Ubuntu @@ -94,7 +108,6 @@ export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc ```bash claude --version # 2.x.x codex --version # 0.x.x -gemini --version # 0.x.x opencode --version # x.x.x cline --version # 2.x.x kilocode --version # x.x.x (or: kilo --version) @@ -157,21 +170,6 @@ EOF --- -### Gemini CLI - -```bash -mkdir -p ~/.gemini && cat > ~/.gemini/settings.json << EOF -{ - "apiKey": "sk-your-omniroute-key", - "baseUrl": "http://localhost:20128/v1" -} -EOF -``` - -**Test:** `gemini "hello"` - ---- - ### OpenCode ```bash @@ -308,7 +306,7 @@ They run as internal routes and use OmniRoute's model routing automatically. --- -## Troubleshooting +## Feilsรธking | Error | Cause | Fix | | ------------------------- | ----------------------- | ------------------------------------------ | @@ -328,17 +326,16 @@ They run as internal routes and use OmniRoute's model routing automatically. OMNIROUTE_URL="http://localhost:20128/v1" OMNIROUTE_KEY="sk-your-omniroute-key" -npm install -g @anthropic-ai/claude-code @openai/codex @google/gemini-cli opencode-ai cline kilecode +npm install -g @anthropic-ai/claude-code @openai/codex opencode-ai cline kilocode # Kiro CLI apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash # Write configs -mkdir -p ~/.claude ~/.codex ~/.gemini ~/.config/opencode ~/.continue +mkdir -p ~/.claude ~/.codex ~/.config/opencode ~/.continue cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" -cat > ~/.gemini/settings.json <<< "{\"apiKey\":\"$OMNIROUTE_KEY\",\"baseUrl\":\"$OMNIROUTE_URL\"}" cat >> ~/.bashrc << EOF export OPENAI_BASE_URL="$OMNIROUTE_URL" export OPENAI_API_KEY="$OMNIROUTE_KEY" diff --git a/docs/i18n/no/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/no/docs/CODEBASE_DOCUMENTATION.md new file mode 100644 index 0000000000..f0501089a8 --- /dev/null +++ b/docs/i18n/no/docs/CODEBASE_DOCUMENTATION.md @@ -0,0 +1,591 @@ +# omniroute โ€” Codebase Documentation (Norsk) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CODEBASE_DOCUMENTATION.md) + +--- + +> 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
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, Qoder, 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. + +#### Arkitektur + +```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 | +| Qoder | 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"] +``` diff --git a/docs/i18n/no/docs/COVERAGE_PLAN.md b/docs/i18n/no/docs/COVERAGE_PLAN.md new file mode 100644 index 0000000000..7c96be302d --- /dev/null +++ b/docs/i18n/no/docs/COVERAGE_PLAN.md @@ -0,0 +1,170 @@ +# Test Coverage Plan (Norsk) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/COVERAGE_PLAN.md) + +--- + +Last updated: 2026-03-28 + +## Baseline + +There are multiple coverage numbers depending on how the report is computed. For planning, only one of them is useful. + +| Metric | Scope | Statements / Lines | Branches | Functions | Notes | +| -------------------- | ----------------------------------------------------- | -----------------: | -------: | --------: | --------------------------------------------------- | +| Legacy | Old `npm run test:coverage` | 79.42% | 75.15% | 67.94% | Inflated: counts test files and excludes `open-sse` | +| Diagnostic | Source-only, excluding tests and excluding `open-sse` | 68.16% | 63.55% | 64.06% | Useful only to isolate `src/**` | +| Recommended baseline | Source-only, excluding tests and including `open-sse` | 56.95% | 66.05% | 57.80% | This is the project-wide baseline to improve | + +The recommended baseline is the number to optimize against. + +## Rules + +- Coverage targets apply to source files, not to `tests/**`. +- `open-sse/**` is part of the product and must remain in scope. +- New code should not reduce coverage in touched areas. +- Prefer testing behavior and branch outcomes over implementation details. +- Prefer temp SQLite databases and small fixtures over broad mocks for `src/lib/db/**`. + +## Current command set + +- `npm run test:coverage` + - Main source coverage gate for the unit test suite + - Generates `text-summary`, `html`, `json-summary`, and `lcov` +- `npm run coverage:report` + - Detailed file-by-file report from the latest run +- `npm run test:coverage:legacy` + - Historical comparison only + +## Milestones + +| Phase | Target | Focus | +| ------- | ---------------------: | ------------------------------------------------- | +| Phase 1 | 60% statements / lines | Quick wins and low-risk utility coverage | +| Phase 2 | 65% statements / lines | DB and route foundations | +| Phase 3 | 70% statements / lines | Provider validation and usage analytics | +| Phase 4 | 75% statements / lines | `open-sse` translators and helpers | +| Phase 5 | 80% statements / lines | `open-sse` handlers and executor branches | +| Phase 6 | 85% statements / lines | Harder edge cases, branch debt, regression suites | +| Phase 7 | 90% statements / lines | Final sweep, gap closure, strict ratchet | + +Branches and functions should ratchet upward with each phase, but the primary hard target is statements / lines. + +## Priority hotspots + +These files or areas offer the best return for the next phases: + +1. `open-sse/handlers` + - `chatCore.ts` at 7.57% + - Overall directory at 29.07% +2. `open-sse/translator/request` + - Overall directory at 36.39% + - Many translators are still near single-digit coverage +3. `open-sse/translator/response` + - Overall directory at 8.07% +4. `open-sse/executors` + - Overall directory at 36.62% +5. `src/lib/db` + - `models.ts` at 20.66% + - `registeredKeys.ts` at 34.46% + - `modelComboMappings.ts` at 36.25% + - `settings.ts` at 46.40% + - `webhooks.ts` at 33.33% +6. `src/lib/usage` + - `usageHistory.ts` at 21.12% + - `usageStats.ts` at 9.56% + - `costCalculator.ts` at 30.00% +7. `src/lib/providers` + - `validation.ts` at 41.16% +8. Low-risk utility and API files for early gains + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/api/errorResponse.ts` + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +## Execution checklist + +### Phase 1: 56.95% -> 60% + +- [x] Fix coverage metric so it reflects source code instead of test files +- [x] Keep a legacy coverage script for comparison +- [x] Record the baseline and hotspots in-repo +- [ ] Add focused tests for low-risk utilities: + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/fetchTimeout.ts` + - `src/lib/api/errorResponse.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/display/names.ts` +- [ ] Add route tests for: + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +### Phase 2: 60% -> 65% + +- [ ] Add DB-backed tests for: + - `src/lib/db/modelComboMappings.ts` + - `src/lib/db/settings.ts` + - `src/lib/db/registeredKeys.ts` +- [ ] Cover branch behavior in: + - `src/lib/providers/validation.ts` + - `src/app/api/v1/embeddings/route.ts` + - `src/app/api/v1/moderations/route.ts` + +### Phase 3: 65% -> 70% + +- [ ] Add usage analytics tests for: + - `src/lib/usage/usageHistory.ts` + - `src/lib/usage/usageStats.ts` + - `src/lib/usage/costCalculator.ts` +- [ ] Expand route coverage for proxy management and settings branches + +### Phase 4: 70% -> 75% + +- [ ] Cover translator helpers and central translation paths: + - `open-sse/translator/index.ts` + - `open-sse/translator/helpers/*` + - `open-sse/translator/request/*` + - `open-sse/translator/response/*` + +### Phase 5: 75% -> 80% + +- [ ] Add handler-level tests for: + - `open-sse/handlers/chatCore.ts` + - `open-sse/handlers/responsesHandler.js` + - `open-sse/handlers/imageGeneration.js` + - `open-sse/handlers/embeddings.js` +- [ ] Add executor branch coverage for provider-specific auth, retries, and endpoint overrides + +### Phase 6: 80% -> 85% + +- [ ] Merge more edge-case suites into the main coverage path +- [ ] Increase function coverage for DB modules with weak constructor/helper coverage +- [ ] Close branch gaps in `settings.ts`, `registeredKeys.ts`, `validation.ts`, and translator helpers + +### Phase 7: 85% -> 90% + +- [ ] Treat the remaining low-coverage files as blockers +- [ ] Add regression tests for every uncovered production bug fixed during the push to 90% +- [ ] Raise the coverage gate in CI only after the local baseline is stable for at least two consecutive runs + +## Ratchet policy + +Update `npm run test:coverage` thresholds only after the project actually exceeds the next milestone with a comfortable buffer. + +Recommended ratchet sequence: + +1. 55/60/55 +2. 60/62/58 +3. 65/64/62 +4. 70/66/66 +5. 75/70/72 +6. 80/75/78 +7. 85/80/84 +8. 90/85/88 + +Order is `statements-lines / branches / functions`. + +## Known gap + +The current coverage command measures the main Node unit suite and includes source reached from it, including `open-sse`. It does not yet merge Vitest coverage into a single unified report. That merge is worth doing later, but it is not a blocker for starting the 60% -> 80% climb. diff --git a/docs/i18n/no/docs/FEATURES.md b/docs/i18n/no/docs/FEATURES.md index b1dfb8c2ae..b97c0eb695 100644 --- a/docs/i18n/no/docs/FEATURES.md +++ b/docs/i18n/no/docs/FEATURES.md @@ -1,6 +1,6 @@ # OmniRoute โ€” Dashboard Features Gallery (Norsk) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/FEATURES.md) --- @@ -10,7 +10,7 @@ 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). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. ![Providers Dashboard](screenshots/01-providers.png) diff --git a/docs/i18n/de/MCP-SERVER.md b/docs/i18n/no/docs/MCP-SERVER.md similarity index 65% rename from docs/i18n/de/MCP-SERVER.md rename to docs/i18n/no/docs/MCP-SERVER.md index 829acd30b1..fc87d35d6e 100644 --- a/docs/i18n/de/MCP-SERVER.md +++ b/docs/i18n/no/docs/MCP-SERVER.md @@ -1,12 +1,12 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/MCP-SERVER.md) +# OmniRoute MCP Server Documentation (Norsk) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/MCP-SERVER.md) --- -# OmniRoute MCP Server Documentation - > Model Context Protocol server with 16 intelligent tools -## Installation +## Installer OmniRoute MCP is built-in. Start it with: @@ -42,16 +42,16 @@ See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, ## Advanced Tools (8) -| Tool | Description | -| :--------------------------------- | :---------------------------------------------- | -| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | -| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | -| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | -| `omniroute_test_combo` | Live-test all models in a combo | -| `omniroute_get_provider_metrics` | Detailed metrics for one provider | -| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | -| `omniroute_explain_route` | Explain a past routing decision | -| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | +| Tool | Description | +| :--------------------------------- | :---------------------------------------------------------- | +| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | +| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | +| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | +| `omniroute_test_combo` | Live-test all models in a combo via a real upstream request | +| `omniroute_get_provider_metrics` | Detailed metrics for one provider | +| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | +| `omniroute_explain_route` | Explain a past routing decision | +| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | ## Authentication diff --git a/docs/i18n/no/docs/RELEASE_CHECKLIST.md b/docs/i18n/no/docs/RELEASE_CHECKLIST.md new file mode 100644 index 0000000000..18a32d6560 --- /dev/null +++ b/docs/i18n/no/docs/RELEASE_CHECKLIST.md @@ -0,0 +1,37 @@ +# Release Checklist (Norsk) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/RELEASE_CHECKLIST.md) + +--- + +Use this checklist before tagging or publishing a new OmniRoute release. + +## Version and Changelog + +1. Bump `package.json` version (`x.y.z`) in the release branch. +2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: + - `## [x.y.z] โ€” YYYY-MM-DD` +3. Keep `## [Unreleased]` as the first changelog section for upcoming work. +4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. + +## API Docs + +1. Update `docs/openapi.yaml`: + - `info.version` must equal `package.json` version. +2. Validate endpoint examples if API contracts changed. + +## Runtime Docs + +1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. +2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. +3. Update localized docs if source docs changed significantly. + +## Automated Check + +Run the sync guard locally before opening PR: + +```bash +npm run check:docs-sync +``` + +CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/no/docs/TROUBLESHOOTING.md b/docs/i18n/no/docs/TROUBLESHOOTING.md new file mode 100644 index 0000000000..d3eafac3d0 --- /dev/null +++ b/docs/i18n/no/docs/TROUBLESHOOTING.md @@ -0,0 +1,256 @@ +# Troubleshooting (Norsk) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/TROUBLESHOOTING.md) + +--- + +Common problems and solutions for OmniRoute. + +--- + +## Quick Fixes + +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | + +--- + +## Provider Issues + +### "Language model did not provide messages" + +**Cause:** Provider quota exhausted. + +**Fix:** + +1. 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, Qoder) 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}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) + +--- + +## Circuit Breaker Issues + +### Provider stuck in OPEN state + +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. + +**Fix:** + +1. 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 +- **SDK returns raw string instead of object** โ€” Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** โ€” Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** โ€” Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** โ€” Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` + +--- + +## Resilience Settings + +### Auto rate-limit not triggering + +- 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. + +--- + +## Optional RAG / LLM failure taxonomy (16 problems) + +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` โ€ฆ `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard โ†’ Health** for real-time system status +- **Translator**: Use **Dashboard โ†’ Translator** to debug format issues diff --git a/docs/i18n/no/USER_GUIDE.md b/docs/i18n/no/docs/USER_GUIDE.md similarity index 82% rename from docs/i18n/no/USER_GUIDE.md rename to docs/i18n/no/docs/USER_GUIDE.md index 8aa08be799..fabf180e67 100644 --- a/docs/i18n/no/USER_GUIDE.md +++ b/docs/i18n/no/docs/USER_GUIDE.md @@ -1,8 +1,6 @@ # User Guide (Norsk) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/USER_GUIDE.md) - -> ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/USER_GUIDE.md) --- @@ -320,7 +318,7 @@ Model: cc/claude-opus-4-6 --- -## ๐Ÿš€ Deployment +## Utrulling ### Global npm install (Recommended) @@ -511,23 +509,26 @@ post_install() { ### Environment Variables -| Variable | Default | Description | -| ------------------------- | ------------------------------------ | ------------------------------------------------------- | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | -| `INITIAL_PASSWORD` | `123456` | First login password | -| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | -| `PORT` | framework default | Service port (`20128` in examples) | -| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | -| `NODE_ENV` | runtime default | Set `production` for deploy | -| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | -| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | -| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | -| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | -| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | -| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | -| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | -| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | +| 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/*` | +| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand | +| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | For the full environment variable reference, see the [README](../README.md). @@ -598,6 +599,11 @@ curl -X POST http://localhost:20128/api/provider-models \ Or use Dashboard: **Providers โ†’ [Provider] โ†’ Custom Models**. +Notes: + +- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers. +- The **Custom Models** section is intended for providers that do not expose managed available-model imports. + ### Dedicated Provider Routes Route requests directly to a specific provider with model validation: @@ -642,6 +648,14 @@ Returns models grouped by provider with types (`chat`, `embedding`, `image`). - Automatic background sync with timeout + fail-fast - Prefer server-side `BASE_URL`/`CLOUD_URL` in production +### Cloudflare Quick Tunnel + +- Available in **Dashboard โ†’ Endpoints** for Docker and other self-hosted deployments +- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint +- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary +- Tunnel URLs are ephemeral and change every time you stop/start the tunnel +- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download + ### LLM Gateway Intelligence (Phase 9) - **Semantic Cache** โ€” Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) @@ -757,11 +771,11 @@ OmniRoute implements provider-level resilience with four components: 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 | +| 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 unless `DISABLE_SQLITE_AUTO_BACKUP=true` | ```bash # API: Export database @@ -787,10 +801,11 @@ curl -X POST http://localhost:20128/api/db-backups/import \ ### Settings Dashboard -The settings page is organized into 5 tabs for easy navigation: +The settings page is organized into 6 tabs for easy navigation: | Tab | Contents | | -------------- | ---------------------------------------------------------------------------------------------- | +| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility | | **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | | **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | | **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | diff --git a/docs/i18n/no/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/no/docs/VM_DEPLOYMENT_GUIDE.md new file mode 100644 index 0000000000..4ba1791948 --- /dev/null +++ b/docs/i18n/no/docs/VM_DEPLOYMENT_GUIDE.md @@ -0,0 +1,403 @@ +# OmniRoute โ€” Deployment Guide on VM with Cloudflare (Norsk) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/VM_DEPLOYMENT_GUIDE.md) + +--- + +Complete guide to install and configure OmniRoute on a VM (VPS) with domain managed via Cloudflare. + +--- + +## Prerequisites + +| Item | Minimum | Recommended | +| ---------- | ------------------------ | ---------------- | +| **CPU** | 1 vCPU | 2 vCPU | +| **RAM** | 1 GB | 2 GB | +| **Disk** | 10 GB SSD | 25 GB SSD | +| **OS** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS | +| **Domain** | Registered on Cloudflare | โ€” | +| **Docker** | Docker Engine 24+ | Docker 27+ | + +**Tested providers**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. + +--- + +## 1. Configure the VM + +### 1.1 Create the instance + +On your preferred VPS provider: + +- Choose Ubuntu 24.04 LTS +- Select the minimum plan (1 vCPU / 1 GB RAM) +- Set a strong root password or configure SSH key +- Note the **public IP** (e.g., `203.0.113.10`) + +### 1.2 Connect via SSH + +```bash +ssh root@203.0.113.10 +``` + +### 1.3 Update the system + +```bash +apt update && apt upgrade -y +``` + +### 1.4 Install Docker + +```bash +# Install dependencies +apt install -y ca-certificates curl gnupg + +# Add official Docker repository +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 Install nginx + +```bash +apt install -y nginx +``` + +### 1.6 Configure 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 +``` + +> **Tip**: For maximum security, restrict ports 80 and 443 to Cloudflare IPs only. See the [Advanced Security](#advanced-security) section. + +--- + +## 2. Install OmniRoute + +### 2.1 Create configuration directory + +```bash +mkdir -p /opt/omniroute +``` + +### 2.2 Create environment variables file + +```bash +cat > /opt/omniroute/.env << โ€˜EOFโ€™ +# === Security === +JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY +INITIAL_PASSWORD=YourSecurePassword123! +API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY +STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY +STORAGE_ENCRYPTION_KEY_VERSION=v1 +MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT + +# === 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 (change to your domain) === +BASE_URL=https://llms.seudominio.com +NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com + +# === Cloud Sync (optional) === +# CLOUD_URL=https://cloud.omniroute.online +# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online +EOF +``` + +> โš ๏ธ **IMPORTANT**: Generate unique secret keys! Use `openssl rand -hex 32` for each key. + +### 2.3 Start the 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 Verify that it is running + +```bash +docker ps | grep omniroute +docker logs omniroute --tail 20 +``` + +It should display: `[DB] SQLite database ready` and `listening on port 20128`. + +--- + +## 3. Configure nginx (Reverse Proxy) + +### 3.1 Generate SSL certificate (Cloudflare Origin) + +In the Cloudflare dashboard: + +1. Go to **SSL/TLS โ†’ Origin Server** +2. Click **Create Certificate** +3. Keep the defaults (15 years, \*.yourdomain.com) +4. Copy the **Origin Certificate** and the **Private Key** + +```bash +mkdir -p /etc/nginx/ssl + +# Paste the certificate +nano /etc/nginx/ssl/origin.crt + +# Paste the private key +nano /etc/nginx/ssl/origin.key + +chmod 600 /etc/nginx/ssl/origin.key +``` + +### 3.2 Nginx Configuration + +```bash +cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ +# Default server โ€” blocks direct access via 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.yourdomain.com; # Change to your domain + + 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.yourdomain.com; + return 301 https://$server_name$request_uri; +} +NGINX +``` + +### 3.3 Enable and Test + +```bash +# Remove default configuration +rm -f /etc/nginx/sites-enabled/default + +# Enable OmniRoute +ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute + +# Test and reload +nginx -t && systemctl reload nginx +``` + +--- + +## 4. Configure Cloudflare DNS + +### 4.1 Add DNS record + +In the Cloudflare dashboard โ†’ DNS: + +| Type | Name | Content | Proxy | +| ---- | ------ | ---------------------- | ---------- | +| A | `llms` | `203.0.113.10` (VM IP) | โœ… Proxied | + +### 4.2 Configure SSL + +Under **SSL/TLS โ†’ Overview**: + +- Mode: **Full (Strict)** + +Under **SSL/TLS โ†’ Edge Certificates**: + +- Always Use HTTPS: โœ… On +- Minimum TLS Version: TLS 1.2 +- Automatic HTTPS Rewrites: โœ… On + +### 4.3 Testing + +```bash +curl -sI https://llms.seudominio.com/health +# Should return HTTP/2 200 +``` + +--- + +## 5. Operations and Maintenance + +### Upgrade to a new version + +```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 +``` + +### View logs + +```bash +docker logs -f omniroute # Real-time stream +docker logs omniroute --tail 50 # Last 50 lines +``` + +### Manual database backup + +```bash +# Copy data from the volume to the host +docker cp omniroute:/app/data ./backup-$(date +%F) + +# Or compress the entire volume +docker run --rm -v omniroute-data:/data -v $(pwd):/backup \ + alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data +``` + +### Restore from 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. Advanced Security + +### Restrict nginx to Cloudflare IPs + +```bash +cat > /etc/nginx/cloudflare-ips.conf << โ€˜CFโ€™ +# Cloudflare IPv4 ranges โ€” update periodically +# 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 +``` + +Add the following to `nginx.conf` inside the `http {}` block: + +```nginx +include /etc/nginx/cloudflare-ips.conf; +``` + +### Install fail2ban + +```bash +apt install -y fail2ban +systemctl enable fail2ban +systemctl start fail2ban + +# Check status +fail2ban-client status sshd +``` + +### Block direct access to the Docker port + +```bash +# Prevent direct external access to port 20128 +iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP +iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT + +# Persist the rules +apt install -y iptables-persistent +netfilter-persistent save +``` + +--- + +## 7. Deploy to Cloudflare Workers (Optional) + +For remote access via Cloudflare Workers (without exposing the VM directly): + +```bash +# In the local repository +cd omnirouteCloud +npm install +npx wrangler login +npx wrangler deploy +``` + +See the full documentation at [omnirouteCloud/README.md](../omnirouteCloud/README.md). + +--- + +## Port Summary + +| Port | Service | Access | +| ----- | ----------- | -------------------------- | +| 22 | SSH | Public (with fail2ban) | +| 80 | nginx HTTP | Redirect โ†’ HTTPS | +| 443 | nginx HTTPS | Via Cloudflare Proxy | +| 20128 | OmniRoute | Localhost only (via nginx) | diff --git a/docs/i18n/no/src/lib/a2a/README.md b/docs/i18n/no/src/lib/a2a/README.md new file mode 100644 index 0000000000..71af328148 --- /dev/null +++ b/docs/i18n/no/src/lib/a2a/README.md @@ -0,0 +1,752 @@ +# OmniRoute A2A Server (Norsk) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../../../src/lib/a2a/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../../../es/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../../../fr/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../../../de/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../../../it/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../../../ru/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../../../zh-CN/src/lib/a2a/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../../../ja/src/lib/a2a/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../../../ko/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../../../ar/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../../../in/src/lib/a2a/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../../../th/src/lib/a2a/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../../../vi/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../../../id/src/lib/a2a/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../../../ms/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../../../nl/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../../../pl/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../../../sv/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../../../no/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../../../da/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../../../fi/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../../../pt/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../../../ro/src/lib/a2a/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../../../hu/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../../../bg/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../../../sk/src/lib/a2a/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../../../uk-UA/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../../../he/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../../../phi/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../../../pt-BR/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../../../cs/src/lib/a2a/README.md) + +--- + +> **Agent-to-Agent Protocol v0.3** โ€” Enables any AI agent to use OmniRoute as an intelligent routing agent via JSON-RPC 2.0. + +The A2A Server exposes OmniRoute as a **first-class agent** that other agents can discover, delegate tasks to, and collaborate with using the [A2A Protocol](https://google.github.io/A2A/). + +--- + +## Arkitektur + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Orchestrator Agent โ”‚ +โ”‚ (LangChain, CrewAI, AutoGen, Custom Agent) โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ 1. GET /.well-known/agent.json (discover) + โ”‚ 2. POST /a2a (JSON-RPC 2.0) + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ OmniRoute A2A Server โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Task Manager โ”‚ โ”‚ Skill Engine โ”‚ โ”‚ SSE Streaming โ”‚ โ”‚ +โ”‚ โ”‚ (lifecycle) โ”‚โ”€โ”€โ”‚ (registry) โ”‚โ”€โ”€โ”‚ (real-time) โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ +โ”‚ Skills: โ”‚ โ”‚ +โ”‚ โ”œโ”€ smart-routing โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ””โ”€ quota-management โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ Routing Decision Logger โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ OmniRoute Gateway (internal) + /v1/chat/completions, /api/combos, /api/usage/quota +``` + +--- + +## Hurtigstart + +### Agent Discovery + +Every A2A-compatible agent exposes an **Agent Card** at `/.well-known/agent.json`: + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +**Response:** + +```json +{ + "name": "OmniRoute", + "description": "Intelligent AI gateway with auto-routing across 50+ providers", + "url": "http://localhost:20128/a2a", + "version": "1.8.1", + "capabilities": { + "streaming": true, + "pushNotifications": false + }, + "skills": [ + { + "id": "smart-routing", + "name": "Smart Routing", + "description": "Routes prompts through OmniRoute intelligent pipeline", + "tags": ["routing", "llm", "multi-provider", "cost-optimization"], + "examples": [ + "Write a hello world in Python", + "Explain quantum computing using the cheapest provider" + ] + }, + { + "id": "quota-management", + "name": "Quota Management", + "description": "Natural-language queries about provider quotas", + "tags": ["quota", "analytics", "cost"], + "examples": [ + "Which provider has the most quota remaining?", + "Suggest a free combo for coding" + ] + } + ], + "authentication": { + "schemes": ["bearer"], + "apiKeyHeader": "Authorization" + } +} +``` + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Send a message to a skill and receive the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python hello world"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "a1b2c3d4-...", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "print('Hello, World!')" }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.0030)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "2026-03-04T..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"Quantum computing..."}}} + +: heartbeat 2026-03-04T21:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Running Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Skills Reference + +### `smart-routing` + +Routes prompts through OmniRoute's intelligent pipeline with full observability. + +**Parameters (in `metadata`):** + +| Parameter | Type | Default | Description | +| --------- | -------- | ------------ | ---------------------------------------------------------------------------------------- | +| `model` | `string` | `"auto"` | Target model (e.g., `claude-sonnet-4`, `gpt-4o`, `auto`) | +| `combo` | `string` | active combo | Specific combo to route through | +| `budget` | `number` | none | Maximum cost in USD for this request | +| `role` | `string` | none | Task role hint: `coding`, `review`, `planning`, `analysis`, `debugging`, `documentation` | + +**Returns:** + +| Field | Description | +| ------------------------------ | --------------------------------------------------------- | +| `artifacts[].content` | The LLM response text | +| `metadata.routing_explanation` | Human-readable explanation of routing decision | +| `metadata.cost_envelope` | Estimated vs actual cost with currency | +| `metadata.resilience_trace` | Array of events (primary_selected, fallback_needed, etc.) | +| `metadata.policy_verdict` | Whether the request was allowed and why | + +### `quota-management` + +Answers natural-language queries about provider quotas. + +**Query types (inferred from message content):** + +| Query Pattern | Response Type | +| ---------------------------------------------- | -------------------------------------------------------- | +| Contains `"ranking"`, `"most quota"`, `"best"` | Providers ranked by remaining quota | +| Contains `"free"`, `"suggest"` | Lists free combos or suggests free-tier providers | +| Default | Full quota summary with warnings for low-quota providers | + +--- + +## Task Lifecycle + +``` +submitted โ”€โ”€โ†’ working โ”€โ”€โ†’ completed + โ”€โ”€โ†’ failed + โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ†’ cancelled +``` + +| State | Description | +| ----------- | ----------------------------------------------------- | +| `submitted` | Task created, queued for execution | +| `working` | Skill handler is executing | +| `completed` | Execution succeeded, artifacts available | +| `failed` | Execution failed or task expired (TTL: 5 min default) | +| `cancelled` | Cancelled by client via `tasks/cancel` | + +- Terminal states: `completed`, `failed`, `cancelled` (no further transitions) +- Expired tasks in `submitted` or `working` are auto-marked as `failed` +- Tasks are garbage-collected after 2ร— TTL + +--- + +## Client Examples + +### Python โ€” Orchestrator Agent + +```python +""" +A2A Client โ€” Python example. +Discovers OmniRoute agent, sends a task, and processes the result. +""" +import requests +import json + +BASE_URL = "http://localhost:20128" +API_KEY = "your-api-key" +HEADERS = { + "Content-Type": "application/json", + "Authorization": f"Bearer {API_KEY}", +} + +# 1. Discover agent capabilities +agent_card = requests.get(f"{BASE_URL}/.well-known/agent.json").json() +print(f"Agent: {agent_card['name']} v{agent_card['version']}") +print(f"Skills: {[s['id'] for s in agent_card['skills']]}") + +# 2. Send a smart-routing task +response = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python quicksort implementation"}], + "metadata": { + "model": "auto", + "combo": "fast-coding", + "budget": 0.10, + } + } +}) +result = response.json()["result"] +print(f"\n๐Ÿ“ Response: {result['artifacts'][0]['content'][:200]}...") +print(f"๐Ÿ”€ Routing: {result['metadata']['routing_explanation']}") +print(f"๐Ÿ’ฐ Cost: ${result['metadata']['cost_envelope']['actual']}") +print(f"๐Ÿ›ก๏ธ Policy: {result['metadata']['policy_verdict']['reason']}") + +# 3. Query quota status +quota_resp = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-2", + "method": "message/send", + "params": { + "skill": "quota-management", + "messages": [{"role": "user", "content": "Which provider has the most quota remaining?"}], + } +}) +quota_result = quota_resp.json()["result"] +print(f"\n๐Ÿ“Š Quota: {quota_result['artifacts'][0]['content']}") +``` + +### TypeScript โ€” Multi-Agent Orchestrator + +```typescript +/** + * A2A Client โ€” TypeScript example. + * Shows agent discovery, task delegation, and streaming. + */ + +const BASE_URL = "http://localhost:20128"; +const API_KEY = "your-api-key"; + +interface JsonRpcResponse { + jsonrpc: "2.0"; + id: string | number; + result?: T; + error?: { code: number; message: string }; +} + +async function a2aCall(method: string, params: Record): Promise { + const resp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: `${method}-${Date.now()}`, + method, + params, + }), + }); + const json: JsonRpcResponse = await resp.json(); + if (json.error) throw new Error(`[${json.error.code}] ${json.error.message}`); + return json.result!; +} + +// โ”€โ”€ Agent Discovery โ”€โ”€ +const agentCard = await fetch(`${BASE_URL}/.well-known/agent.json`).then((r) => r.json()); +console.log(`Connected to: ${agentCard.name} (${agentCard.skills.length} skills)`); + +// โ”€โ”€ Smart Routing: Send a coding task โ”€โ”€ +const routingResult = await a2aCall("message/send", { + skill: "smart-routing", + messages: [{ role: "user", content: "Implement a Redis cache wrapper in TypeScript" }], + metadata: { model: "claude-sonnet-4", role: "coding" }, +}); +console.log("Response:", routingResult.artifacts[0].content); +console.log("Provider:", routingResult.metadata.routing_explanation); + +// โ”€โ”€ Quota Management: Find free alternatives โ”€โ”€ +const quotaResult = await a2aCall("message/send", { + skill: "quota-management", + messages: [{ role: "user", content: "Suggest free combos for documentation" }], +}); +console.log("Free combos:", quotaResult.artifacts[0].content); + +// โ”€โ”€ Streaming: Real-time response โ”€โ”€ +const streamResp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "stream-1", + method: "message/stream", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Explain microservices architecture" }], + }, + }), +}); + +const reader = streamResp.body!.getReader(); +const decoder = new TextDecoder(); +while (true) { + const { done, value } = await reader.read(); + if (done) break; + const chunk = decoder.decode(value); + for (const line of chunk.split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + if (event.params.chunk) { + process.stdout.write(event.params.chunk.content); + } + if (event.params.task.state === "completed") { + console.log("\nโœ… Stream completed"); + } + } + } +} +``` + +### Python โ€” LangChain A2A Integration + +```python +""" +LangChain integration โ€” Use OmniRoute A2A as a custom LLM. +""" +from langchain.llms.base import BaseLLM +from langchain.schema import LLMResult, Generation +import requests +from typing import List, Optional + +class OmniRouteA2A(BaseLLM): + base_url: str = "http://localhost:20128" + api_key: str = "" + model: str = "auto" + combo: Optional[str] = None + + @property + def _llm_type(self) -> str: + return "omniroute-a2a" + + def _call(self, prompt: str, stop: Optional[List[str]] = None, **kwargs) -> str: + response = requests.post( + f"{self.base_url}/a2a", + headers={ + "Content-Type": "application/json", + "Authorization": f"Bearer {self.api_key}", + }, + json={ + "jsonrpc": "2.0", + "id": "langchain-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": prompt}], + "metadata": { + "model": self.model, + **({"combo": self.combo} if self.combo else {}), + }, + }, + }, + ) + result = response.json()["result"] + return result["artifacts"][0]["content"] + + def _generate(self, prompts: List[str], stop=None, **kwargs) -> LLMResult: + return LLMResult( + generations=[[Generation(text=self._call(p, stop))] for p in prompts] + ) + +# Usage +llm = OmniRouteA2A( + base_url="http://localhost:20128", + api_key="your-key", + model="auto", + combo="fast-coding", +) +result = llm("Write a Python function to merge two sorted lists") +print(result) +``` + +### Go โ€” A2A Client + +```go +package main + +import ( + "bytes" + "encoding/json" + "fmt" + "io" + "net/http" +) + +const baseURL = "http://localhost:20128" +const apiKey = "your-api-key" + +type JsonRpcRequest struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Method string `json:"method"` + Params interface{} `json:"params"` +} + +type JsonRpcResponse struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Result interface{} `json:"result"` + Error *struct { + Code int `json:"code"` + Message string `json:"message"` + } `json:"error"` +} + +func a2aCall(method string, params interface{}) (*JsonRpcResponse, error) { + body, _ := json.Marshal(JsonRpcRequest{ + Jsonrpc: "2.0", + ID: "go-1", + Method: method, + Params: params, + }) + + req, _ := http.NewRequest("POST", baseURL+"/a2a", bytes.NewReader(body)) + req.Header.Set("Content-Type", "application/json") + req.Header.Set("Authorization", "Bearer "+apiKey) + + resp, err := http.DefaultClient.Do(req) + if err != nil { + return nil, err + } + defer resp.Body.Close() + data, _ := io.ReadAll(resp.Body) + + var result JsonRpcResponse + json.Unmarshal(data, &result) + return &result, nil +} + +func main() { + // Discover agent + resp, _ := http.Get(baseURL + "/.well-known/agent.json") + defer resp.Body.Close() + body, _ := io.ReadAll(resp.Body) + fmt.Println("Agent Card:", string(body)) + + // Send smart-routing task + result, _ := a2aCall("message/send", map[string]interface{}{ + "skill": "smart-routing", + "messages": []map[string]string{{"role": "user", "content": "Hello from Go!"}}, + "metadata": map[string]interface{}{"model": "auto"}, + }) + out, _ := json.MarshalIndent(result.Result, "", " ") + fmt.Println("Result:", string(out)) +} +``` + +--- + +## Use Cases + +### ๐Ÿค– Use Case 1: Multi-Agent Coding Pipeline + +An orchestrator agent delegates code generation to OmniRoute, then passes the output to a review agent. + +```python +def coding_pipeline(task: str): + # Step 1: Generate code via OmniRoute A2A + code_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Write production-quality code: {task}"} + ], metadata={"model": "auto", "role": "coding"}) + code = code_result["artifacts"][0]["content"] + + # Step 2: Review the code via OmniRoute A2A (different model) + review_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Review this code for bugs and improvements:\n\n{code}"} + ], metadata={"model": "auto", "role": "review"}) + review = review_result["artifacts"][0]["content"] + + # Step 3: Check costs + print(f"Code cost: ${code_result['metadata']['cost_envelope']['actual']}") + print(f"Review cost: ${review_result['metadata']['cost_envelope']['actual']}") + + return {"code": code, "review": review} +``` + +### ๐Ÿ’ก Use Case 2: Quota-Aware Agent Swarm + +Multiple agents share quota through OmniRoute, using the quota skill to coordinate. + +```python +async def quota_aware_agent(agent_name: str, task: str): + # Check quota before starting + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Which provider has the most quota remaining?"} + ]) + print(f"[{agent_name}] {quota['artifacts'][0]['content']}") + + # Send request with budget constraint + result = a2a_send("smart-routing", [ + {"role": "user", "content": task} + ], metadata={"budget": 0.05}) + + policy = result["metadata"]["policy_verdict"] + if not policy["allowed"]: + print(f"[{agent_name}] โš ๏ธ Budget exceeded: {policy['reason']}") + # Fall back to free combo + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Suggest free combos"} + ]) + print(f"[{agent_name}] Free alternatives: {quota['artifacts'][0]['content']}") + + return result +``` + +### ๐Ÿ“Š Use Case 3: Real-Time Streaming Dashboard + +A monitoring agent streams responses and displays progress in real-time. + +```typescript +async function streamingDashboard(prompt: string) { + const response = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { "Content-Type": "application/json", Authorization: `Bearer ${API_KEY}` }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "dash-1", + method: "message/stream", + params: { skill: "smart-routing", messages: [{ role: "user", content: prompt }] }, + }), + }); + + let totalChunks = 0; + const reader = response.body!.getReader(); + const decoder = new TextDecoder(); + + while (true) { + const { done, value } = await reader.read(); + if (done) break; + + for (const line of decoder.decode(value).split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + const state = event.params.task.state; + + if (state === "working" && event.params.chunk) { + totalChunks++; + process.stdout.write( + `\r[Chunk ${totalChunks}] ${event.params.chunk.content.slice(0, 50)}...` + ); + } + if (state === "completed") { + const meta = event.params.metadata; + console.log( + `\nโœ… Done | Cost: $${meta?.cost_envelope?.actual || 0} | Route: ${meta?.routing_explanation || "N/A"}` + ); + } + if (state === "failed") { + console.error(`\nโŒ Failed: ${event.params.metadata?.error}`); + } + } + } + } +} +``` + +### ๐Ÿ” Use Case 4: Task Polling Pattern + +For long-running tasks, poll the task status instead of waiting synchronously. + +```python +import time + +def poll_task(task_id: str, timeout: int = 60): + """Poll task status until completion or timeout.""" + start = time.time() + while time.time() - start < timeout: + result = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "poll-1", + "method": "tasks/get", + "params": {"taskId": task_id}, + }).json() + + task = result["result"]["task"] + state = task["state"] + print(f" Task {task_id[:8]}... state={state}") + + if state in ("completed", "failed", "cancelled"): + return task + time.sleep(2) + + # Timeout โ€” cancel the task + requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "cancel-1", + "method": "tasks/cancel", + "params": {"taskId": task_id}, + }) + raise TimeoutError(f"Task {task_id} timed out after {timeout}s") +``` + +--- + +## Error Codes + +| Code | Constant | Meaning | +| ------ | ------------------------ | ---------------------------------------- | +| -32700 | โ€” | Parse error (invalid JSON) | +| -32600 | `INVALID_REQUEST` | Invalid JSON-RPC request or unauthorized | +| -32601 | `METHOD_NOT_FOUND` | Unknown method or skill | +| -32602 | `INVALID_PARAMS` | Missing or invalid parameters | +| -32603 | `INTERNAL_ERROR` | Skill execution failed | +| -32001 | `TASK_NOT_FOUND` | Task ID not found | +| -32002 | `TASK_ALREADY_COMPLETED` | Cannot modify a completed task | +| -32003 | `UNAUTHORIZED` | Invalid or missing API key | +| -32004 | `BUDGET_EXCEEDED` | Request exceeds configured budget | +| -32005 | `PROVIDER_UNAVAILABLE` | No available providers | + +--- + +## Authentication + +All `/a2a` requests require a Bearer token via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server (`OMNIROUTE_API_KEY` is empty), authentication is bypassed. + +--- + +## File Structure + +``` +src/lib/a2a/ +โ”œโ”€โ”€ taskManager.ts # Task lifecycle (create/update/cancel/list), TTL, cleanup +โ”œโ”€โ”€ taskExecution.ts # Generic task executor with state management +โ”œโ”€โ”€ streaming.ts # SSE stream formatting, heartbeat, chunk/completion events +โ”œโ”€โ”€ routingLogger.ts # Routing decision logger (stats, history, retention) +โ””โ”€โ”€ skills/ + โ”œโ”€โ”€ smartRouting.ts # Smart routing skill (routes via /v1/chat/completions) + โ””โ”€โ”€ quotaManagement.ts # Quota management skill (natural-language quota queries) + +src/app/a2a/ +โ””โ”€โ”€ route.ts # Next.js API route handler (JSON-RPC 2.0 dispatch) + +open-sse/mcp-server/ +โ””โ”€โ”€ schemas/a2a.ts # Zod schemas (AgentCard, Task, JSON-RPC, SSE events) +``` + +--- + +## Comparison: MCP vs A2A + +| Feature | MCP Server | A2A Server | +| ----------------- | ---------------------------- | ------------------------------------------------- | +| **Protocol** | Model Context Protocol | Agent-to-Agent Protocol v0.3 | +| **Transport** | stdio / HTTP | HTTP (JSON-RPC 2.0) | +| **Discovery** | Tool listing via MCP | `/.well-known/agent.json` | +| **Granularity** | 16 individual tools | 2 high-level skills | +| **Best for** | IDE agents (Cursor, VS Code) | Multi-agent systems (LangChain, CrewAI) | +| **Streaming** | Not supported | SSE via `message/stream` | +| **Task tracking** | No | Full lifecycle (submitted โ†’ completed) | +| **Observability** | Audit log per tool call | Cost envelope + resilience trace + policy verdict | + +--- + +## Lisens + +Part of [OmniRoute](https://github.com/diegosouzapw/OmniRoute) โ€” MIT License. diff --git a/docs/i18n/phi/A2A-SERVER.md b/docs/i18n/phi/A2A-SERVER.md deleted file mode 100644 index 01531ff482..0000000000 --- a/docs/i18n/phi/A2A-SERVER.md +++ /dev/null @@ -1,200 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/A2A-SERVER.md) - ---- - -# OmniRoute A2A Server Documentation - -> Agent-to-Agent Protocol v0.3 โ€” OmniRoute as an intelligent routing agent - -## Agent Discovery - -```bash -curl http://localhost:20128/.well-known/agent.json -``` - -Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements. - ---- - -## Authentication - -All `/a2a` requests require an API key via the `Authorization` header: - -``` -Authorization: Bearer YOUR_OMNIROUTE_API_KEY -``` - -If no API key is configured on the server, authentication is bypassed. - ---- - -## JSON-RPC 2.0 Methods - -### `message/send` โ€” Synchronous Execution - -Sends a message to a skill and waits for the complete response. - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{ - "jsonrpc": "2.0", - "id": "1", - "method": "message/send", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Write a hello world in Python"}], - "metadata": {"model": "auto", "combo": "fast-coding"} - } - }' -``` - -**Response:** - -```json -{ - "jsonrpc": "2.0", - "id": "1", - "result": { - "task": { "id": "uuid", "state": "completed" }, - "artifacts": [{ "type": "text", "content": "..." }], - "metadata": { - "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)", - "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, - "resilience_trace": [ - { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." } - ], - "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } - } - } -} -``` - -### `message/stream` โ€” SSE Streaming - -Same as `message/send` but returns Server-Sent Events for real-time streaming. - -```bash -curl -N -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{ - "jsonrpc": "2.0", - "id": "1", - "method": "message/stream", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Explain quantum computing"}] - } - }' -``` - -**SSE Events:** - -``` -data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}} - -: heartbeat 2026-03-03T17:00:00Z - -data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} -``` - -### `tasks/get` โ€” Query Task Status - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' -``` - -### `tasks/cancel` โ€” Cancel a Task - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' -``` - ---- - -## Available Skills - -| Skill | Description | -| :----------------- | :------------------------------------------------------------------------------------------------------------------------------ | -| `smart-routing` | Routes prompts through OmniRoute's intelligent pipeline. Returns response with routing explanation, cost, and resilience trace. | -| `quota-management` | Answers natural-language queries about provider quotas, suggests free combos, and provides quota rankings. | - ---- - -## Task Lifecycle - -``` -submitted โ†’ working โ†’ completed - โ†’ failed - โ†’ cancelled -``` - -- Tasks expire after 5 minutes (configurable) -- Terminal states: `completed`, `failed`, `cancelled` -- Event log tracks every state transition - ---- - -## Error Codes - -| Code | Meaning | -| :----- | :----------------------------- | -| -32700 | Parse error (invalid JSON) | -| -32600 | Invalid request / Unauthorized | -| -32601 | Method or skill not found | -| -32602 | Invalid params | -| -32603 | Internal error | - ---- - -## Integration Examples - -### Python (requests) - -```python -import requests - -resp = requests.post("http://localhost:20128/a2a", json={ - "jsonrpc": "2.0", "id": "1", - "method": "message/send", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Hello"}] - } -}, headers={"Authorization": "Bearer YOUR_KEY"}) - -result = resp.json()["result"] -print(result["artifacts"][0]["content"]) -print(result["metadata"]["routing_explanation"]) -``` - -### TypeScript (fetch) - -```typescript -const resp = await fetch("http://localhost:20128/a2a", { - method: "POST", - headers: { - "Content-Type": "application/json", - Authorization: "Bearer YOUR_KEY", - }, - body: JSON.stringify({ - jsonrpc: "2.0", - id: "1", - method: "message/send", - params: { - skill: "smart-routing", - messages: [{ role: "user", content: "Hello" }], - }, - }), -}); -const { result } = await resp.json(); -console.log(result.metadata.routing_explanation); -``` diff --git a/docs/i18n/phi/API_REFERENCE.md b/docs/i18n/phi/API_REFERENCE.md deleted file mode 100644 index b878605221..0000000000 --- a/docs/i18n/phi/API_REFERENCE.md +++ /dev/null @@ -1,455 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/API_REFERENCE.md) - ---- - -# API Reference - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/API_REFERENCE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/API_REFERENCE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/API_REFERENCE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/API_REFERENCE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/API_REFERENCE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/API_REFERENCE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/API_REFERENCE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/API_REFERENCE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/API_REFERENCE.md) - -Complete reference for all OmniRoute API endpoints. - ---- - -## Table of Contents - -- [Chat Completions](#chat-completions) -- [Embeddings](#embeddings) -- [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`. - -### ACP Agents - -| Endpoint | Method | Description | -| ----------------- | ------ | -------------------------------------------------------- | -| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | -| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | -| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | - -GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). - -### Resilience & Rate Limits - -| Endpoint | Method | Description | -| ----------------------- | ------- | ------------------------------- | -| `/api/resilience` | 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` diff --git a/docs/i18n/phi/ARCHITECTURE.md b/docs/i18n/phi/ARCHITECTURE.md deleted file mode 100644 index 4ea06a29f2..0000000000 --- a/docs/i18n/phi/ARCHITECTURE.md +++ /dev/null @@ -1,787 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/ARCHITECTURE.md) - ---- - -# OmniRoute Architecture - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/ARCHITECTURE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/ARCHITECTURE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/ARCHITECTURE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/ARCHITECTURE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/ARCHITECTURE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/ARCHITECTURE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/ARCHITECTURE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/ARCHITECTURE.md) - -_Last updated: 2026-03-04_ - -## 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 (`...`) for reasoning models -- Response sanitization for strict OpenAI SDK compatibility -- Role normalization (developerโ†’system, systemโ†’user) for cross-provider compatibility -- Structured output conversion (json_schema โ†’ Gemini responseSchema) -- Local persistence for providers, keys, aliases, combos, settings, pricing -- Usage/cost tracking and request logging -- Optional cloud sync for multi-device/state sync -- IP allowlist/blocklist for API access control -- Thinking budget management (passthrough/auto/custom/adaptive) -- Global system prompt injection -- Session tracking and fingerprinting -- Per-account enhanced rate limiting with provider-specific profiles -- Circuit breaker pattern for provider resilience -- Anti-thundering herd protection with mutex locking -- Signature-based request deduplication cache -- Domain layer: model availability, cost rules, fallback policy, lockout policy -- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) -- Policy engine for centralized request evaluation (lockout โ†’ budget โ†’ fallback) -- Request telemetry with p50/p95/p99 latency aggregation -- Correlation ID (X-Request-Id) for end-to-end tracing -- Compliance audit logging with opt-out per API key -- Eval framework for LLM quality assurance -- Resilience UI dashboard with real-time circuit breaker status -- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) - -Primary runtime model: - -- Next.js 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[(storage.sqlite)] - UDB[(usage tables + log artifacts)] - end - - subgraph Upstreams[Upstream Providers] - P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/Qoder/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/route.ts` (GET) -- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) -- OAuth: `src/app/api/oauth/*` -- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` -- Usage: `src/app/api/usage/*` -- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` -- CLI tooling helpers: `src/app/api/cli-tools/*` -- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) -- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) -- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) -- Sessions: `src/app/api/sessions` (GET) -- Rate limits: `src/app/api/rate-limits` (GET) -- Resilience: `src/app/api/resilience` (GET/PATCH) โ€” provider profiles, circuit breaker, rate limit state -- Resilience reset: `src/app/api/resilience/reset` (POST) โ€” reset breakers + cooldowns -- Cache stats: `src/app/api/cache/stats` (GET/DELETE) -- Model availability: `src/app/api/models/availability` (GET/POST) -- Telemetry: `src/app/api/telemetry/summary` (GET) -- Budget: `src/app/api/usage/budget` (GET/POST) -- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) -- Compliance audit: `src/app/api/compliance/audit-log` (GET) -- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) -- Policies: `src/app/api/policies` (GET/POST) - -## 2) SSE + 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` -- Response sanitization: `open-sse/handlers/responseSanitizer.ts` -- Role normalization: `open-sse/services/roleNormalizer.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`, `qoder.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 (SQLite): - -- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) -- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) -- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) -- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** - -Usage persistence: - -- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) -- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` -- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) -- legacy JSON files are migrated to SQLite by startup migrations when present - -Domain State DB (SQLite): - -- `src/lib/db/domainState.ts` โ€” CRUD operations 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: - -- primary runtime DB: `${DATA_DIR}/storage.sqlite` -- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) -- structured call payload archives: `${DATA_DIR}/call_logs/` -- optional translator/request debug sessions: `/logs/...` - -## Deployment Topology - -```mermaid -flowchart LR - 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[(storage.sqlite)] - UsageDB[(usage tables + log artifacts)] - end - - subgraph External[External Services] - Providers[AI Providers] - SyncCloud[Cloud Sync Service] - end - - CLI --> Next - Browser --> Next - Next --> Core - Next --> MainDB - Core --> MainDB - Core --> UsageDB - Core --> Providers - Next --> SyncCloud -``` - -## Module Mapping (Decision-Critical) - -### Route and API Modules - -- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs -- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) -- `src/app/api/providers*`: provider CRUD, validation, testing -- `src/app/api/provider-nodes*`: custom compatible node management -- `src/app/api/provider-models`: custom model management (CRUD) -- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) -- `src/app/api/oauth/*`: OAuth/device-code flows -- `src/app/api/keys*`: local API key lifecycle -- `src/app/api/models/alias`: alias management -- `src/app/api/combos*`: fallback combo management -- `src/app/api/pricing`: pricing overrides for cost calculation -- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) -- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) -- `src/app/api/usage/*`: usage and logs APIs -- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers -- `src/app/api/cli-tools/*`: local CLI config writers/checkers -- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) -- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) -- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) -- `src/app/api/sessions`: active session listing (GET) -- `src/app/api/rate-limits`: per-account rate limit status (GET) - -### Routing and Execution Core - -- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop -- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup -- `open-sse/executors/*`: provider-specific network and format behavior - -### Translation Registry and Format Converters - -- `open-sse/translator/index.ts`: translator registry and orchestration -- Request translators: `open-sse/translator/request/*` -- Response translators: `open-sse/translator/response/*` -- Format constants: `open-sse/translator/formats.ts` - -### Persistence - -- `src/lib/db/*`: persistent config/state and domain persistence on SQLite -- `src/lib/localDb.ts`: compatibility re-export for DB modules -- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables - -## Provider Executor Coverage (Strategy Pattern) - -Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. - -| Executor | Provider(s) | Special Handling | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | -| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, Qoder, 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 | -| Qoder | openai | OAuth (Basic) | โœ… | โœ… | โœ… | โš ๏ธ Per request | -| OpenRouter | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| GLM/Kimi/MiniMax | claude | API Key | โœ… | โœ… | โŒ | โŒ | -| DeepSeek | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Groq | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| xAI (Grok) | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Mistral | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Perplexity | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Together AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Fireworks AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Cerebras | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Cohere | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| NVIDIA NIM | openai | API Key | โœ… | โœ… | โŒ | โŒ | - -## Format Translation Coverage - -Detected source formats include: - -- `openai` -- `openai-responses` -- `claude` -- `gemini` - -Target formats include: - -- OpenAI chat/Responses -- Claude -- Gemini/Gemini-CLI/Antigravity envelope -- Kiro -- Cursor - -Translations use **OpenAI as the hub format** โ€” all conversions go through OpenAI as intermediate: - -``` -Source Format โ†’ OpenAI (hub) โ†’ Target Format -``` - -Translations are selected dynamically based on source payload shape and provider target format. - -Additional processing layers in the translation pipeline: - -- **Response sanitization** โ€” Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance -- **Role normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI targets; merges `system` โ†’ `user` for models that reject the system role (GLM, ERNIE) -- **Think tag extraction** โ€” Parses `...` blocks from content into `reasoning_content` field -- **Structured output** โ€” Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` - -## Supported API Endpoints - -| 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 `/logs//` 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 - -- SQLite schema migrations and auto-upgrade hooks at startup -- legacy JSON โ†’ SQLite migration compatibility path - -## Observability and Operational Signals - -Runtime visibility sources: - -- console logs from `src/sse/utils/logger.ts` -- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) -- textual request status log in `log.txt` (optional/compat) -- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` -- dashboard usage endpoints (`/api/usage/*`) for UI consumption - -## Security-Sensitive Boundaries - -- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing -- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning -- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format -- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level -- Cloud sync endpoints rely on API key auth + machine id semantics - -## Environment and Runtime Matrix - -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` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. -2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. -3. Request logger writes full headers/body when enabled; treat log directory as sensitive. -4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. -5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. -6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). -7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). -8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). - -## Operational Verification Checklist - -- Build from source: `npm run build` -- Build Docker image: `docker build -t omniroute .` -- Start service and verify: -- `GET /api/settings` -- `GET /api/v1/models` -- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/phi/AUTO-COMBO.md b/docs/i18n/phi/AUTO-COMBO.md deleted file mode 100644 index 2166e41dff..0000000000 --- a/docs/i18n/phi/AUTO-COMBO.md +++ /dev/null @@ -1,67 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/AUTO-COMBO.md) - ---- - -# OmniRoute Auto-Combo Engine - -> Self-managing model chains with adaptive scoring - -## How It Works - -The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**: - -| Factor | Weight | Description | -| :--------- | :----- | :---------------------------------------------- | -| Quota | 0.20 | Remaining capacity [0..1] | -| Health | 0.25 | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 | -| CostInv | 0.20 | Inverse cost (cheaper = higher score) | -| LatencyInv | 0.15 | Inverse p95 latency (faster = higher) | -| TaskFit | 0.10 | Model ร— task type fitness score | -| Stability | 0.10 | Low variance in latency/errors | - -## Mode Packs - -| Pack | Focus | Key Weight | -| :---------------------- | :----------- | :--------------- | -| ๐Ÿš€ **Ship Fast** | Speed | latencyInv: 0.35 | -| ๐Ÿ’ฐ **Cost Saver** | Economy | costInv: 0.40 | -| ๐ŸŽฏ **Quality First** | Best model | taskFit: 0.40 | -| ๐Ÿ“ก **Offline Friendly** | Availability | quota: 0.40 | - -## Self-Healing - -- **Temporary exclusion**: Score < 0.2 โ†’ excluded for 5 min (progressive backoff, max 30 min) -- **Circuit breaker awareness**: OPEN โ†’ auto-excluded; HALF_OPEN โ†’ probe requests -- **Incident mode**: >50% OPEN โ†’ disable exploration, maximize stability -- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout - -## Bandit Exploration - -5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode. - -## API - -```bash -# Create auto-combo -curl -X POST http://localhost:20128/api/combos/auto \ - -H "Content-Type: application/json" \ - -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}' - -# List auto-combos -curl http://localhost:20128/api/combos/auto -``` - -## Task Fitness - -30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` โ†’ high coding score). - -## Files - -| File | Purpose | -| :------------------------------------------- | :------------------------------------ | -| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization | -| `open-sse/services/autoCombo/taskFitness.ts` | Model ร— task fitness lookup | -| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap | -| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode | -| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles | -| `src/app/api/combos/auto/route.ts` | REST API | diff --git a/docs/i18n/phi/CHANGELOG.md b/docs/i18n/phi/CHANGELOG.md index 0055f6dda6..b43b737984 100644 --- a/docs/i18n/phi/CHANGELOG.md +++ b/docs/i18n/phi/CHANGELOG.md @@ -1,12 +1,92 @@ # Changelog (Filipino) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CHANGELOG.md) --- - ## [Unreleased] +### ๐Ÿ› ๏ธ Maintenance + +- **AGENTS.md rewrite:** Condensed from 297โ†’153 lines. Added build/lint/test commands (including single-test execution), code style guidelines (Prettier, TypeScript, ESLint, naming, imports, error handling, security), and trimmed verbose architecture tables for AI agent consumption. + +## [3.4.2] - 2026-04-01 + +### ๐Ÿ› Bug Fixes + +- **CI Stabilization:** Fixed failing analytics/settings Playwright selectors and request assertions so GitHub Actions E2E runs pass reliably across localized UIs and switch-based controls. +- **Deterministic Tests:** Removed date-sensitive quota fixtures from Copilot usage tests and aligned idempotency/model catalog tests with the merged runtime behavior. +- **MCP Type Hardening:** Removed zero-budget explicit `any` regressions from the MCP server tool registration path, restoring the `check:any-budget:t11` workflow gate. + +### ๐Ÿ› ๏ธ Maintenance + +- **Release Branch Integration:** Consolidated the active feature branches into `release/v3.4.2` on top of current `main` and validated the branch with lint, unit, coverage, build, and CI-mode E2E runs. + +## [3.4.1] - 2026-03-31 + +> [!WARNING] +> **BREAKING CHANGE: request logging, retention, and logging environment variables have been redesigned.** +> On the first startup after upgrading, OmniRoute archives legacy request logs from `DATA_DIR/logs/`, legacy `DATA_DIR/call_logs/`, and `DATA_DIR/log.txt` into `DATA_DIR/log_archives/*.zip`, then removes the deprecated layout and switches to the new unified artifact format under `DATA_DIR/call_logs/`. + +### โœจ New Features + +- **.ENV Migration Utility:** Included `scripts/migrate-env.mjs` to seamlessly migrate ` Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` - ---- - -## Step 2 โ€” Install CLI Tools - -All npm-based tools require Node.js 18+: - -```bash -# Claude Code (Anthropic) -npm install -g @anthropic-ai/claude-code - -# OpenAI Codex -npm install -g @openai/codex - -# Gemini CLI (Google) -npm install -g @google/gemini-cli - -# OpenCode -npm install -g opencode-ai - -# Cline -npm install -g cline - -# KiloCode -npm install -g kilecode - -# Kiro CLI (Amazon โ€” requires curl + unzip) -apt-get install -y unzip # on Debian/Ubuntu -curl -fsSL https://cli.kiro.dev/install | bash -export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc -``` - -**Verify:** - -```bash -claude --version # 2.x.x -codex --version # 0.x.x -gemini --version # 0.x.x -opencode --version # x.x.x -cline --version # 2.x.x -kilocode --version # x.x.x (or: kilo --version) -kiro-cli --version # 1.x.x -``` - ---- - -## Step 3 โ€” Set Global Environment Variables - -Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`: - -```bash -# OmniRoute Universal Endpoint -export OPENAI_BASE_URL="http://localhost:20128/v1" -export OPENAI_API_KEY="sk-your-omniroute-key" -export ANTHROPIC_BASE_URL="http://localhost:20128/v1" -export ANTHROPIC_API_KEY="sk-your-omniroute-key" -export GEMINI_BASE_URL="http://localhost:20128/v1" -export GEMINI_API_KEY="sk-your-omniroute-key" -``` - -> For a **remote server** replace `localhost:20128` with the server IP or domain, -> e.g. `http://192.168.0.15:20128`. - ---- - -## Step 4 โ€” Configure Each Tool - -### Claude Code - -```bash -# Via CLI: -claude config set --global api-base-url http://localhost:20128/v1 - -# Or create ~/.claude/settings.json: -mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF -{ - "apiBaseUrl": "http://localhost:20128/v1", - "apiKey": "sk-your-omniroute-key" -} -EOF -``` - -**Test:** `claude "say hello"` - ---- - -### OpenAI Codex - -```bash -mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF -model: auto -apiKey: sk-your-omniroute-key -apiBaseUrl: http://localhost:20128/v1 -EOF -``` - -**Test:** `codex "what is 2+2?"` - ---- - -### Gemini CLI - -```bash -mkdir -p ~/.gemini && cat > ~/.gemini/settings.json << EOF -{ - "apiKey": "sk-your-omniroute-key", - "baseUrl": "http://localhost:20128/v1" -} -EOF -``` - -**Test:** `gemini "hello"` - ---- - -### OpenCode - -```bash -mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF -[provider.openai] -base_url = "http://localhost:20128/v1" -api_key = "sk-your-omniroute-key" -EOF -``` - -**Test:** `opencode` - ---- - -### Cline (CLI or VS Code) - -**CLI mode:** - -```bash -mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF -{ - "apiProvider": "openai", - "openAiBaseUrl": "http://localhost:20128/v1", - "openAiApiKey": "sk-your-omniroute-key" -} -EOF -``` - -**VS Code mode:** -Cline extension settings โ†’ API Provider: `OpenAI Compatible` โ†’ Base URL: `http://localhost:20128/v1` - -Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ Cline โ†’ Apply Config**. - ---- - -### KiloCode (CLI or VS Code) - -**CLI mode:** - -```bash -kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key -``` - -**VS Code settings:** - -```json -{ - "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", - "kilo-code.apiKey": "sk-your-omniroute-key" -} -``` - -Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ KiloCode โ†’ Apply Config**. - ---- - -### Continue (VS Code Extension) - -Edit `~/.continue/config.yaml`: - -```yaml -models: - - name: OmniRoute - provider: openai - model: auto - apiBase: http://localhost:20128/v1 - apiKey: sk-your-omniroute-key - default: true -``` - -Restart VS Code after editing. - ---- - -### Kiro CLI (Amazon) - -```bash -# Login to your AWS/Kiro account: -kiro-cli login - -# The CLI uses its own auth โ€” OmniRoute is not needed as backend for Kiro CLI itself. -# Use kiro-cli alongside OmniRoute for other tools. -kiro-cli status -``` - ---- - -### Cursor (Desktop App) - -> **Note:** Cursor routes requests through its cloud. For OmniRoute integration, -> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL. - -Via GUI: **Settings โ†’ Models โ†’ OpenAI API Key** - -- Base URL: `https://your-domain.com/v1` -- API Key: your OmniRoute key - ---- - -## Dashboard Auto-Configuration - -The OmniRoute dashboard automates configuration for most tools: - -1. Go to `http://localhost:20128/dashboard/cli-tools` -2. Expand any tool card -3. Select your API key from the dropdown -4. Click **Apply Config** (if tool is detected as installed) -5. Or copy the generated config snippet manually - ---- - -## Built-in Agents: Droid & OpenClaw - -**Droid** and **OpenClaw** are AI agents built directly into OmniRoute โ€” no installation needed. -They run as internal routes and use OmniRoute's model routing automatically. - -- Access: `http://localhost:20128/dashboard/agents` -- Configure: same combos and providers as all other tools -- No API key or CLI install required - ---- - -## Available API Endpoints - -| Endpoint | Description | Use For | -| -------------------------- | ----------------------------- | --------------------------- | -| `/v1/chat/completions` | Standard chat (all providers) | All modern tools | -| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows | -| `/v1/completions` | Legacy text completions | Older tools using `prompt:` | -| `/v1/embeddings` | Text embeddings | RAG, search | -| `/v1/images/generations` | Image generation | DALL-E, Flux, etc. | -| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS | -| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI | - ---- - -## Troubleshooting - -| Error | Cause | Fix | -| ------------------------- | ----------------------- | ------------------------------------------ | -| `Connection refused` | OmniRoute not running | `pm2 start omniroute` | -| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` | -| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` | -| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` | -| CLI shows "not installed" | Binary not in PATH | Check `which ` | -| `kiro-cli: not found` | Not in PATH | `export PATH="$HOME/.local/bin:$PATH"` | - ---- - -## Quick Setup Script (One Command) - -```bash -# Install all CLIs and configure for OmniRoute (replace with your key and server URL) -OMNIROUTE_URL="http://localhost:20128/v1" -OMNIROUTE_KEY="sk-your-omniroute-key" - -npm install -g @anthropic-ai/claude-code @openai/codex @google/gemini-cli opencode-ai cline kilecode - -# Kiro CLI -apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash - -# Write configs -mkdir -p ~/.claude ~/.codex ~/.gemini ~/.config/opencode ~/.continue - -cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" -cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" -cat > ~/.gemini/settings.json <<< "{\"apiKey\":\"$OMNIROUTE_KEY\",\"baseUrl\":\"$OMNIROUTE_URL\"}" -cat >> ~/.bashrc << EOF -export OPENAI_BASE_URL="$OMNIROUTE_URL" -export OPENAI_API_KEY="$OMNIROUTE_KEY" -export ANTHROPIC_BASE_URL="$OMNIROUTE_URL" -export ANTHROPIC_API_KEY="$OMNIROUTE_KEY" -EOF - -source ~/.bashrc -echo "โœ… All CLIs installed and configured for OmniRoute" -``` diff --git a/docs/i18n/phi/CODEBASE_DOCUMENTATION.md b/docs/i18n/phi/CODEBASE_DOCUMENTATION.md deleted file mode 100644 index e2d7950052..0000000000 --- a/docs/i18n/phi/CODEBASE_DOCUMENTATION.md +++ /dev/null @@ -1,593 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CODEBASE_DOCUMENTATION.md) - ---- - -# omniroute โ€” Codebase Documentation - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) - -> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. - ---- - -## 1. 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
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, Qoder, 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 | -| Qoder | 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"] -``` diff --git a/docs/i18n/phi/CONTRIBUTING.md b/docs/i18n/phi/CONTRIBUTING.md new file mode 100644 index 0000000000..27d1271267 --- /dev/null +++ b/docs/i18n/phi/CONTRIBUTING.md @@ -0,0 +1,299 @@ +# Contributing to OmniRoute (Filipino) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CONTRIBUTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CONTRIBUTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CONTRIBUTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CONTRIBUTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CONTRIBUTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CONTRIBUTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CONTRIBUTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CONTRIBUTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CONTRIBUTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CONTRIBUTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CONTRIBUTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CONTRIBUTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CONTRIBUTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CONTRIBUTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CONTRIBUTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CONTRIBUTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CONTRIBUTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CONTRIBUTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CONTRIBUTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CONTRIBUTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CONTRIBUTING.md) + +--- + +Thank you for your interest in contributing! This guide covers everything you need to get started. + +--- + +## Development Setup + +### Prerequisites + +- **Node.js** >= 18 < 24 (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` | `20128` | Server port | +| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | Base URL for frontend | +| `JWT_SECRET` | (generate above) | JWT signing secret | +| `INITIAL_PASSWORD` | `CHANGEME` | First login password | +| `APP_LOG_LEVEL` | `info` | Log verbosity level | + +### Dashboard Settings + +The dashboard provides UI toggles for features that can also be configured via environment variables: + +| Setting Location | Toggle | Description | +| ------------------- | ------------------ | ------------------------------ | +| Settings โ†’ Advanced | Debug Mode | Enable debug request logs (UI) | +| Settings โ†’ General | Sidebar Visibility | Show/hide sidebar sections | + +These settings are stored in the database and persist across restarts, overriding env var defaults when set. + +### 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:20128/dashboard` +- **API**: `http://localhost:20128/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`, `mcp`, `a2a`, `memory`, `skills`. + +--- + +## Running Tests + +```bash +# All tests (unit + vitest + ecosystem + e2e) +npm run test:all + +# Single test file (Node.js native test runner โ€” most tests use this) +node --import tsx/esm --test tests/unit/your-file.test.mjs + +# Vitest (MCP server, autoCombo, cache) +npm run test:vitest + +# E2E tests (requires Playwright) +npm run test:e2e + +# Protocol clients E2E (MCP transports, A2A) +npm run test:protocols:e2e + +# Ecosystem compatibility tests +npm run test:ecosystem + +# Coverage (55% min statements/lines/functions; 60% branches) +npm run test:coverage +npm run coverage:report + +# Lint + format check +npm run lint +npm run check +``` + +Coverage notes: + +- `npm run test:coverage` measures source coverage for the main unit test suite, excludes `tests/**`, and includes `open-sse/**` +- `npm run coverage:report` prints the detailed file-by-file report from the latest coverage run +- `npm run test:coverage:legacy` preserves the older metric for historical comparison +- See `docs/COVERAGE_PLAN.md` for the phased coverage improvement roadmap + +Current test status: **122 unit test files** covering: + +- Provider translators and format conversion +- Rate limiting, circuit breaker, and resilience +- Semantic cache, idempotency, progress tracking +- Database operations and schema (21 DB modules) +- OAuth flows and authentication +- API endpoint validation (Zod v4) +- MCP server tools and scope enforcement +- Memory and Skills systems + +--- + +## Code Style + +- **ESLint** โ€” Run `npm run lint` before committing +- **Prettier** โ€” Auto-formatted via `lint-staged` on commit (2 spaces, semicolons, double quotes, 100 char width, es5 trailing commas) +- **TypeScript** โ€” All `src/` code uses `.ts`/`.tsx`; `open-sse/` uses `.ts`/`.js`; document with TSDoc (`@param`, `@returns`, `@throws`) +- **No `eval()`** โ€” ESLint enforces `no-eval`, `no-implied-eval`, `no-new-func` +- **Zod validation** โ€” Use Zod v4 schemas for all API input validation +- **Naming**: Files = camelCase/kebab-case, components = PascalCase, constants = UPPER_SNAKE + +--- + +## Project Structure + +``` +src/ # TypeScript (.ts / .tsx) +โ”œโ”€โ”€ app/ # Next.js 16 App Router +โ”‚ โ”œโ”€โ”€ (dashboard)/ # Dashboard pages (23 sections) +โ”‚ โ”œโ”€โ”€ api/ # API routes (51 directories) +โ”‚ โ””โ”€โ”€ login/ # Auth pages (.tsx) +โ”œโ”€โ”€ domain/ # Policy engine (policyEngine, comboResolver, costRules, etc.) +โ”œโ”€โ”€ lib/ # Core business logic (.ts) +โ”‚ โ”œโ”€โ”€ a2a/ # Agent-to-Agent v0.3 protocol server +โ”‚ โ”œโ”€โ”€ acp/ # Agent Communication Protocol registry +โ”‚ โ”œโ”€โ”€ compliance/ # Compliance policy engine +โ”‚ โ”œโ”€โ”€ db/ # SQLite database layer (21 modules + 16 migrations) +โ”‚ โ”œโ”€โ”€ memory/ # Persistent conversational memory +โ”‚ โ”œโ”€โ”€ oauth/ # OAuth providers, services, and utilities +โ”‚ โ”œโ”€โ”€ skills/ # Extensible skill framework +โ”‚ โ”œโ”€โ”€ usage/ # Usage tracking and cost calculation +โ”‚ โ””โ”€โ”€ localDb.ts # Re-export layer only โ€” never add logic here +โ”œโ”€โ”€ middleware/ # Request middleware (promptInjectionGuard) +โ”œโ”€โ”€ mitm/ # MITM proxy (cert, DNS, target routing) +โ”œโ”€โ”€ shared/ +โ”‚ โ”œโ”€โ”€ components/ # React components (.tsx) +โ”‚ โ”œโ”€โ”€ constants/ # Provider definitions (60+), MCP scopes, routing strategies +โ”‚ โ”œโ”€โ”€ utils/ # Circuit breaker, sanitizer, auth helpers +โ”‚ โ””โ”€โ”€ validation/ # Zod v4 schemas +โ””โ”€โ”€ sse/ # SSE proxy pipeline + +open-sse/ # @omniroute/open-sse workspace +โ”œโ”€โ”€ executors/ # 14 provider-specific request executors +โ”œโ”€โ”€ handlers/ # 11 request handlers (chat, responses, embeddings, images, etc.) +โ”œโ”€โ”€ mcp-server/ # MCP server (25 tools, 3 transports, 10 scopes) +โ”œโ”€โ”€ services/ # 36+ services (combo, autoCombo, rateLimitManager, etc.) +โ”œโ”€โ”€ translator/ # Format translators (OpenAI โ†” Claude โ†” Gemini โ†” Responses โ†” Ollama) +โ”œโ”€โ”€ transformer/ # Responses API transformer +โ””โ”€โ”€ utils/ # 22 utility modules (stream, TLS, proxy, logging) + +electron/ # Electron desktop app (cross-platform) + +tests/ +โ”œโ”€โ”€ unit/ # Node.js test runner (122 test files) +โ”œโ”€โ”€ integration/ # Integration tests +โ”œโ”€โ”€ e2e/ # Playwright tests +โ”œโ”€โ”€ security/ # Security tests +โ”œโ”€โ”€ translator/ # Translator-specific tests +โ””โ”€โ”€ load/ # Load tests + +docs/ # Documentation +โ”œโ”€โ”€ ARCHITECTURE.md # System architecture +โ”œโ”€โ”€ API_REFERENCE.md # All endpoints +โ”œโ”€โ”€ USER_GUIDE.md # Provider setup, CLI integration +โ”œโ”€โ”€ TROUBLESHOOTING.md # Common issues +โ”œโ”€โ”€ MCP-SERVER.md # MCP server (25 tools) +โ”œโ”€โ”€ A2A-SERVER.md # A2A agent protocol +โ”œโ”€โ”€ AUTO-COMBO.md # Auto-combo engine +โ”œโ”€โ”€ CLI-TOOLS.md # CLI tools integration +โ”œโ”€โ”€ COVERAGE_PLAN.md # Test coverage improvement plan +โ”œโ”€โ”€ openapi.yaml # OpenAPI specification +โ””โ”€โ”€ adr/ # Architecture Decision Records +``` + +--- + +## Adding a New Provider + +### Step 1: Register Provider Constants + +Add to `src/shared/constants/providers.ts` โ€” Zod-validated at module load. + +### Step 2: Add Executor (if custom logic needed) + +Create executor in `open-sse/executors/your-provider.ts` extending the base executor. + +### Step 3: Add Translator (if non-OpenAI format) + +Create request/response translators in `open-sse/translator/`. + +### Step 4: Add OAuth Config (if OAuth-based) + +Add OAuth credentials in `src/lib/oauth/constants/oauth.ts` and service in `src/lib/oauth/services/`. + +### Step 5: Register Models + +Add model definitions in `open-sse/config/providerRegistry.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 +- [ ] All inputs validated with Zod schemas +- [ ] CHANGELOG updated (if user-facing change) +- [ ] Documentation updated (if applicable) + +--- + +## Releasing + +Releases are managed via the `/generate-release` workflow. When a new GitHub Release is created, the package is **automatically published to npm** via GitHub Actions. + +--- + +## Getting Help + +- **Architecture**: See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) +- **API Reference**: See [`docs/API_REFERENCE.md`](docs/API_REFERENCE.md) +- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **ADRs**: See `docs/adr/` for architectural decision records diff --git a/docs/i18n/phi/FEATURES.md b/docs/i18n/phi/FEATURES.md deleted file mode 100644 index d0d27cea0b..0000000000 --- a/docs/i18n/phi/FEATURES.md +++ /dev/null @@ -1,147 +0,0 @@ -# OmniRoute โ€” Dashboard Features Gallery (Filipino) - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) - -> ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../docs/FEATURES.md) - ---- - -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 (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. - -![Providers Dashboard](screenshots/01-providers.png) - ---- - -## ๐ŸŽจ Combos - -Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. - -![Combos Dashboard](screenshots/02-combos.png) - ---- - -## ๐Ÿ“Š Analytics - -Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. - -![Analytics Dashboard](screenshots/03-analytics.png) - ---- - -## ๐Ÿฅ System Health - -Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. - -![Health Dashboard](screenshots/04-health.png) - ---- - -## ๐Ÿ”ง Translator Playground - -Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). - -![Translator Playground](screenshots/05-translator.png) - ---- - -## ๐ŸŽฎ Model Playground _(v2.0.9+)_ - -Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. - ---- - -## ๐ŸŽจ Themes _(v2.0.5+)_ - -Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. - ---- - -## โš™๏ธ Settings - -Comprehensive settings panel with tabs: - -- **General** โ€” System storage, backup management (export/import database) -- **Appearance** โ€” Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls -- **Security** โ€” API endpoint protection, custom provider blocking, IP filtering, session info -- **Routing** โ€” Model aliases, background task degradation -- **Resilience** โ€” Rate limit persistence, circuit breaker tuning -- **Advanced** โ€” Configuration overrides - -![Settings Dashboard](screenshots/06-settings.png) - ---- - -## ๐Ÿ”ง CLI Tools - -One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. - -![CLI Tools Dashboard](screenshots/07-cli-tools.png) - ---- - -## ๐Ÿค– CLI Agents _(v2.0.11+)_ - -Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: - -- **Installation status** โ€” Installed / Not Found with version detection -- **Protocol badges** โ€” stdio, HTTP, etc. -- **Custom agents** โ€” Register any CLI tool via form (name, binary, version command, spawn args) -- **CLI Fingerprint Matching** โ€” Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP - ---- - -## ๐Ÿ–ผ๏ธ Media _(v2.0.3+)_ - -Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. - ---- - -## ๐Ÿ“ Request Logs - -Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. - -![Usage Logs](screenshots/08-usage.png) - ---- - -## ๐ŸŒ API Endpoint - -Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. - -![Endpoint Dashboard](screenshots/09-endpoint.png) - ---- - -## ๐Ÿ”‘ API Key Management - -Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. - ---- - -## ๐Ÿ“‹ Audit Log - -Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. - ---- - -## ๐Ÿ–ฅ๏ธ Desktop Application - -Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. - -Key features: - -- Server readiness polling (no blank screen on cold start) -- System tray with port management -- Content Security Policy -- Single-instance lock -- Auto-update on restart -- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) -- Hardened Electron build packaging โ€” symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+) - -๐Ÿ“– See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/phi/MCP-SERVER.md b/docs/i18n/phi/MCP-SERVER.md deleted file mode 100644 index 829acd30b1..0000000000 --- a/docs/i18n/phi/MCP-SERVER.md +++ /dev/null @@ -1,87 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/MCP-SERVER.md) - ---- - -# OmniRoute MCP Server Documentation - -> Model Context Protocol server with 16 intelligent tools - -## Installation - -OmniRoute MCP is built-in. Start it with: - -```bash -omniroute --mcp -``` - -Or via the open-sse transport: - -```bash -# HTTP streamable transport (port 20130) -omniroute --dev # MCP auto-starts on /mcp endpoint -``` - -## IDE Configuration - -See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup. - ---- - -## Essential Tools (8) - -| Tool | Description | -| :------------------------------ | :--------------------------------------- | -| `omniroute_get_health` | Gateway health, circuit breakers, uptime | -| `omniroute_list_combos` | All configured combos with models | -| `omniroute_get_combo_metrics` | Performance metrics for a specific combo | -| `omniroute_switch_combo` | Switch active combo by ID/name | -| `omniroute_check_quota` | Quota status per provider or all | -| `omniroute_route_request` | Send a chat completion through OmniRoute | -| `omniroute_cost_report` | Cost analytics for a time period | -| `omniroute_list_models_catalog` | Full model catalog with capabilities | - -## Advanced Tools (8) - -| Tool | Description | -| :--------------------------------- | :---------------------------------------------- | -| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | -| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | -| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | -| `omniroute_test_combo` | Live-test all models in a combo | -| `omniroute_get_provider_metrics` | Detailed metrics for one provider | -| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | -| `omniroute_explain_route` | Explain a past routing decision | -| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | - -## Authentication - -MCP tools are authenticated via API key scopes. Each tool requires specific scopes: - -| Scope | Tools | -| :------------- | :----------------------------------------------- | -| `read:health` | get_health, get_provider_metrics | -| `read:combos` | list_combos, get_combo_metrics | -| `write:combos` | switch_combo | -| `read:quota` | check_quota | -| `write:route` | route_request, simulate_route, test_combo | -| `read:usage` | cost_report, get_session_snapshot, explain_route | -| `write:config` | set_budget_guard, set_resilience_profile | -| `read:models` | list_models_catalog, best_combo_for_task | - -## Audit Logging - -Every tool call is logged to `mcp_tool_audit` with: - -- Tool name, arguments, result -- Duration (ms), success/failure -- API key hash, timestamp - -## Files - -| File | Purpose | -| :------------------------------------------- | :------------------------------------------ | -| `open-sse/mcp-server/server.ts` | MCP server creation + 16 tool registrations | -| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport | -| `open-sse/mcp-server/auth.ts` | API key + scope validation | -| `open-sse/mcp-server/audit.ts` | Tool call audit logging | -| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers | diff --git a/docs/i18n/phi/README.md b/docs/i18n/phi/README.md index 2f2a8bb6b7..837f0c10fb 100644 --- a/docs/i18n/phi/README.md +++ b/docs/i18n/phi/README.md @@ -1,12 +1,12 @@ # ๐Ÿš€ OmniRoute โ€” The Free AI Gateway (Filipino) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/README.md) --- ### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback. -_Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._ +_Your universal API proxy โ€” one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._ **Chat Completions โ€ข Embeddings โ€ข Image Generation โ€ข Video โ€ข Music โ€ข Audio โ€ข Reranking โ€ข **Web Search** โ€ข MCP Server โ€ข A2A Protocol โ€ข 100% TypeScript** @@ -46,15 +46,17 @@ _Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now wi > - `APP_LOG_FILE_PATH` > - `APP_LOG_MAX_FILE_SIZE` > - `APP_LOG_RETENTION_DAYS` +> - `APP_LOG_MAX_FILES` > - `APP_LOG_LEVEL` > - `APP_LOG_FORMAT` > - `CALL_LOG_RETENTION_DAYS` +> - `CALL_LOG_MAX_ENTRIES` > > For release details and upgrade notes, see the [CHANGELOG](CHANGELOG.md). --- -## ๐Ÿ†• What's New in v3.0.0 +## ๐Ÿ†• What's New > **Upgrading from v2.9.5?** โ€” See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes. @@ -274,7 +276,7 @@ Developers pay $20โ€“200/month for Claude Pro, Codex Pro, or GitHub Copilot. Eve - **Smart 4-Tier Fallback** โ€” If subscription quota runs out, automatically redirects to API Key โ†’ Cheap โ†’ Free with zero manual intervention - **Real-Time Quota Tracking** โ€” Shows token consumption in real-time with reset countdown (5h, daily, weekly) - **Multi-Account Support** โ€” Multiple accounts per provider with auto round-robin โ€” when one runs out, switches to the next -- **Custom Combos** โ€” Customizable fallback chains with 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Custom Combos** โ€” Customizable fallback chains with 9 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random) - **Codex Business Quotas** โ€” Business/Team workspace quota monitoring directly in the dashboard @@ -286,7 +288,7 @@ OpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If **How OmniRoute solves it:** -- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 67+ providers +- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 60+ providers - **Format Translation** โ€” Automatic and transparent: OpenAI โ†” Claude โ†” Gemini โ†” Responses API - **Response Sanitization** โ€” Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+ - **Role Normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI providers; `system` โ†’ `user` for GLM/ERNIE @@ -372,7 +374,7 @@ Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code.. - **CLI Tools Dashboard** โ€” Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline - **GitHub Copilot Config Generator** โ€” Generates `chatLanguageModels.json` for VS Code with bulk model selection - **Onboarding Wizard** โ€” Guided 4-step setup for first-time users -- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 67+ providers +- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 60+ providers @@ -419,7 +421,7 @@ When a call fails, the dev doesn't know if it was a rate limit, expired token, w - **SQLite Proxy Logs** โ€” Persistent logs that survive server restarts - **Translator Playground** โ€” 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time) - **Request Telemetry** โ€” p50/p95/p99 latency + X-Request-Id tracing -- **File-Based Logging with Rotation** โ€” Console interceptor captures everything to JSON log with size-based rotation +- **File-Based Logging with Rotation** โ€” App logs rotate by size, retention days, and archive count; call log artifacts rotate by retention days and file count - **System Info Report** โ€” `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage. @@ -514,7 +516,7 @@ Developers who want all responses in a specific language, with a specific tone, - **System Prompt Injection** โ€” Global prompt applied to all requests - **Thinking Budget Validation** โ€” Reasoning token allocation control per request (passthrough, auto, custom, adaptive) -- **6 Routing Strategies** โ€” Global strategies that determine how requests are distributed +- **9 Routing Strategies** โ€” Global strategies that determine how requests are distributed - **Wildcard Router** โ€” `provider/*` patterns route dynamically to any provider - **Combo Enable/Disable Toggle** โ€” Toggle combos directly from the dashboard - **Provider Toggle** โ€” Enable/disable all connections for a provider with one click @@ -581,7 +583,7 @@ Different clients should have least-privilege access to tool categories. **How OmniRoute solves it:** -- 9 granular MCP scopes for controlled tool access +- 10 granular MCP scopes for controlled tool access - Scope enforcement and visibility in MCP management UI - Safe default posture for operational tooling @@ -1325,19 +1327,19 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. ### ๐Ÿค– Agent & Protocol Operations (v2.0) -| Feature | What It Does | -| ------------------------------------- | -------------------------------------------------------------------------------------------------- | -| ๐Ÿ”ง **MCP Server (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) | -| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | -| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | -| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | -| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | -| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | -| ๐Ÿ” **MCP Scope Enforcement** | 9 granular scope permissions for controlled tool access | -| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | -| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | -| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | -| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | +| Feature | What It Does | +| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| ๐Ÿ”ง **MCP Server (25 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools | +| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | +| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | +| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | +| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | +| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | +| ๐Ÿ” **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access | +| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | +| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | +| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | +| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | ### ๐Ÿง  Routing & Intelligence @@ -1348,7 +1350,7 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. | ๐Ÿ”„ **Format Translation** | OpenAI โ†” Claude โ†” Gemini โ†” Responses with schema-safe conversions | | ๐Ÿ‘ฅ **Multi-Account Support** | Multiple accounts per provider with intelligent selection | | ๐Ÿ”„ **Auto Token Refresh** | OAuth tokens refresh automatically with retry | -| ๐ŸŽจ **Custom Combos** | 6 balancing strategies + fallback chain control | +| ๐ŸŽจ **Custom Combos** | 9 balancing strategies + fallback chain control | | ๐ŸŒ **Wildcard Router** | `provider/*` dynamic routing | | ๐Ÿง  **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits | | ๐Ÿ”€ **Model Aliases** | Built-in + custom model aliasing and migration safety | @@ -1949,6 +1951,7 @@ opencode - Request artifacts are written to `DATA_DIR/call_logs/` as one JSON file per request - Enable pipeline capture from Dashboard โ†’ Logs โ†’ Request Logs if you need detailed per-stage payloads - Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log` +- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed **Connection test shows "Invalid" for OpenAI-compatible providers** diff --git a/docs/i18n/phi/RELEASE_CHECKLIST.md b/docs/i18n/phi/RELEASE_CHECKLIST.md deleted file mode 100644 index 903e812c3f..0000000000 --- a/docs/i18n/phi/RELEASE_CHECKLIST.md +++ /dev/null @@ -1,37 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/RELEASE_CHECKLIST.md) - ---- - -# Release Checklist - -Use this checklist before tagging or publishing a new OmniRoute release. - -## Version and Changelog - -1. Bump `package.json` version (`x.y.z`) in the release branch. -2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: - - `## [x.y.z] โ€” YYYY-MM-DD` -3. Keep `## [Unreleased]` as the first changelog section for upcoming work. -4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. - -## API Docs - -1. Update `docs/openapi.yaml`: - - `info.version` must equal `package.json` version. -2. Validate endpoint examples if API contracts changed. - -## Runtime Docs - -1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. -2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. -3. Update localized docs if source docs changed significantly. - -## Automated Check - -Run the sync guard locally before opening PR: - -```bash -npm run check:docs-sync -``` - -CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/phi/SECURITY.md b/docs/i18n/phi/SECURITY.md new file mode 100644 index 0000000000..3b3189b55a --- /dev/null +++ b/docs/i18n/phi/SECURITY.md @@ -0,0 +1,179 @@ +# Security Policy (Filipino) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../SECURITY.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/SECURITY.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/SECURITY.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/SECURITY.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/SECURITY.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/SECURITY.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/SECURITY.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/SECURITY.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/SECURITY.md) + +--- + +## 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 | +| ------- | -------------- | +| 3.4.x | โœ… Active | +| 3.0.x | โœ… Security | +| < 3.0.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 | +| **MCP Scopes** | 10 granular scopes for MCP tool access control | + +### ๐Ÿ›ก๏ธ 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:::` +- 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** | Allowlist/blocklist IP ranges in dashboard | +| **Rate Limiting** | Per-provider rate limits with automatic backoff | +| **Anti-Thundering Herd** | Mutex + per-connection locking prevents cascading 502s | +| **TLS Fingerprint** | Browser-like TLS fingerprint spoofing to reduce bot detection | +| **CLI Fingerprint** | Per-provider header/body ordering to match native CLI signatures | + +### ๐Ÿ”Œ Resilience & Availability + +| 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 `CALL_LOG_RETENTION_DAYS` | +| **No-Log Opt-out** | Per API key `noLog` flag disables request logging | +| **Audit Log** | Administrative actions tracked in `audit_log` table | +| **MCP Audit** | SQLite-backed audit logging for all MCP tool calls | +| **Zod Validation** | All API inputs validated with Zod v4 schemas at module load | + +--- + +## 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 +- Provider constants validated at module load via Zod (`src/shared/validation/providerSchema.ts`) diff --git a/docs/i18n/phi/TROUBLESHOOTING.md b/docs/i18n/phi/TROUBLESHOOTING.md deleted file mode 100644 index 63c148000a..0000000000 --- a/docs/i18n/phi/TROUBLESHOOTING.md +++ /dev/null @@ -1,258 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/TROUBLESHOOTING.md) - ---- - -# Troubleshooting - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/TROUBLESHOOTING.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/TROUBLESHOOTING.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/TROUBLESHOOTING.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/TROUBLESHOOTING.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/TROUBLESHOOTING.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/TROUBLESHOOTING.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/TROUBLESHOOTING.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/TROUBLESHOOTING.md) - -Common problems and solutions for OmniRoute. - ---- - -## Quick Fixes - -| Problem | Solution | -| ----------------------------- | ------------------------------------------------------------------ | -| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | -| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | -| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | -| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | -| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | - ---- - -## Provider Issues - -### "Language model did not provide messages" - -**Cause:** Provider quota exhausted. - -**Fix:** - -1. 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, Qoder) 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}/storage.sqlite` (providers, combos, aliases, keys, settings) -- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` -- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) - ---- - -## Circuit Breaker Issues - -### Provider stuck in OPEN state - -When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. - -**Fix:** - -1. 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 -- **SDK returns raw string instead of object** โ€” Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures -- **GLM/ERNIE rejects `system` role** โ€” Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models -- **`developer` role not recognized** โ€” Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers -- **`json_schema` not working with Gemini** โ€” Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` - ---- - -## Resilience Settings - -### Auto rate-limit not triggering - -- 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. - ---- - -## Optional RAG / LLM failure taxonomy (16 problems) - -Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. - -In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. - -If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: - -- retrieval drift and broken context boundaries -- empty or stale indexes and vector stores -- embedding versus semantic mismatch -- prompt assembly and context window issues -- logic collapse and overconfident answers -- long chain and agent coordination failures -- multi agent memory and role drift -- deployment and bootstrap ordering problems - -The idea is simple: - -1. When you investigate a bad response, capture: - - user task and request - - route or provider combo in OmniRoute - - any RAG context used downstream (retrieved documents, tool calls, etc) -2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` โ€ฆ `No.16`). -3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. -4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. - -Full text and concrete recipes live here (MIT license, text only): - -[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) - -You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. - ---- - -## Still Stuck? - -- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details -- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints -- **Health Dashboard**: Check **Dashboard โ†’ Health** for real-time system status -- **Translator**: Use **Dashboard โ†’ Translator** to debug format issues diff --git a/docs/i18n/phi/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/phi/VM_DEPLOYMENT_GUIDE.md deleted file mode 100644 index b7ac46710e..0000000000 --- a/docs/i18n/phi/VM_DEPLOYMENT_GUIDE.md +++ /dev/null @@ -1,401 +0,0 @@ -# OmniRoute โ€” Gabay sa Deployment sa VM gamit ang Cloudflare - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](../pt-BR/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](../es/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](../fr/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](../it/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](../ru/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](../zh-CN/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](../de/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](../in/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](../th/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](../uk-UA/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](../ar/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](../ja/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](../vi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](../bg/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](../da/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](../fi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](../he/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](../hu/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](../id/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](../ko/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](../ms/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](../nl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](../no/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](../pt/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](../ro/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](../pl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](../sk/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](../sv/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](../phi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](../cs/VM_DEPLOYMENT_GUIDE.md) - -Kumpletong gabay sa pag-install at pag-configure ng OmniRoute sa isang VM (VPS) na may domain na pinamamahalaan sa pamamagitan ng Cloudflare. - ---- - -## Mga kinakailangan - -| aytem | Pinakamababa | Inirerekomenda | -| ---------- | -------------------------- | ---------------- | -| **CPU** | 1 vCPU | 2 vCPU | -| **RAM** | 1 GB | 2 GB | -| **Disk** | 10 GB SSD | 25 GB SSD | -| **OS** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS | -| **Domain** | Nakarehistro sa Cloudflare | โ€” | -| **Docker** | Docker Engine 24+ | Docker 27+ | - -**Mga nasubok na provider**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. - ---- - -## 1. I-configure ang VM - -### 1.1 Lumikha ng instance - -Sa iyong gustong VPS provider: - -- Piliin ang Ubuntu 24.04 LTS -- Piliin ang minimum na plano (1 vCPU / 1 GB RAM) -- Magtakda ng malakas na root password o i-configure ang SSH key -- Tandaan ang **pampublikong IP** (hal., `203.0.113.10`) - -### 1.2 Kumonekta sa pamamagitan ng SSH - -```bash -ssh root@203.0.113.10 -``` - -### 1.3 I-update ang system - -```bash -apt update && apt upgrade -y -``` - -### 1.4 I-install ang Docker - -```bash -# Install dependencies -apt install -y ca-certificates curl gnupg - -# Add official Docker repository -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 I-install ang nginx - -```bash -apt install -y nginx -``` - -### 1.6 I-configure ang 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 -``` - -> **Tip**: Para sa maximum na seguridad, paghigpitan ang mga port 80 at 443 sa mga Cloudflare IP lamang. Tingnan ang seksyong [Advanced Security](#advanced-security). - ---- - -## 2. I-install ang OmniRoute - -### 2.1 Lumikha ng direktoryo ng pagsasaayos - -```bash -mkdir -p /opt/omniroute -``` - -### 2.2 Lumikha ng file ng mga variable ng kapaligiran - -```bash -cat > /opt/omniroute/.env << โ€˜EOFโ€™ -# === Security === -JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY -INITIAL_PASSWORD=YourSecurePassword123! -API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY -STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY -STORAGE_ENCRYPTION_KEY_VERSION=v1 -MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT - -# === 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 (change to your domain) === -BASE_URL=https://llms.seudominio.com -NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com - -# === Cloud Sync (optional) === -# CLOUD_URL=https://cloud.omniroute.online -# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online -EOF -``` - -> โš ๏ธ **MAHALAGA**: Bumuo ng mga natatanging lihim na key! Gamitin ang `openssl rand -hex 32` para sa bawat key. - -### 2.3 Simulan ang lalagyan - -```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 I-verify na ito ay tumatakbo - -```bash -docker ps | grep omniroute -docker logs omniroute --tail 20 -``` - -Dapat itong magpakita ng: `[DB] SQLite database ready` at `listening on port 20128`. - ---- - -## 3. I-configure ang nginx (Reverse Proxy) - -### 3.1 Bumuo ng SSL certificate (Cloudflare Origin) - -Sa dashboard ng Cloudflare: - -1. Pumunta sa **SSL/TLS โ†’ Origin Server** -2. I-click ang **Gumawa ng Sertipiko** -3. Panatilihin ang mga default (15 taon, \*.yourdomain.com) -4. Kopyahin ang **Origin Certificate** at ang **Private Key** - -```bash -mkdir -p /etc/nginx/ssl - -# Paste the certificate -nano /etc/nginx/ssl/origin.crt - -# Paste the private key -nano /etc/nginx/ssl/origin.key - -chmod 600 /etc/nginx/ssl/origin.key -``` - -### 3.2 Configuration ng Nginx - -```bash -cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ -# Default server โ€” blocks direct access via 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.yourdomain.com; # Change to your domain - - 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.yourdomain.com; - return 301 https://$server_name$request_uri; -} -NGINX -``` - -### 3.3 Paganahin at Pagsubok - -```bash -# Remove default configuration -rm -f /etc/nginx/sites-enabled/default - -# Enable OmniRoute -ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute - -# Test and reload -nginx -t && systemctl reload nginx -``` - ---- - -## 4. I-configure ang Cloudflare DNS - -### 4.1 Magdagdag ng DNS record - -Sa Cloudflare dashboard โ†’ DNS: - -| Uri | Pangalan | Nilalaman | Proxy | -| ----- | -------- | ---------------------- | ---------- | -| Isang | `llms` | `203.0.113.10` (VM IP) | โœ… Proxied | - -### 4.2 I-configure ang SSL - -Sa ilalim ng **SSL/TLS โ†’ Pangkalahatang-ideya**: - -- Mode: **Buong (Mahigpit)** - -Sa ilalim ng **SSL/TLS โ†’ Edge Certificates**: - -- Palaging Gumamit ng HTTPS: โœ… Naka-on -- Minimum na Bersyon ng TLS: TLS 1.2 -- Mga Awtomatikong HTTPS Rewrite: โœ… Naka-on - -### 4.3 Pagsubok - -```bash -curl -sI https://llms.seudominio.com/health -# Should return HTTP/2 200 -``` - ---- - -## 5. Mga Operasyon at Pagpapanatili - -### Mag-upgrade sa bagong bersyon - -```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 -``` - -### Tingnan ang mga log - -```bash -docker logs -f omniroute # Real-time stream -docker logs omniroute --tail 50 # Last 50 lines -``` - -### Manu-manong backup ng database - -```bash -# Copy data from the volume to the host -docker cp omniroute:/app/data ./backup-$(date +%F) - -# Or compress the entire volume -docker run --rm -v omniroute-data:/data -v $(pwd):/backup \ - alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data -``` - -### Ibalik mula sa 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. Advanced na Seguridad - -### Limitahan ang nginx sa mga Cloudflare IP - -```bash -cat > /etc/nginx/cloudflare-ips.conf << โ€˜CFโ€™ -# Cloudflare IPv4 ranges โ€” update periodically -# 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 -``` - -Idagdag ang sumusunod sa `nginx.conf` sa loob ng `http {}` block: - -```nginx -include /etc/nginx/cloudflare-ips.conf; -``` - -### I-install ang fail2ban - -```bash -apt install -y fail2ban -systemctl enable fail2ban -systemctl start fail2ban - -# Check status -fail2ban-client status sshd -``` - -### I-block ang direktang access sa Docker port - -```bash -# Prevent direct external access to port 20128 -iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP -iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT - -# Persist the rules -apt install -y iptables-persistent -netfilter-persistent save -``` - ---- - -## 7. I-deploy sa Cloudflare Workers (Opsyonal) - -Para sa malayuang pag-access sa pamamagitan ng Cloudflare Workers (nang hindi direktang inilalantad ang VM): - -```bash -# In the local repository -cd omnirouteCloud -npm install -npx wrangler login -npx wrangler deploy -``` - -Tingnan ang buong dokumentasyon sa [omnirouteCloud/README.md](../omnirouteCloud/README.md). - ---- - -## Buod ng Port - -| Port | Serbisyo | Access | -| ----- | ----------- | ---------------------------------------- | -| 22 | SSH | Pampubliko (na may fail2ban) | -| 80 | nginx HTTP | I-redirect โ†’ HTTPS | -| 443 | nginx HTTPS | Sa pamamagitan ng Cloudflare Proxy | -| 20128 | OmniRoute | Localhost lang (sa pamamagitan ng nginx) | diff --git a/docs/i18n/phi/docs/A2A-SERVER.md b/docs/i18n/phi/docs/A2A-SERVER.md new file mode 100644 index 0000000000..5cbe349f85 --- /dev/null +++ b/docs/i18n/phi/docs/A2A-SERVER.md @@ -0,0 +1,200 @@ +# OmniRoute A2A Server Documentation (Filipino) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/A2A-SERVER.md) + +--- + +> Agent-to-Agent Protocol v0.3 โ€” OmniRoute as an intelligent routing agent + +## Agent Discovery + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements. + +--- + +## Authentication + +All `/a2a` requests require an API key via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server, authentication is bypassed. + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Sends a message to a skill and waits for the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a hello world in Python"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "uuid", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "..." }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}} + +: heartbeat 2026-03-03T17:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Available Skills + +| Skill | Description | +| :----------------- | :------------------------------------------------------------------------------------------------------------------------------ | +| `smart-routing` | Routes prompts through OmniRoute's intelligent pipeline. Returns response with routing explanation, cost, and resilience trace. | +| `quota-management` | Answers natural-language queries about provider quotas, suggests free combos, and provides quota rankings. | + +--- + +## Task Lifecycle + +``` +submitted โ†’ working โ†’ completed + โ†’ failed + โ†’ cancelled +``` + +- Tasks expire after 5 minutes (configurable) +- Terminal states: `completed`, `failed`, `cancelled` +- Event log tracks every state transition + +--- + +## Error Codes + +| Code | Meaning | +| :----- | :----------------------------- | +| -32700 | Parse error (invalid JSON) | +| -32600 | Invalid request / Unauthorized | +| -32601 | Method or skill not found | +| -32602 | Invalid params | +| -32603 | Internal error | + +--- + +## Integration Examples + +### Python (requests) + +```python +import requests + +resp = requests.post("http://localhost:20128/a2a", json={ + "jsonrpc": "2.0", "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Hello"}] + } +}, headers={"Authorization": "Bearer YOUR_KEY"}) + +result = resp.json()["result"] +print(result["artifacts"][0]["content"]) +print(result["metadata"]["routing_explanation"]) +``` + +### TypeScript (fetch) + +```typescript +const resp = await fetch("http://localhost:20128/a2a", { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: "Bearer YOUR_KEY", + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "1", + method: "message/send", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Hello" }], + }, + }), +}); +const { result } = await resp.json(); +console.log(result.metadata.routing_explanation); +``` diff --git a/docs/i18n/phi/docs/API_REFERENCE.md b/docs/i18n/phi/docs/API_REFERENCE.md new file mode 100644 index 0000000000..baca9640a9 --- /dev/null +++ b/docs/i18n/phi/docs/API_REFERENCE.md @@ -0,0 +1,465 @@ +# API Reference (Filipino) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/API_REFERENCE.md) + +--- + +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 | +| `X-Session-Id` | Request | Sticky session key for external session affinity | +| `x_session_id` | Request | Underscore variant also accepted (direct HTTP) | +| `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 | +| `X-OmniRoute-Session-Id` | Response | Effective session ID used by OmniRoute | + +> Nginx note: if you rely on underscore headers (for example `x_session_id`), enable `underscores_in_headers 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/stats + +# Clear all caches +DELETE /api/cache/stats +``` + +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/PATCH | 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 + provider summary (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`) | +| `/api/cache/stats` | 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 | + +### Tunnels + +| Endpoint | Method | Description | +| -------------------------- | ------ | ----------------------------------------------------------------------- | +| `/api/tunnels/cloudflared` | GET | Read Cloudflare Quick Tunnel install/runtime status for the dashboard | +| `/api/tunnels/cloudflared` | POST | Enable or disable the Cloudflare Quick Tunnel (`action=enable/disable`) | + +### 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`. + +### ACP Agents + +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | + +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). + +### Resilience & Rate Limits + +| Endpoint | Method | Description | +| ----------------------- | --------- | ------------------------------- | +| `/api/resilience` | GET/PATCH | 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` diff --git a/docs/i18n/phi/docs/ARCHITECTURE.md b/docs/i18n/phi/docs/ARCHITECTURE.md new file mode 100644 index 0000000000..4cb30f7ff3 --- /dev/null +++ b/docs/i18n/phi/docs/ARCHITECTURE.md @@ -0,0 +1,814 @@ +# OmniRoute Architecture (Filipino) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/ARCHITECTURE.md) + +--- + +_Last updated: 2026-03-28_ + +## 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 (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developerโ†’system, systemโ†’user) for cross-provider compatibility +- Structured output conversion (json_schema โ†’ Gemini responseSchema) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) +- Global system prompt injection +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout โ†’ budget โ†’ fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) + +Primary runtime model: + +- Next.js 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.) + +## Dashboard Surface (Current) + +Main pages under `src/app/(dashboard)/dashboard/`: + +- `/dashboard` โ€” quick start + provider overview +- `/dashboard/endpoint` โ€” endpoint proxy + MCP + A2A + API endpoint tabs +- `/dashboard/providers` โ€” provider connections and credentials +- `/dashboard/combos` โ€” combo strategies, templates, model routing rules +- `/dashboard/costs` โ€” cost aggregation and pricing visibility +- `/dashboard/analytics` โ€” usage analytics and evaluations +- `/dashboard/limits` โ€” quota/rate controls +- `/dashboard/cli-tools` โ€” CLI onboarding, runtime detection, config generation +- `/dashboard/agents` โ€” detected ACP agents + custom agent registration +- `/dashboard/media` โ€” image/video/music playground +- `/dashboard/search-tools` โ€” search provider testing and history +- `/dashboard/health` โ€” uptime, circuit breakers, rate limits +- `/dashboard/logs` โ€” request/proxy/audit/console logs +- `/dashboard/settings` โ€” system settings tabs (general, routing, combo defaults, etc.) +- `/dashboard/api-manager` โ€” API key lifecycle and model permissions + +## 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[(storage.sqlite)] + UDB[(usage tables + log artifacts)] + end + + subgraph Upstreams[Upstream Providers] + P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/Qoder/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/route.ts` (GET) +- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- OAuth: `src/app/api/oauth/*` +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` +- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI tooling helpers: `src/app/api/cli-tools/*` +- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) +- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) โ€” provider profiles, circuit breaker, rate limit state +- Resilience reset: `src/app/api/resilience/reset` (POST) โ€” reset breakers + cooldowns +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) +- Telemetry: `src/app/api/telemetry/summary` (GET) +- Budget: `src/app/api/usage/budget` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Policies: `src/app/api/policies` (GET/POST) + +## 2) SSE + 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` +- Response sanitization: `open-sse/handlers/responseSanitizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.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`, `qoder.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 (SQLite): + +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** + +Usage persistence: + +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present + +Domain State DB (SQLite): + +- `src/lib/db/domainState.ts` โ€” CRUD operations 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`, `src/shared/services/modelSyncScheduler.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Periodic task: `src/shared/services/modelSyncScheduler.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. Combo routing adds one extra guard: provider-scoped 400s such as upstream content-block and role-validation failures are treated as model-local failures so later combo targets can still run. + +## 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: + +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` + +## Deployment Topology + +```mermaid +flowchart LR + 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[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] + end + + subgraph External[External Services] + Providers[AI Providers] + SyncCloud[Cloud Sync Service] + end + + CLI --> Next + Browser --> Next + Next --> Core + Next --> MainDB + Core --> MainDB + Core --> UsageDB + Core --> Providers + Next --> SyncCloud +``` + +## Module Mapping (Decision-Critical) + +### Route and API Modules + +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle +- `src/app/api/models/alias`: alias management +- `src/app/api/combos*`: fallback combo management +- `src/app/api/pricing`: pricing overrides for cost calculation +- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers +- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) +- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) +- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) +- `src/app/api/sessions`: active session listing (GET) +- `src/app/api/rate-limits`: per-account rate limit status (GET) + +### Routing and Execution Core + +- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior + +### Translation Registry and Format Converters + +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` +- Format constants: `open-sse/translator/formats.ts` + +### Persistence + +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables + +## Provider Executor Coverage (Strategy Pattern) + +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. + +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, Qoder, 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 | +| Qoder | openai | OAuth (Basic) | โœ… | โœ… | โœ… | โš ๏ธ Per request | +| OpenRouter | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| GLM/Kimi/MiniMax | claude | API Key | โœ… | โœ… | โŒ | โŒ | +| DeepSeek | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Groq | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| xAI (Grok) | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Mistral | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Perplexity | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Together AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Fireworks AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Cerebras | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Cohere | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| NVIDIA NIM | openai | API Key | โœ… | โœ… | โŒ | โŒ | + +## Format Translation Coverage + +Detected source formats include: + +- `openai` +- `openai-responses` +- `claude` +- `gemini` + +Target formats include: + +- OpenAI chat/Responses +- Claude +- Gemini/Gemini-CLI/Antigravity envelope +- Kiro +- Cursor + +Translations use **OpenAI as the hub format** โ€” all conversions go through OpenAI as intermediate: + +``` +Source Format โ†’ OpenAI (hub) โ†’ Target Format +``` + +Translations are selected dynamically based on source payload shape and provider target format. + +Additional processing layers in the translation pipeline: + +- **Response sanitization** โ€” Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI targets; merges `system` โ†’ `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** โ€” Parses `...` blocks from content into `reasoning_content` field +- **Structured output** โ€” Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` + +## Supported API Endpoints + +| 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` | Provider Models | Provider model metadata backing custom and managed available models | + +## 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 `/logs//` 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 + +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON โ†’ SQLite migration compatibility path + +## Observability and Operational Signals + +Runtime visibility sources: + +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- four-stage detailed payload captures in SQLite (`request_detail_logs`) when `settings.detailed_logs_enabled=true` +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption + +Detailed request payload capture stores up to four JSON payload stages per routed call: + +- raw request received from the client +- translated request actually sent upstream +- provider response reconstructed as JSON; streamed responses are compacted to the final summary plus stream metadata +- final client response returned by OmniRoute; streamed responses are stored in the same compact summary form + +## Security-Sensitive Boundaries + +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics + +## Environment and Runtime Matrix + +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` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). + +## Operational Verification Checklist + +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: +- `GET /api/settings` +- `GET /api/v1/models` +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/phi/docs/AUTO-COMBO.md b/docs/i18n/phi/docs/AUTO-COMBO.md new file mode 100644 index 0000000000..dd41888c65 --- /dev/null +++ b/docs/i18n/phi/docs/AUTO-COMBO.md @@ -0,0 +1,67 @@ +# OmniRoute Auto-Combo Engine (Filipino) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/AUTO-COMBO.md) + +--- + +> Self-managing model chains with adaptive scoring + +## How It Works + +The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**: + +| Factor | Weight | Description | +| :--------- | :----- | :---------------------------------------------- | +| Quota | 0.20 | Remaining capacity [0..1] | +| Health | 0.25 | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 | +| CostInv | 0.20 | Inverse cost (cheaper = higher score) | +| LatencyInv | 0.15 | Inverse p95 latency (faster = higher) | +| TaskFit | 0.10 | Model ร— task type fitness score | +| Stability | 0.10 | Low variance in latency/errors | + +## Mode Packs + +| Pack | Focus | Key Weight | +| :---------------------- | :----------- | :--------------- | +| ๐Ÿš€ **Ship Fast** | Speed | latencyInv: 0.35 | +| ๐Ÿ’ฐ **Cost Saver** | Economy | costInv: 0.40 | +| ๐ŸŽฏ **Quality First** | Best model | taskFit: 0.40 | +| ๐Ÿ“ก **Offline Friendly** | Availability | quota: 0.40 | + +## Self-Healing + +- **Temporary exclusion**: Score < 0.2 โ†’ excluded for 5 min (progressive backoff, max 30 min) +- **Circuit breaker awareness**: OPEN โ†’ auto-excluded; HALF_OPEN โ†’ probe requests +- **Incident mode**: >50% OPEN โ†’ disable exploration, maximize stability +- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout + +## Bandit Exploration + +5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode. + +## API + +```bash +# Create auto-combo +curl -X POST http://localhost:20128/api/combos/auto \ + -H "Content-Type: application/json" \ + -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}' + +# List auto-combos +curl http://localhost:20128/api/combos/auto +``` + +## Task Fitness + +30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` โ†’ high coding score). + +## Files + +| File | Purpose | +| :------------------------------------------- | :------------------------------------ | +| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization | +| `open-sse/services/autoCombo/taskFitness.ts` | Model ร— task fitness lookup | +| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap | +| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode | +| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles | +| `src/app/api/combos/auto/route.ts` | REST API | diff --git a/docs/i18n/phi/docs/CLI-TOOLS.md b/docs/i18n/phi/docs/CLI-TOOLS.md new file mode 100644 index 0000000000..ad736dcb36 --- /dev/null +++ b/docs/i18n/phi/docs/CLI-TOOLS.md @@ -0,0 +1,348 @@ +# CLI Tools Setup Guide โ€” OmniRoute (Filipino) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CLI-TOOLS.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CLI-TOOLS.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CLI-TOOLS.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CLI-TOOLS.md) + +--- + +This guide explains how to install and configure all supported AI coding CLI tools +to use **OmniRoute** as the unified backend, giving you centralized key management, +cost tracking, model switching, and request logging across every tool. + +--- + +## How It Works + +``` +Claude / Codex / OpenCode / Cline / KiloCode / Continue / Kiro / Cursor / Copilot + โ”‚ + โ–ผ (all point to OmniRoute) + http://YOUR_SERVER:20128/v1 + โ”‚ + โ–ผ (OmniRoute routes to the right provider) + Anthropic / OpenAI / Gemini / DeepSeek / Groq / Mistral / ... +``` + +**Benefits:** + +- One API key to manage all tools +- Cost tracking across all CLIs in the dashboard +- Model switching without reconfiguring every tool +- Works locally and on remote servers (VPS) + +--- + +## Supported Tools (Dashboard Source of Truth) + +The dashboard cards in `/dashboard/cli-tools` are generated from `src/shared/constants/cliTools.ts`. +Current list (v3.0.0-rc.16): + +| Tool | ID | Command | Setup Mode | Install Method | +| ------------------ | ------------- | ---------- | ---------- | -------------- | +| **Claude Code** | `claude` | `claude` | env | npm | +| **OpenAI Codex** | `codex` | `codex` | custom | npm | +| **Factory Droid** | `droid` | `droid` | custom | bundled/CLI | +| **OpenClaw** | `openclaw` | `openclaw` | custom | bundled/CLI | +| **Cursor** | `cursor` | app | guide | desktop app | +| **Cline** | `cline` | `cline` | custom | npm | +| **Kilo Code** | `kilo` | `kilocode` | custom | npm | +| **Continue** | `continue` | extension | guide | VS Code | +| **Antigravity** | `antigravity` | internal | mitm | OmniRoute | +| **GitHub Copilot** | `copilot` | extension | custom | VS Code | +| **OpenCode** | `opencode` | `opencode` | guide | npm | +| **Kiro AI** | `kiro` | app/cli | mitm | desktop/CLI | + +### CLI fingerprint sync (Agents + Settings) + +`/dashboard/agents` and `Settings > CLI Fingerprint` use `src/shared/constants/cliCompatProviders.ts`. +This keeps provider IDs aligned with CLI cards and legacy IDs. + +| CLI ID | Fingerprint Provider ID | +| ---------------------------------------------------------------------------------------------------- | ----------------------- | +| `kilo` | `kilocode` | +| `copilot` | `github` | +| `claude` / `codex` / `antigravity` / `kiro` / `cursor` / `cline` / `opencode` / `droid` / `openclaw` | same ID | + +Legacy IDs still accepted for compatibility: `copilot`, `kimi-coding`, `qwen`. + +--- + +## Step 1 โ€” Get an OmniRoute API Key + +1. Open the OmniRoute dashboard โ†’ **API Manager** (`/dashboard/api-manager`) +2. Click **Create API Key** +3. Give it a name (e.g. `cli-tools`) and select all permissions +4. Copy the key โ€” you'll need it for every CLI below + +> Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` + +--- + +## Step 2 โ€” Install CLI Tools + +All npm-based tools require Node.js 18+: + +```bash +# Claude Code (Anthropic) +npm install -g @anthropic-ai/claude-code + +# OpenAI Codex +npm install -g @openai/codex + +# OpenCode +npm install -g opencode-ai + +# Cline +npm install -g cline + +# KiloCode +npm install -g kilocode + +# Kiro CLI (Amazon โ€” requires curl + unzip) +apt-get install -y unzip # on Debian/Ubuntu +curl -fsSL https://cli.kiro.dev/install | bash +export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc +``` + +**Verify:** + +```bash +claude --version # 2.x.x +codex --version # 0.x.x +opencode --version # x.x.x +cline --version # 2.x.x +kilocode --version # x.x.x (or: kilo --version) +kiro-cli --version # 1.x.x +``` + +--- + +## Step 3 โ€” Set Global Environment Variables + +Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`: + +```bash +# OmniRoute Universal Endpoint +export OPENAI_BASE_URL="http://localhost:20128/v1" +export OPENAI_API_KEY="sk-your-omniroute-key" +export ANTHROPIC_BASE_URL="http://localhost:20128/v1" +export ANTHROPIC_API_KEY="sk-your-omniroute-key" +export GEMINI_BASE_URL="http://localhost:20128/v1" +export GEMINI_API_KEY="sk-your-omniroute-key" +``` + +> For a **remote server** replace `localhost:20128` with the server IP or domain, +> e.g. `http://192.168.0.15:20128`. + +--- + +## Step 4 โ€” Configure Each Tool + +### Claude Code + +```bash +# Via CLI: +claude config set --global api-base-url http://localhost:20128/v1 + +# Or create ~/.claude/settings.json: +mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF +{ + "apiBaseUrl": "http://localhost:20128/v1", + "apiKey": "sk-your-omniroute-key" +} +EOF +``` + +**Test:** `claude "say hello"` + +--- + +### OpenAI Codex + +```bash +mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF +model: auto +apiKey: sk-your-omniroute-key +apiBaseUrl: http://localhost:20128/v1 +EOF +``` + +**Test:** `codex "what is 2+2?"` + +--- + +### OpenCode + +```bash +mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF +[provider.openai] +base_url = "http://localhost:20128/v1" +api_key = "sk-your-omniroute-key" +EOF +``` + +**Test:** `opencode` + +--- + +### Cline (CLI or VS Code) + +**CLI mode:** + +```bash +mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF +{ + "apiProvider": "openai", + "openAiBaseUrl": "http://localhost:20128/v1", + "openAiApiKey": "sk-your-omniroute-key" +} +EOF +``` + +**VS Code mode:** +Cline extension settings โ†’ API Provider: `OpenAI Compatible` โ†’ Base URL: `http://localhost:20128/v1` + +Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ Cline โ†’ Apply Config**. + +--- + +### KiloCode (CLI or VS Code) + +**CLI mode:** + +```bash +kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key +``` + +**VS Code settings:** + +```json +{ + "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", + "kilo-code.apiKey": "sk-your-omniroute-key" +} +``` + +Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ KiloCode โ†’ Apply Config**. + +--- + +### Continue (VS Code Extension) + +Edit `~/.continue/config.yaml`: + +```yaml +models: + - name: OmniRoute + provider: openai + model: auto + apiBase: http://localhost:20128/v1 + apiKey: sk-your-omniroute-key + default: true +``` + +Restart VS Code after editing. + +--- + +### Kiro CLI (Amazon) + +```bash +# Login to your AWS/Kiro account: +kiro-cli login + +# The CLI uses its own auth โ€” OmniRoute is not needed as backend for Kiro CLI itself. +# Use kiro-cli alongside OmniRoute for other tools. +kiro-cli status +``` + +--- + +### Cursor (Desktop App) + +> **Note:** Cursor routes requests through its cloud. For OmniRoute integration, +> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL. + +Via GUI: **Settings โ†’ Models โ†’ OpenAI API Key** + +- Base URL: `https://your-domain.com/v1` +- API Key: your OmniRoute key + +--- + +## Dashboard Auto-Configuration + +The OmniRoute dashboard automates configuration for most tools: + +1. Go to `http://localhost:20128/dashboard/cli-tools` +2. Expand any tool card +3. Select your API key from the dropdown +4. Click **Apply Config** (if tool is detected as installed) +5. Or copy the generated config snippet manually + +--- + +## Built-in Agents: Droid & OpenClaw + +**Droid** and **OpenClaw** are AI agents built directly into OmniRoute โ€” no installation needed. +They run as internal routes and use OmniRoute's model routing automatically. + +- Access: `http://localhost:20128/dashboard/agents` +- Configure: same combos and providers as all other tools +- No API key or CLI install required + +--- + +## Available API Endpoints + +| Endpoint | Description | Use For | +| -------------------------- | ----------------------------- | --------------------------- | +| `/v1/chat/completions` | Standard chat (all providers) | All modern tools | +| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows | +| `/v1/completions` | Legacy text completions | Older tools using `prompt:` | +| `/v1/embeddings` | Text embeddings | RAG, search | +| `/v1/images/generations` | Image generation | DALL-E, Flux, etc. | +| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS | +| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI | + +--- + +## Pag-troubleshoot + +| Error | Cause | Fix | +| ------------------------- | ----------------------- | ------------------------------------------ | +| `Connection refused` | OmniRoute not running | `pm2 start omniroute` | +| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` | +| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` | +| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` | +| CLI shows "not installed" | Binary not in PATH | Check `which ` | +| `kiro-cli: not found` | Not in PATH | `export PATH="$HOME/.local/bin:$PATH"` | + +--- + +## Quick Setup Script (One Command) + +```bash +# Install all CLIs and configure for OmniRoute (replace with your key and server URL) +OMNIROUTE_URL="http://localhost:20128/v1" +OMNIROUTE_KEY="sk-your-omniroute-key" + +npm install -g @anthropic-ai/claude-code @openai/codex opencode-ai cline kilocode + +# Kiro CLI +apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash + +# Write configs +mkdir -p ~/.claude ~/.codex ~/.config/opencode ~/.continue + +cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" +cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" +cat >> ~/.bashrc << EOF +export OPENAI_BASE_URL="$OMNIROUTE_URL" +export OPENAI_API_KEY="$OMNIROUTE_KEY" +export ANTHROPIC_BASE_URL="$OMNIROUTE_URL" +export ANTHROPIC_API_KEY="$OMNIROUTE_KEY" +EOF + +source ~/.bashrc +echo "โœ… All CLIs installed and configured for OmniRoute" +``` diff --git a/docs/i18n/phi/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/phi/docs/CODEBASE_DOCUMENTATION.md new file mode 100644 index 0000000000..cf1dfd94df --- /dev/null +++ b/docs/i18n/phi/docs/CODEBASE_DOCUMENTATION.md @@ -0,0 +1,591 @@ +# omniroute โ€” Codebase Documentation (Filipino) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CODEBASE_DOCUMENTATION.md) + +--- + +> 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
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, Qoder, 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. + +#### Arkitektura + +```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 | +| Qoder | 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"] +``` diff --git a/docs/i18n/phi/docs/COVERAGE_PLAN.md b/docs/i18n/phi/docs/COVERAGE_PLAN.md new file mode 100644 index 0000000000..22229c030b --- /dev/null +++ b/docs/i18n/phi/docs/COVERAGE_PLAN.md @@ -0,0 +1,170 @@ +# Test Coverage Plan (Filipino) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/COVERAGE_PLAN.md) + +--- + +Last updated: 2026-03-28 + +## Baseline + +There are multiple coverage numbers depending on how the report is computed. For planning, only one of them is useful. + +| Metric | Scope | Statements / Lines | Branches | Functions | Notes | +| -------------------- | ----------------------------------------------------- | -----------------: | -------: | --------: | --------------------------------------------------- | +| Legacy | Old `npm run test:coverage` | 79.42% | 75.15% | 67.94% | Inflated: counts test files and excludes `open-sse` | +| Diagnostic | Source-only, excluding tests and excluding `open-sse` | 68.16% | 63.55% | 64.06% | Useful only to isolate `src/**` | +| Recommended baseline | Source-only, excluding tests and including `open-sse` | 56.95% | 66.05% | 57.80% | This is the project-wide baseline to improve | + +The recommended baseline is the number to optimize against. + +## Rules + +- Coverage targets apply to source files, not to `tests/**`. +- `open-sse/**` is part of the product and must remain in scope. +- New code should not reduce coverage in touched areas. +- Prefer testing behavior and branch outcomes over implementation details. +- Prefer temp SQLite databases and small fixtures over broad mocks for `src/lib/db/**`. + +## Current command set + +- `npm run test:coverage` + - Main source coverage gate for the unit test suite + - Generates `text-summary`, `html`, `json-summary`, and `lcov` +- `npm run coverage:report` + - Detailed file-by-file report from the latest run +- `npm run test:coverage:legacy` + - Historical comparison only + +## Milestones + +| Phase | Target | Focus | +| ------- | ---------------------: | ------------------------------------------------- | +| Phase 1 | 60% statements / lines | Quick wins and low-risk utility coverage | +| Phase 2 | 65% statements / lines | DB and route foundations | +| Phase 3 | 70% statements / lines | Provider validation and usage analytics | +| Phase 4 | 75% statements / lines | `open-sse` translators and helpers | +| Phase 5 | 80% statements / lines | `open-sse` handlers and executor branches | +| Phase 6 | 85% statements / lines | Harder edge cases, branch debt, regression suites | +| Phase 7 | 90% statements / lines | Final sweep, gap closure, strict ratchet | + +Branches and functions should ratchet upward with each phase, but the primary hard target is statements / lines. + +## Priority hotspots + +These files or areas offer the best return for the next phases: + +1. `open-sse/handlers` + - `chatCore.ts` at 7.57% + - Overall directory at 29.07% +2. `open-sse/translator/request` + - Overall directory at 36.39% + - Many translators are still near single-digit coverage +3. `open-sse/translator/response` + - Overall directory at 8.07% +4. `open-sse/executors` + - Overall directory at 36.62% +5. `src/lib/db` + - `models.ts` at 20.66% + - `registeredKeys.ts` at 34.46% + - `modelComboMappings.ts` at 36.25% + - `settings.ts` at 46.40% + - `webhooks.ts` at 33.33% +6. `src/lib/usage` + - `usageHistory.ts` at 21.12% + - `usageStats.ts` at 9.56% + - `costCalculator.ts` at 30.00% +7. `src/lib/providers` + - `validation.ts` at 41.16% +8. Low-risk utility and API files for early gains + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/api/errorResponse.ts` + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +## Execution checklist + +### Phase 1: 56.95% -> 60% + +- [x] Fix coverage metric so it reflects source code instead of test files +- [x] Keep a legacy coverage script for comparison +- [x] Record the baseline and hotspots in-repo +- [ ] Add focused tests for low-risk utilities: + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/fetchTimeout.ts` + - `src/lib/api/errorResponse.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/display/names.ts` +- [ ] Add route tests for: + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +### Phase 2: 60% -> 65% + +- [ ] Add DB-backed tests for: + - `src/lib/db/modelComboMappings.ts` + - `src/lib/db/settings.ts` + - `src/lib/db/registeredKeys.ts` +- [ ] Cover branch behavior in: + - `src/lib/providers/validation.ts` + - `src/app/api/v1/embeddings/route.ts` + - `src/app/api/v1/moderations/route.ts` + +### Phase 3: 65% -> 70% + +- [ ] Add usage analytics tests for: + - `src/lib/usage/usageHistory.ts` + - `src/lib/usage/usageStats.ts` + - `src/lib/usage/costCalculator.ts` +- [ ] Expand route coverage for proxy management and settings branches + +### Phase 4: 70% -> 75% + +- [ ] Cover translator helpers and central translation paths: + - `open-sse/translator/index.ts` + - `open-sse/translator/helpers/*` + - `open-sse/translator/request/*` + - `open-sse/translator/response/*` + +### Phase 5: 75% -> 80% + +- [ ] Add handler-level tests for: + - `open-sse/handlers/chatCore.ts` + - `open-sse/handlers/responsesHandler.js` + - `open-sse/handlers/imageGeneration.js` + - `open-sse/handlers/embeddings.js` +- [ ] Add executor branch coverage for provider-specific auth, retries, and endpoint overrides + +### Phase 6: 80% -> 85% + +- [ ] Merge more edge-case suites into the main coverage path +- [ ] Increase function coverage for DB modules with weak constructor/helper coverage +- [ ] Close branch gaps in `settings.ts`, `registeredKeys.ts`, `validation.ts`, and translator helpers + +### Phase 7: 85% -> 90% + +- [ ] Treat the remaining low-coverage files as blockers +- [ ] Add regression tests for every uncovered production bug fixed during the push to 90% +- [ ] Raise the coverage gate in CI only after the local baseline is stable for at least two consecutive runs + +## Ratchet policy + +Update `npm run test:coverage` thresholds only after the project actually exceeds the next milestone with a comfortable buffer. + +Recommended ratchet sequence: + +1. 55/60/55 +2. 60/62/58 +3. 65/64/62 +4. 70/66/66 +5. 75/70/72 +6. 80/75/78 +7. 85/80/84 +8. 90/85/88 + +Order is `statements-lines / branches / functions`. + +## Known gap + +The current coverage command measures the main Node unit suite and includes source reached from it, including `open-sse`. It does not yet merge Vitest coverage into a single unified report. That merge is worth doing later, but it is not a blocker for starting the 60% -> 80% climb. diff --git a/docs/i18n/phi/docs/FEATURES.md b/docs/i18n/phi/docs/FEATURES.md index c1b37a7b03..96460e693e 100644 --- a/docs/i18n/phi/docs/FEATURES.md +++ b/docs/i18n/phi/docs/FEATURES.md @@ -1,6 +1,6 @@ # OmniRoute โ€” Dashboard Features Gallery (Filipino) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/FEATURES.md) --- @@ -10,7 +10,7 @@ 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). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. ![Providers Dashboard](screenshots/01-providers.png) diff --git a/docs/i18n/phi/docs/MCP-SERVER.md b/docs/i18n/phi/docs/MCP-SERVER.md new file mode 100644 index 0000000000..662e23ebae --- /dev/null +++ b/docs/i18n/phi/docs/MCP-SERVER.md @@ -0,0 +1,87 @@ +# OmniRoute MCP Server Documentation (Filipino) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/MCP-SERVER.md) + +--- + +> Model Context Protocol server with 16 intelligent tools + +## I-install + +OmniRoute MCP is built-in. Start it with: + +```bash +omniroute --mcp +``` + +Or via the open-sse transport: + +```bash +# HTTP streamable transport (port 20130) +omniroute --dev # MCP auto-starts on /mcp endpoint +``` + +## IDE Configuration + +See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup. + +--- + +## Essential Tools (8) + +| Tool | Description | +| :------------------------------ | :--------------------------------------- | +| `omniroute_get_health` | Gateway health, circuit breakers, uptime | +| `omniroute_list_combos` | All configured combos with models | +| `omniroute_get_combo_metrics` | Performance metrics for a specific combo | +| `omniroute_switch_combo` | Switch active combo by ID/name | +| `omniroute_check_quota` | Quota status per provider or all | +| `omniroute_route_request` | Send a chat completion through OmniRoute | +| `omniroute_cost_report` | Cost analytics for a time period | +| `omniroute_list_models_catalog` | Full model catalog with capabilities | + +## Advanced Tools (8) + +| Tool | Description | +| :--------------------------------- | :---------------------------------------------------------- | +| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | +| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | +| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | +| `omniroute_test_combo` | Live-test all models in a combo via a real upstream request | +| `omniroute_get_provider_metrics` | Detailed metrics for one provider | +| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | +| `omniroute_explain_route` | Explain a past routing decision | +| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | + +## Authentication + +MCP tools are authenticated via API key scopes. Each tool requires specific scopes: + +| Scope | Tools | +| :------------- | :----------------------------------------------- | +| `read:health` | get_health, get_provider_metrics | +| `read:combos` | list_combos, get_combo_metrics | +| `write:combos` | switch_combo | +| `read:quota` | check_quota | +| `write:route` | route_request, simulate_route, test_combo | +| `read:usage` | cost_report, get_session_snapshot, explain_route | +| `write:config` | set_budget_guard, set_resilience_profile | +| `read:models` | list_models_catalog, best_combo_for_task | + +## Audit Logging + +Every tool call is logged to `mcp_tool_audit` with: + +- Tool name, arguments, result +- Duration (ms), success/failure +- API key hash, timestamp + +## Files + +| File | Purpose | +| :------------------------------------------- | :------------------------------------------ | +| `open-sse/mcp-server/server.ts` | MCP server creation + 16 tool registrations | +| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport | +| `open-sse/mcp-server/auth.ts` | API key + scope validation | +| `open-sse/mcp-server/audit.ts` | Tool call audit logging | +| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers | diff --git a/docs/i18n/phi/docs/RELEASE_CHECKLIST.md b/docs/i18n/phi/docs/RELEASE_CHECKLIST.md new file mode 100644 index 0000000000..35cfb32021 --- /dev/null +++ b/docs/i18n/phi/docs/RELEASE_CHECKLIST.md @@ -0,0 +1,37 @@ +# Release Checklist (Filipino) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/RELEASE_CHECKLIST.md) + +--- + +Use this checklist before tagging or publishing a new OmniRoute release. + +## Version and Changelog + +1. Bump `package.json` version (`x.y.z`) in the release branch. +2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: + - `## [x.y.z] โ€” YYYY-MM-DD` +3. Keep `## [Unreleased]` as the first changelog section for upcoming work. +4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. + +## API Docs + +1. Update `docs/openapi.yaml`: + - `info.version` must equal `package.json` version. +2. Validate endpoint examples if API contracts changed. + +## Runtime Docs + +1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. +2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. +3. Update localized docs if source docs changed significantly. + +## Automated Check + +Run the sync guard locally before opening PR: + +```bash +npm run check:docs-sync +``` + +CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/phi/docs/TROUBLESHOOTING.md b/docs/i18n/phi/docs/TROUBLESHOOTING.md new file mode 100644 index 0000000000..c926c13cd0 --- /dev/null +++ b/docs/i18n/phi/docs/TROUBLESHOOTING.md @@ -0,0 +1,256 @@ +# Troubleshooting (Filipino) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/TROUBLESHOOTING.md) + +--- + +Common problems and solutions for OmniRoute. + +--- + +## Quick Fixes + +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | + +--- + +## Provider Issues + +### "Language model did not provide messages" + +**Cause:** Provider quota exhausted. + +**Fix:** + +1. 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, Qoder) 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}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) + +--- + +## Circuit Breaker Issues + +### Provider stuck in OPEN state + +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. + +**Fix:** + +1. 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 +- **SDK returns raw string instead of object** โ€” Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** โ€” Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** โ€” Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** โ€” Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` + +--- + +## Resilience Settings + +### Auto rate-limit not triggering + +- 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. + +--- + +## Optional RAG / LLM failure taxonomy (16 problems) + +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` โ€ฆ `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard โ†’ Health** for real-time system status +- **Translator**: Use **Dashboard โ†’ Translator** to debug format issues diff --git a/docs/i18n/phi/USER_GUIDE.md b/docs/i18n/phi/docs/USER_GUIDE.md similarity index 82% rename from docs/i18n/phi/USER_GUIDE.md rename to docs/i18n/phi/docs/USER_GUIDE.md index ec3799bcb6..7f0e2ff071 100644 --- a/docs/i18n/phi/USER_GUIDE.md +++ b/docs/i18n/phi/docs/USER_GUIDE.md @@ -1,8 +1,6 @@ # User Guide (Filipino) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/USER_GUIDE.md) - -> ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/USER_GUIDE.md) --- @@ -320,7 +318,7 @@ Model: cc/claude-opus-4-6 --- -## ๐Ÿš€ Deployment +## Pag-deploy ### Global npm install (Recommended) @@ -511,23 +509,26 @@ post_install() { ### Environment Variables -| Variable | Default | Description | -| ------------------------- | ------------------------------------ | ------------------------------------------------------- | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | -| `INITIAL_PASSWORD` | `123456` | First login password | -| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | -| `PORT` | framework default | Service port (`20128` in examples) | -| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | -| `NODE_ENV` | runtime default | Set `production` for deploy | -| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | -| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | -| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | -| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | -| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | -| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | -| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | -| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | +| 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/*` | +| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand | +| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | For the full environment variable reference, see the [README](../README.md). @@ -598,6 +599,11 @@ curl -X POST http://localhost:20128/api/provider-models \ Or use Dashboard: **Providers โ†’ [Provider] โ†’ Custom Models**. +Notes: + +- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers. +- The **Custom Models** section is intended for providers that do not expose managed available-model imports. + ### Dedicated Provider Routes Route requests directly to a specific provider with model validation: @@ -642,6 +648,14 @@ Returns models grouped by provider with types (`chat`, `embedding`, `image`). - Automatic background sync with timeout + fail-fast - Prefer server-side `BASE_URL`/`CLOUD_URL` in production +### Cloudflare Quick Tunnel + +- Available in **Dashboard โ†’ Endpoints** for Docker and other self-hosted deployments +- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint +- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary +- Tunnel URLs are ephemeral and change every time you stop/start the tunnel +- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download + ### LLM Gateway Intelligence (Phase 9) - **Semantic Cache** โ€” Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) @@ -757,11 +771,11 @@ OmniRoute implements provider-level resilience with four components: 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 | +| 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 unless `DISABLE_SQLITE_AUTO_BACKUP=true` | ```bash # API: Export database @@ -787,10 +801,11 @@ curl -X POST http://localhost:20128/api/db-backups/import \ ### Settings Dashboard -The settings page is organized into 5 tabs for easy navigation: +The settings page is organized into 6 tabs for easy navigation: | Tab | Contents | | -------------- | ---------------------------------------------------------------------------------------------- | +| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility | | **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | | **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | | **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | diff --git a/docs/i18n/ms/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/phi/docs/VM_DEPLOYMENT_GUIDE.md similarity index 54% rename from docs/i18n/ms/VM_DEPLOYMENT_GUIDE.md rename to docs/i18n/phi/docs/VM_DEPLOYMENT_GUIDE.md index 8257f10e21..68aa5999d2 100644 --- a/docs/i18n/ms/VM_DEPLOYMENT_GUIDE.md +++ b/docs/i18n/phi/docs/VM_DEPLOYMENT_GUIDE.md @@ -1,50 +1,52 @@ -# OmniRoute โ€” Panduan Penggunaan pada VM dengan Cloudflare +# OmniRoute โ€” Deployment Guide on VM with Cloudflare (Filipino) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](../pt-BR/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](../es/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](../fr/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](../it/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](../ru/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](../zh-CN/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](../de/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](../in/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](../th/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](../uk-UA/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](../ar/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](../ja/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](../vi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](../bg/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](../da/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](../fi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](../he/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](../hu/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](../id/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](../ko/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](../ms/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](../nl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](../no/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](../pt/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](../ro/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](../pl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](../sk/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](../sv/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](../phi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](../cs/VM_DEPLOYMENT_GUIDE.md) - -Panduan lengkap untuk memasang dan mengkonfigurasi OmniRoute pada VM (VPS) dengan domain yang diuruskan melalui Cloudflare. +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/VM_DEPLOYMENT_GUIDE.md) --- -## Prasyarat - -| Item | Minimum | Disyorkan | -| ---------- | ----------------------- | ---------------- | -| **CPU** | 1 vCPU | 2 vCPU | -| **RAM** | 1 GB | 2 GB | -| **Cakera** | 10 GB SSD | 25 GB SSD | -| **OS** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS | -| **Domain** | Berdaftar di Cloudflare | โ€” | -| **Docker** | Enjin Docker 24+ | Docker 27+ | - -**Pembekal yang diuji**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. +Complete guide to install and configure OmniRoute on a VM (VPS) with domain managed via Cloudflare. --- -## 1. Konfigurasikan VM +## Prerequisites -### 1.1 Cipta contoh +| Item | Minimum | Recommended | +| ---------- | ------------------------ | ---------------- | +| **CPU** | 1 vCPU | 2 vCPU | +| **RAM** | 1 GB | 2 GB | +| **Disk** | 10 GB SSD | 25 GB SSD | +| **OS** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS | +| **Domain** | Registered on Cloudflare | โ€” | +| **Docker** | Docker Engine 24+ | Docker 27+ | -Pada pembekal VPS pilihan anda: +**Tested providers**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. -- Pilih Ubuntu 24.04 LTS -- Pilih pelan minimum (1 vCPU / 1 GB RAM) -- Tetapkan kata laluan akar yang kuat atau konfigurasikan kunci SSH -- Perhatikan **IP awam** (cth., `203.0.113.10`) +--- -### 1.2 Sambung melalui SSH +## 1. Configure the VM + +### 1.1 Create the instance + +On your preferred VPS provider: + +- Choose Ubuntu 24.04 LTS +- Select the minimum plan (1 vCPU / 1 GB RAM) +- Set a strong root password or configure SSH key +- Note the **public IP** (e.g., `203.0.113.10`) + +### 1.2 Connect via SSH ```bash ssh root@203.0.113.10 ``` -### 1.3 Kemas kini sistem +### 1.3 Update the system ```bash apt update && apt upgrade -y ``` -### 1.4 Pasang Docker +### 1.4 Install Docker ```bash # Install dependencies @@ -59,13 +61,13 @@ apt update apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin ``` -### 1.5 Pasang nginx +### 1.5 Install nginx ```bash apt install -y nginx ``` -### 1.6 Konfigurasi Firewall (UFW) +### 1.6 Configure Firewall (UFW) ```bash ufw default deny incoming @@ -76,19 +78,19 @@ ufw allow 443/tcp # HTTPS ufw enable ``` -> **Petua**: Untuk keselamatan maksimum, hadkan port 80 dan 443 kepada IP Cloudflare sahaja. Lihat bahagian [Advanced Security](#advanced-security). +> **Tip**: For maximum security, restrict ports 80 and 443 to Cloudflare IPs only. See the [Advanced Security](#advanced-security) section. --- -## 2. Pasang OmniRoute +## 2. Install OmniRoute -### 2.1 Cipta direktori konfigurasi +### 2.1 Create configuration directory ```bash mkdir -p /opt/omniroute ``` -### 2.2 Cipta fail pembolehubah persekitaran +### 2.2 Create environment variables file ```bash cat > /opt/omniroute/.env << โ€˜EOFโ€™ @@ -120,9 +122,9 @@ NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com EOF ``` -> โš ๏ธ **PENTING**: Jana kunci rahsia unik! Gunakan `openssl rand -hex 32` untuk setiap kunci. +> โš ๏ธ **IMPORTANT**: Generate unique secret keys! Use `openssl rand -hex 32` for each key. -### 2.3 Mulakan bekas +### 2.3 Start the container ```bash docker pull diegosouzapw/omniroute:latest @@ -136,27 +138,27 @@ docker run -d \ diegosouzapw/omniroute:latest ``` -### 2.4 Sahkan bahawa ia sedang berjalan +### 2.4 Verify that it is running ```bash docker ps | grep omniroute docker logs omniroute --tail 20 ``` -Ia sepatutnya memaparkan: `[DB] SQLite database ready` dan `listening on port 20128`. +It should display: `[DB] SQLite database ready` and `listening on port 20128`. --- -## 3. Konfigurasikan nginx (Proksi Songsang) +## 3. Configure nginx (Reverse Proxy) -### 3.1 Jana sijil SSL (Cloudflare Origin) +### 3.1 Generate SSL certificate (Cloudflare Origin) -Dalam papan pemuka Cloudflare: +In the Cloudflare dashboard: -1. Pergi ke **SSL/TLS โ†’ Pelayan Asal** -2. Klik **Buat Sijil** -3. Kekalkan lalai (15 tahun, \*.yourdomain.com) -4. Salin **Sijil Asal** dan **Kunci Persendirian** +1. Go to **SSL/TLS โ†’ Origin Server** +2. Click **Create Certificate** +3. Keep the defaults (15 years, \*.yourdomain.com) +4. Copy the **Origin Certificate** and the **Private Key** ```bash mkdir -p /etc/nginx/ssl @@ -170,7 +172,7 @@ nano /etc/nginx/ssl/origin.key chmod 600 /etc/nginx/ssl/origin.key ``` -### 3.2 Konfigurasi Nginx +### 3.2 Nginx Configuration ```bash cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ @@ -228,7 +230,7 @@ server { NGINX ``` -### 3.3 Dayakan dan Uji +### 3.3 Enable and Test ```bash # Remove default configuration @@ -243,29 +245,29 @@ nginx -t && systemctl reload nginx --- -## 4. Konfigurasikan Cloudflare DNS +## 4. Configure Cloudflare DNS -### 4.1 Tambah rekod DNS +### 4.1 Add DNS record -Dalam papan pemuka Cloudflare โ†’ DNS: +In the Cloudflare dashboard โ†’ DNS: -| Taip | Nama | Kandungan | Proksi | -| ---- | ------ | ---------------------- | ----------- | -| A | `llms` | `203.0.113.10` (VM IP) | โœ… Diproksi | +| Type | Name | Content | Proxy | +| ---- | ------ | ---------------------- | ---------- | +| A | `llms` | `203.0.113.10` (VM IP) | โœ… Proxied | -### 4.2 Konfigurasikan SSL +### 4.2 Configure SSL -Di bawah **SSL/TLS โ†’ Gambaran Keseluruhan**: +Under **SSL/TLS โ†’ Overview**: -- Mod: **Penuh (Ketat)** +- Mode: **Full (Strict)** -Di bawah **SSL/TLS โ†’ Sijil Edge**: +Under **SSL/TLS โ†’ Edge Certificates**: -- Sentiasa Gunakan HTTPS: โœ… Hidup -- Versi TLS minimum: TLS 1.2 -- Penulisan Semula HTTPS Automatik: โœ… Hidup +- Always Use HTTPS: โœ… On +- Minimum TLS Version: TLS 1.2 +- Automatic HTTPS Rewrites: โœ… On -### 4.3 Pengujian +### 4.3 Testing ```bash curl -sI https://llms.seudominio.com/health @@ -274,9 +276,9 @@ curl -sI https://llms.seudominio.com/health --- -## 5. Operasi dan Penyelenggaraan +## 5. Operations and Maintenance -### Naik taraf kepada versi baharu +### Upgrade to a new version ```bash docker pull diegosouzapw/omniroute:latest @@ -288,14 +290,14 @@ docker run -d --name omniroute --restart unless-stopped \ diegosouzapw/omniroute:latest ``` -### Lihat log +### View logs ```bash docker logs -f omniroute # Real-time stream docker logs omniroute --tail 50 # Last 50 lines ``` -### Sandaran pangkalan data manual +### Manual database backup ```bash # Copy data from the volume to the host @@ -306,7 +308,7 @@ docker run --rm -v omniroute-data:/data -v $(pwd):/backup \ alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data ``` -### Pulihkan daripada sandaran +### Restore from backup ```bash docker stop omniroute @@ -317,9 +319,9 @@ docker start omniroute --- -## 6. Keselamatan Lanjutan +## 6. Advanced Security -### Hadkan nginx kepada IP Cloudflare +### Restrict nginx to Cloudflare IPs ```bash cat > /etc/nginx/cloudflare-ips.conf << โ€˜CFโ€™ @@ -344,13 +346,13 @@ real_ip_header CF-Connecting-IP; CF ``` -Tambahkan yang berikut pada `nginx.conf` di dalam blok `http {}`: +Add the following to `nginx.conf` inside the `http {}` block: ```nginx include /etc/nginx/cloudflare-ips.conf; ``` -### Pasang fail2ban +### Install fail2ban ```bash apt install -y fail2ban @@ -361,7 +363,7 @@ systemctl start fail2ban fail2ban-client status sshd ``` -### Sekat akses terus ke pelabuhan Docker +### Block direct access to the Docker port ```bash # Prevent direct external access to port 20128 @@ -375,9 +377,9 @@ netfilter-persistent save --- -## 7. Sebarkan ke Cloudflare Workers (Pilihan) +## 7. Deploy to Cloudflare Workers (Optional) -Untuk akses jauh melalui Cloudflare Workers (tanpa mendedahkan VM secara langsung): +For remote access via Cloudflare Workers (without exposing the VM directly): ```bash # In the local repository @@ -387,15 +389,15 @@ npx wrangler login npx wrangler deploy ``` -Lihat dokumentasi penuh di [omnirouteCloud/README.md](../omnirouteCloud/README.md). +See the full documentation at [omnirouteCloud/README.md](../omnirouteCloud/README.md). --- -## Ringkasan Pelabuhan +## Port Summary -| Pelabuhan | Perkhidmatan | Akses | -| --------- | ------------ | -------------------------------- | -| 22 | SSH | Awam (dengan fail2ban) | -| 80 | nginx HTTP | Ubah hala โ†’ HTTPS | -| 443 | nginx HTTPS | Melalui Proksi Cloudflare | -| 20128 | OmniRoute | Localhost sahaja (melalui nginx) | +| Port | Service | Access | +| ----- | ----------- | -------------------------- | +| 22 | SSH | Public (with fail2ban) | +| 80 | nginx HTTP | Redirect โ†’ HTTPS | +| 443 | nginx HTTPS | Via Cloudflare Proxy | +| 20128 | OmniRoute | Localhost only (via nginx) | diff --git a/docs/i18n/phi/src/lib/a2a/README.md b/docs/i18n/phi/src/lib/a2a/README.md new file mode 100644 index 0000000000..daf6be9458 --- /dev/null +++ b/docs/i18n/phi/src/lib/a2a/README.md @@ -0,0 +1,752 @@ +# OmniRoute A2A Server (Filipino) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../../../src/lib/a2a/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../../../es/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../../../fr/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../../../de/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../../../it/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../../../ru/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../../../zh-CN/src/lib/a2a/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../../../ja/src/lib/a2a/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../../../ko/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../../../ar/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../../../in/src/lib/a2a/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../../../th/src/lib/a2a/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../../../vi/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../../../id/src/lib/a2a/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../../../ms/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../../../nl/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../../../pl/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../../../sv/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../../../no/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../../../da/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../../../fi/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../../../pt/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../../../ro/src/lib/a2a/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../../../hu/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../../../bg/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../../../sk/src/lib/a2a/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../../../uk-UA/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../../../he/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../../../phi/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../../../pt-BR/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../../../cs/src/lib/a2a/README.md) + +--- + +> **Agent-to-Agent Protocol v0.3** โ€” Enables any AI agent to use OmniRoute as an intelligent routing agent via JSON-RPC 2.0. + +The A2A Server exposes OmniRoute as a **first-class agent** that other agents can discover, delegate tasks to, and collaborate with using the [A2A Protocol](https://google.github.io/A2A/). + +--- + +## Arkitektura + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Orchestrator Agent โ”‚ +โ”‚ (LangChain, CrewAI, AutoGen, Custom Agent) โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ 1. GET /.well-known/agent.json (discover) + โ”‚ 2. POST /a2a (JSON-RPC 2.0) + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ OmniRoute A2A Server โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Task Manager โ”‚ โ”‚ Skill Engine โ”‚ โ”‚ SSE Streaming โ”‚ โ”‚ +โ”‚ โ”‚ (lifecycle) โ”‚โ”€โ”€โ”‚ (registry) โ”‚โ”€โ”€โ”‚ (real-time) โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ +โ”‚ Skills: โ”‚ โ”‚ +โ”‚ โ”œโ”€ smart-routing โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ””โ”€ quota-management โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ Routing Decision Logger โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ OmniRoute Gateway (internal) + /v1/chat/completions, /api/combos, /api/usage/quota +``` + +--- + +## Mabilis na Simula + +### Agent Discovery + +Every A2A-compatible agent exposes an **Agent Card** at `/.well-known/agent.json`: + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +**Response:** + +```json +{ + "name": "OmniRoute", + "description": "Intelligent AI gateway with auto-routing across 50+ providers", + "url": "http://localhost:20128/a2a", + "version": "1.8.1", + "capabilities": { + "streaming": true, + "pushNotifications": false + }, + "skills": [ + { + "id": "smart-routing", + "name": "Smart Routing", + "description": "Routes prompts through OmniRoute intelligent pipeline", + "tags": ["routing", "llm", "multi-provider", "cost-optimization"], + "examples": [ + "Write a hello world in Python", + "Explain quantum computing using the cheapest provider" + ] + }, + { + "id": "quota-management", + "name": "Quota Management", + "description": "Natural-language queries about provider quotas", + "tags": ["quota", "analytics", "cost"], + "examples": [ + "Which provider has the most quota remaining?", + "Suggest a free combo for coding" + ] + } + ], + "authentication": { + "schemes": ["bearer"], + "apiKeyHeader": "Authorization" + } +} +``` + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Send a message to a skill and receive the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python hello world"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "a1b2c3d4-...", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "print('Hello, World!')" }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.0030)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "2026-03-04T..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"Quantum computing..."}}} + +: heartbeat 2026-03-04T21:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Running Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Skills Reference + +### `smart-routing` + +Routes prompts through OmniRoute's intelligent pipeline with full observability. + +**Parameters (in `metadata`):** + +| Parameter | Type | Default | Description | +| --------- | -------- | ------------ | ---------------------------------------------------------------------------------------- | +| `model` | `string` | `"auto"` | Target model (e.g., `claude-sonnet-4`, `gpt-4o`, `auto`) | +| `combo` | `string` | active combo | Specific combo to route through | +| `budget` | `number` | none | Maximum cost in USD for this request | +| `role` | `string` | none | Task role hint: `coding`, `review`, `planning`, `analysis`, `debugging`, `documentation` | + +**Returns:** + +| Field | Description | +| ------------------------------ | --------------------------------------------------------- | +| `artifacts[].content` | The LLM response text | +| `metadata.routing_explanation` | Human-readable explanation of routing decision | +| `metadata.cost_envelope` | Estimated vs actual cost with currency | +| `metadata.resilience_trace` | Array of events (primary_selected, fallback_needed, etc.) | +| `metadata.policy_verdict` | Whether the request was allowed and why | + +### `quota-management` + +Answers natural-language queries about provider quotas. + +**Query types (inferred from message content):** + +| Query Pattern | Response Type | +| ---------------------------------------------- | -------------------------------------------------------- | +| Contains `"ranking"`, `"most quota"`, `"best"` | Providers ranked by remaining quota | +| Contains `"free"`, `"suggest"` | Lists free combos or suggests free-tier providers | +| Default | Full quota summary with warnings for low-quota providers | + +--- + +## Task Lifecycle + +``` +submitted โ”€โ”€โ†’ working โ”€โ”€โ†’ completed + โ”€โ”€โ†’ failed + โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ†’ cancelled +``` + +| State | Description | +| ----------- | ----------------------------------------------------- | +| `submitted` | Task created, queued for execution | +| `working` | Skill handler is executing | +| `completed` | Execution succeeded, artifacts available | +| `failed` | Execution failed or task expired (TTL: 5 min default) | +| `cancelled` | Cancelled by client via `tasks/cancel` | + +- Terminal states: `completed`, `failed`, `cancelled` (no further transitions) +- Expired tasks in `submitted` or `working` are auto-marked as `failed` +- Tasks are garbage-collected after 2ร— TTL + +--- + +## Client Examples + +### Python โ€” Orchestrator Agent + +```python +""" +A2A Client โ€” Python example. +Discovers OmniRoute agent, sends a task, and processes the result. +""" +import requests +import json + +BASE_URL = "http://localhost:20128" +API_KEY = "your-api-key" +HEADERS = { + "Content-Type": "application/json", + "Authorization": f"Bearer {API_KEY}", +} + +# 1. Discover agent capabilities +agent_card = requests.get(f"{BASE_URL}/.well-known/agent.json").json() +print(f"Agent: {agent_card['name']} v{agent_card['version']}") +print(f"Skills: {[s['id'] for s in agent_card['skills']]}") + +# 2. Send a smart-routing task +response = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python quicksort implementation"}], + "metadata": { + "model": "auto", + "combo": "fast-coding", + "budget": 0.10, + } + } +}) +result = response.json()["result"] +print(f"\n๐Ÿ“ Response: {result['artifacts'][0]['content'][:200]}...") +print(f"๐Ÿ”€ Routing: {result['metadata']['routing_explanation']}") +print(f"๐Ÿ’ฐ Cost: ${result['metadata']['cost_envelope']['actual']}") +print(f"๐Ÿ›ก๏ธ Policy: {result['metadata']['policy_verdict']['reason']}") + +# 3. Query quota status +quota_resp = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-2", + "method": "message/send", + "params": { + "skill": "quota-management", + "messages": [{"role": "user", "content": "Which provider has the most quota remaining?"}], + } +}) +quota_result = quota_resp.json()["result"] +print(f"\n๐Ÿ“Š Quota: {quota_result['artifacts'][0]['content']}") +``` + +### TypeScript โ€” Multi-Agent Orchestrator + +```typescript +/** + * A2A Client โ€” TypeScript example. + * Shows agent discovery, task delegation, and streaming. + */ + +const BASE_URL = "http://localhost:20128"; +const API_KEY = "your-api-key"; + +interface JsonRpcResponse { + jsonrpc: "2.0"; + id: string | number; + result?: T; + error?: { code: number; message: string }; +} + +async function a2aCall(method: string, params: Record): Promise { + const resp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: `${method}-${Date.now()}`, + method, + params, + }), + }); + const json: JsonRpcResponse = await resp.json(); + if (json.error) throw new Error(`[${json.error.code}] ${json.error.message}`); + return json.result!; +} + +// โ”€โ”€ Agent Discovery โ”€โ”€ +const agentCard = await fetch(`${BASE_URL}/.well-known/agent.json`).then((r) => r.json()); +console.log(`Connected to: ${agentCard.name} (${agentCard.skills.length} skills)`); + +// โ”€โ”€ Smart Routing: Send a coding task โ”€โ”€ +const routingResult = await a2aCall("message/send", { + skill: "smart-routing", + messages: [{ role: "user", content: "Implement a Redis cache wrapper in TypeScript" }], + metadata: { model: "claude-sonnet-4", role: "coding" }, +}); +console.log("Response:", routingResult.artifacts[0].content); +console.log("Provider:", routingResult.metadata.routing_explanation); + +// โ”€โ”€ Quota Management: Find free alternatives โ”€โ”€ +const quotaResult = await a2aCall("message/send", { + skill: "quota-management", + messages: [{ role: "user", content: "Suggest free combos for documentation" }], +}); +console.log("Free combos:", quotaResult.artifacts[0].content); + +// โ”€โ”€ Streaming: Real-time response โ”€โ”€ +const streamResp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "stream-1", + method: "message/stream", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Explain microservices architecture" }], + }, + }), +}); + +const reader = streamResp.body!.getReader(); +const decoder = new TextDecoder(); +while (true) { + const { done, value } = await reader.read(); + if (done) break; + const chunk = decoder.decode(value); + for (const line of chunk.split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + if (event.params.chunk) { + process.stdout.write(event.params.chunk.content); + } + if (event.params.task.state === "completed") { + console.log("\nโœ… Stream completed"); + } + } + } +} +``` + +### Python โ€” LangChain A2A Integration + +```python +""" +LangChain integration โ€” Use OmniRoute A2A as a custom LLM. +""" +from langchain.llms.base import BaseLLM +from langchain.schema import LLMResult, Generation +import requests +from typing import List, Optional + +class OmniRouteA2A(BaseLLM): + base_url: str = "http://localhost:20128" + api_key: str = "" + model: str = "auto" + combo: Optional[str] = None + + @property + def _llm_type(self) -> str: + return "omniroute-a2a" + + def _call(self, prompt: str, stop: Optional[List[str]] = None, **kwargs) -> str: + response = requests.post( + f"{self.base_url}/a2a", + headers={ + "Content-Type": "application/json", + "Authorization": f"Bearer {self.api_key}", + }, + json={ + "jsonrpc": "2.0", + "id": "langchain-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": prompt}], + "metadata": { + "model": self.model, + **({"combo": self.combo} if self.combo else {}), + }, + }, + }, + ) + result = response.json()["result"] + return result["artifacts"][0]["content"] + + def _generate(self, prompts: List[str], stop=None, **kwargs) -> LLMResult: + return LLMResult( + generations=[[Generation(text=self._call(p, stop))] for p in prompts] + ) + +# Usage +llm = OmniRouteA2A( + base_url="http://localhost:20128", + api_key="your-key", + model="auto", + combo="fast-coding", +) +result = llm("Write a Python function to merge two sorted lists") +print(result) +``` + +### Go โ€” A2A Client + +```go +package main + +import ( + "bytes" + "encoding/json" + "fmt" + "io" + "net/http" +) + +const baseURL = "http://localhost:20128" +const apiKey = "your-api-key" + +type JsonRpcRequest struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Method string `json:"method"` + Params interface{} `json:"params"` +} + +type JsonRpcResponse struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Result interface{} `json:"result"` + Error *struct { + Code int `json:"code"` + Message string `json:"message"` + } `json:"error"` +} + +func a2aCall(method string, params interface{}) (*JsonRpcResponse, error) { + body, _ := json.Marshal(JsonRpcRequest{ + Jsonrpc: "2.0", + ID: "go-1", + Method: method, + Params: params, + }) + + req, _ := http.NewRequest("POST", baseURL+"/a2a", bytes.NewReader(body)) + req.Header.Set("Content-Type", "application/json") + req.Header.Set("Authorization", "Bearer "+apiKey) + + resp, err := http.DefaultClient.Do(req) + if err != nil { + return nil, err + } + defer resp.Body.Close() + data, _ := io.ReadAll(resp.Body) + + var result JsonRpcResponse + json.Unmarshal(data, &result) + return &result, nil +} + +func main() { + // Discover agent + resp, _ := http.Get(baseURL + "/.well-known/agent.json") + defer resp.Body.Close() + body, _ := io.ReadAll(resp.Body) + fmt.Println("Agent Card:", string(body)) + + // Send smart-routing task + result, _ := a2aCall("message/send", map[string]interface{}{ + "skill": "smart-routing", + "messages": []map[string]string{{"role": "user", "content": "Hello from Go!"}}, + "metadata": map[string]interface{}{"model": "auto"}, + }) + out, _ := json.MarshalIndent(result.Result, "", " ") + fmt.Println("Result:", string(out)) +} +``` + +--- + +## Use Cases + +### ๐Ÿค– Use Case 1: Multi-Agent Coding Pipeline + +An orchestrator agent delegates code generation to OmniRoute, then passes the output to a review agent. + +```python +def coding_pipeline(task: str): + # Step 1: Generate code via OmniRoute A2A + code_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Write production-quality code: {task}"} + ], metadata={"model": "auto", "role": "coding"}) + code = code_result["artifacts"][0]["content"] + + # Step 2: Review the code via OmniRoute A2A (different model) + review_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Review this code for bugs and improvements:\n\n{code}"} + ], metadata={"model": "auto", "role": "review"}) + review = review_result["artifacts"][0]["content"] + + # Step 3: Check costs + print(f"Code cost: ${code_result['metadata']['cost_envelope']['actual']}") + print(f"Review cost: ${review_result['metadata']['cost_envelope']['actual']}") + + return {"code": code, "review": review} +``` + +### ๐Ÿ’ก Use Case 2: Quota-Aware Agent Swarm + +Multiple agents share quota through OmniRoute, using the quota skill to coordinate. + +```python +async def quota_aware_agent(agent_name: str, task: str): + # Check quota before starting + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Which provider has the most quota remaining?"} + ]) + print(f"[{agent_name}] {quota['artifacts'][0]['content']}") + + # Send request with budget constraint + result = a2a_send("smart-routing", [ + {"role": "user", "content": task} + ], metadata={"budget": 0.05}) + + policy = result["metadata"]["policy_verdict"] + if not policy["allowed"]: + print(f"[{agent_name}] โš ๏ธ Budget exceeded: {policy['reason']}") + # Fall back to free combo + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Suggest free combos"} + ]) + print(f"[{agent_name}] Free alternatives: {quota['artifacts'][0]['content']}") + + return result +``` + +### ๐Ÿ“Š Use Case 3: Real-Time Streaming Dashboard + +A monitoring agent streams responses and displays progress in real-time. + +```typescript +async function streamingDashboard(prompt: string) { + const response = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { "Content-Type": "application/json", Authorization: `Bearer ${API_KEY}` }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "dash-1", + method: "message/stream", + params: { skill: "smart-routing", messages: [{ role: "user", content: prompt }] }, + }), + }); + + let totalChunks = 0; + const reader = response.body!.getReader(); + const decoder = new TextDecoder(); + + while (true) { + const { done, value } = await reader.read(); + if (done) break; + + for (const line of decoder.decode(value).split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + const state = event.params.task.state; + + if (state === "working" && event.params.chunk) { + totalChunks++; + process.stdout.write( + `\r[Chunk ${totalChunks}] ${event.params.chunk.content.slice(0, 50)}...` + ); + } + if (state === "completed") { + const meta = event.params.metadata; + console.log( + `\nโœ… Done | Cost: $${meta?.cost_envelope?.actual || 0} | Route: ${meta?.routing_explanation || "N/A"}` + ); + } + if (state === "failed") { + console.error(`\nโŒ Failed: ${event.params.metadata?.error}`); + } + } + } + } +} +``` + +### ๐Ÿ” Use Case 4: Task Polling Pattern + +For long-running tasks, poll the task status instead of waiting synchronously. + +```python +import time + +def poll_task(task_id: str, timeout: int = 60): + """Poll task status until completion or timeout.""" + start = time.time() + while time.time() - start < timeout: + result = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "poll-1", + "method": "tasks/get", + "params": {"taskId": task_id}, + }).json() + + task = result["result"]["task"] + state = task["state"] + print(f" Task {task_id[:8]}... state={state}") + + if state in ("completed", "failed", "cancelled"): + return task + time.sleep(2) + + # Timeout โ€” cancel the task + requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "cancel-1", + "method": "tasks/cancel", + "params": {"taskId": task_id}, + }) + raise TimeoutError(f"Task {task_id} timed out after {timeout}s") +``` + +--- + +## Error Codes + +| Code | Constant | Meaning | +| ------ | ------------------------ | ---------------------------------------- | +| -32700 | โ€” | Parse error (invalid JSON) | +| -32600 | `INVALID_REQUEST` | Invalid JSON-RPC request or unauthorized | +| -32601 | `METHOD_NOT_FOUND` | Unknown method or skill | +| -32602 | `INVALID_PARAMS` | Missing or invalid parameters | +| -32603 | `INTERNAL_ERROR` | Skill execution failed | +| -32001 | `TASK_NOT_FOUND` | Task ID not found | +| -32002 | `TASK_ALREADY_COMPLETED` | Cannot modify a completed task | +| -32003 | `UNAUTHORIZED` | Invalid or missing API key | +| -32004 | `BUDGET_EXCEEDED` | Request exceeds configured budget | +| -32005 | `PROVIDER_UNAVAILABLE` | No available providers | + +--- + +## Authentication + +All `/a2a` requests require a Bearer token via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server (`OMNIROUTE_API_KEY` is empty), authentication is bypassed. + +--- + +## File Structure + +``` +src/lib/a2a/ +โ”œโ”€โ”€ taskManager.ts # Task lifecycle (create/update/cancel/list), TTL, cleanup +โ”œโ”€โ”€ taskExecution.ts # Generic task executor with state management +โ”œโ”€โ”€ streaming.ts # SSE stream formatting, heartbeat, chunk/completion events +โ”œโ”€โ”€ routingLogger.ts # Routing decision logger (stats, history, retention) +โ””โ”€โ”€ skills/ + โ”œโ”€โ”€ smartRouting.ts # Smart routing skill (routes via /v1/chat/completions) + โ””โ”€โ”€ quotaManagement.ts # Quota management skill (natural-language quota queries) + +src/app/a2a/ +โ””โ”€โ”€ route.ts # Next.js API route handler (JSON-RPC 2.0 dispatch) + +open-sse/mcp-server/ +โ””โ”€โ”€ schemas/a2a.ts # Zod schemas (AgentCard, Task, JSON-RPC, SSE events) +``` + +--- + +## Comparison: MCP vs A2A + +| Feature | MCP Server | A2A Server | +| ----------------- | ---------------------------- | ------------------------------------------------- | +| **Protocol** | Model Context Protocol | Agent-to-Agent Protocol v0.3 | +| **Transport** | stdio / HTTP | HTTP (JSON-RPC 2.0) | +| **Discovery** | Tool listing via MCP | `/.well-known/agent.json` | +| **Granularity** | 16 individual tools | 2 high-level skills | +| **Best for** | IDE agents (Cursor, VS Code) | Multi-agent systems (LangChain, CrewAI) | +| **Streaming** | Not supported | SSE via `message/stream` | +| **Task tracking** | No | Full lifecycle (submitted โ†’ completed) | +| **Observability** | Audit log per tool call | Cost envelope + resilience trace + policy verdict | + +--- + +## Lisensya + +Part of [OmniRoute](https://github.com/diegosouzapw/OmniRoute) โ€” MIT License. diff --git a/docs/i18n/pl/A2A-SERVER.md b/docs/i18n/pl/A2A-SERVER.md deleted file mode 100644 index 01531ff482..0000000000 --- a/docs/i18n/pl/A2A-SERVER.md +++ /dev/null @@ -1,200 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/A2A-SERVER.md) - ---- - -# OmniRoute A2A Server Documentation - -> Agent-to-Agent Protocol v0.3 โ€” OmniRoute as an intelligent routing agent - -## Agent Discovery - -```bash -curl http://localhost:20128/.well-known/agent.json -``` - -Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements. - ---- - -## Authentication - -All `/a2a` requests require an API key via the `Authorization` header: - -``` -Authorization: Bearer YOUR_OMNIROUTE_API_KEY -``` - -If no API key is configured on the server, authentication is bypassed. - ---- - -## JSON-RPC 2.0 Methods - -### `message/send` โ€” Synchronous Execution - -Sends a message to a skill and waits for the complete response. - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{ - "jsonrpc": "2.0", - "id": "1", - "method": "message/send", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Write a hello world in Python"}], - "metadata": {"model": "auto", "combo": "fast-coding"} - } - }' -``` - -**Response:** - -```json -{ - "jsonrpc": "2.0", - "id": "1", - "result": { - "task": { "id": "uuid", "state": "completed" }, - "artifacts": [{ "type": "text", "content": "..." }], - "metadata": { - "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)", - "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, - "resilience_trace": [ - { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." } - ], - "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } - } - } -} -``` - -### `message/stream` โ€” SSE Streaming - -Same as `message/send` but returns Server-Sent Events for real-time streaming. - -```bash -curl -N -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{ - "jsonrpc": "2.0", - "id": "1", - "method": "message/stream", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Explain quantum computing"}] - } - }' -``` - -**SSE Events:** - -``` -data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}} - -: heartbeat 2026-03-03T17:00:00Z - -data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} -``` - -### `tasks/get` โ€” Query Task Status - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' -``` - -### `tasks/cancel` โ€” Cancel a Task - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' -``` - ---- - -## Available Skills - -| Skill | Description | -| :----------------- | :------------------------------------------------------------------------------------------------------------------------------ | -| `smart-routing` | Routes prompts through OmniRoute's intelligent pipeline. Returns response with routing explanation, cost, and resilience trace. | -| `quota-management` | Answers natural-language queries about provider quotas, suggests free combos, and provides quota rankings. | - ---- - -## Task Lifecycle - -``` -submitted โ†’ working โ†’ completed - โ†’ failed - โ†’ cancelled -``` - -- Tasks expire after 5 minutes (configurable) -- Terminal states: `completed`, `failed`, `cancelled` -- Event log tracks every state transition - ---- - -## Error Codes - -| Code | Meaning | -| :----- | :----------------------------- | -| -32700 | Parse error (invalid JSON) | -| -32600 | Invalid request / Unauthorized | -| -32601 | Method or skill not found | -| -32602 | Invalid params | -| -32603 | Internal error | - ---- - -## Integration Examples - -### Python (requests) - -```python -import requests - -resp = requests.post("http://localhost:20128/a2a", json={ - "jsonrpc": "2.0", "id": "1", - "method": "message/send", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Hello"}] - } -}, headers={"Authorization": "Bearer YOUR_KEY"}) - -result = resp.json()["result"] -print(result["artifacts"][0]["content"]) -print(result["metadata"]["routing_explanation"]) -``` - -### TypeScript (fetch) - -```typescript -const resp = await fetch("http://localhost:20128/a2a", { - method: "POST", - headers: { - "Content-Type": "application/json", - Authorization: "Bearer YOUR_KEY", - }, - body: JSON.stringify({ - jsonrpc: "2.0", - id: "1", - method: "message/send", - params: { - skill: "smart-routing", - messages: [{ role: "user", content: "Hello" }], - }, - }), -}); -const { result } = await resp.json(); -console.log(result.metadata.routing_explanation); -``` diff --git a/docs/i18n/pl/API_REFERENCE.md b/docs/i18n/pl/API_REFERENCE.md deleted file mode 100644 index b878605221..0000000000 --- a/docs/i18n/pl/API_REFERENCE.md +++ /dev/null @@ -1,455 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/API_REFERENCE.md) - ---- - -# API Reference - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/API_REFERENCE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/API_REFERENCE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/API_REFERENCE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/API_REFERENCE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/API_REFERENCE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/API_REFERENCE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/API_REFERENCE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/API_REFERENCE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/API_REFERENCE.md) - -Complete reference for all OmniRoute API endpoints. - ---- - -## Table of Contents - -- [Chat Completions](#chat-completions) -- [Embeddings](#embeddings) -- [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`. - -### ACP Agents - -| Endpoint | Method | Description | -| ----------------- | ------ | -------------------------------------------------------- | -| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | -| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | -| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | - -GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). - -### Resilience & Rate Limits - -| Endpoint | Method | Description | -| ----------------------- | ------- | ------------------------------- | -| `/api/resilience` | 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` diff --git a/docs/i18n/pl/ARCHITECTURE.md b/docs/i18n/pl/ARCHITECTURE.md deleted file mode 100644 index 4ea06a29f2..0000000000 --- a/docs/i18n/pl/ARCHITECTURE.md +++ /dev/null @@ -1,787 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/ARCHITECTURE.md) - ---- - -# OmniRoute Architecture - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/ARCHITECTURE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/ARCHITECTURE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/ARCHITECTURE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/ARCHITECTURE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/ARCHITECTURE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/ARCHITECTURE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/ARCHITECTURE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/ARCHITECTURE.md) - -_Last updated: 2026-03-04_ - -## 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 (`...`) for reasoning models -- Response sanitization for strict OpenAI SDK compatibility -- Role normalization (developerโ†’system, systemโ†’user) for cross-provider compatibility -- Structured output conversion (json_schema โ†’ Gemini responseSchema) -- Local persistence for providers, keys, aliases, combos, settings, pricing -- Usage/cost tracking and request logging -- Optional cloud sync for multi-device/state sync -- IP allowlist/blocklist for API access control -- Thinking budget management (passthrough/auto/custom/adaptive) -- Global system prompt injection -- Session tracking and fingerprinting -- Per-account enhanced rate limiting with provider-specific profiles -- Circuit breaker pattern for provider resilience -- Anti-thundering herd protection with mutex locking -- Signature-based request deduplication cache -- Domain layer: model availability, cost rules, fallback policy, lockout policy -- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) -- Policy engine for centralized request evaluation (lockout โ†’ budget โ†’ fallback) -- Request telemetry with p50/p95/p99 latency aggregation -- Correlation ID (X-Request-Id) for end-to-end tracing -- Compliance audit logging with opt-out per API key -- Eval framework for LLM quality assurance -- Resilience UI dashboard with real-time circuit breaker status -- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) - -Primary runtime model: - -- Next.js 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[(storage.sqlite)] - UDB[(usage tables + log artifacts)] - end - - subgraph Upstreams[Upstream Providers] - P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/Qoder/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/route.ts` (GET) -- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) -- OAuth: `src/app/api/oauth/*` -- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` -- Usage: `src/app/api/usage/*` -- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` -- CLI tooling helpers: `src/app/api/cli-tools/*` -- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) -- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) -- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) -- Sessions: `src/app/api/sessions` (GET) -- Rate limits: `src/app/api/rate-limits` (GET) -- Resilience: `src/app/api/resilience` (GET/PATCH) โ€” provider profiles, circuit breaker, rate limit state -- Resilience reset: `src/app/api/resilience/reset` (POST) โ€” reset breakers + cooldowns -- Cache stats: `src/app/api/cache/stats` (GET/DELETE) -- Model availability: `src/app/api/models/availability` (GET/POST) -- Telemetry: `src/app/api/telemetry/summary` (GET) -- Budget: `src/app/api/usage/budget` (GET/POST) -- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) -- Compliance audit: `src/app/api/compliance/audit-log` (GET) -- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) -- Policies: `src/app/api/policies` (GET/POST) - -## 2) SSE + 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` -- Response sanitization: `open-sse/handlers/responseSanitizer.ts` -- Role normalization: `open-sse/services/roleNormalizer.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`, `qoder.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 (SQLite): - -- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) -- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) -- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) -- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** - -Usage persistence: - -- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) -- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` -- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) -- legacy JSON files are migrated to SQLite by startup migrations when present - -Domain State DB (SQLite): - -- `src/lib/db/domainState.ts` โ€” CRUD operations 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: - -- primary runtime DB: `${DATA_DIR}/storage.sqlite` -- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) -- structured call payload archives: `${DATA_DIR}/call_logs/` -- optional translator/request debug sessions: `/logs/...` - -## Deployment Topology - -```mermaid -flowchart LR - 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[(storage.sqlite)] - UsageDB[(usage tables + log artifacts)] - end - - subgraph External[External Services] - Providers[AI Providers] - SyncCloud[Cloud Sync Service] - end - - CLI --> Next - Browser --> Next - Next --> Core - Next --> MainDB - Core --> MainDB - Core --> UsageDB - Core --> Providers - Next --> SyncCloud -``` - -## Module Mapping (Decision-Critical) - -### Route and API Modules - -- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs -- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) -- `src/app/api/providers*`: provider CRUD, validation, testing -- `src/app/api/provider-nodes*`: custom compatible node management -- `src/app/api/provider-models`: custom model management (CRUD) -- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) -- `src/app/api/oauth/*`: OAuth/device-code flows -- `src/app/api/keys*`: local API key lifecycle -- `src/app/api/models/alias`: alias management -- `src/app/api/combos*`: fallback combo management -- `src/app/api/pricing`: pricing overrides for cost calculation -- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) -- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) -- `src/app/api/usage/*`: usage and logs APIs -- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers -- `src/app/api/cli-tools/*`: local CLI config writers/checkers -- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) -- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) -- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) -- `src/app/api/sessions`: active session listing (GET) -- `src/app/api/rate-limits`: per-account rate limit status (GET) - -### Routing and Execution Core - -- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop -- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup -- `open-sse/executors/*`: provider-specific network and format behavior - -### Translation Registry and Format Converters - -- `open-sse/translator/index.ts`: translator registry and orchestration -- Request translators: `open-sse/translator/request/*` -- Response translators: `open-sse/translator/response/*` -- Format constants: `open-sse/translator/formats.ts` - -### Persistence - -- `src/lib/db/*`: persistent config/state and domain persistence on SQLite -- `src/lib/localDb.ts`: compatibility re-export for DB modules -- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables - -## Provider Executor Coverage (Strategy Pattern) - -Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. - -| Executor | Provider(s) | Special Handling | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | -| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, Qoder, 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 | -| Qoder | openai | OAuth (Basic) | โœ… | โœ… | โœ… | โš ๏ธ Per request | -| OpenRouter | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| GLM/Kimi/MiniMax | claude | API Key | โœ… | โœ… | โŒ | โŒ | -| DeepSeek | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Groq | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| xAI (Grok) | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Mistral | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Perplexity | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Together AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Fireworks AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Cerebras | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Cohere | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| NVIDIA NIM | openai | API Key | โœ… | โœ… | โŒ | โŒ | - -## Format Translation Coverage - -Detected source formats include: - -- `openai` -- `openai-responses` -- `claude` -- `gemini` - -Target formats include: - -- OpenAI chat/Responses -- Claude -- Gemini/Gemini-CLI/Antigravity envelope -- Kiro -- Cursor - -Translations use **OpenAI as the hub format** โ€” all conversions go through OpenAI as intermediate: - -``` -Source Format โ†’ OpenAI (hub) โ†’ Target Format -``` - -Translations are selected dynamically based on source payload shape and provider target format. - -Additional processing layers in the translation pipeline: - -- **Response sanitization** โ€” Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance -- **Role normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI targets; merges `system` โ†’ `user` for models that reject the system role (GLM, ERNIE) -- **Think tag extraction** โ€” Parses `...` blocks from content into `reasoning_content` field -- **Structured output** โ€” Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` - -## Supported API Endpoints - -| 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 `/logs//` 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 - -- SQLite schema migrations and auto-upgrade hooks at startup -- legacy JSON โ†’ SQLite migration compatibility path - -## Observability and Operational Signals - -Runtime visibility sources: - -- console logs from `src/sse/utils/logger.ts` -- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) -- textual request status log in `log.txt` (optional/compat) -- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` -- dashboard usage endpoints (`/api/usage/*`) for UI consumption - -## Security-Sensitive Boundaries - -- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing -- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning -- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format -- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level -- Cloud sync endpoints rely on API key auth + machine id semantics - -## Environment and Runtime Matrix - -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` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. -2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. -3. Request logger writes full headers/body when enabled; treat log directory as sensitive. -4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. -5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. -6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). -7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). -8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). - -## Operational Verification Checklist - -- Build from source: `npm run build` -- Build Docker image: `docker build -t omniroute .` -- Start service and verify: -- `GET /api/settings` -- `GET /api/v1/models` -- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/pl/AUTO-COMBO.md b/docs/i18n/pl/AUTO-COMBO.md deleted file mode 100644 index 2166e41dff..0000000000 --- a/docs/i18n/pl/AUTO-COMBO.md +++ /dev/null @@ -1,67 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/AUTO-COMBO.md) - ---- - -# OmniRoute Auto-Combo Engine - -> Self-managing model chains with adaptive scoring - -## How It Works - -The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**: - -| Factor | Weight | Description | -| :--------- | :----- | :---------------------------------------------- | -| Quota | 0.20 | Remaining capacity [0..1] | -| Health | 0.25 | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 | -| CostInv | 0.20 | Inverse cost (cheaper = higher score) | -| LatencyInv | 0.15 | Inverse p95 latency (faster = higher) | -| TaskFit | 0.10 | Model ร— task type fitness score | -| Stability | 0.10 | Low variance in latency/errors | - -## Mode Packs - -| Pack | Focus | Key Weight | -| :---------------------- | :----------- | :--------------- | -| ๐Ÿš€ **Ship Fast** | Speed | latencyInv: 0.35 | -| ๐Ÿ’ฐ **Cost Saver** | Economy | costInv: 0.40 | -| ๐ŸŽฏ **Quality First** | Best model | taskFit: 0.40 | -| ๐Ÿ“ก **Offline Friendly** | Availability | quota: 0.40 | - -## Self-Healing - -- **Temporary exclusion**: Score < 0.2 โ†’ excluded for 5 min (progressive backoff, max 30 min) -- **Circuit breaker awareness**: OPEN โ†’ auto-excluded; HALF_OPEN โ†’ probe requests -- **Incident mode**: >50% OPEN โ†’ disable exploration, maximize stability -- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout - -## Bandit Exploration - -5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode. - -## API - -```bash -# Create auto-combo -curl -X POST http://localhost:20128/api/combos/auto \ - -H "Content-Type: application/json" \ - -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}' - -# List auto-combos -curl http://localhost:20128/api/combos/auto -``` - -## Task Fitness - -30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` โ†’ high coding score). - -## Files - -| File | Purpose | -| :------------------------------------------- | :------------------------------------ | -| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization | -| `open-sse/services/autoCombo/taskFitness.ts` | Model ร— task fitness lookup | -| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap | -| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode | -| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles | -| `src/app/api/combos/auto/route.ts` | REST API | diff --git a/docs/i18n/pl/CHANGELOG.md b/docs/i18n/pl/CHANGELOG.md index 6d1415dec5..05822720eb 100644 --- a/docs/i18n/pl/CHANGELOG.md +++ b/docs/i18n/pl/CHANGELOG.md @@ -1,12 +1,92 @@ # Changelog (Polski) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CHANGELOG.md) --- - ## [Unreleased] +### ๐Ÿ› ๏ธ Maintenance + +- **AGENTS.md rewrite:** Condensed from 297โ†’153 lines. Added build/lint/test commands (including single-test execution), code style guidelines (Prettier, TypeScript, ESLint, naming, imports, error handling, security), and trimmed verbose architecture tables for AI agent consumption. + +## [3.4.2] - 2026-04-01 + +### ๐Ÿ› Bug Fixes + +- **CI Stabilization:** Fixed failing analytics/settings Playwright selectors and request assertions so GitHub Actions E2E runs pass reliably across localized UIs and switch-based controls. +- **Deterministic Tests:** Removed date-sensitive quota fixtures from Copilot usage tests and aligned idempotency/model catalog tests with the merged runtime behavior. +- **MCP Type Hardening:** Removed zero-budget explicit `any` regressions from the MCP server tool registration path, restoring the `check:any-budget:t11` workflow gate. + +### ๐Ÿ› ๏ธ Maintenance + +- **Release Branch Integration:** Consolidated the active feature branches into `release/v3.4.2` on top of current `main` and validated the branch with lint, unit, coverage, build, and CI-mode E2E runs. + +## [3.4.1] - 2026-03-31 + +> [!WARNING] +> **BREAKING CHANGE: request logging, retention, and logging environment variables have been redesigned.** +> On the first startup after upgrading, OmniRoute archives legacy request logs from `DATA_DIR/logs/`, legacy `DATA_DIR/call_logs/`, and `DATA_DIR/log.txt` into `DATA_DIR/log_archives/*.zip`, then removes the deprecated layout and switches to the new unified artifact format under `DATA_DIR/call_logs/`. + +### โœจ New Features + +- **.ENV Migration Utility:** Included `scripts/migrate-env.mjs` to seamlessly migrate ` Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` - ---- - -## Step 2 โ€” Install CLI Tools - -All npm-based tools require Node.js 18+: - -```bash -# Claude Code (Anthropic) -npm install -g @anthropic-ai/claude-code - -# OpenAI Codex -npm install -g @openai/codex - -# Gemini CLI (Google) -npm install -g @google/gemini-cli - -# OpenCode -npm install -g opencode-ai - -# Cline -npm install -g cline - -# KiloCode -npm install -g kilecode - -# Kiro CLI (Amazon โ€” requires curl + unzip) -apt-get install -y unzip # on Debian/Ubuntu -curl -fsSL https://cli.kiro.dev/install | bash -export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc -``` - -**Verify:** - -```bash -claude --version # 2.x.x -codex --version # 0.x.x -gemini --version # 0.x.x -opencode --version # x.x.x -cline --version # 2.x.x -kilocode --version # x.x.x (or: kilo --version) -kiro-cli --version # 1.x.x -``` - ---- - -## Step 3 โ€” Set Global Environment Variables - -Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`: - -```bash -# OmniRoute Universal Endpoint -export OPENAI_BASE_URL="http://localhost:20128/v1" -export OPENAI_API_KEY="sk-your-omniroute-key" -export ANTHROPIC_BASE_URL="http://localhost:20128/v1" -export ANTHROPIC_API_KEY="sk-your-omniroute-key" -export GEMINI_BASE_URL="http://localhost:20128/v1" -export GEMINI_API_KEY="sk-your-omniroute-key" -``` - -> For a **remote server** replace `localhost:20128` with the server IP or domain, -> e.g. `http://192.168.0.15:20128`. - ---- - -## Step 4 โ€” Configure Each Tool - -### Claude Code - -```bash -# Via CLI: -claude config set --global api-base-url http://localhost:20128/v1 - -# Or create ~/.claude/settings.json: -mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF -{ - "apiBaseUrl": "http://localhost:20128/v1", - "apiKey": "sk-your-omniroute-key" -} -EOF -``` - -**Test:** `claude "say hello"` - ---- - -### OpenAI Codex - -```bash -mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF -model: auto -apiKey: sk-your-omniroute-key -apiBaseUrl: http://localhost:20128/v1 -EOF -``` - -**Test:** `codex "what is 2+2?"` - ---- - -### Gemini CLI - -```bash -mkdir -p ~/.gemini && cat > ~/.gemini/settings.json << EOF -{ - "apiKey": "sk-your-omniroute-key", - "baseUrl": "http://localhost:20128/v1" -} -EOF -``` - -**Test:** `gemini "hello"` - ---- - -### OpenCode - -```bash -mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF -[provider.openai] -base_url = "http://localhost:20128/v1" -api_key = "sk-your-omniroute-key" -EOF -``` - -**Test:** `opencode` - ---- - -### Cline (CLI or VS Code) - -**CLI mode:** - -```bash -mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF -{ - "apiProvider": "openai", - "openAiBaseUrl": "http://localhost:20128/v1", - "openAiApiKey": "sk-your-omniroute-key" -} -EOF -``` - -**VS Code mode:** -Cline extension settings โ†’ API Provider: `OpenAI Compatible` โ†’ Base URL: `http://localhost:20128/v1` - -Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ Cline โ†’ Apply Config**. - ---- - -### KiloCode (CLI or VS Code) - -**CLI mode:** - -```bash -kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key -``` - -**VS Code settings:** - -```json -{ - "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", - "kilo-code.apiKey": "sk-your-omniroute-key" -} -``` - -Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ KiloCode โ†’ Apply Config**. - ---- - -### Continue (VS Code Extension) - -Edit `~/.continue/config.yaml`: - -```yaml -models: - - name: OmniRoute - provider: openai - model: auto - apiBase: http://localhost:20128/v1 - apiKey: sk-your-omniroute-key - default: true -``` - -Restart VS Code after editing. - ---- - -### Kiro CLI (Amazon) - -```bash -# Login to your AWS/Kiro account: -kiro-cli login - -# The CLI uses its own auth โ€” OmniRoute is not needed as backend for Kiro CLI itself. -# Use kiro-cli alongside OmniRoute for other tools. -kiro-cli status -``` - ---- - -### Cursor (Desktop App) - -> **Note:** Cursor routes requests through its cloud. For OmniRoute integration, -> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL. - -Via GUI: **Settings โ†’ Models โ†’ OpenAI API Key** - -- Base URL: `https://your-domain.com/v1` -- API Key: your OmniRoute key - ---- - -## Dashboard Auto-Configuration - -The OmniRoute dashboard automates configuration for most tools: - -1. Go to `http://localhost:20128/dashboard/cli-tools` -2. Expand any tool card -3. Select your API key from the dropdown -4. Click **Apply Config** (if tool is detected as installed) -5. Or copy the generated config snippet manually - ---- - -## Built-in Agents: Droid & OpenClaw - -**Droid** and **OpenClaw** are AI agents built directly into OmniRoute โ€” no installation needed. -They run as internal routes and use OmniRoute's model routing automatically. - -- Access: `http://localhost:20128/dashboard/agents` -- Configure: same combos and providers as all other tools -- No API key or CLI install required - ---- - -## Available API Endpoints - -| Endpoint | Description | Use For | -| -------------------------- | ----------------------------- | --------------------------- | -| `/v1/chat/completions` | Standard chat (all providers) | All modern tools | -| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows | -| `/v1/completions` | Legacy text completions | Older tools using `prompt:` | -| `/v1/embeddings` | Text embeddings | RAG, search | -| `/v1/images/generations` | Image generation | DALL-E, Flux, etc. | -| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS | -| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI | - ---- - -## Troubleshooting - -| Error | Cause | Fix | -| ------------------------- | ----------------------- | ------------------------------------------ | -| `Connection refused` | OmniRoute not running | `pm2 start omniroute` | -| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` | -| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` | -| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` | -| CLI shows "not installed" | Binary not in PATH | Check `which ` | -| `kiro-cli: not found` | Not in PATH | `export PATH="$HOME/.local/bin:$PATH"` | - ---- - -## Quick Setup Script (One Command) - -```bash -# Install all CLIs and configure for OmniRoute (replace with your key and server URL) -OMNIROUTE_URL="http://localhost:20128/v1" -OMNIROUTE_KEY="sk-your-omniroute-key" - -npm install -g @anthropic-ai/claude-code @openai/codex @google/gemini-cli opencode-ai cline kilecode - -# Kiro CLI -apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash - -# Write configs -mkdir -p ~/.claude ~/.codex ~/.gemini ~/.config/opencode ~/.continue - -cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" -cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" -cat > ~/.gemini/settings.json <<< "{\"apiKey\":\"$OMNIROUTE_KEY\",\"baseUrl\":\"$OMNIROUTE_URL\"}" -cat >> ~/.bashrc << EOF -export OPENAI_BASE_URL="$OMNIROUTE_URL" -export OPENAI_API_KEY="$OMNIROUTE_KEY" -export ANTHROPIC_BASE_URL="$OMNIROUTE_URL" -export ANTHROPIC_API_KEY="$OMNIROUTE_KEY" -EOF - -source ~/.bashrc -echo "โœ… All CLIs installed and configured for OmniRoute" -``` diff --git a/docs/i18n/pl/CODEBASE_DOCUMENTATION.md b/docs/i18n/pl/CODEBASE_DOCUMENTATION.md deleted file mode 100644 index e2d7950052..0000000000 --- a/docs/i18n/pl/CODEBASE_DOCUMENTATION.md +++ /dev/null @@ -1,593 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CODEBASE_DOCUMENTATION.md) - ---- - -# omniroute โ€” Codebase Documentation - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) - -> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. - ---- - -## 1. 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
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, Qoder, 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 | -| Qoder | 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"] -``` diff --git a/docs/i18n/pl/CONTRIBUTING.md b/docs/i18n/pl/CONTRIBUTING.md new file mode 100644 index 0000000000..bac8146b81 --- /dev/null +++ b/docs/i18n/pl/CONTRIBUTING.md @@ -0,0 +1,299 @@ +# Contributing to OmniRoute (Polski) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CONTRIBUTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CONTRIBUTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CONTRIBUTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CONTRIBUTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CONTRIBUTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CONTRIBUTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CONTRIBUTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CONTRIBUTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CONTRIBUTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CONTRIBUTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CONTRIBUTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CONTRIBUTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CONTRIBUTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CONTRIBUTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CONTRIBUTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CONTRIBUTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CONTRIBUTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CONTRIBUTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CONTRIBUTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CONTRIBUTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CONTRIBUTING.md) + +--- + +Thank you for your interest in contributing! This guide covers everything you need to get started. + +--- + +## Development Setup + +### Prerequisites + +- **Node.js** >= 18 < 24 (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` | `20128` | Server port | +| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | Base URL for frontend | +| `JWT_SECRET` | (generate above) | JWT signing secret | +| `INITIAL_PASSWORD` | `CHANGEME` | First login password | +| `APP_LOG_LEVEL` | `info` | Log verbosity level | + +### Dashboard Settings + +The dashboard provides UI toggles for features that can also be configured via environment variables: + +| Setting Location | Toggle | Description | +| ------------------- | ------------------ | ------------------------------ | +| Settings โ†’ Advanced | Debug Mode | Enable debug request logs (UI) | +| Settings โ†’ General | Sidebar Visibility | Show/hide sidebar sections | + +These settings are stored in the database and persist across restarts, overriding env var defaults when set. + +### 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:20128/dashboard` +- **API**: `http://localhost:20128/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`, `mcp`, `a2a`, `memory`, `skills`. + +--- + +## Running Tests + +```bash +# All tests (unit + vitest + ecosystem + e2e) +npm run test:all + +# Single test file (Node.js native test runner โ€” most tests use this) +node --import tsx/esm --test tests/unit/your-file.test.mjs + +# Vitest (MCP server, autoCombo, cache) +npm run test:vitest + +# E2E tests (requires Playwright) +npm run test:e2e + +# Protocol clients E2E (MCP transports, A2A) +npm run test:protocols:e2e + +# Ecosystem compatibility tests +npm run test:ecosystem + +# Coverage (55% min statements/lines/functions; 60% branches) +npm run test:coverage +npm run coverage:report + +# Lint + format check +npm run lint +npm run check +``` + +Coverage notes: + +- `npm run test:coverage` measures source coverage for the main unit test suite, excludes `tests/**`, and includes `open-sse/**` +- `npm run coverage:report` prints the detailed file-by-file report from the latest coverage run +- `npm run test:coverage:legacy` preserves the older metric for historical comparison +- See `docs/COVERAGE_PLAN.md` for the phased coverage improvement roadmap + +Current test status: **122 unit test files** covering: + +- Provider translators and format conversion +- Rate limiting, circuit breaker, and resilience +- Semantic cache, idempotency, progress tracking +- Database operations and schema (21 DB modules) +- OAuth flows and authentication +- API endpoint validation (Zod v4) +- MCP server tools and scope enforcement +- Memory and Skills systems + +--- + +## Code Style + +- **ESLint** โ€” Run `npm run lint` before committing +- **Prettier** โ€” Auto-formatted via `lint-staged` on commit (2 spaces, semicolons, double quotes, 100 char width, es5 trailing commas) +- **TypeScript** โ€” All `src/` code uses `.ts`/`.tsx`; `open-sse/` uses `.ts`/`.js`; document with TSDoc (`@param`, `@returns`, `@throws`) +- **No `eval()`** โ€” ESLint enforces `no-eval`, `no-implied-eval`, `no-new-func` +- **Zod validation** โ€” Use Zod v4 schemas for all API input validation +- **Naming**: Files = camelCase/kebab-case, components = PascalCase, constants = UPPER_SNAKE + +--- + +## Project Structure + +``` +src/ # TypeScript (.ts / .tsx) +โ”œโ”€โ”€ app/ # Next.js 16 App Router +โ”‚ โ”œโ”€โ”€ (dashboard)/ # Dashboard pages (23 sections) +โ”‚ โ”œโ”€โ”€ api/ # API routes (51 directories) +โ”‚ โ””โ”€โ”€ login/ # Auth pages (.tsx) +โ”œโ”€โ”€ domain/ # Policy engine (policyEngine, comboResolver, costRules, etc.) +โ”œโ”€โ”€ lib/ # Core business logic (.ts) +โ”‚ โ”œโ”€โ”€ a2a/ # Agent-to-Agent v0.3 protocol server +โ”‚ โ”œโ”€โ”€ acp/ # Agent Communication Protocol registry +โ”‚ โ”œโ”€โ”€ compliance/ # Compliance policy engine +โ”‚ โ”œโ”€โ”€ db/ # SQLite database layer (21 modules + 16 migrations) +โ”‚ โ”œโ”€โ”€ memory/ # Persistent conversational memory +โ”‚ โ”œโ”€โ”€ oauth/ # OAuth providers, services, and utilities +โ”‚ โ”œโ”€โ”€ skills/ # Extensible skill framework +โ”‚ โ”œโ”€โ”€ usage/ # Usage tracking and cost calculation +โ”‚ โ””โ”€โ”€ localDb.ts # Re-export layer only โ€” never add logic here +โ”œโ”€โ”€ middleware/ # Request middleware (promptInjectionGuard) +โ”œโ”€โ”€ mitm/ # MITM proxy (cert, DNS, target routing) +โ”œโ”€โ”€ shared/ +โ”‚ โ”œโ”€โ”€ components/ # React components (.tsx) +โ”‚ โ”œโ”€โ”€ constants/ # Provider definitions (60+), MCP scopes, routing strategies +โ”‚ โ”œโ”€โ”€ utils/ # Circuit breaker, sanitizer, auth helpers +โ”‚ โ””โ”€โ”€ validation/ # Zod v4 schemas +โ””โ”€โ”€ sse/ # SSE proxy pipeline + +open-sse/ # @omniroute/open-sse workspace +โ”œโ”€โ”€ executors/ # 14 provider-specific request executors +โ”œโ”€โ”€ handlers/ # 11 request handlers (chat, responses, embeddings, images, etc.) +โ”œโ”€โ”€ mcp-server/ # MCP server (25 tools, 3 transports, 10 scopes) +โ”œโ”€โ”€ services/ # 36+ services (combo, autoCombo, rateLimitManager, etc.) +โ”œโ”€โ”€ translator/ # Format translators (OpenAI โ†” Claude โ†” Gemini โ†” Responses โ†” Ollama) +โ”œโ”€โ”€ transformer/ # Responses API transformer +โ””โ”€โ”€ utils/ # 22 utility modules (stream, TLS, proxy, logging) + +electron/ # Electron desktop app (cross-platform) + +tests/ +โ”œโ”€โ”€ unit/ # Node.js test runner (122 test files) +โ”œโ”€โ”€ integration/ # Integration tests +โ”œโ”€โ”€ e2e/ # Playwright tests +โ”œโ”€โ”€ security/ # Security tests +โ”œโ”€โ”€ translator/ # Translator-specific tests +โ””โ”€โ”€ load/ # Load tests + +docs/ # Documentation +โ”œโ”€โ”€ ARCHITECTURE.md # System architecture +โ”œโ”€โ”€ API_REFERENCE.md # All endpoints +โ”œโ”€โ”€ USER_GUIDE.md # Provider setup, CLI integration +โ”œโ”€โ”€ TROUBLESHOOTING.md # Common issues +โ”œโ”€โ”€ MCP-SERVER.md # MCP server (25 tools) +โ”œโ”€โ”€ A2A-SERVER.md # A2A agent protocol +โ”œโ”€โ”€ AUTO-COMBO.md # Auto-combo engine +โ”œโ”€โ”€ CLI-TOOLS.md # CLI tools integration +โ”œโ”€โ”€ COVERAGE_PLAN.md # Test coverage improvement plan +โ”œโ”€โ”€ openapi.yaml # OpenAPI specification +โ””โ”€โ”€ adr/ # Architecture Decision Records +``` + +--- + +## Adding a New Provider + +### Step 1: Register Provider Constants + +Add to `src/shared/constants/providers.ts` โ€” Zod-validated at module load. + +### Step 2: Add Executor (if custom logic needed) + +Create executor in `open-sse/executors/your-provider.ts` extending the base executor. + +### Step 3: Add Translator (if non-OpenAI format) + +Create request/response translators in `open-sse/translator/`. + +### Step 4: Add OAuth Config (if OAuth-based) + +Add OAuth credentials in `src/lib/oauth/constants/oauth.ts` and service in `src/lib/oauth/services/`. + +### Step 5: Register Models + +Add model definitions in `open-sse/config/providerRegistry.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 +- [ ] All inputs validated with Zod schemas +- [ ] CHANGELOG updated (if user-facing change) +- [ ] Documentation updated (if applicable) + +--- + +## Releasing + +Releases are managed via the `/generate-release` workflow. When a new GitHub Release is created, the package is **automatically published to npm** via GitHub Actions. + +--- + +## Getting Help + +- **Architecture**: See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) +- **API Reference**: See [`docs/API_REFERENCE.md`](docs/API_REFERENCE.md) +- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **ADRs**: See `docs/adr/` for architectural decision records diff --git a/docs/i18n/pl/FEATURES.md b/docs/i18n/pl/FEATURES.md deleted file mode 100644 index b5050f750e..0000000000 --- a/docs/i18n/pl/FEATURES.md +++ /dev/null @@ -1,147 +0,0 @@ -# OmniRoute โ€” Dashboard Features Gallery (Polski) - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) - -> ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../docs/FEATURES.md) - ---- - -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 (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. - -![Providers Dashboard](screenshots/01-providers.png) - ---- - -## ๐ŸŽจ Combos - -Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. - -![Combos Dashboard](screenshots/02-combos.png) - ---- - -## ๐Ÿ“Š Analytics - -Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. - -![Analytics Dashboard](screenshots/03-analytics.png) - ---- - -## ๐Ÿฅ System Health - -Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. - -![Health Dashboard](screenshots/04-health.png) - ---- - -## ๐Ÿ”ง Translator Playground - -Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). - -![Translator Playground](screenshots/05-translator.png) - ---- - -## ๐ŸŽฎ Model Playground _(v2.0.9+)_ - -Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. - ---- - -## ๐ŸŽจ Themes _(v2.0.5+)_ - -Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. - ---- - -## โš™๏ธ Settings - -Comprehensive settings panel with tabs: - -- **General** โ€” System storage, backup management (export/import database) -- **Appearance** โ€” Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls -- **Security** โ€” API endpoint protection, custom provider blocking, IP filtering, session info -- **Routing** โ€” Model aliases, background task degradation -- **Resilience** โ€” Rate limit persistence, circuit breaker tuning -- **Advanced** โ€” Configuration overrides - -![Settings Dashboard](screenshots/06-settings.png) - ---- - -## ๐Ÿ”ง CLI Tools - -One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. - -![CLI Tools Dashboard](screenshots/07-cli-tools.png) - ---- - -## ๐Ÿค– CLI Agents _(v2.0.11+)_ - -Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: - -- **Installation status** โ€” Installed / Not Found with version detection -- **Protocol badges** โ€” stdio, HTTP, etc. -- **Custom agents** โ€” Register any CLI tool via form (name, binary, version command, spawn args) -- **CLI Fingerprint Matching** โ€” Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP - ---- - -## ๐Ÿ–ผ๏ธ Media _(v2.0.3+)_ - -Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. - ---- - -## ๐Ÿ“ Request Logs - -Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. - -![Usage Logs](screenshots/08-usage.png) - ---- - -## ๐ŸŒ API Endpoint - -Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. - -![Endpoint Dashboard](screenshots/09-endpoint.png) - ---- - -## ๐Ÿ”‘ API Key Management - -Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. - ---- - -## ๐Ÿ“‹ Audit Log - -Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. - ---- - -## ๐Ÿ–ฅ๏ธ Desktop Application - -Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. - -Key features: - -- Server readiness polling (no blank screen on cold start) -- System tray with port management -- Content Security Policy -- Single-instance lock -- Auto-update on restart -- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) -- Hardened Electron build packaging โ€” symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+) - -๐Ÿ“– See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/pl/MCP-SERVER.md b/docs/i18n/pl/MCP-SERVER.md deleted file mode 100644 index 829acd30b1..0000000000 --- a/docs/i18n/pl/MCP-SERVER.md +++ /dev/null @@ -1,87 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/MCP-SERVER.md) - ---- - -# OmniRoute MCP Server Documentation - -> Model Context Protocol server with 16 intelligent tools - -## Installation - -OmniRoute MCP is built-in. Start it with: - -```bash -omniroute --mcp -``` - -Or via the open-sse transport: - -```bash -# HTTP streamable transport (port 20130) -omniroute --dev # MCP auto-starts on /mcp endpoint -``` - -## IDE Configuration - -See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup. - ---- - -## Essential Tools (8) - -| Tool | Description | -| :------------------------------ | :--------------------------------------- | -| `omniroute_get_health` | Gateway health, circuit breakers, uptime | -| `omniroute_list_combos` | All configured combos with models | -| `omniroute_get_combo_metrics` | Performance metrics for a specific combo | -| `omniroute_switch_combo` | Switch active combo by ID/name | -| `omniroute_check_quota` | Quota status per provider or all | -| `omniroute_route_request` | Send a chat completion through OmniRoute | -| `omniroute_cost_report` | Cost analytics for a time period | -| `omniroute_list_models_catalog` | Full model catalog with capabilities | - -## Advanced Tools (8) - -| Tool | Description | -| :--------------------------------- | :---------------------------------------------- | -| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | -| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | -| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | -| `omniroute_test_combo` | Live-test all models in a combo | -| `omniroute_get_provider_metrics` | Detailed metrics for one provider | -| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | -| `omniroute_explain_route` | Explain a past routing decision | -| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | - -## Authentication - -MCP tools are authenticated via API key scopes. Each tool requires specific scopes: - -| Scope | Tools | -| :------------- | :----------------------------------------------- | -| `read:health` | get_health, get_provider_metrics | -| `read:combos` | list_combos, get_combo_metrics | -| `write:combos` | switch_combo | -| `read:quota` | check_quota | -| `write:route` | route_request, simulate_route, test_combo | -| `read:usage` | cost_report, get_session_snapshot, explain_route | -| `write:config` | set_budget_guard, set_resilience_profile | -| `read:models` | list_models_catalog, best_combo_for_task | - -## Audit Logging - -Every tool call is logged to `mcp_tool_audit` with: - -- Tool name, arguments, result -- Duration (ms), success/failure -- API key hash, timestamp - -## Files - -| File | Purpose | -| :------------------------------------------- | :------------------------------------------ | -| `open-sse/mcp-server/server.ts` | MCP server creation + 16 tool registrations | -| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport | -| `open-sse/mcp-server/auth.ts` | API key + scope validation | -| `open-sse/mcp-server/audit.ts` | Tool call audit logging | -| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers | diff --git a/docs/i18n/pl/README.md b/docs/i18n/pl/README.md index 35e056e8a1..3e964e500f 100644 --- a/docs/i18n/pl/README.md +++ b/docs/i18n/pl/README.md @@ -1,12 +1,12 @@ # ๐Ÿš€ OmniRoute โ€” The Free AI Gateway (Polski) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/README.md) --- ### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback. -_Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._ +_Your universal API proxy โ€” one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._ **Chat Completions โ€ข Embeddings โ€ข Image Generation โ€ข Video โ€ข Music โ€ข Audio โ€ข Reranking โ€ข **Web Search** โ€ข MCP Server โ€ข A2A Protocol โ€ข 100% TypeScript** @@ -46,15 +46,17 @@ _Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now wi > - `APP_LOG_FILE_PATH` > - `APP_LOG_MAX_FILE_SIZE` > - `APP_LOG_RETENTION_DAYS` +> - `APP_LOG_MAX_FILES` > - `APP_LOG_LEVEL` > - `APP_LOG_FORMAT` > - `CALL_LOG_RETENTION_DAYS` +> - `CALL_LOG_MAX_ENTRIES` > > For release details and upgrade notes, see the [CHANGELOG](CHANGELOG.md). --- -## ๐Ÿ†• What's New in v3.0.0 +## ๐Ÿ†• What's New > **Upgrading from v2.9.5?** โ€” See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes. @@ -274,7 +276,7 @@ Developers pay $20โ€“200/month for Claude Pro, Codex Pro, or GitHub Copilot. Eve - **Smart 4-Tier Fallback** โ€” If subscription quota runs out, automatically redirects to API Key โ†’ Cheap โ†’ Free with zero manual intervention - **Real-Time Quota Tracking** โ€” Shows token consumption in real-time with reset countdown (5h, daily, weekly) - **Multi-Account Support** โ€” Multiple accounts per provider with auto round-robin โ€” when one runs out, switches to the next -- **Custom Combos** โ€” Customizable fallback chains with 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Custom Combos** โ€” Customizable fallback chains with 9 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random) - **Codex Business Quotas** โ€” Business/Team workspace quota monitoring directly in the dashboard @@ -286,7 +288,7 @@ OpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If **How OmniRoute solves it:** -- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 67+ providers +- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 60+ providers - **Format Translation** โ€” Automatic and transparent: OpenAI โ†” Claude โ†” Gemini โ†” Responses API - **Response Sanitization** โ€” Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+ - **Role Normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI providers; `system` โ†’ `user` for GLM/ERNIE @@ -372,7 +374,7 @@ Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code.. - **CLI Tools Dashboard** โ€” Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline - **GitHub Copilot Config Generator** โ€” Generates `chatLanguageModels.json` for VS Code with bulk model selection - **Onboarding Wizard** โ€” Guided 4-step setup for first-time users -- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 67+ providers +- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 60+ providers @@ -419,7 +421,7 @@ When a call fails, the dev doesn't know if it was a rate limit, expired token, w - **SQLite Proxy Logs** โ€” Persistent logs that survive server restarts - **Translator Playground** โ€” 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time) - **Request Telemetry** โ€” p50/p95/p99 latency + X-Request-Id tracing -- **File-Based Logging with Rotation** โ€” Console interceptor captures everything to JSON log with size-based rotation +- **File-Based Logging with Rotation** โ€” App logs rotate by size, retention days, and archive count; call log artifacts rotate by retention days and file count - **System Info Report** โ€” `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage. @@ -514,7 +516,7 @@ Developers who want all responses in a specific language, with a specific tone, - **System Prompt Injection** โ€” Global prompt applied to all requests - **Thinking Budget Validation** โ€” Reasoning token allocation control per request (passthrough, auto, custom, adaptive) -- **6 Routing Strategies** โ€” Global strategies that determine how requests are distributed +- **9 Routing Strategies** โ€” Global strategies that determine how requests are distributed - **Wildcard Router** โ€” `provider/*` patterns route dynamically to any provider - **Combo Enable/Disable Toggle** โ€” Toggle combos directly from the dashboard - **Provider Toggle** โ€” Enable/disable all connections for a provider with one click @@ -581,7 +583,7 @@ Different clients should have least-privilege access to tool categories. **How OmniRoute solves it:** -- 9 granular MCP scopes for controlled tool access +- 10 granular MCP scopes for controlled tool access - Scope enforcement and visibility in MCP management UI - Safe default posture for operational tooling @@ -1325,19 +1327,19 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. ### ๐Ÿค– Agent & Protocol Operations (v2.0) -| Feature | What It Does | -| ------------------------------------- | -------------------------------------------------------------------------------------------------- | -| ๐Ÿ”ง **MCP Server (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) | -| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | -| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | -| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | -| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | -| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | -| ๐Ÿ” **MCP Scope Enforcement** | 9 granular scope permissions for controlled tool access | -| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | -| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | -| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | -| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | +| Feature | What It Does | +| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| ๐Ÿ”ง **MCP Server (25 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools | +| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | +| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | +| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | +| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | +| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | +| ๐Ÿ” **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access | +| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | +| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | +| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | +| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | ### ๐Ÿง  Routing & Intelligence @@ -1348,7 +1350,7 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. | ๐Ÿ”„ **Format Translation** | OpenAI โ†” Claude โ†” Gemini โ†” Responses with schema-safe conversions | | ๐Ÿ‘ฅ **Multi-Account Support** | Multiple accounts per provider with intelligent selection | | ๐Ÿ”„ **Auto Token Refresh** | OAuth tokens refresh automatically with retry | -| ๐ŸŽจ **Custom Combos** | 6 balancing strategies + fallback chain control | +| ๐ŸŽจ **Custom Combos** | 9 balancing strategies + fallback chain control | | ๐ŸŒ **Wildcard Router** | `provider/*` dynamic routing | | ๐Ÿง  **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits | | ๐Ÿ”€ **Model Aliases** | Built-in + custom model aliasing and migration safety | @@ -1949,6 +1951,7 @@ opencode - Request artifacts are written to `DATA_DIR/call_logs/` as one JSON file per request - Enable pipeline capture from Dashboard โ†’ Logs โ†’ Request Logs if you need detailed per-stage payloads - Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log` +- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed **Connection test shows "Invalid" for OpenAI-compatible providers** diff --git a/docs/i18n/pl/RELEASE_CHECKLIST.md b/docs/i18n/pl/RELEASE_CHECKLIST.md deleted file mode 100644 index 903e812c3f..0000000000 --- a/docs/i18n/pl/RELEASE_CHECKLIST.md +++ /dev/null @@ -1,37 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/RELEASE_CHECKLIST.md) - ---- - -# Release Checklist - -Use this checklist before tagging or publishing a new OmniRoute release. - -## Version and Changelog - -1. Bump `package.json` version (`x.y.z`) in the release branch. -2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: - - `## [x.y.z] โ€” YYYY-MM-DD` -3. Keep `## [Unreleased]` as the first changelog section for upcoming work. -4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. - -## API Docs - -1. Update `docs/openapi.yaml`: - - `info.version` must equal `package.json` version. -2. Validate endpoint examples if API contracts changed. - -## Runtime Docs - -1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. -2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. -3. Update localized docs if source docs changed significantly. - -## Automated Check - -Run the sync guard locally before opening PR: - -```bash -npm run check:docs-sync -``` - -CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/pl/SECURITY.md b/docs/i18n/pl/SECURITY.md new file mode 100644 index 0000000000..79d98e35b6 --- /dev/null +++ b/docs/i18n/pl/SECURITY.md @@ -0,0 +1,179 @@ +# Security Policy (Polski) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../SECURITY.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/SECURITY.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/SECURITY.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/SECURITY.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/SECURITY.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/SECURITY.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/SECURITY.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/SECURITY.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/SECURITY.md) + +--- + +## 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 | +| ------- | -------------- | +| 3.4.x | โœ… Active | +| 3.0.x | โœ… Security | +| < 3.0.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 | +| **MCP Scopes** | 10 granular scopes for MCP tool access control | + +### ๐Ÿ›ก๏ธ 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:::` +- 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** | Allowlist/blocklist IP ranges in dashboard | +| **Rate Limiting** | Per-provider rate limits with automatic backoff | +| **Anti-Thundering Herd** | Mutex + per-connection locking prevents cascading 502s | +| **TLS Fingerprint** | Browser-like TLS fingerprint spoofing to reduce bot detection | +| **CLI Fingerprint** | Per-provider header/body ordering to match native CLI signatures | + +### ๐Ÿ”Œ Resilience & Availability + +| 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 `CALL_LOG_RETENTION_DAYS` | +| **No-Log Opt-out** | Per API key `noLog` flag disables request logging | +| **Audit Log** | Administrative actions tracked in `audit_log` table | +| **MCP Audit** | SQLite-backed audit logging for all MCP tool calls | +| **Zod Validation** | All API inputs validated with Zod v4 schemas at module load | + +--- + +## 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 +- Provider constants validated at module load via Zod (`src/shared/validation/providerSchema.ts`) diff --git a/docs/i18n/pl/TROUBLESHOOTING.md b/docs/i18n/pl/TROUBLESHOOTING.md deleted file mode 100644 index 63c148000a..0000000000 --- a/docs/i18n/pl/TROUBLESHOOTING.md +++ /dev/null @@ -1,258 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/TROUBLESHOOTING.md) - ---- - -# Troubleshooting - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/TROUBLESHOOTING.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/TROUBLESHOOTING.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/TROUBLESHOOTING.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/TROUBLESHOOTING.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/TROUBLESHOOTING.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/TROUBLESHOOTING.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/TROUBLESHOOTING.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/TROUBLESHOOTING.md) - -Common problems and solutions for OmniRoute. - ---- - -## Quick Fixes - -| Problem | Solution | -| ----------------------------- | ------------------------------------------------------------------ | -| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | -| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | -| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | -| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | -| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | - ---- - -## Provider Issues - -### "Language model did not provide messages" - -**Cause:** Provider quota exhausted. - -**Fix:** - -1. 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, Qoder) 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}/storage.sqlite` (providers, combos, aliases, keys, settings) -- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` -- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) - ---- - -## Circuit Breaker Issues - -### Provider stuck in OPEN state - -When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. - -**Fix:** - -1. 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 -- **SDK returns raw string instead of object** โ€” Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures -- **GLM/ERNIE rejects `system` role** โ€” Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models -- **`developer` role not recognized** โ€” Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers -- **`json_schema` not working with Gemini** โ€” Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` - ---- - -## Resilience Settings - -### Auto rate-limit not triggering - -- 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. - ---- - -## Optional RAG / LLM failure taxonomy (16 problems) - -Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. - -In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. - -If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: - -- retrieval drift and broken context boundaries -- empty or stale indexes and vector stores -- embedding versus semantic mismatch -- prompt assembly and context window issues -- logic collapse and overconfident answers -- long chain and agent coordination failures -- multi agent memory and role drift -- deployment and bootstrap ordering problems - -The idea is simple: - -1. When you investigate a bad response, capture: - - user task and request - - route or provider combo in OmniRoute - - any RAG context used downstream (retrieved documents, tool calls, etc) -2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` โ€ฆ `No.16`). -3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. -4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. - -Full text and concrete recipes live here (MIT license, text only): - -[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) - -You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. - ---- - -## Still Stuck? - -- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details -- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints -- **Health Dashboard**: Check **Dashboard โ†’ Health** for real-time system status -- **Translator**: Use **Dashboard โ†’ Translator** to debug format issues diff --git a/docs/i18n/pl/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/pl/VM_DEPLOYMENT_GUIDE.md deleted file mode 100644 index ca1e2fd8a6..0000000000 --- a/docs/i18n/pl/VM_DEPLOYMENT_GUIDE.md +++ /dev/null @@ -1,401 +0,0 @@ -# OmniRoute โ€” Przewodnik wdraลผania na maszynie wirtualnej z Cloudflare - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](../pt-BR/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](../es/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](../fr/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](../it/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](../ru/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](../zh-CN/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](../de/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](../in/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](../th/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](../uk-UA/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](../ar/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](../ja/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](../vi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](../bg/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](../da/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](../fi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](../he/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](../hu/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](../id/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](../ko/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](../ms/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](../nl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](../no/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](../pt/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](../ro/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](../pl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](../sk/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](../sv/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](../phi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](../cs/VM_DEPLOYMENT_GUIDE.md) - -Kompletny przewodnik dotyczฤ…cy instalacji i konfiguracji OmniRoute na maszynie wirtualnej (VPS) z domenฤ… zarzฤ…dzanฤ… przez Cloudflare. - ---- - -## Warunki wstฤ™pne - -| Pozycja | Minimalne | Polecane | -| --------------------- | --------------------------- | --------------------- | -| **Procesor** | 1 procesor wirtualny | 2 procesory wirtualne | -| **RAM** | 1 GB | 2 GB | -| **Dysk** | Dysk SSD 10 GB | Dysk SSD 25 GB | -| **System operacyjny** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS | -| **Domena** | Zarejestrowany w Cloudflare | โ€” | -| **Doker** | Silnik Dockera 24+ | Doker 27+ | - -**Testowani dostawcy**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. - ---- - -## 1. Skonfiguruj maszynฤ™ wirtualnฤ… - -### 1.1 Utwรณrz instancjฤ™ - -U preferowanego dostawcy VPS: - -- Wybierz Ubuntu 24.04 LTS -- Wybierz plan minimalny (1 vCPU / 1 GB RAM) -- Ustaw silne hasล‚o roota lub skonfiguruj klucz SSH -- Zanotuj **publiczny adres IP** (np. `203.0.113.10`) - -### 1.2 Poล‚ฤ…cz siฤ™ przez SSH - -```bash -ssh root@203.0.113.10 -``` - -### 1.3 Zaktualizuj system - -```bash -apt update && apt upgrade -y -``` - -### 1.4 Zainstaluj Dockera - -```bash -# Install dependencies -apt install -y ca-certificates curl gnupg - -# Add official Docker repository -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 Zainstaluj nginx - -```bash -apt install -y nginx -``` - -### 1.6 Skonfiguruj zaporฤ™ sieciowฤ… (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 -``` - -> **Wskazรณwka**: Dla maksymalnego bezpieczeล„stwa ogranicz porty 80 i 443 tylko do adresรณw IP Cloudflare. Zobacz sekcjฤ™ [Advanced Security](#advanced-security). - ---- - -## 2. Zainstaluj OmniRoute - -### 2.1 Utwรณrz katalog konfiguracyjny - -```bash -mkdir -p /opt/omniroute -``` - -### 2.2 Utwรณrz plik zmiennych ล›rodowiskowych - -```bash -cat > /opt/omniroute/.env << โ€˜EOFโ€™ -# === Security === -JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY -INITIAL_PASSWORD=YourSecurePassword123! -API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY -STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY -STORAGE_ENCRYPTION_KEY_VERSION=v1 -MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT - -# === 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 (change to your domain) === -BASE_URL=https://llms.seudominio.com -NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com - -# === Cloud Sync (optional) === -# CLOUD_URL=https://cloud.omniroute.online -# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online -EOF -``` - -> โš ๏ธ **WAลปNE**: Wygeneruj unikalne tajne klucze! Uลผyj `openssl rand -hex 32` dla kaลผdego klucza. - -### 2.3 Uruchom kontener - -```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 Sprawdลบ, czy dziaล‚a - -```bash -docker ps | grep omniroute -docker logs omniroute --tail 20 -``` - -Powinien wyล›wietliฤ‡: `[DB] SQLite database ready` i `listening on port 20128`. - ---- - -## 3. Skonfiguruj nginx (odwrotny serwer proxy) - -### 3.1 Wygeneruj certyfikat SSL (Cloudflare Origin) - -W panelu Cloudflare: - -1. Przejdลบ do **SSL/TLS โ†’ Serwer Origin** -2. Kliknij **Utwรณrz certyfikat** -3. Zachowaj ustawienia domyล›lne (15 lat, \*.twojadomena.com) -4. Skopiuj **Certyfikat pochodzenia** i **Klucz prywatny** - -```bash -mkdir -p /etc/nginx/ssl - -# Paste the certificate -nano /etc/nginx/ssl/origin.crt - -# Paste the private key -nano /etc/nginx/ssl/origin.key - -chmod 600 /etc/nginx/ssl/origin.key -``` - -### 3.2 Konfiguracja Nginx - -```bash -cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ -# Default server โ€” blocks direct access via 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.yourdomain.com; # Change to your domain - - 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.yourdomain.com; - return 301 https://$server_name$request_uri; -} -NGINX -``` - -### 3.3 Wล‚ฤ…cz i przetestuj - -```bash -# Remove default configuration -rm -f /etc/nginx/sites-enabled/default - -# Enable OmniRoute -ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute - -# Test and reload -nginx -t && systemctl reload nginx -``` - ---- - -## 4. Skonfiguruj DNS Cloudflare - -### 4.1 Dodaj rekord DNS - -W panelu Cloudflare โ†’ DNS: - -| Wpisz | Imiฤ™ | Treล›ฤ‡ | Peล‚nomocnik | -| ----- | ------ | -------------------------------------- | ----------- | -| | `llms` | `203.0.113.10` (IP maszyny wirtualnej) | โœ…Przesล‚ane | - -### 4.2 Skonfiguruj SSL - -W obszarze **SSL/TLS โ†’ Przeglฤ…d**: - -- Tryb: **Peล‚ny (ล›cisล‚y)** - -W obszarze **SSL/TLS โ†’ Certyfikaty brzegowe**: - -- Zawsze uลผywaj protokoล‚u HTTPS: โœ… Wล‚ฤ…cz -- Minimalna wersja TLS: TLS 1.2 -- Automatyczne przepisywanie protokoล‚u HTTPS: โœ… Wล‚ฤ…czone - -### 4.3 Testowanie - -```bash -curl -sI https://llms.seudominio.com/health -# Should return HTTP/2 200 -``` - ---- - -## 5. Obsล‚uga i konserwacja - -### Uaktualnij do nowej wersji - -```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 -``` - -### Wyล›wietl logi - -```bash -docker logs -f omniroute # Real-time stream -docker logs omniroute --tail 50 # Last 50 lines -``` - -### Rฤ™czna kopia zapasowa bazy danych - -```bash -# Copy data from the volume to the host -docker cp omniroute:/app/data ./backup-$(date +%F) - -# Or compress the entire volume -docker run --rm -v omniroute-data:/data -v $(pwd):/backup \ - alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data -``` - -### Przywrรณฤ‡ z kopii zapasowej - -```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. Zaawansowane zabezpieczenia - -### Ogranicz nginx do adresรณw IP Cloudflare - -```bash -cat > /etc/nginx/cloudflare-ips.conf << โ€˜CFโ€™ -# Cloudflare IPv4 ranges โ€” update periodically -# 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 -``` - -Dodaj nastฤ™pujฤ…ce polecenie do `nginx.conf` wewnฤ…trz bloku `http {}`: - -```nginx -include /etc/nginx/cloudflare-ips.conf; -``` - -### Zainstaluj Fail2ban - -```bash -apt install -y fail2ban -systemctl enable fail2ban -systemctl start fail2ban - -# Check status -fail2ban-client status sshd -``` - -### Zablokuj bezpoล›redni dostฤ™p do portu Dockera - -```bash -# Prevent direct external access to port 20128 -iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP -iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT - -# Persist the rules -apt install -y iptables-persistent -netfilter-persistent save -``` - ---- - -## 7. Wdrรณลผ do pracownikรณw Cloudflare (opcjonalnie) - -W przypadku zdalnego dostฤ™pu za poล›rednictwem Cloudflare Workers (bez bezpoล›redniego ujawniania maszyny wirtualnej): - -```bash -# In the local repository -cd omnirouteCloud -npm install -npx wrangler login -npx wrangler deploy -``` - -Zobacz peล‚nฤ… dokumentacjฤ™ pod adresem [omnirouteCloud/README.md](../omnirouteCloud/README.md). - ---- - -## Podsumowanie portu - -| Port | Usล‚uga | Dostฤ™p | -| ----- | ----------- | ------------------------------ | -| 22 | SSH | Publiczne (z funkcjฤ… Fail2ban) | -| 80 | Nginx HTTP | Przekierowanie โ†’ HTTPS | -| 443 | nginx HTTPS | Przez serwer proxy Cloudflare | -| 20128 | OmniRoute | Tylko Localhost (przez Nginx) | diff --git a/docs/i18n/pl/docs/A2A-SERVER.md b/docs/i18n/pl/docs/A2A-SERVER.md new file mode 100644 index 0000000000..b44ec69ba2 --- /dev/null +++ b/docs/i18n/pl/docs/A2A-SERVER.md @@ -0,0 +1,200 @@ +# OmniRoute A2A Server Documentation (Polski) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/A2A-SERVER.md) + +--- + +> Agent-to-Agent Protocol v0.3 โ€” OmniRoute as an intelligent routing agent + +## Agent Discovery + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements. + +--- + +## Authentication + +All `/a2a` requests require an API key via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server, authentication is bypassed. + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Sends a message to a skill and waits for the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a hello world in Python"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "uuid", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "..." }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}} + +: heartbeat 2026-03-03T17:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Available Skills + +| Skill | Description | +| :----------------- | :------------------------------------------------------------------------------------------------------------------------------ | +| `smart-routing` | Routes prompts through OmniRoute's intelligent pipeline. Returns response with routing explanation, cost, and resilience trace. | +| `quota-management` | Answers natural-language queries about provider quotas, suggests free combos, and provides quota rankings. | + +--- + +## Task Lifecycle + +``` +submitted โ†’ working โ†’ completed + โ†’ failed + โ†’ cancelled +``` + +- Tasks expire after 5 minutes (configurable) +- Terminal states: `completed`, `failed`, `cancelled` +- Event log tracks every state transition + +--- + +## Error Codes + +| Code | Meaning | +| :----- | :----------------------------- | +| -32700 | Parse error (invalid JSON) | +| -32600 | Invalid request / Unauthorized | +| -32601 | Method or skill not found | +| -32602 | Invalid params | +| -32603 | Internal error | + +--- + +## Integration Examples + +### Python (requests) + +```python +import requests + +resp = requests.post("http://localhost:20128/a2a", json={ + "jsonrpc": "2.0", "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Hello"}] + } +}, headers={"Authorization": "Bearer YOUR_KEY"}) + +result = resp.json()["result"] +print(result["artifacts"][0]["content"]) +print(result["metadata"]["routing_explanation"]) +``` + +### TypeScript (fetch) + +```typescript +const resp = await fetch("http://localhost:20128/a2a", { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: "Bearer YOUR_KEY", + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "1", + method: "message/send", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Hello" }], + }, + }), +}); +const { result } = await resp.json(); +console.log(result.metadata.routing_explanation); +``` diff --git a/docs/i18n/pl/docs/API_REFERENCE.md b/docs/i18n/pl/docs/API_REFERENCE.md new file mode 100644 index 0000000000..b5b0269554 --- /dev/null +++ b/docs/i18n/pl/docs/API_REFERENCE.md @@ -0,0 +1,465 @@ +# API Reference (Polski) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/API_REFERENCE.md) + +--- + +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 | +| `X-Session-Id` | Request | Sticky session key for external session affinity | +| `x_session_id` | Request | Underscore variant also accepted (direct HTTP) | +| `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 | +| `X-OmniRoute-Session-Id` | Response | Effective session ID used by OmniRoute | + +> Nginx note: if you rely on underscore headers (for example `x_session_id`), enable `underscores_in_headers 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/stats + +# Clear all caches +DELETE /api/cache/stats +``` + +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/PATCH | 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 + provider summary (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`) | +| `/api/cache/stats` | 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 | + +### Tunnels + +| Endpoint | Method | Description | +| -------------------------- | ------ | ----------------------------------------------------------------------- | +| `/api/tunnels/cloudflared` | GET | Read Cloudflare Quick Tunnel install/runtime status for the dashboard | +| `/api/tunnels/cloudflared` | POST | Enable or disable the Cloudflare Quick Tunnel (`action=enable/disable`) | + +### 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`. + +### ACP Agents + +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | + +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). + +### Resilience & Rate Limits + +| Endpoint | Method | Description | +| ----------------------- | --------- | ------------------------------- | +| `/api/resilience` | GET/PATCH | 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` diff --git a/docs/i18n/pl/docs/ARCHITECTURE.md b/docs/i18n/pl/docs/ARCHITECTURE.md new file mode 100644 index 0000000000..7af92ad9d6 --- /dev/null +++ b/docs/i18n/pl/docs/ARCHITECTURE.md @@ -0,0 +1,814 @@ +# OmniRoute Architecture (Polski) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/ARCHITECTURE.md) + +--- + +_Last updated: 2026-03-28_ + +## 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 (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developerโ†’system, systemโ†’user) for cross-provider compatibility +- Structured output conversion (json_schema โ†’ Gemini responseSchema) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) +- Global system prompt injection +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout โ†’ budget โ†’ fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) + +Primary runtime model: + +- Next.js 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.) + +## Dashboard Surface (Current) + +Main pages under `src/app/(dashboard)/dashboard/`: + +- `/dashboard` โ€” quick start + provider overview +- `/dashboard/endpoint` โ€” endpoint proxy + MCP + A2A + API endpoint tabs +- `/dashboard/providers` โ€” provider connections and credentials +- `/dashboard/combos` โ€” combo strategies, templates, model routing rules +- `/dashboard/costs` โ€” cost aggregation and pricing visibility +- `/dashboard/analytics` โ€” usage analytics and evaluations +- `/dashboard/limits` โ€” quota/rate controls +- `/dashboard/cli-tools` โ€” CLI onboarding, runtime detection, config generation +- `/dashboard/agents` โ€” detected ACP agents + custom agent registration +- `/dashboard/media` โ€” image/video/music playground +- `/dashboard/search-tools` โ€” search provider testing and history +- `/dashboard/health` โ€” uptime, circuit breakers, rate limits +- `/dashboard/logs` โ€” request/proxy/audit/console logs +- `/dashboard/settings` โ€” system settings tabs (general, routing, combo defaults, etc.) +- `/dashboard/api-manager` โ€” API key lifecycle and model permissions + +## 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[(storage.sqlite)] + UDB[(usage tables + log artifacts)] + end + + subgraph Upstreams[Upstream Providers] + P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/Qoder/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/route.ts` (GET) +- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- OAuth: `src/app/api/oauth/*` +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` +- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI tooling helpers: `src/app/api/cli-tools/*` +- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) +- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) โ€” provider profiles, circuit breaker, rate limit state +- Resilience reset: `src/app/api/resilience/reset` (POST) โ€” reset breakers + cooldowns +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) +- Telemetry: `src/app/api/telemetry/summary` (GET) +- Budget: `src/app/api/usage/budget` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Policies: `src/app/api/policies` (GET/POST) + +## 2) SSE + 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` +- Response sanitization: `open-sse/handlers/responseSanitizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.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`, `qoder.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 (SQLite): + +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** + +Usage persistence: + +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present + +Domain State DB (SQLite): + +- `src/lib/db/domainState.ts` โ€” CRUD operations 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`, `src/shared/services/modelSyncScheduler.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Periodic task: `src/shared/services/modelSyncScheduler.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. Combo routing adds one extra guard: provider-scoped 400s such as upstream content-block and role-validation failures are treated as model-local failures so later combo targets can still run. + +## 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: + +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` + +## Deployment Topology + +```mermaid +flowchart LR + 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[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] + end + + subgraph External[External Services] + Providers[AI Providers] + SyncCloud[Cloud Sync Service] + end + + CLI --> Next + Browser --> Next + Next --> Core + Next --> MainDB + Core --> MainDB + Core --> UsageDB + Core --> Providers + Next --> SyncCloud +``` + +## Module Mapping (Decision-Critical) + +### Route and API Modules + +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle +- `src/app/api/models/alias`: alias management +- `src/app/api/combos*`: fallback combo management +- `src/app/api/pricing`: pricing overrides for cost calculation +- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers +- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) +- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) +- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) +- `src/app/api/sessions`: active session listing (GET) +- `src/app/api/rate-limits`: per-account rate limit status (GET) + +### Routing and Execution Core + +- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior + +### Translation Registry and Format Converters + +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` +- Format constants: `open-sse/translator/formats.ts` + +### Persistence + +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables + +## Provider Executor Coverage (Strategy Pattern) + +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. + +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, Qoder, 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 | +| Qoder | openai | OAuth (Basic) | โœ… | โœ… | โœ… | โš ๏ธ Per request | +| OpenRouter | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| GLM/Kimi/MiniMax | claude | API Key | โœ… | โœ… | โŒ | โŒ | +| DeepSeek | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Groq | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| xAI (Grok) | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Mistral | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Perplexity | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Together AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Fireworks AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Cerebras | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Cohere | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| NVIDIA NIM | openai | API Key | โœ… | โœ… | โŒ | โŒ | + +## Format Translation Coverage + +Detected source formats include: + +- `openai` +- `openai-responses` +- `claude` +- `gemini` + +Target formats include: + +- OpenAI chat/Responses +- Claude +- Gemini/Gemini-CLI/Antigravity envelope +- Kiro +- Cursor + +Translations use **OpenAI as the hub format** โ€” all conversions go through OpenAI as intermediate: + +``` +Source Format โ†’ OpenAI (hub) โ†’ Target Format +``` + +Translations are selected dynamically based on source payload shape and provider target format. + +Additional processing layers in the translation pipeline: + +- **Response sanitization** โ€” Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI targets; merges `system` โ†’ `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** โ€” Parses `...` blocks from content into `reasoning_content` field +- **Structured output** โ€” Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` + +## Supported API Endpoints + +| 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` | Provider Models | Provider model metadata backing custom and managed available models | + +## 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 `/logs//` 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 + +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON โ†’ SQLite migration compatibility path + +## Observability and Operational Signals + +Runtime visibility sources: + +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- four-stage detailed payload captures in SQLite (`request_detail_logs`) when `settings.detailed_logs_enabled=true` +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption + +Detailed request payload capture stores up to four JSON payload stages per routed call: + +- raw request received from the client +- translated request actually sent upstream +- provider response reconstructed as JSON; streamed responses are compacted to the final summary plus stream metadata +- final client response returned by OmniRoute; streamed responses are stored in the same compact summary form + +## Security-Sensitive Boundaries + +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics + +## Environment and Runtime Matrix + +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` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). + +## Operational Verification Checklist + +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: +- `GET /api/settings` +- `GET /api/v1/models` +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/pl/docs/AUTO-COMBO.md b/docs/i18n/pl/docs/AUTO-COMBO.md new file mode 100644 index 0000000000..db096ff398 --- /dev/null +++ b/docs/i18n/pl/docs/AUTO-COMBO.md @@ -0,0 +1,67 @@ +# OmniRoute Auto-Combo Engine (Polski) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/AUTO-COMBO.md) + +--- + +> Self-managing model chains with adaptive scoring + +## How It Works + +The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**: + +| Factor | Weight | Description | +| :--------- | :----- | :---------------------------------------------- | +| Quota | 0.20 | Remaining capacity [0..1] | +| Health | 0.25 | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 | +| CostInv | 0.20 | Inverse cost (cheaper = higher score) | +| LatencyInv | 0.15 | Inverse p95 latency (faster = higher) | +| TaskFit | 0.10 | Model ร— task type fitness score | +| Stability | 0.10 | Low variance in latency/errors | + +## Mode Packs + +| Pack | Focus | Key Weight | +| :---------------------- | :----------- | :--------------- | +| ๐Ÿš€ **Ship Fast** | Speed | latencyInv: 0.35 | +| ๐Ÿ’ฐ **Cost Saver** | Economy | costInv: 0.40 | +| ๐ŸŽฏ **Quality First** | Best model | taskFit: 0.40 | +| ๐Ÿ“ก **Offline Friendly** | Availability | quota: 0.40 | + +## Self-Healing + +- **Temporary exclusion**: Score < 0.2 โ†’ excluded for 5 min (progressive backoff, max 30 min) +- **Circuit breaker awareness**: OPEN โ†’ auto-excluded; HALF_OPEN โ†’ probe requests +- **Incident mode**: >50% OPEN โ†’ disable exploration, maximize stability +- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout + +## Bandit Exploration + +5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode. + +## API + +```bash +# Create auto-combo +curl -X POST http://localhost:20128/api/combos/auto \ + -H "Content-Type: application/json" \ + -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}' + +# List auto-combos +curl http://localhost:20128/api/combos/auto +``` + +## Task Fitness + +30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` โ†’ high coding score). + +## Files + +| File | Purpose | +| :------------------------------------------- | :------------------------------------ | +| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization | +| `open-sse/services/autoCombo/taskFitness.ts` | Model ร— task fitness lookup | +| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap | +| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode | +| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles | +| `src/app/api/combos/auto/route.ts` | REST API | diff --git a/docs/i18n/pl/docs/CLI-TOOLS.md b/docs/i18n/pl/docs/CLI-TOOLS.md new file mode 100644 index 0000000000..bc00e6319b --- /dev/null +++ b/docs/i18n/pl/docs/CLI-TOOLS.md @@ -0,0 +1,348 @@ +# CLI Tools Setup Guide โ€” OmniRoute (Polski) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CLI-TOOLS.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CLI-TOOLS.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CLI-TOOLS.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CLI-TOOLS.md) + +--- + +This guide explains how to install and configure all supported AI coding CLI tools +to use **OmniRoute** as the unified backend, giving you centralized key management, +cost tracking, model switching, and request logging across every tool. + +--- + +## How It Works + +``` +Claude / Codex / OpenCode / Cline / KiloCode / Continue / Kiro / Cursor / Copilot + โ”‚ + โ–ผ (all point to OmniRoute) + http://YOUR_SERVER:20128/v1 + โ”‚ + โ–ผ (OmniRoute routes to the right provider) + Anthropic / OpenAI / Gemini / DeepSeek / Groq / Mistral / ... +``` + +**Benefits:** + +- One API key to manage all tools +- Cost tracking across all CLIs in the dashboard +- Model switching without reconfiguring every tool +- Works locally and on remote servers (VPS) + +--- + +## Supported Tools (Dashboard Source of Truth) + +The dashboard cards in `/dashboard/cli-tools` are generated from `src/shared/constants/cliTools.ts`. +Current list (v3.0.0-rc.16): + +| Tool | ID | Command | Setup Mode | Install Method | +| ------------------ | ------------- | ---------- | ---------- | -------------- | +| **Claude Code** | `claude` | `claude` | env | npm | +| **OpenAI Codex** | `codex` | `codex` | custom | npm | +| **Factory Droid** | `droid` | `droid` | custom | bundled/CLI | +| **OpenClaw** | `openclaw` | `openclaw` | custom | bundled/CLI | +| **Cursor** | `cursor` | app | guide | desktop app | +| **Cline** | `cline` | `cline` | custom | npm | +| **Kilo Code** | `kilo` | `kilocode` | custom | npm | +| **Continue** | `continue` | extension | guide | VS Code | +| **Antigravity** | `antigravity` | internal | mitm | OmniRoute | +| **GitHub Copilot** | `copilot` | extension | custom | VS Code | +| **OpenCode** | `opencode` | `opencode` | guide | npm | +| **Kiro AI** | `kiro` | app/cli | mitm | desktop/CLI | + +### CLI fingerprint sync (Agents + Settings) + +`/dashboard/agents` and `Settings > CLI Fingerprint` use `src/shared/constants/cliCompatProviders.ts`. +This keeps provider IDs aligned with CLI cards and legacy IDs. + +| CLI ID | Fingerprint Provider ID | +| ---------------------------------------------------------------------------------------------------- | ----------------------- | +| `kilo` | `kilocode` | +| `copilot` | `github` | +| `claude` / `codex` / `antigravity` / `kiro` / `cursor` / `cline` / `opencode` / `droid` / `openclaw` | same ID | + +Legacy IDs still accepted for compatibility: `copilot`, `kimi-coding`, `qwen`. + +--- + +## Step 1 โ€” Get an OmniRoute API Key + +1. Open the OmniRoute dashboard โ†’ **API Manager** (`/dashboard/api-manager`) +2. Click **Create API Key** +3. Give it a name (e.g. `cli-tools`) and select all permissions +4. Copy the key โ€” you'll need it for every CLI below + +> Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` + +--- + +## Step 2 โ€” Install CLI Tools + +All npm-based tools require Node.js 18+: + +```bash +# Claude Code (Anthropic) +npm install -g @anthropic-ai/claude-code + +# OpenAI Codex +npm install -g @openai/codex + +# OpenCode +npm install -g opencode-ai + +# Cline +npm install -g cline + +# KiloCode +npm install -g kilocode + +# Kiro CLI (Amazon โ€” requires curl + unzip) +apt-get install -y unzip # on Debian/Ubuntu +curl -fsSL https://cli.kiro.dev/install | bash +export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc +``` + +**Verify:** + +```bash +claude --version # 2.x.x +codex --version # 0.x.x +opencode --version # x.x.x +cline --version # 2.x.x +kilocode --version # x.x.x (or: kilo --version) +kiro-cli --version # 1.x.x +``` + +--- + +## Step 3 โ€” Set Global Environment Variables + +Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`: + +```bash +# OmniRoute Universal Endpoint +export OPENAI_BASE_URL="http://localhost:20128/v1" +export OPENAI_API_KEY="sk-your-omniroute-key" +export ANTHROPIC_BASE_URL="http://localhost:20128/v1" +export ANTHROPIC_API_KEY="sk-your-omniroute-key" +export GEMINI_BASE_URL="http://localhost:20128/v1" +export GEMINI_API_KEY="sk-your-omniroute-key" +``` + +> For a **remote server** replace `localhost:20128` with the server IP or domain, +> e.g. `http://192.168.0.15:20128`. + +--- + +## Step 4 โ€” Configure Each Tool + +### Claude Code + +```bash +# Via CLI: +claude config set --global api-base-url http://localhost:20128/v1 + +# Or create ~/.claude/settings.json: +mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF +{ + "apiBaseUrl": "http://localhost:20128/v1", + "apiKey": "sk-your-omniroute-key" +} +EOF +``` + +**Test:** `claude "say hello"` + +--- + +### OpenAI Codex + +```bash +mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF +model: auto +apiKey: sk-your-omniroute-key +apiBaseUrl: http://localhost:20128/v1 +EOF +``` + +**Test:** `codex "what is 2+2?"` + +--- + +### OpenCode + +```bash +mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF +[provider.openai] +base_url = "http://localhost:20128/v1" +api_key = "sk-your-omniroute-key" +EOF +``` + +**Test:** `opencode` + +--- + +### Cline (CLI or VS Code) + +**CLI mode:** + +```bash +mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF +{ + "apiProvider": "openai", + "openAiBaseUrl": "http://localhost:20128/v1", + "openAiApiKey": "sk-your-omniroute-key" +} +EOF +``` + +**VS Code mode:** +Cline extension settings โ†’ API Provider: `OpenAI Compatible` โ†’ Base URL: `http://localhost:20128/v1` + +Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ Cline โ†’ Apply Config**. + +--- + +### KiloCode (CLI or VS Code) + +**CLI mode:** + +```bash +kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key +``` + +**VS Code settings:** + +```json +{ + "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", + "kilo-code.apiKey": "sk-your-omniroute-key" +} +``` + +Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ KiloCode โ†’ Apply Config**. + +--- + +### Continue (VS Code Extension) + +Edit `~/.continue/config.yaml`: + +```yaml +models: + - name: OmniRoute + provider: openai + model: auto + apiBase: http://localhost:20128/v1 + apiKey: sk-your-omniroute-key + default: true +``` + +Restart VS Code after editing. + +--- + +### Kiro CLI (Amazon) + +```bash +# Login to your AWS/Kiro account: +kiro-cli login + +# The CLI uses its own auth โ€” OmniRoute is not needed as backend for Kiro CLI itself. +# Use kiro-cli alongside OmniRoute for other tools. +kiro-cli status +``` + +--- + +### Cursor (Desktop App) + +> **Note:** Cursor routes requests through its cloud. For OmniRoute integration, +> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL. + +Via GUI: **Settings โ†’ Models โ†’ OpenAI API Key** + +- Base URL: `https://your-domain.com/v1` +- API Key: your OmniRoute key + +--- + +## Dashboard Auto-Configuration + +The OmniRoute dashboard automates configuration for most tools: + +1. Go to `http://localhost:20128/dashboard/cli-tools` +2. Expand any tool card +3. Select your API key from the dropdown +4. Click **Apply Config** (if tool is detected as installed) +5. Or copy the generated config snippet manually + +--- + +## Built-in Agents: Droid & OpenClaw + +**Droid** and **OpenClaw** are AI agents built directly into OmniRoute โ€” no installation needed. +They run as internal routes and use OmniRoute's model routing automatically. + +- Access: `http://localhost:20128/dashboard/agents` +- Configure: same combos and providers as all other tools +- No API key or CLI install required + +--- + +## Available API Endpoints + +| Endpoint | Description | Use For | +| -------------------------- | ----------------------------- | --------------------------- | +| `/v1/chat/completions` | Standard chat (all providers) | All modern tools | +| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows | +| `/v1/completions` | Legacy text completions | Older tools using `prompt:` | +| `/v1/embeddings` | Text embeddings | RAG, search | +| `/v1/images/generations` | Image generation | DALL-E, Flux, etc. | +| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS | +| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI | + +--- + +## Rozwiฤ…zywanie problemรณw + +| Error | Cause | Fix | +| ------------------------- | ----------------------- | ------------------------------------------ | +| `Connection refused` | OmniRoute not running | `pm2 start omniroute` | +| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` | +| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` | +| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` | +| CLI shows "not installed" | Binary not in PATH | Check `which ` | +| `kiro-cli: not found` | Not in PATH | `export PATH="$HOME/.local/bin:$PATH"` | + +--- + +## Quick Setup Script (One Command) + +```bash +# Install all CLIs and configure for OmniRoute (replace with your key and server URL) +OMNIROUTE_URL="http://localhost:20128/v1" +OMNIROUTE_KEY="sk-your-omniroute-key" + +npm install -g @anthropic-ai/claude-code @openai/codex opencode-ai cline kilocode + +# Kiro CLI +apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash + +# Write configs +mkdir -p ~/.claude ~/.codex ~/.config/opencode ~/.continue + +cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" +cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" +cat >> ~/.bashrc << EOF +export OPENAI_BASE_URL="$OMNIROUTE_URL" +export OPENAI_API_KEY="$OMNIROUTE_KEY" +export ANTHROPIC_BASE_URL="$OMNIROUTE_URL" +export ANTHROPIC_API_KEY="$OMNIROUTE_KEY" +EOF + +source ~/.bashrc +echo "โœ… All CLIs installed and configured for OmniRoute" +``` diff --git a/docs/i18n/pl/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/pl/docs/CODEBASE_DOCUMENTATION.md new file mode 100644 index 0000000000..4110967ad9 --- /dev/null +++ b/docs/i18n/pl/docs/CODEBASE_DOCUMENTATION.md @@ -0,0 +1,591 @@ +# omniroute โ€” Codebase Documentation (Polski) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CODEBASE_DOCUMENTATION.md) + +--- + +> 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
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, Qoder, 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. + +#### Architektura + +```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 | +| Qoder | 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"] +``` diff --git a/docs/i18n/pl/docs/COVERAGE_PLAN.md b/docs/i18n/pl/docs/COVERAGE_PLAN.md new file mode 100644 index 0000000000..3b696819bd --- /dev/null +++ b/docs/i18n/pl/docs/COVERAGE_PLAN.md @@ -0,0 +1,170 @@ +# Test Coverage Plan (Polski) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/COVERAGE_PLAN.md) + +--- + +Last updated: 2026-03-28 + +## Baseline + +There are multiple coverage numbers depending on how the report is computed. For planning, only one of them is useful. + +| Metric | Scope | Statements / Lines | Branches | Functions | Notes | +| -------------------- | ----------------------------------------------------- | -----------------: | -------: | --------: | --------------------------------------------------- | +| Legacy | Old `npm run test:coverage` | 79.42% | 75.15% | 67.94% | Inflated: counts test files and excludes `open-sse` | +| Diagnostic | Source-only, excluding tests and excluding `open-sse` | 68.16% | 63.55% | 64.06% | Useful only to isolate `src/**` | +| Recommended baseline | Source-only, excluding tests and including `open-sse` | 56.95% | 66.05% | 57.80% | This is the project-wide baseline to improve | + +The recommended baseline is the number to optimize against. + +## Rules + +- Coverage targets apply to source files, not to `tests/**`. +- `open-sse/**` is part of the product and must remain in scope. +- New code should not reduce coverage in touched areas. +- Prefer testing behavior and branch outcomes over implementation details. +- Prefer temp SQLite databases and small fixtures over broad mocks for `src/lib/db/**`. + +## Current command set + +- `npm run test:coverage` + - Main source coverage gate for the unit test suite + - Generates `text-summary`, `html`, `json-summary`, and `lcov` +- `npm run coverage:report` + - Detailed file-by-file report from the latest run +- `npm run test:coverage:legacy` + - Historical comparison only + +## Milestones + +| Phase | Target | Focus | +| ------- | ---------------------: | ------------------------------------------------- | +| Phase 1 | 60% statements / lines | Quick wins and low-risk utility coverage | +| Phase 2 | 65% statements / lines | DB and route foundations | +| Phase 3 | 70% statements / lines | Provider validation and usage analytics | +| Phase 4 | 75% statements / lines | `open-sse` translators and helpers | +| Phase 5 | 80% statements / lines | `open-sse` handlers and executor branches | +| Phase 6 | 85% statements / lines | Harder edge cases, branch debt, regression suites | +| Phase 7 | 90% statements / lines | Final sweep, gap closure, strict ratchet | + +Branches and functions should ratchet upward with each phase, but the primary hard target is statements / lines. + +## Priority hotspots + +These files or areas offer the best return for the next phases: + +1. `open-sse/handlers` + - `chatCore.ts` at 7.57% + - Overall directory at 29.07% +2. `open-sse/translator/request` + - Overall directory at 36.39% + - Many translators are still near single-digit coverage +3. `open-sse/translator/response` + - Overall directory at 8.07% +4. `open-sse/executors` + - Overall directory at 36.62% +5. `src/lib/db` + - `models.ts` at 20.66% + - `registeredKeys.ts` at 34.46% + - `modelComboMappings.ts` at 36.25% + - `settings.ts` at 46.40% + - `webhooks.ts` at 33.33% +6. `src/lib/usage` + - `usageHistory.ts` at 21.12% + - `usageStats.ts` at 9.56% + - `costCalculator.ts` at 30.00% +7. `src/lib/providers` + - `validation.ts` at 41.16% +8. Low-risk utility and API files for early gains + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/api/errorResponse.ts` + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +## Execution checklist + +### Phase 1: 56.95% -> 60% + +- [x] Fix coverage metric so it reflects source code instead of test files +- [x] Keep a legacy coverage script for comparison +- [x] Record the baseline and hotspots in-repo +- [ ] Add focused tests for low-risk utilities: + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/fetchTimeout.ts` + - `src/lib/api/errorResponse.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/display/names.ts` +- [ ] Add route tests for: + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +### Phase 2: 60% -> 65% + +- [ ] Add DB-backed tests for: + - `src/lib/db/modelComboMappings.ts` + - `src/lib/db/settings.ts` + - `src/lib/db/registeredKeys.ts` +- [ ] Cover branch behavior in: + - `src/lib/providers/validation.ts` + - `src/app/api/v1/embeddings/route.ts` + - `src/app/api/v1/moderations/route.ts` + +### Phase 3: 65% -> 70% + +- [ ] Add usage analytics tests for: + - `src/lib/usage/usageHistory.ts` + - `src/lib/usage/usageStats.ts` + - `src/lib/usage/costCalculator.ts` +- [ ] Expand route coverage for proxy management and settings branches + +### Phase 4: 70% -> 75% + +- [ ] Cover translator helpers and central translation paths: + - `open-sse/translator/index.ts` + - `open-sse/translator/helpers/*` + - `open-sse/translator/request/*` + - `open-sse/translator/response/*` + +### Phase 5: 75% -> 80% + +- [ ] Add handler-level tests for: + - `open-sse/handlers/chatCore.ts` + - `open-sse/handlers/responsesHandler.js` + - `open-sse/handlers/imageGeneration.js` + - `open-sse/handlers/embeddings.js` +- [ ] Add executor branch coverage for provider-specific auth, retries, and endpoint overrides + +### Phase 6: 80% -> 85% + +- [ ] Merge more edge-case suites into the main coverage path +- [ ] Increase function coverage for DB modules with weak constructor/helper coverage +- [ ] Close branch gaps in `settings.ts`, `registeredKeys.ts`, `validation.ts`, and translator helpers + +### Phase 7: 85% -> 90% + +- [ ] Treat the remaining low-coverage files as blockers +- [ ] Add regression tests for every uncovered production bug fixed during the push to 90% +- [ ] Raise the coverage gate in CI only after the local baseline is stable for at least two consecutive runs + +## Ratchet policy + +Update `npm run test:coverage` thresholds only after the project actually exceeds the next milestone with a comfortable buffer. + +Recommended ratchet sequence: + +1. 55/60/55 +2. 60/62/58 +3. 65/64/62 +4. 70/66/66 +5. 75/70/72 +6. 80/75/78 +7. 85/80/84 +8. 90/85/88 + +Order is `statements-lines / branches / functions`. + +## Known gap + +The current coverage command measures the main Node unit suite and includes source reached from it, including `open-sse`. It does not yet merge Vitest coverage into a single unified report. That merge is worth doing later, but it is not a blocker for starting the 60% -> 80% climb. diff --git a/docs/i18n/pl/docs/FEATURES.md b/docs/i18n/pl/docs/FEATURES.md index ba2a20869e..d9f8056f2e 100644 --- a/docs/i18n/pl/docs/FEATURES.md +++ b/docs/i18n/pl/docs/FEATURES.md @@ -1,6 +1,6 @@ # OmniRoute โ€” Dashboard Features Gallery (Polski) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/FEATURES.md) --- @@ -10,7 +10,7 @@ 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). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. ![Providers Dashboard](screenshots/01-providers.png) diff --git a/docs/i18n/pl/docs/MCP-SERVER.md b/docs/i18n/pl/docs/MCP-SERVER.md new file mode 100644 index 0000000000..bd3090a73f --- /dev/null +++ b/docs/i18n/pl/docs/MCP-SERVER.md @@ -0,0 +1,87 @@ +# OmniRoute MCP Server Documentation (Polski) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/MCP-SERVER.md) + +--- + +> Model Context Protocol server with 16 intelligent tools + +## Zainstaluj + +OmniRoute MCP is built-in. Start it with: + +```bash +omniroute --mcp +``` + +Or via the open-sse transport: + +```bash +# HTTP streamable transport (port 20130) +omniroute --dev # MCP auto-starts on /mcp endpoint +``` + +## IDE Configuration + +See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup. + +--- + +## Essential Tools (8) + +| Tool | Description | +| :------------------------------ | :--------------------------------------- | +| `omniroute_get_health` | Gateway health, circuit breakers, uptime | +| `omniroute_list_combos` | All configured combos with models | +| `omniroute_get_combo_metrics` | Performance metrics for a specific combo | +| `omniroute_switch_combo` | Switch active combo by ID/name | +| `omniroute_check_quota` | Quota status per provider or all | +| `omniroute_route_request` | Send a chat completion through OmniRoute | +| `omniroute_cost_report` | Cost analytics for a time period | +| `omniroute_list_models_catalog` | Full model catalog with capabilities | + +## Advanced Tools (8) + +| Tool | Description | +| :--------------------------------- | :---------------------------------------------------------- | +| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | +| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | +| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | +| `omniroute_test_combo` | Live-test all models in a combo via a real upstream request | +| `omniroute_get_provider_metrics` | Detailed metrics for one provider | +| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | +| `omniroute_explain_route` | Explain a past routing decision | +| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | + +## Authentication + +MCP tools are authenticated via API key scopes. Each tool requires specific scopes: + +| Scope | Tools | +| :------------- | :----------------------------------------------- | +| `read:health` | get_health, get_provider_metrics | +| `read:combos` | list_combos, get_combo_metrics | +| `write:combos` | switch_combo | +| `read:quota` | check_quota | +| `write:route` | route_request, simulate_route, test_combo | +| `read:usage` | cost_report, get_session_snapshot, explain_route | +| `write:config` | set_budget_guard, set_resilience_profile | +| `read:models` | list_models_catalog, best_combo_for_task | + +## Audit Logging + +Every tool call is logged to `mcp_tool_audit` with: + +- Tool name, arguments, result +- Duration (ms), success/failure +- API key hash, timestamp + +## Files + +| File | Purpose | +| :------------------------------------------- | :------------------------------------------ | +| `open-sse/mcp-server/server.ts` | MCP server creation + 16 tool registrations | +| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport | +| `open-sse/mcp-server/auth.ts` | API key + scope validation | +| `open-sse/mcp-server/audit.ts` | Tool call audit logging | +| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers | diff --git a/docs/i18n/pl/docs/RELEASE_CHECKLIST.md b/docs/i18n/pl/docs/RELEASE_CHECKLIST.md new file mode 100644 index 0000000000..59cd24ecbb --- /dev/null +++ b/docs/i18n/pl/docs/RELEASE_CHECKLIST.md @@ -0,0 +1,37 @@ +# Release Checklist (Polski) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/RELEASE_CHECKLIST.md) + +--- + +Use this checklist before tagging or publishing a new OmniRoute release. + +## Version and Changelog + +1. Bump `package.json` version (`x.y.z`) in the release branch. +2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: + - `## [x.y.z] โ€” YYYY-MM-DD` +3. Keep `## [Unreleased]` as the first changelog section for upcoming work. +4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. + +## API Docs + +1. Update `docs/openapi.yaml`: + - `info.version` must equal `package.json` version. +2. Validate endpoint examples if API contracts changed. + +## Runtime Docs + +1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. +2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. +3. Update localized docs if source docs changed significantly. + +## Automated Check + +Run the sync guard locally before opening PR: + +```bash +npm run check:docs-sync +``` + +CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/pl/docs/TROUBLESHOOTING.md b/docs/i18n/pl/docs/TROUBLESHOOTING.md new file mode 100644 index 0000000000..562dcd2a75 --- /dev/null +++ b/docs/i18n/pl/docs/TROUBLESHOOTING.md @@ -0,0 +1,256 @@ +# Troubleshooting (Polski) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/TROUBLESHOOTING.md) + +--- + +Common problems and solutions for OmniRoute. + +--- + +## Quick Fixes + +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | + +--- + +## Provider Issues + +### "Language model did not provide messages" + +**Cause:** Provider quota exhausted. + +**Fix:** + +1. 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, Qoder) 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}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) + +--- + +## Circuit Breaker Issues + +### Provider stuck in OPEN state + +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. + +**Fix:** + +1. 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 +- **SDK returns raw string instead of object** โ€” Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** โ€” Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** โ€” Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** โ€” Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` + +--- + +## Resilience Settings + +### Auto rate-limit not triggering + +- 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. + +--- + +## Optional RAG / LLM failure taxonomy (16 problems) + +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` โ€ฆ `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard โ†’ Health** for real-time system status +- **Translator**: Use **Dashboard โ†’ Translator** to debug format issues diff --git a/docs/i18n/pl/USER_GUIDE.md b/docs/i18n/pl/docs/USER_GUIDE.md similarity index 82% rename from docs/i18n/pl/USER_GUIDE.md rename to docs/i18n/pl/docs/USER_GUIDE.md index 8f503a32f6..fd8c5f391c 100644 --- a/docs/i18n/pl/USER_GUIDE.md +++ b/docs/i18n/pl/docs/USER_GUIDE.md @@ -1,8 +1,6 @@ # User Guide (Polski) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/USER_GUIDE.md) - -> ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/USER_GUIDE.md) --- @@ -320,7 +318,7 @@ Model: cc/claude-opus-4-6 --- -## ๐Ÿš€ Deployment +## Wdroลผenie ### Global npm install (Recommended) @@ -511,23 +509,26 @@ post_install() { ### Environment Variables -| Variable | Default | Description | -| ------------------------- | ------------------------------------ | ------------------------------------------------------- | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | -| `INITIAL_PASSWORD` | `123456` | First login password | -| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | -| `PORT` | framework default | Service port (`20128` in examples) | -| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | -| `NODE_ENV` | runtime default | Set `production` for deploy | -| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | -| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | -| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | -| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | -| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | -| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | -| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | -| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | +| 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/*` | +| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand | +| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | For the full environment variable reference, see the [README](../README.md). @@ -598,6 +599,11 @@ curl -X POST http://localhost:20128/api/provider-models \ Or use Dashboard: **Providers โ†’ [Provider] โ†’ Custom Models**. +Notes: + +- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers. +- The **Custom Models** section is intended for providers that do not expose managed available-model imports. + ### Dedicated Provider Routes Route requests directly to a specific provider with model validation: @@ -642,6 +648,14 @@ Returns models grouped by provider with types (`chat`, `embedding`, `image`). - Automatic background sync with timeout + fail-fast - Prefer server-side `BASE_URL`/`CLOUD_URL` in production +### Cloudflare Quick Tunnel + +- Available in **Dashboard โ†’ Endpoints** for Docker and other self-hosted deployments +- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint +- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary +- Tunnel URLs are ephemeral and change every time you stop/start the tunnel +- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download + ### LLM Gateway Intelligence (Phase 9) - **Semantic Cache** โ€” Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) @@ -757,11 +771,11 @@ OmniRoute implements provider-level resilience with four components: 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 | +| 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 unless `DISABLE_SQLITE_AUTO_BACKUP=true` | ```bash # API: Export database @@ -787,10 +801,11 @@ curl -X POST http://localhost:20128/api/db-backups/import \ ### Settings Dashboard -The settings page is organized into 5 tabs for easy navigation: +The settings page is organized into 6 tabs for easy navigation: | Tab | Contents | | -------------- | ---------------------------------------------------------------------------------------------- | +| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility | | **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | | **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | | **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | diff --git a/docs/i18n/pl/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/pl/docs/VM_DEPLOYMENT_GUIDE.md new file mode 100644 index 0000000000..6e2ade272f --- /dev/null +++ b/docs/i18n/pl/docs/VM_DEPLOYMENT_GUIDE.md @@ -0,0 +1,403 @@ +# OmniRoute โ€” Deployment Guide on VM with Cloudflare (Polski) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/VM_DEPLOYMENT_GUIDE.md) + +--- + +Complete guide to install and configure OmniRoute on a VM (VPS) with domain managed via Cloudflare. + +--- + +## Prerequisites + +| Item | Minimum | Recommended | +| ---------- | ------------------------ | ---------------- | +| **CPU** | 1 vCPU | 2 vCPU | +| **RAM** | 1 GB | 2 GB | +| **Disk** | 10 GB SSD | 25 GB SSD | +| **OS** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS | +| **Domain** | Registered on Cloudflare | โ€” | +| **Docker** | Docker Engine 24+ | Docker 27+ | + +**Tested providers**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. + +--- + +## 1. Configure the VM + +### 1.1 Create the instance + +On your preferred VPS provider: + +- Choose Ubuntu 24.04 LTS +- Select the minimum plan (1 vCPU / 1 GB RAM) +- Set a strong root password or configure SSH key +- Note the **public IP** (e.g., `203.0.113.10`) + +### 1.2 Connect via SSH + +```bash +ssh root@203.0.113.10 +``` + +### 1.3 Update the system + +```bash +apt update && apt upgrade -y +``` + +### 1.4 Install Docker + +```bash +# Install dependencies +apt install -y ca-certificates curl gnupg + +# Add official Docker repository +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 Install nginx + +```bash +apt install -y nginx +``` + +### 1.6 Configure 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 +``` + +> **Tip**: For maximum security, restrict ports 80 and 443 to Cloudflare IPs only. See the [Advanced Security](#advanced-security) section. + +--- + +## 2. Install OmniRoute + +### 2.1 Create configuration directory + +```bash +mkdir -p /opt/omniroute +``` + +### 2.2 Create environment variables file + +```bash +cat > /opt/omniroute/.env << โ€˜EOFโ€™ +# === Security === +JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY +INITIAL_PASSWORD=YourSecurePassword123! +API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY +STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY +STORAGE_ENCRYPTION_KEY_VERSION=v1 +MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT + +# === 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 (change to your domain) === +BASE_URL=https://llms.seudominio.com +NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com + +# === Cloud Sync (optional) === +# CLOUD_URL=https://cloud.omniroute.online +# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online +EOF +``` + +> โš ๏ธ **IMPORTANT**: Generate unique secret keys! Use `openssl rand -hex 32` for each key. + +### 2.3 Start the 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 Verify that it is running + +```bash +docker ps | grep omniroute +docker logs omniroute --tail 20 +``` + +It should display: `[DB] SQLite database ready` and `listening on port 20128`. + +--- + +## 3. Configure nginx (Reverse Proxy) + +### 3.1 Generate SSL certificate (Cloudflare Origin) + +In the Cloudflare dashboard: + +1. Go to **SSL/TLS โ†’ Origin Server** +2. Click **Create Certificate** +3. Keep the defaults (15 years, \*.yourdomain.com) +4. Copy the **Origin Certificate** and the **Private Key** + +```bash +mkdir -p /etc/nginx/ssl + +# Paste the certificate +nano /etc/nginx/ssl/origin.crt + +# Paste the private key +nano /etc/nginx/ssl/origin.key + +chmod 600 /etc/nginx/ssl/origin.key +``` + +### 3.2 Nginx Configuration + +```bash +cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ +# Default server โ€” blocks direct access via 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.yourdomain.com; # Change to your domain + + 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.yourdomain.com; + return 301 https://$server_name$request_uri; +} +NGINX +``` + +### 3.3 Enable and Test + +```bash +# Remove default configuration +rm -f /etc/nginx/sites-enabled/default + +# Enable OmniRoute +ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute + +# Test and reload +nginx -t && systemctl reload nginx +``` + +--- + +## 4. Configure Cloudflare DNS + +### 4.1 Add DNS record + +In the Cloudflare dashboard โ†’ DNS: + +| Type | Name | Content | Proxy | +| ---- | ------ | ---------------------- | ---------- | +| A | `llms` | `203.0.113.10` (VM IP) | โœ… Proxied | + +### 4.2 Configure SSL + +Under **SSL/TLS โ†’ Overview**: + +- Mode: **Full (Strict)** + +Under **SSL/TLS โ†’ Edge Certificates**: + +- Always Use HTTPS: โœ… On +- Minimum TLS Version: TLS 1.2 +- Automatic HTTPS Rewrites: โœ… On + +### 4.3 Testing + +```bash +curl -sI https://llms.seudominio.com/health +# Should return HTTP/2 200 +``` + +--- + +## 5. Operations and Maintenance + +### Upgrade to a new version + +```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 +``` + +### View logs + +```bash +docker logs -f omniroute # Real-time stream +docker logs omniroute --tail 50 # Last 50 lines +``` + +### Manual database backup + +```bash +# Copy data from the volume to the host +docker cp omniroute:/app/data ./backup-$(date +%F) + +# Or compress the entire volume +docker run --rm -v omniroute-data:/data -v $(pwd):/backup \ + alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data +``` + +### Restore from 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. Advanced Security + +### Restrict nginx to Cloudflare IPs + +```bash +cat > /etc/nginx/cloudflare-ips.conf << โ€˜CFโ€™ +# Cloudflare IPv4 ranges โ€” update periodically +# 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 +``` + +Add the following to `nginx.conf` inside the `http {}` block: + +```nginx +include /etc/nginx/cloudflare-ips.conf; +``` + +### Install fail2ban + +```bash +apt install -y fail2ban +systemctl enable fail2ban +systemctl start fail2ban + +# Check status +fail2ban-client status sshd +``` + +### Block direct access to the Docker port + +```bash +# Prevent direct external access to port 20128 +iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP +iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT + +# Persist the rules +apt install -y iptables-persistent +netfilter-persistent save +``` + +--- + +## 7. Deploy to Cloudflare Workers (Optional) + +For remote access via Cloudflare Workers (without exposing the VM directly): + +```bash +# In the local repository +cd omnirouteCloud +npm install +npx wrangler login +npx wrangler deploy +``` + +See the full documentation at [omnirouteCloud/README.md](../omnirouteCloud/README.md). + +--- + +## Port Summary + +| Port | Service | Access | +| ----- | ----------- | -------------------------- | +| 22 | SSH | Public (with fail2ban) | +| 80 | nginx HTTP | Redirect โ†’ HTTPS | +| 443 | nginx HTTPS | Via Cloudflare Proxy | +| 20128 | OmniRoute | Localhost only (via nginx) | diff --git a/docs/i18n/pl/src/lib/a2a/README.md b/docs/i18n/pl/src/lib/a2a/README.md new file mode 100644 index 0000000000..dfb71747d8 --- /dev/null +++ b/docs/i18n/pl/src/lib/a2a/README.md @@ -0,0 +1,752 @@ +# OmniRoute A2A Server (Polski) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../../../src/lib/a2a/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../../../es/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../../../fr/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../../../de/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../../../it/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../../../ru/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../../../zh-CN/src/lib/a2a/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../../../ja/src/lib/a2a/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../../../ko/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../../../ar/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../../../in/src/lib/a2a/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../../../th/src/lib/a2a/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../../../vi/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../../../id/src/lib/a2a/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../../../ms/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../../../nl/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../../../pl/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../../../sv/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../../../no/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../../../da/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../../../fi/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../../../pt/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../../../ro/src/lib/a2a/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../../../hu/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../../../bg/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../../../sk/src/lib/a2a/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../../../uk-UA/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../../../he/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../../../phi/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../../../pt-BR/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../../../cs/src/lib/a2a/README.md) + +--- + +> **Agent-to-Agent Protocol v0.3** โ€” Enables any AI agent to use OmniRoute as an intelligent routing agent via JSON-RPC 2.0. + +The A2A Server exposes OmniRoute as a **first-class agent** that other agents can discover, delegate tasks to, and collaborate with using the [A2A Protocol](https://google.github.io/A2A/). + +--- + +## Architektura + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Orchestrator Agent โ”‚ +โ”‚ (LangChain, CrewAI, AutoGen, Custom Agent) โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ 1. GET /.well-known/agent.json (discover) + โ”‚ 2. POST /a2a (JSON-RPC 2.0) + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ OmniRoute A2A Server โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Task Manager โ”‚ โ”‚ Skill Engine โ”‚ โ”‚ SSE Streaming โ”‚ โ”‚ +โ”‚ โ”‚ (lifecycle) โ”‚โ”€โ”€โ”‚ (registry) โ”‚โ”€โ”€โ”‚ (real-time) โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ +โ”‚ Skills: โ”‚ โ”‚ +โ”‚ โ”œโ”€ smart-routing โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ””โ”€ quota-management โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ Routing Decision Logger โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ OmniRoute Gateway (internal) + /v1/chat/completions, /api/combos, /api/usage/quota +``` + +--- + +## Szybki start + +### Agent Discovery + +Every A2A-compatible agent exposes an **Agent Card** at `/.well-known/agent.json`: + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +**Response:** + +```json +{ + "name": "OmniRoute", + "description": "Intelligent AI gateway with auto-routing across 50+ providers", + "url": "http://localhost:20128/a2a", + "version": "1.8.1", + "capabilities": { + "streaming": true, + "pushNotifications": false + }, + "skills": [ + { + "id": "smart-routing", + "name": "Smart Routing", + "description": "Routes prompts through OmniRoute intelligent pipeline", + "tags": ["routing", "llm", "multi-provider", "cost-optimization"], + "examples": [ + "Write a hello world in Python", + "Explain quantum computing using the cheapest provider" + ] + }, + { + "id": "quota-management", + "name": "Quota Management", + "description": "Natural-language queries about provider quotas", + "tags": ["quota", "analytics", "cost"], + "examples": [ + "Which provider has the most quota remaining?", + "Suggest a free combo for coding" + ] + } + ], + "authentication": { + "schemes": ["bearer"], + "apiKeyHeader": "Authorization" + } +} +``` + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Send a message to a skill and receive the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python hello world"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "a1b2c3d4-...", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "print('Hello, World!')" }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.0030)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "2026-03-04T..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"Quantum computing..."}}} + +: heartbeat 2026-03-04T21:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Running Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Skills Reference + +### `smart-routing` + +Routes prompts through OmniRoute's intelligent pipeline with full observability. + +**Parameters (in `metadata`):** + +| Parameter | Type | Default | Description | +| --------- | -------- | ------------ | ---------------------------------------------------------------------------------------- | +| `model` | `string` | `"auto"` | Target model (e.g., `claude-sonnet-4`, `gpt-4o`, `auto`) | +| `combo` | `string` | active combo | Specific combo to route through | +| `budget` | `number` | none | Maximum cost in USD for this request | +| `role` | `string` | none | Task role hint: `coding`, `review`, `planning`, `analysis`, `debugging`, `documentation` | + +**Returns:** + +| Field | Description | +| ------------------------------ | --------------------------------------------------------- | +| `artifacts[].content` | The LLM response text | +| `metadata.routing_explanation` | Human-readable explanation of routing decision | +| `metadata.cost_envelope` | Estimated vs actual cost with currency | +| `metadata.resilience_trace` | Array of events (primary_selected, fallback_needed, etc.) | +| `metadata.policy_verdict` | Whether the request was allowed and why | + +### `quota-management` + +Answers natural-language queries about provider quotas. + +**Query types (inferred from message content):** + +| Query Pattern | Response Type | +| ---------------------------------------------- | -------------------------------------------------------- | +| Contains `"ranking"`, `"most quota"`, `"best"` | Providers ranked by remaining quota | +| Contains `"free"`, `"suggest"` | Lists free combos or suggests free-tier providers | +| Default | Full quota summary with warnings for low-quota providers | + +--- + +## Task Lifecycle + +``` +submitted โ”€โ”€โ†’ working โ”€โ”€โ†’ completed + โ”€โ”€โ†’ failed + โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ†’ cancelled +``` + +| State | Description | +| ----------- | ----------------------------------------------------- | +| `submitted` | Task created, queued for execution | +| `working` | Skill handler is executing | +| `completed` | Execution succeeded, artifacts available | +| `failed` | Execution failed or task expired (TTL: 5 min default) | +| `cancelled` | Cancelled by client via `tasks/cancel` | + +- Terminal states: `completed`, `failed`, `cancelled` (no further transitions) +- Expired tasks in `submitted` or `working` are auto-marked as `failed` +- Tasks are garbage-collected after 2ร— TTL + +--- + +## Client Examples + +### Python โ€” Orchestrator Agent + +```python +""" +A2A Client โ€” Python example. +Discovers OmniRoute agent, sends a task, and processes the result. +""" +import requests +import json + +BASE_URL = "http://localhost:20128" +API_KEY = "your-api-key" +HEADERS = { + "Content-Type": "application/json", + "Authorization": f"Bearer {API_KEY}", +} + +# 1. Discover agent capabilities +agent_card = requests.get(f"{BASE_URL}/.well-known/agent.json").json() +print(f"Agent: {agent_card['name']} v{agent_card['version']}") +print(f"Skills: {[s['id'] for s in agent_card['skills']]}") + +# 2. Send a smart-routing task +response = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python quicksort implementation"}], + "metadata": { + "model": "auto", + "combo": "fast-coding", + "budget": 0.10, + } + } +}) +result = response.json()["result"] +print(f"\n๐Ÿ“ Response: {result['artifacts'][0]['content'][:200]}...") +print(f"๐Ÿ”€ Routing: {result['metadata']['routing_explanation']}") +print(f"๐Ÿ’ฐ Cost: ${result['metadata']['cost_envelope']['actual']}") +print(f"๐Ÿ›ก๏ธ Policy: {result['metadata']['policy_verdict']['reason']}") + +# 3. Query quota status +quota_resp = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-2", + "method": "message/send", + "params": { + "skill": "quota-management", + "messages": [{"role": "user", "content": "Which provider has the most quota remaining?"}], + } +}) +quota_result = quota_resp.json()["result"] +print(f"\n๐Ÿ“Š Quota: {quota_result['artifacts'][0]['content']}") +``` + +### TypeScript โ€” Multi-Agent Orchestrator + +```typescript +/** + * A2A Client โ€” TypeScript example. + * Shows agent discovery, task delegation, and streaming. + */ + +const BASE_URL = "http://localhost:20128"; +const API_KEY = "your-api-key"; + +interface JsonRpcResponse { + jsonrpc: "2.0"; + id: string | number; + result?: T; + error?: { code: number; message: string }; +} + +async function a2aCall(method: string, params: Record): Promise { + const resp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: `${method}-${Date.now()}`, + method, + params, + }), + }); + const json: JsonRpcResponse = await resp.json(); + if (json.error) throw new Error(`[${json.error.code}] ${json.error.message}`); + return json.result!; +} + +// โ”€โ”€ Agent Discovery โ”€โ”€ +const agentCard = await fetch(`${BASE_URL}/.well-known/agent.json`).then((r) => r.json()); +console.log(`Connected to: ${agentCard.name} (${agentCard.skills.length} skills)`); + +// โ”€โ”€ Smart Routing: Send a coding task โ”€โ”€ +const routingResult = await a2aCall("message/send", { + skill: "smart-routing", + messages: [{ role: "user", content: "Implement a Redis cache wrapper in TypeScript" }], + metadata: { model: "claude-sonnet-4", role: "coding" }, +}); +console.log("Response:", routingResult.artifacts[0].content); +console.log("Provider:", routingResult.metadata.routing_explanation); + +// โ”€โ”€ Quota Management: Find free alternatives โ”€โ”€ +const quotaResult = await a2aCall("message/send", { + skill: "quota-management", + messages: [{ role: "user", content: "Suggest free combos for documentation" }], +}); +console.log("Free combos:", quotaResult.artifacts[0].content); + +// โ”€โ”€ Streaming: Real-time response โ”€โ”€ +const streamResp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "stream-1", + method: "message/stream", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Explain microservices architecture" }], + }, + }), +}); + +const reader = streamResp.body!.getReader(); +const decoder = new TextDecoder(); +while (true) { + const { done, value } = await reader.read(); + if (done) break; + const chunk = decoder.decode(value); + for (const line of chunk.split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + if (event.params.chunk) { + process.stdout.write(event.params.chunk.content); + } + if (event.params.task.state === "completed") { + console.log("\nโœ… Stream completed"); + } + } + } +} +``` + +### Python โ€” LangChain A2A Integration + +```python +""" +LangChain integration โ€” Use OmniRoute A2A as a custom LLM. +""" +from langchain.llms.base import BaseLLM +from langchain.schema import LLMResult, Generation +import requests +from typing import List, Optional + +class OmniRouteA2A(BaseLLM): + base_url: str = "http://localhost:20128" + api_key: str = "" + model: str = "auto" + combo: Optional[str] = None + + @property + def _llm_type(self) -> str: + return "omniroute-a2a" + + def _call(self, prompt: str, stop: Optional[List[str]] = None, **kwargs) -> str: + response = requests.post( + f"{self.base_url}/a2a", + headers={ + "Content-Type": "application/json", + "Authorization": f"Bearer {self.api_key}", + }, + json={ + "jsonrpc": "2.0", + "id": "langchain-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": prompt}], + "metadata": { + "model": self.model, + **({"combo": self.combo} if self.combo else {}), + }, + }, + }, + ) + result = response.json()["result"] + return result["artifacts"][0]["content"] + + def _generate(self, prompts: List[str], stop=None, **kwargs) -> LLMResult: + return LLMResult( + generations=[[Generation(text=self._call(p, stop))] for p in prompts] + ) + +# Usage +llm = OmniRouteA2A( + base_url="http://localhost:20128", + api_key="your-key", + model="auto", + combo="fast-coding", +) +result = llm("Write a Python function to merge two sorted lists") +print(result) +``` + +### Go โ€” A2A Client + +```go +package main + +import ( + "bytes" + "encoding/json" + "fmt" + "io" + "net/http" +) + +const baseURL = "http://localhost:20128" +const apiKey = "your-api-key" + +type JsonRpcRequest struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Method string `json:"method"` + Params interface{} `json:"params"` +} + +type JsonRpcResponse struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Result interface{} `json:"result"` + Error *struct { + Code int `json:"code"` + Message string `json:"message"` + } `json:"error"` +} + +func a2aCall(method string, params interface{}) (*JsonRpcResponse, error) { + body, _ := json.Marshal(JsonRpcRequest{ + Jsonrpc: "2.0", + ID: "go-1", + Method: method, + Params: params, + }) + + req, _ := http.NewRequest("POST", baseURL+"/a2a", bytes.NewReader(body)) + req.Header.Set("Content-Type", "application/json") + req.Header.Set("Authorization", "Bearer "+apiKey) + + resp, err := http.DefaultClient.Do(req) + if err != nil { + return nil, err + } + defer resp.Body.Close() + data, _ := io.ReadAll(resp.Body) + + var result JsonRpcResponse + json.Unmarshal(data, &result) + return &result, nil +} + +func main() { + // Discover agent + resp, _ := http.Get(baseURL + "/.well-known/agent.json") + defer resp.Body.Close() + body, _ := io.ReadAll(resp.Body) + fmt.Println("Agent Card:", string(body)) + + // Send smart-routing task + result, _ := a2aCall("message/send", map[string]interface{}{ + "skill": "smart-routing", + "messages": []map[string]string{{"role": "user", "content": "Hello from Go!"}}, + "metadata": map[string]interface{}{"model": "auto"}, + }) + out, _ := json.MarshalIndent(result.Result, "", " ") + fmt.Println("Result:", string(out)) +} +``` + +--- + +## Use Cases + +### ๐Ÿค– Use Case 1: Multi-Agent Coding Pipeline + +An orchestrator agent delegates code generation to OmniRoute, then passes the output to a review agent. + +```python +def coding_pipeline(task: str): + # Step 1: Generate code via OmniRoute A2A + code_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Write production-quality code: {task}"} + ], metadata={"model": "auto", "role": "coding"}) + code = code_result["artifacts"][0]["content"] + + # Step 2: Review the code via OmniRoute A2A (different model) + review_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Review this code for bugs and improvements:\n\n{code}"} + ], metadata={"model": "auto", "role": "review"}) + review = review_result["artifacts"][0]["content"] + + # Step 3: Check costs + print(f"Code cost: ${code_result['metadata']['cost_envelope']['actual']}") + print(f"Review cost: ${review_result['metadata']['cost_envelope']['actual']}") + + return {"code": code, "review": review} +``` + +### ๐Ÿ’ก Use Case 2: Quota-Aware Agent Swarm + +Multiple agents share quota through OmniRoute, using the quota skill to coordinate. + +```python +async def quota_aware_agent(agent_name: str, task: str): + # Check quota before starting + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Which provider has the most quota remaining?"} + ]) + print(f"[{agent_name}] {quota['artifacts'][0]['content']}") + + # Send request with budget constraint + result = a2a_send("smart-routing", [ + {"role": "user", "content": task} + ], metadata={"budget": 0.05}) + + policy = result["metadata"]["policy_verdict"] + if not policy["allowed"]: + print(f"[{agent_name}] โš ๏ธ Budget exceeded: {policy['reason']}") + # Fall back to free combo + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Suggest free combos"} + ]) + print(f"[{agent_name}] Free alternatives: {quota['artifacts'][0]['content']}") + + return result +``` + +### ๐Ÿ“Š Use Case 3: Real-Time Streaming Dashboard + +A monitoring agent streams responses and displays progress in real-time. + +```typescript +async function streamingDashboard(prompt: string) { + const response = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { "Content-Type": "application/json", Authorization: `Bearer ${API_KEY}` }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "dash-1", + method: "message/stream", + params: { skill: "smart-routing", messages: [{ role: "user", content: prompt }] }, + }), + }); + + let totalChunks = 0; + const reader = response.body!.getReader(); + const decoder = new TextDecoder(); + + while (true) { + const { done, value } = await reader.read(); + if (done) break; + + for (const line of decoder.decode(value).split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + const state = event.params.task.state; + + if (state === "working" && event.params.chunk) { + totalChunks++; + process.stdout.write( + `\r[Chunk ${totalChunks}] ${event.params.chunk.content.slice(0, 50)}...` + ); + } + if (state === "completed") { + const meta = event.params.metadata; + console.log( + `\nโœ… Done | Cost: $${meta?.cost_envelope?.actual || 0} | Route: ${meta?.routing_explanation || "N/A"}` + ); + } + if (state === "failed") { + console.error(`\nโŒ Failed: ${event.params.metadata?.error}`); + } + } + } + } +} +``` + +### ๐Ÿ” Use Case 4: Task Polling Pattern + +For long-running tasks, poll the task status instead of waiting synchronously. + +```python +import time + +def poll_task(task_id: str, timeout: int = 60): + """Poll task status until completion or timeout.""" + start = time.time() + while time.time() - start < timeout: + result = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "poll-1", + "method": "tasks/get", + "params": {"taskId": task_id}, + }).json() + + task = result["result"]["task"] + state = task["state"] + print(f" Task {task_id[:8]}... state={state}") + + if state in ("completed", "failed", "cancelled"): + return task + time.sleep(2) + + # Timeout โ€” cancel the task + requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "cancel-1", + "method": "tasks/cancel", + "params": {"taskId": task_id}, + }) + raise TimeoutError(f"Task {task_id} timed out after {timeout}s") +``` + +--- + +## Error Codes + +| Code | Constant | Meaning | +| ------ | ------------------------ | ---------------------------------------- | +| -32700 | โ€” | Parse error (invalid JSON) | +| -32600 | `INVALID_REQUEST` | Invalid JSON-RPC request or unauthorized | +| -32601 | `METHOD_NOT_FOUND` | Unknown method or skill | +| -32602 | `INVALID_PARAMS` | Missing or invalid parameters | +| -32603 | `INTERNAL_ERROR` | Skill execution failed | +| -32001 | `TASK_NOT_FOUND` | Task ID not found | +| -32002 | `TASK_ALREADY_COMPLETED` | Cannot modify a completed task | +| -32003 | `UNAUTHORIZED` | Invalid or missing API key | +| -32004 | `BUDGET_EXCEEDED` | Request exceeds configured budget | +| -32005 | `PROVIDER_UNAVAILABLE` | No available providers | + +--- + +## Authentication + +All `/a2a` requests require a Bearer token via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server (`OMNIROUTE_API_KEY` is empty), authentication is bypassed. + +--- + +## File Structure + +``` +src/lib/a2a/ +โ”œโ”€โ”€ taskManager.ts # Task lifecycle (create/update/cancel/list), TTL, cleanup +โ”œโ”€โ”€ taskExecution.ts # Generic task executor with state management +โ”œโ”€โ”€ streaming.ts # SSE stream formatting, heartbeat, chunk/completion events +โ”œโ”€โ”€ routingLogger.ts # Routing decision logger (stats, history, retention) +โ””โ”€โ”€ skills/ + โ”œโ”€โ”€ smartRouting.ts # Smart routing skill (routes via /v1/chat/completions) + โ””โ”€โ”€ quotaManagement.ts # Quota management skill (natural-language quota queries) + +src/app/a2a/ +โ””โ”€โ”€ route.ts # Next.js API route handler (JSON-RPC 2.0 dispatch) + +open-sse/mcp-server/ +โ””โ”€โ”€ schemas/a2a.ts # Zod schemas (AgentCard, Task, JSON-RPC, SSE events) +``` + +--- + +## Comparison: MCP vs A2A + +| Feature | MCP Server | A2A Server | +| ----------------- | ---------------------------- | ------------------------------------------------- | +| **Protocol** | Model Context Protocol | Agent-to-Agent Protocol v0.3 | +| **Transport** | stdio / HTTP | HTTP (JSON-RPC 2.0) | +| **Discovery** | Tool listing via MCP | `/.well-known/agent.json` | +| **Granularity** | 16 individual tools | 2 high-level skills | +| **Best for** | IDE agents (Cursor, VS Code) | Multi-agent systems (LangChain, CrewAI) | +| **Streaming** | Not supported | SSE via `message/stream` | +| **Task tracking** | No | Full lifecycle (submitted โ†’ completed) | +| **Observability** | Audit log per tool call | Cost envelope + resilience trace + policy verdict | + +--- + +## Licencja + +Part of [OmniRoute](https://github.com/diegosouzapw/OmniRoute) โ€” MIT License. diff --git a/docs/i18n/pt-BR/A2A-SERVER.md b/docs/i18n/pt-BR/A2A-SERVER.md deleted file mode 100644 index 01531ff482..0000000000 --- a/docs/i18n/pt-BR/A2A-SERVER.md +++ /dev/null @@ -1,200 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/A2A-SERVER.md) - ---- - -# OmniRoute A2A Server Documentation - -> Agent-to-Agent Protocol v0.3 โ€” OmniRoute as an intelligent routing agent - -## Agent Discovery - -```bash -curl http://localhost:20128/.well-known/agent.json -``` - -Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements. - ---- - -## Authentication - -All `/a2a` requests require an API key via the `Authorization` header: - -``` -Authorization: Bearer YOUR_OMNIROUTE_API_KEY -``` - -If no API key is configured on the server, authentication is bypassed. - ---- - -## JSON-RPC 2.0 Methods - -### `message/send` โ€” Synchronous Execution - -Sends a message to a skill and waits for the complete response. - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{ - "jsonrpc": "2.0", - "id": "1", - "method": "message/send", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Write a hello world in Python"}], - "metadata": {"model": "auto", "combo": "fast-coding"} - } - }' -``` - -**Response:** - -```json -{ - "jsonrpc": "2.0", - "id": "1", - "result": { - "task": { "id": "uuid", "state": "completed" }, - "artifacts": [{ "type": "text", "content": "..." }], - "metadata": { - "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)", - "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, - "resilience_trace": [ - { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." } - ], - "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } - } - } -} -``` - -### `message/stream` โ€” SSE Streaming - -Same as `message/send` but returns Server-Sent Events for real-time streaming. - -```bash -curl -N -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{ - "jsonrpc": "2.0", - "id": "1", - "method": "message/stream", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Explain quantum computing"}] - } - }' -``` - -**SSE Events:** - -``` -data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}} - -: heartbeat 2026-03-03T17:00:00Z - -data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} -``` - -### `tasks/get` โ€” Query Task Status - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' -``` - -### `tasks/cancel` โ€” Cancel a Task - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' -``` - ---- - -## Available Skills - -| Skill | Description | -| :----------------- | :------------------------------------------------------------------------------------------------------------------------------ | -| `smart-routing` | Routes prompts through OmniRoute's intelligent pipeline. Returns response with routing explanation, cost, and resilience trace. | -| `quota-management` | Answers natural-language queries about provider quotas, suggests free combos, and provides quota rankings. | - ---- - -## Task Lifecycle - -``` -submitted โ†’ working โ†’ completed - โ†’ failed - โ†’ cancelled -``` - -- Tasks expire after 5 minutes (configurable) -- Terminal states: `completed`, `failed`, `cancelled` -- Event log tracks every state transition - ---- - -## Error Codes - -| Code | Meaning | -| :----- | :----------------------------- | -| -32700 | Parse error (invalid JSON) | -| -32600 | Invalid request / Unauthorized | -| -32601 | Method or skill not found | -| -32602 | Invalid params | -| -32603 | Internal error | - ---- - -## Integration Examples - -### Python (requests) - -```python -import requests - -resp = requests.post("http://localhost:20128/a2a", json={ - "jsonrpc": "2.0", "id": "1", - "method": "message/send", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Hello"}] - } -}, headers={"Authorization": "Bearer YOUR_KEY"}) - -result = resp.json()["result"] -print(result["artifacts"][0]["content"]) -print(result["metadata"]["routing_explanation"]) -``` - -### TypeScript (fetch) - -```typescript -const resp = await fetch("http://localhost:20128/a2a", { - method: "POST", - headers: { - "Content-Type": "application/json", - Authorization: "Bearer YOUR_KEY", - }, - body: JSON.stringify({ - jsonrpc: "2.0", - id: "1", - method: "message/send", - params: { - skill: "smart-routing", - messages: [{ role: "user", content: "Hello" }], - }, - }), -}); -const { result } = await resp.json(); -console.log(result.metadata.routing_explanation); -``` diff --git a/docs/i18n/pt-BR/API_REFERENCE.md b/docs/i18n/pt-BR/API_REFERENCE.md deleted file mode 100644 index b878605221..0000000000 --- a/docs/i18n/pt-BR/API_REFERENCE.md +++ /dev/null @@ -1,455 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/API_REFERENCE.md) - ---- - -# API Reference - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/API_REFERENCE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/API_REFERENCE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/API_REFERENCE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/API_REFERENCE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/API_REFERENCE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/API_REFERENCE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/API_REFERENCE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/API_REFERENCE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/API_REFERENCE.md) - -Complete reference for all OmniRoute API endpoints. - ---- - -## Table of Contents - -- [Chat Completions](#chat-completions) -- [Embeddings](#embeddings) -- [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`. - -### ACP Agents - -| Endpoint | Method | Description | -| ----------------- | ------ | -------------------------------------------------------- | -| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | -| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | -| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | - -GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). - -### Resilience & Rate Limits - -| Endpoint | Method | Description | -| ----------------------- | ------- | ------------------------------- | -| `/api/resilience` | 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` diff --git a/docs/i18n/pt-BR/ARCHITECTURE.md b/docs/i18n/pt-BR/ARCHITECTURE.md deleted file mode 100644 index 4ea06a29f2..0000000000 --- a/docs/i18n/pt-BR/ARCHITECTURE.md +++ /dev/null @@ -1,787 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/ARCHITECTURE.md) - ---- - -# OmniRoute Architecture - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/ARCHITECTURE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/ARCHITECTURE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/ARCHITECTURE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/ARCHITECTURE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/ARCHITECTURE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/ARCHITECTURE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/ARCHITECTURE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/ARCHITECTURE.md) - -_Last updated: 2026-03-04_ - -## 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 (`...`) for reasoning models -- Response sanitization for strict OpenAI SDK compatibility -- Role normalization (developerโ†’system, systemโ†’user) for cross-provider compatibility -- Structured output conversion (json_schema โ†’ Gemini responseSchema) -- Local persistence for providers, keys, aliases, combos, settings, pricing -- Usage/cost tracking and request logging -- Optional cloud sync for multi-device/state sync -- IP allowlist/blocklist for API access control -- Thinking budget management (passthrough/auto/custom/adaptive) -- Global system prompt injection -- Session tracking and fingerprinting -- Per-account enhanced rate limiting with provider-specific profiles -- Circuit breaker pattern for provider resilience -- Anti-thundering herd protection with mutex locking -- Signature-based request deduplication cache -- Domain layer: model availability, cost rules, fallback policy, lockout policy -- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) -- Policy engine for centralized request evaluation (lockout โ†’ budget โ†’ fallback) -- Request telemetry with p50/p95/p99 latency aggregation -- Correlation ID (X-Request-Id) for end-to-end tracing -- Compliance audit logging with opt-out per API key -- Eval framework for LLM quality assurance -- Resilience UI dashboard with real-time circuit breaker status -- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) - -Primary runtime model: - -- Next.js 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[(storage.sqlite)] - UDB[(usage tables + log artifacts)] - end - - subgraph Upstreams[Upstream Providers] - P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/Qoder/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/route.ts` (GET) -- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) -- OAuth: `src/app/api/oauth/*` -- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` -- Usage: `src/app/api/usage/*` -- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` -- CLI tooling helpers: `src/app/api/cli-tools/*` -- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) -- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) -- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) -- Sessions: `src/app/api/sessions` (GET) -- Rate limits: `src/app/api/rate-limits` (GET) -- Resilience: `src/app/api/resilience` (GET/PATCH) โ€” provider profiles, circuit breaker, rate limit state -- Resilience reset: `src/app/api/resilience/reset` (POST) โ€” reset breakers + cooldowns -- Cache stats: `src/app/api/cache/stats` (GET/DELETE) -- Model availability: `src/app/api/models/availability` (GET/POST) -- Telemetry: `src/app/api/telemetry/summary` (GET) -- Budget: `src/app/api/usage/budget` (GET/POST) -- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) -- Compliance audit: `src/app/api/compliance/audit-log` (GET) -- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) -- Policies: `src/app/api/policies` (GET/POST) - -## 2) SSE + 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` -- Response sanitization: `open-sse/handlers/responseSanitizer.ts` -- Role normalization: `open-sse/services/roleNormalizer.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`, `qoder.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 (SQLite): - -- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) -- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) -- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) -- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** - -Usage persistence: - -- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) -- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` -- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) -- legacy JSON files are migrated to SQLite by startup migrations when present - -Domain State DB (SQLite): - -- `src/lib/db/domainState.ts` โ€” CRUD operations 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: - -- primary runtime DB: `${DATA_DIR}/storage.sqlite` -- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) -- structured call payload archives: `${DATA_DIR}/call_logs/` -- optional translator/request debug sessions: `/logs/...` - -## Deployment Topology - -```mermaid -flowchart LR - 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[(storage.sqlite)] - UsageDB[(usage tables + log artifacts)] - end - - subgraph External[External Services] - Providers[AI Providers] - SyncCloud[Cloud Sync Service] - end - - CLI --> Next - Browser --> Next - Next --> Core - Next --> MainDB - Core --> MainDB - Core --> UsageDB - Core --> Providers - Next --> SyncCloud -``` - -## Module Mapping (Decision-Critical) - -### Route and API Modules - -- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs -- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) -- `src/app/api/providers*`: provider CRUD, validation, testing -- `src/app/api/provider-nodes*`: custom compatible node management -- `src/app/api/provider-models`: custom model management (CRUD) -- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) -- `src/app/api/oauth/*`: OAuth/device-code flows -- `src/app/api/keys*`: local API key lifecycle -- `src/app/api/models/alias`: alias management -- `src/app/api/combos*`: fallback combo management -- `src/app/api/pricing`: pricing overrides for cost calculation -- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) -- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) -- `src/app/api/usage/*`: usage and logs APIs -- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers -- `src/app/api/cli-tools/*`: local CLI config writers/checkers -- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) -- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) -- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) -- `src/app/api/sessions`: active session listing (GET) -- `src/app/api/rate-limits`: per-account rate limit status (GET) - -### Routing and Execution Core - -- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop -- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup -- `open-sse/executors/*`: provider-specific network and format behavior - -### Translation Registry and Format Converters - -- `open-sse/translator/index.ts`: translator registry and orchestration -- Request translators: `open-sse/translator/request/*` -- Response translators: `open-sse/translator/response/*` -- Format constants: `open-sse/translator/formats.ts` - -### Persistence - -- `src/lib/db/*`: persistent config/state and domain persistence on SQLite -- `src/lib/localDb.ts`: compatibility re-export for DB modules -- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables - -## Provider Executor Coverage (Strategy Pattern) - -Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. - -| Executor | Provider(s) | Special Handling | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | -| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, Qoder, 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 | -| Qoder | openai | OAuth (Basic) | โœ… | โœ… | โœ… | โš ๏ธ Per request | -| OpenRouter | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| GLM/Kimi/MiniMax | claude | API Key | โœ… | โœ… | โŒ | โŒ | -| DeepSeek | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Groq | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| xAI (Grok) | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Mistral | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Perplexity | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Together AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Fireworks AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Cerebras | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Cohere | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| NVIDIA NIM | openai | API Key | โœ… | โœ… | โŒ | โŒ | - -## Format Translation Coverage - -Detected source formats include: - -- `openai` -- `openai-responses` -- `claude` -- `gemini` - -Target formats include: - -- OpenAI chat/Responses -- Claude -- Gemini/Gemini-CLI/Antigravity envelope -- Kiro -- Cursor - -Translations use **OpenAI as the hub format** โ€” all conversions go through OpenAI as intermediate: - -``` -Source Format โ†’ OpenAI (hub) โ†’ Target Format -``` - -Translations are selected dynamically based on source payload shape and provider target format. - -Additional processing layers in the translation pipeline: - -- **Response sanitization** โ€” Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance -- **Role normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI targets; merges `system` โ†’ `user` for models that reject the system role (GLM, ERNIE) -- **Think tag extraction** โ€” Parses `...` blocks from content into `reasoning_content` field -- **Structured output** โ€” Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` - -## Supported API Endpoints - -| 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 `/logs//` 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 - -- SQLite schema migrations and auto-upgrade hooks at startup -- legacy JSON โ†’ SQLite migration compatibility path - -## Observability and Operational Signals - -Runtime visibility sources: - -- console logs from `src/sse/utils/logger.ts` -- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) -- textual request status log in `log.txt` (optional/compat) -- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` -- dashboard usage endpoints (`/api/usage/*`) for UI consumption - -## Security-Sensitive Boundaries - -- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing -- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning -- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format -- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level -- Cloud sync endpoints rely on API key auth + machine id semantics - -## Environment and Runtime Matrix - -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` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. -2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. -3. Request logger writes full headers/body when enabled; treat log directory as sensitive. -4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. -5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. -6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). -7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). -8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). - -## Operational Verification Checklist - -- Build from source: `npm run build` -- Build Docker image: `docker build -t omniroute .` -- Start service and verify: -- `GET /api/settings` -- `GET /api/v1/models` -- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/pt-BR/AUTO-COMBO.md b/docs/i18n/pt-BR/AUTO-COMBO.md deleted file mode 100644 index 2166e41dff..0000000000 --- a/docs/i18n/pt-BR/AUTO-COMBO.md +++ /dev/null @@ -1,67 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/AUTO-COMBO.md) - ---- - -# OmniRoute Auto-Combo Engine - -> Self-managing model chains with adaptive scoring - -## How It Works - -The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**: - -| Factor | Weight | Description | -| :--------- | :----- | :---------------------------------------------- | -| Quota | 0.20 | Remaining capacity [0..1] | -| Health | 0.25 | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 | -| CostInv | 0.20 | Inverse cost (cheaper = higher score) | -| LatencyInv | 0.15 | Inverse p95 latency (faster = higher) | -| TaskFit | 0.10 | Model ร— task type fitness score | -| Stability | 0.10 | Low variance in latency/errors | - -## Mode Packs - -| Pack | Focus | Key Weight | -| :---------------------- | :----------- | :--------------- | -| ๐Ÿš€ **Ship Fast** | Speed | latencyInv: 0.35 | -| ๐Ÿ’ฐ **Cost Saver** | Economy | costInv: 0.40 | -| ๐ŸŽฏ **Quality First** | Best model | taskFit: 0.40 | -| ๐Ÿ“ก **Offline Friendly** | Availability | quota: 0.40 | - -## Self-Healing - -- **Temporary exclusion**: Score < 0.2 โ†’ excluded for 5 min (progressive backoff, max 30 min) -- **Circuit breaker awareness**: OPEN โ†’ auto-excluded; HALF_OPEN โ†’ probe requests -- **Incident mode**: >50% OPEN โ†’ disable exploration, maximize stability -- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout - -## Bandit Exploration - -5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode. - -## API - -```bash -# Create auto-combo -curl -X POST http://localhost:20128/api/combos/auto \ - -H "Content-Type: application/json" \ - -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}' - -# List auto-combos -curl http://localhost:20128/api/combos/auto -``` - -## Task Fitness - -30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` โ†’ high coding score). - -## Files - -| File | Purpose | -| :------------------------------------------- | :------------------------------------ | -| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization | -| `open-sse/services/autoCombo/taskFitness.ts` | Model ร— task fitness lookup | -| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap | -| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode | -| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles | -| `src/app/api/combos/auto/route.ts` | REST API | diff --git a/docs/i18n/pt-BR/CHANGELOG.md b/docs/i18n/pt-BR/CHANGELOG.md index d8388b5edf..867e6fe6f0 100644 --- a/docs/i18n/pt-BR/CHANGELOG.md +++ b/docs/i18n/pt-BR/CHANGELOG.md @@ -1,12 +1,92 @@ # Changelog (Portuguรชs (Brasil)) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CHANGELOG.md) --- - ## [Unreleased] +### ๐Ÿ› ๏ธ Maintenance + +- **AGENTS.md rewrite:** Condensed from 297โ†’153 lines. Added build/lint/test commands (including single-test execution), code style guidelines (Prettier, TypeScript, ESLint, naming, imports, error handling, security), and trimmed verbose architecture tables for AI agent consumption. + +## [3.4.2] - 2026-04-01 + +### ๐Ÿ› Bug Fixes + +- **CI Stabilization:** Fixed failing analytics/settings Playwright selectors and request assertions so GitHub Actions E2E runs pass reliably across localized UIs and switch-based controls. +- **Deterministic Tests:** Removed date-sensitive quota fixtures from Copilot usage tests and aligned idempotency/model catalog tests with the merged runtime behavior. +- **MCP Type Hardening:** Removed zero-budget explicit `any` regressions from the MCP server tool registration path, restoring the `check:any-budget:t11` workflow gate. + +### ๐Ÿ› ๏ธ Maintenance + +- **Release Branch Integration:** Consolidated the active feature branches into `release/v3.4.2` on top of current `main` and validated the branch with lint, unit, coverage, build, and CI-mode E2E runs. + +## [3.4.1] - 2026-03-31 + +> [!WARNING] +> **BREAKING CHANGE: request logging, retention, and logging environment variables have been redesigned.** +> On the first startup after upgrading, OmniRoute archives legacy request logs from `DATA_DIR/logs/`, legacy `DATA_DIR/call_logs/`, and `DATA_DIR/log.txt` into `DATA_DIR/log_archives/*.zip`, then removes the deprecated layout and switches to the new unified artifact format under `DATA_DIR/call_logs/`. + +### โœจ New Features + +- **.ENV Migration Utility:** Included `scripts/migrate-env.mjs` to seamlessly migrate ` Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` - ---- - -## Step 2 โ€” Install CLI Tools - -All npm-based tools require Node.js 18+: - -```bash -# Claude Code (Anthropic) -npm install -g @anthropic-ai/claude-code - -# OpenAI Codex -npm install -g @openai/codex - -# Gemini CLI (Google) -npm install -g @google/gemini-cli - -# OpenCode -npm install -g opencode-ai - -# Cline -npm install -g cline - -# KiloCode -npm install -g kilecode - -# Kiro CLI (Amazon โ€” requires curl + unzip) -apt-get install -y unzip # on Debian/Ubuntu -curl -fsSL https://cli.kiro.dev/install | bash -export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc -``` - -**Verify:** - -```bash -claude --version # 2.x.x -codex --version # 0.x.x -gemini --version # 0.x.x -opencode --version # x.x.x -cline --version # 2.x.x -kilocode --version # x.x.x (or: kilo --version) -kiro-cli --version # 1.x.x -``` - ---- - -## Step 3 โ€” Set Global Environment Variables - -Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`: - -```bash -# OmniRoute Universal Endpoint -export OPENAI_BASE_URL="http://localhost:20128/v1" -export OPENAI_API_KEY="sk-your-omniroute-key" -export ANTHROPIC_BASE_URL="http://localhost:20128/v1" -export ANTHROPIC_API_KEY="sk-your-omniroute-key" -export GEMINI_BASE_URL="http://localhost:20128/v1" -export GEMINI_API_KEY="sk-your-omniroute-key" -``` - -> For a **remote server** replace `localhost:20128` with the server IP or domain, -> e.g. `http://192.168.0.15:20128`. - ---- - -## Step 4 โ€” Configure Each Tool - -### Claude Code - -```bash -# Via CLI: -claude config set --global api-base-url http://localhost:20128/v1 - -# Or create ~/.claude/settings.json: -mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF -{ - "apiBaseUrl": "http://localhost:20128/v1", - "apiKey": "sk-your-omniroute-key" -} -EOF -``` - -**Test:** `claude "say hello"` - ---- - -### OpenAI Codex - -```bash -mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF -model: auto -apiKey: sk-your-omniroute-key -apiBaseUrl: http://localhost:20128/v1 -EOF -``` - -**Test:** `codex "what is 2+2?"` - ---- - -### Gemini CLI - -```bash -mkdir -p ~/.gemini && cat > ~/.gemini/settings.json << EOF -{ - "apiKey": "sk-your-omniroute-key", - "baseUrl": "http://localhost:20128/v1" -} -EOF -``` - -**Test:** `gemini "hello"` - ---- - -### OpenCode - -```bash -mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF -[provider.openai] -base_url = "http://localhost:20128/v1" -api_key = "sk-your-omniroute-key" -EOF -``` - -**Test:** `opencode` - ---- - -### Cline (CLI or VS Code) - -**CLI mode:** - -```bash -mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF -{ - "apiProvider": "openai", - "openAiBaseUrl": "http://localhost:20128/v1", - "openAiApiKey": "sk-your-omniroute-key" -} -EOF -``` - -**VS Code mode:** -Cline extension settings โ†’ API Provider: `OpenAI Compatible` โ†’ Base URL: `http://localhost:20128/v1` - -Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ Cline โ†’ Apply Config**. - ---- - -### KiloCode (CLI or VS Code) - -**CLI mode:** - -```bash -kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key -``` - -**VS Code settings:** - -```json -{ - "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", - "kilo-code.apiKey": "sk-your-omniroute-key" -} -``` - -Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ KiloCode โ†’ Apply Config**. - ---- - -### Continue (VS Code Extension) - -Edit `~/.continue/config.yaml`: - -```yaml -models: - - name: OmniRoute - provider: openai - model: auto - apiBase: http://localhost:20128/v1 - apiKey: sk-your-omniroute-key - default: true -``` - -Restart VS Code after editing. - ---- - -### Kiro CLI (Amazon) - -```bash -# Login to your AWS/Kiro account: -kiro-cli login - -# The CLI uses its own auth โ€” OmniRoute is not needed as backend for Kiro CLI itself. -# Use kiro-cli alongside OmniRoute for other tools. -kiro-cli status -``` - ---- - -### Cursor (Desktop App) - -> **Note:** Cursor routes requests through its cloud. For OmniRoute integration, -> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL. - -Via GUI: **Settings โ†’ Models โ†’ OpenAI API Key** - -- Base URL: `https://your-domain.com/v1` -- API Key: your OmniRoute key - ---- - -## Dashboard Auto-Configuration - -The OmniRoute dashboard automates configuration for most tools: - -1. Go to `http://localhost:20128/dashboard/cli-tools` -2. Expand any tool card -3. Select your API key from the dropdown -4. Click **Apply Config** (if tool is detected as installed) -5. Or copy the generated config snippet manually - ---- - -## Built-in Agents: Droid & OpenClaw - -**Droid** and **OpenClaw** are AI agents built directly into OmniRoute โ€” no installation needed. -They run as internal routes and use OmniRoute's model routing automatically. - -- Access: `http://localhost:20128/dashboard/agents` -- Configure: same combos and providers as all other tools -- No API key or CLI install required - ---- - -## Available API Endpoints - -| Endpoint | Description | Use For | -| -------------------------- | ----------------------------- | --------------------------- | -| `/v1/chat/completions` | Standard chat (all providers) | All modern tools | -| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows | -| `/v1/completions` | Legacy text completions | Older tools using `prompt:` | -| `/v1/embeddings` | Text embeddings | RAG, search | -| `/v1/images/generations` | Image generation | DALL-E, Flux, etc. | -| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS | -| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI | - ---- - -## Troubleshooting - -| Error | Cause | Fix | -| ------------------------- | ----------------------- | ------------------------------------------ | -| `Connection refused` | OmniRoute not running | `pm2 start omniroute` | -| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` | -| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` | -| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` | -| CLI shows "not installed" | Binary not in PATH | Check `which ` | -| `kiro-cli: not found` | Not in PATH | `export PATH="$HOME/.local/bin:$PATH"` | - ---- - -## Quick Setup Script (One Command) - -```bash -# Install all CLIs and configure for OmniRoute (replace with your key and server URL) -OMNIROUTE_URL="http://localhost:20128/v1" -OMNIROUTE_KEY="sk-your-omniroute-key" - -npm install -g @anthropic-ai/claude-code @openai/codex @google/gemini-cli opencode-ai cline kilecode - -# Kiro CLI -apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash - -# Write configs -mkdir -p ~/.claude ~/.codex ~/.gemini ~/.config/opencode ~/.continue - -cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" -cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" -cat > ~/.gemini/settings.json <<< "{\"apiKey\":\"$OMNIROUTE_KEY\",\"baseUrl\":\"$OMNIROUTE_URL\"}" -cat >> ~/.bashrc << EOF -export OPENAI_BASE_URL="$OMNIROUTE_URL" -export OPENAI_API_KEY="$OMNIROUTE_KEY" -export ANTHROPIC_BASE_URL="$OMNIROUTE_URL" -export ANTHROPIC_API_KEY="$OMNIROUTE_KEY" -EOF - -source ~/.bashrc -echo "โœ… All CLIs installed and configured for OmniRoute" -``` diff --git a/docs/i18n/pt-BR/CODEBASE_DOCUMENTATION.md b/docs/i18n/pt-BR/CODEBASE_DOCUMENTATION.md deleted file mode 100644 index e2d7950052..0000000000 --- a/docs/i18n/pt-BR/CODEBASE_DOCUMENTATION.md +++ /dev/null @@ -1,593 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CODEBASE_DOCUMENTATION.md) - ---- - -# omniroute โ€” Codebase Documentation - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) - -> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. - ---- - -## 1. 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
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, Qoder, 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 | -| Qoder | 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"] -``` diff --git a/docs/i18n/pt-BR/CONTRIBUTING.md b/docs/i18n/pt-BR/CONTRIBUTING.md new file mode 100644 index 0000000000..1f472aca34 --- /dev/null +++ b/docs/i18n/pt-BR/CONTRIBUTING.md @@ -0,0 +1,299 @@ +# Contributing to OmniRoute (Portuguรชs (Brasil)) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CONTRIBUTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CONTRIBUTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CONTRIBUTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CONTRIBUTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CONTRIBUTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CONTRIBUTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CONTRIBUTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CONTRIBUTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CONTRIBUTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CONTRIBUTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CONTRIBUTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CONTRIBUTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CONTRIBUTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CONTRIBUTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CONTRIBUTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CONTRIBUTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CONTRIBUTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CONTRIBUTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CONTRIBUTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CONTRIBUTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CONTRIBUTING.md) + +--- + +Thank you for your interest in contributing! This guide covers everything you need to get started. + +--- + +## Development Setup + +### Prerequisites + +- **Node.js** >= 18 < 24 (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` | `20128` | Server port | +| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | Base URL for frontend | +| `JWT_SECRET` | (generate above) | JWT signing secret | +| `INITIAL_PASSWORD` | `CHANGEME` | First login password | +| `APP_LOG_LEVEL` | `info` | Log verbosity level | + +### Dashboard Settings + +The dashboard provides UI toggles for features that can also be configured via environment variables: + +| Setting Location | Toggle | Description | +| ------------------- | ------------------ | ------------------------------ | +| Settings โ†’ Advanced | Debug Mode | Enable debug request logs (UI) | +| Settings โ†’ General | Sidebar Visibility | Show/hide sidebar sections | + +These settings are stored in the database and persist across restarts, overriding env var defaults when set. + +### 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:20128/dashboard` +- **API**: `http://localhost:20128/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`, `mcp`, `a2a`, `memory`, `skills`. + +--- + +## Running Tests + +```bash +# All tests (unit + vitest + ecosystem + e2e) +npm run test:all + +# Single test file (Node.js native test runner โ€” most tests use this) +node --import tsx/esm --test tests/unit/your-file.test.mjs + +# Vitest (MCP server, autoCombo, cache) +npm run test:vitest + +# E2E tests (requires Playwright) +npm run test:e2e + +# Protocol clients E2E (MCP transports, A2A) +npm run test:protocols:e2e + +# Ecosystem compatibility tests +npm run test:ecosystem + +# Coverage (55% min statements/lines/functions; 60% branches) +npm run test:coverage +npm run coverage:report + +# Lint + format check +npm run lint +npm run check +``` + +Coverage notes: + +- `npm run test:coverage` measures source coverage for the main unit test suite, excludes `tests/**`, and includes `open-sse/**` +- `npm run coverage:report` prints the detailed file-by-file report from the latest coverage run +- `npm run test:coverage:legacy` preserves the older metric for historical comparison +- See `docs/COVERAGE_PLAN.md` for the phased coverage improvement roadmap + +Current test status: **122 unit test files** covering: + +- Provider translators and format conversion +- Rate limiting, circuit breaker, and resilience +- Semantic cache, idempotency, progress tracking +- Database operations and schema (21 DB modules) +- OAuth flows and authentication +- API endpoint validation (Zod v4) +- MCP server tools and scope enforcement +- Memory and Skills systems + +--- + +## Code Style + +- **ESLint** โ€” Run `npm run lint` before committing +- **Prettier** โ€” Auto-formatted via `lint-staged` on commit (2 spaces, semicolons, double quotes, 100 char width, es5 trailing commas) +- **TypeScript** โ€” All `src/` code uses `.ts`/`.tsx`; `open-sse/` uses `.ts`/`.js`; document with TSDoc (`@param`, `@returns`, `@throws`) +- **No `eval()`** โ€” ESLint enforces `no-eval`, `no-implied-eval`, `no-new-func` +- **Zod validation** โ€” Use Zod v4 schemas for all API input validation +- **Naming**: Files = camelCase/kebab-case, components = PascalCase, constants = UPPER_SNAKE + +--- + +## Project Structure + +``` +src/ # TypeScript (.ts / .tsx) +โ”œโ”€โ”€ app/ # Next.js 16 App Router +โ”‚ โ”œโ”€โ”€ (dashboard)/ # Dashboard pages (23 sections) +โ”‚ โ”œโ”€โ”€ api/ # API routes (51 directories) +โ”‚ โ””โ”€โ”€ login/ # Auth pages (.tsx) +โ”œโ”€โ”€ domain/ # Policy engine (policyEngine, comboResolver, costRules, etc.) +โ”œโ”€โ”€ lib/ # Core business logic (.ts) +โ”‚ โ”œโ”€โ”€ a2a/ # Agent-to-Agent v0.3 protocol server +โ”‚ โ”œโ”€โ”€ acp/ # Agent Communication Protocol registry +โ”‚ โ”œโ”€โ”€ compliance/ # Compliance policy engine +โ”‚ โ”œโ”€โ”€ db/ # SQLite database layer (21 modules + 16 migrations) +โ”‚ โ”œโ”€โ”€ memory/ # Persistent conversational memory +โ”‚ โ”œโ”€โ”€ oauth/ # OAuth providers, services, and utilities +โ”‚ โ”œโ”€โ”€ skills/ # Extensible skill framework +โ”‚ โ”œโ”€โ”€ usage/ # Usage tracking and cost calculation +โ”‚ โ””โ”€โ”€ localDb.ts # Re-export layer only โ€” never add logic here +โ”œโ”€โ”€ middleware/ # Request middleware (promptInjectionGuard) +โ”œโ”€โ”€ mitm/ # MITM proxy (cert, DNS, target routing) +โ”œโ”€โ”€ shared/ +โ”‚ โ”œโ”€โ”€ components/ # React components (.tsx) +โ”‚ โ”œโ”€โ”€ constants/ # Provider definitions (60+), MCP scopes, routing strategies +โ”‚ โ”œโ”€โ”€ utils/ # Circuit breaker, sanitizer, auth helpers +โ”‚ โ””โ”€โ”€ validation/ # Zod v4 schemas +โ””โ”€โ”€ sse/ # SSE proxy pipeline + +open-sse/ # @omniroute/open-sse workspace +โ”œโ”€โ”€ executors/ # 14 provider-specific request executors +โ”œโ”€โ”€ handlers/ # 11 request handlers (chat, responses, embeddings, images, etc.) +โ”œโ”€โ”€ mcp-server/ # MCP server (25 tools, 3 transports, 10 scopes) +โ”œโ”€โ”€ services/ # 36+ services (combo, autoCombo, rateLimitManager, etc.) +โ”œโ”€โ”€ translator/ # Format translators (OpenAI โ†” Claude โ†” Gemini โ†” Responses โ†” Ollama) +โ”œโ”€โ”€ transformer/ # Responses API transformer +โ””โ”€โ”€ utils/ # 22 utility modules (stream, TLS, proxy, logging) + +electron/ # Electron desktop app (cross-platform) + +tests/ +โ”œโ”€โ”€ unit/ # Node.js test runner (122 test files) +โ”œโ”€โ”€ integration/ # Integration tests +โ”œโ”€โ”€ e2e/ # Playwright tests +โ”œโ”€โ”€ security/ # Security tests +โ”œโ”€โ”€ translator/ # Translator-specific tests +โ””โ”€โ”€ load/ # Load tests + +docs/ # Documentation +โ”œโ”€โ”€ ARCHITECTURE.md # System architecture +โ”œโ”€โ”€ API_REFERENCE.md # All endpoints +โ”œโ”€โ”€ USER_GUIDE.md # Provider setup, CLI integration +โ”œโ”€โ”€ TROUBLESHOOTING.md # Common issues +โ”œโ”€โ”€ MCP-SERVER.md # MCP server (25 tools) +โ”œโ”€โ”€ A2A-SERVER.md # A2A agent protocol +โ”œโ”€โ”€ AUTO-COMBO.md # Auto-combo engine +โ”œโ”€โ”€ CLI-TOOLS.md # CLI tools integration +โ”œโ”€โ”€ COVERAGE_PLAN.md # Test coverage improvement plan +โ”œโ”€โ”€ openapi.yaml # OpenAPI specification +โ””โ”€โ”€ adr/ # Architecture Decision Records +``` + +--- + +## Adding a New Provider + +### Step 1: Register Provider Constants + +Add to `src/shared/constants/providers.ts` โ€” Zod-validated at module load. + +### Step 2: Add Executor (if custom logic needed) + +Create executor in `open-sse/executors/your-provider.ts` extending the base executor. + +### Step 3: Add Translator (if non-OpenAI format) + +Create request/response translators in `open-sse/translator/`. + +### Step 4: Add OAuth Config (if OAuth-based) + +Add OAuth credentials in `src/lib/oauth/constants/oauth.ts` and service in `src/lib/oauth/services/`. + +### Step 5: Register Models + +Add model definitions in `open-sse/config/providerRegistry.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 +- [ ] All inputs validated with Zod schemas +- [ ] CHANGELOG updated (if user-facing change) +- [ ] Documentation updated (if applicable) + +--- + +## Releasing + +Releases are managed via the `/generate-release` workflow. When a new GitHub Release is created, the package is **automatically published to npm** via GitHub Actions. + +--- + +## Getting Help + +- **Architecture**: See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) +- **API Reference**: See [`docs/API_REFERENCE.md`](docs/API_REFERENCE.md) +- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **ADRs**: See `docs/adr/` for architectural decision records diff --git a/docs/i18n/pt-BR/FEATURES.md b/docs/i18n/pt-BR/FEATURES.md deleted file mode 100644 index dfe257e6e8..0000000000 --- a/docs/i18n/pt-BR/FEATURES.md +++ /dev/null @@ -1,148 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/FEATURES.md) - ---- - -# OmniRoute โ€” Dashboard Features Gallery - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](FEATURES.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/FEATURES.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/FEATURES.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/FEATURES.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/FEATURES.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/FEATURES.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/FEATURES.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/FEATURES.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/FEATURES.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/FEATURES.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/FEATURES.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/FEATURES.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/FEATURES.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/FEATURES.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/FEATURES.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/FEATURES.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/FEATURES.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/FEATURES.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/FEATURES.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/FEATURES.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/FEATURES.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/FEATURES.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/FEATURES.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/FEATURES.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/FEATURES.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/FEATURES.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/FEATURES.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/FEATURES.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/FEATURES.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/FEATURES.md) - -Visual guide to every section of the OmniRoute dashboard. - ---- - -## ๐Ÿ”Œ Providers - -Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (Qoder, Qwen, Kiro). - -- **Ollama Cloud** โ€” Cloud-hosted Ollama models at `api.ollama.com` (free "Light usage" tier); use `ollamacloud/` prefix - -![Providers Dashboard](screenshots/01-providers.png) - ---- - -## ๐ŸŽจ Combos - -Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. - -![Combos Dashboard](screenshots/02-combos.png) - ---- - -## ๐Ÿ“Š Analytics - -Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. - -![Analytics Dashboard](screenshots/03-analytics.png) - ---- - -## ๐Ÿฅ System Health - -Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. - -![Health Dashboard](screenshots/04-health.png) - ---- - -## ๐Ÿ”ง Translator Playground - -Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). - -![Translator Playground](screenshots/05-translator.png) - ---- - -## ๐ŸŽฎ Model Playground _(v2.0.9+)_ - -Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. - ---- - -## ๐ŸŽจ Themes _(v2.0.5+)_ - -Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. - ---- - -## โš™๏ธ Settings - -Comprehensive settings panel with tabs: - -- **General** โ€” System storage, backup management (export/import database) -- **Appearance** โ€” Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls -- **Security** โ€” API endpoint protection, custom provider blocking, IP filtering, session info -- **Routing** โ€” Model aliases, background task degradation -- **Resilience** โ€” Rate limit persistence, circuit breaker tuning -- **Advanced** โ€” Configuration overrides - -![Settings Dashboard](screenshots/06-settings.png) - ---- - -## ๐Ÿ”ง CLI Tools - -One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. - -![CLI Tools Dashboard](screenshots/07-cli-tools.png) - ---- - -## ๐Ÿค– CLI Agents _(v2.0.11+)_ - -Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: - -- **Installation status** โ€” Installed / Not Found with version detection -- **Protocol badges** โ€” stdio, HTTP, etc. -- **Custom agents** โ€” Register any CLI tool via form (name, binary, version command, spawn args) -- **CLI Fingerprint Matching** โ€” Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP - ---- - -## ๐Ÿ–ผ๏ธ Media _(v2.0.3+)_ - -Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. - ---- - -## ๐Ÿ“ Request Logs - -Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. - -![Usage Logs](screenshots/08-usage.png) - ---- - -## ๐ŸŒ API Endpoint - -Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. - -![Endpoint Dashboard](screenshots/09-endpoint.png) - ---- - -## ๐Ÿ”‘ API Key Management - -Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. - ---- - -## ๐Ÿ“‹ Audit Log - -Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. - ---- - -## ๐Ÿ–ฅ๏ธ Desktop Application - -Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. - -Key features: - -- Server readiness polling (no blank screen on cold start) -- System tray with port management -- Content Security Policy -- Single-instance lock -- Auto-update on restart -- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) - -๐Ÿ“– See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/pt-BR/MCP-SERVER.md b/docs/i18n/pt-BR/MCP-SERVER.md deleted file mode 100644 index 829acd30b1..0000000000 --- a/docs/i18n/pt-BR/MCP-SERVER.md +++ /dev/null @@ -1,87 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/MCP-SERVER.md) - ---- - -# OmniRoute MCP Server Documentation - -> Model Context Protocol server with 16 intelligent tools - -## Installation - -OmniRoute MCP is built-in. Start it with: - -```bash -omniroute --mcp -``` - -Or via the open-sse transport: - -```bash -# HTTP streamable transport (port 20130) -omniroute --dev # MCP auto-starts on /mcp endpoint -``` - -## IDE Configuration - -See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup. - ---- - -## Essential Tools (8) - -| Tool | Description | -| :------------------------------ | :--------------------------------------- | -| `omniroute_get_health` | Gateway health, circuit breakers, uptime | -| `omniroute_list_combos` | All configured combos with models | -| `omniroute_get_combo_metrics` | Performance metrics for a specific combo | -| `omniroute_switch_combo` | Switch active combo by ID/name | -| `omniroute_check_quota` | Quota status per provider or all | -| `omniroute_route_request` | Send a chat completion through OmniRoute | -| `omniroute_cost_report` | Cost analytics for a time period | -| `omniroute_list_models_catalog` | Full model catalog with capabilities | - -## Advanced Tools (8) - -| Tool | Description | -| :--------------------------------- | :---------------------------------------------- | -| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | -| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | -| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | -| `omniroute_test_combo` | Live-test all models in a combo | -| `omniroute_get_provider_metrics` | Detailed metrics for one provider | -| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | -| `omniroute_explain_route` | Explain a past routing decision | -| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | - -## Authentication - -MCP tools are authenticated via API key scopes. Each tool requires specific scopes: - -| Scope | Tools | -| :------------- | :----------------------------------------------- | -| `read:health` | get_health, get_provider_metrics | -| `read:combos` | list_combos, get_combo_metrics | -| `write:combos` | switch_combo | -| `read:quota` | check_quota | -| `write:route` | route_request, simulate_route, test_combo | -| `read:usage` | cost_report, get_session_snapshot, explain_route | -| `write:config` | set_budget_guard, set_resilience_profile | -| `read:models` | list_models_catalog, best_combo_for_task | - -## Audit Logging - -Every tool call is logged to `mcp_tool_audit` with: - -- Tool name, arguments, result -- Duration (ms), success/failure -- API key hash, timestamp - -## Files - -| File | Purpose | -| :------------------------------------------- | :------------------------------------------ | -| `open-sse/mcp-server/server.ts` | MCP server creation + 16 tool registrations | -| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport | -| `open-sse/mcp-server/auth.ts` | API key + scope validation | -| `open-sse/mcp-server/audit.ts` | Tool call audit logging | -| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers | diff --git a/docs/i18n/pt-BR/README.md b/docs/i18n/pt-BR/README.md index 68c5c90f81..a5015c7e6f 100644 --- a/docs/i18n/pt-BR/README.md +++ b/docs/i18n/pt-BR/README.md @@ -1,12 +1,12 @@ # ๐Ÿš€ OmniRoute โ€” The Free AI Gateway (Portuguรชs (Brasil)) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/README.md) --- ### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback. -_Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._ +_Your universal API proxy โ€” one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._ **Chat Completions โ€ข Embeddings โ€ข Image Generation โ€ข Video โ€ข Music โ€ข Audio โ€ข Reranking โ€ข **Web Search** โ€ข MCP Server โ€ข A2A Protocol โ€ข 100% TypeScript** @@ -46,15 +46,17 @@ _Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now wi > - `APP_LOG_FILE_PATH` > - `APP_LOG_MAX_FILE_SIZE` > - `APP_LOG_RETENTION_DAYS` +> - `APP_LOG_MAX_FILES` > - `APP_LOG_LEVEL` > - `APP_LOG_FORMAT` > - `CALL_LOG_RETENTION_DAYS` +> - `CALL_LOG_MAX_ENTRIES` > > For release details and upgrade notes, see the [CHANGELOG](CHANGELOG.md). --- -## ๐Ÿ†• What's New in v3.0.0 +## ๐Ÿ†• What's New > **Upgrading from v2.9.5?** โ€” See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes. @@ -274,7 +276,7 @@ Developers pay $20โ€“200/month for Claude Pro, Codex Pro, or GitHub Copilot. Eve - **Smart 4-Tier Fallback** โ€” If subscription quota runs out, automatically redirects to API Key โ†’ Cheap โ†’ Free with zero manual intervention - **Real-Time Quota Tracking** โ€” Shows token consumption in real-time with reset countdown (5h, daily, weekly) - **Multi-Account Support** โ€” Multiple accounts per provider with auto round-robin โ€” when one runs out, switches to the next -- **Custom Combos** โ€” Customizable fallback chains with 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Custom Combos** โ€” Customizable fallback chains with 9 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random) - **Codex Business Quotas** โ€” Business/Team workspace quota monitoring directly in the dashboard @@ -286,7 +288,7 @@ OpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If **How OmniRoute solves it:** -- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 67+ providers +- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 60+ providers - **Format Translation** โ€” Automatic and transparent: OpenAI โ†” Claude โ†” Gemini โ†” Responses API - **Response Sanitization** โ€” Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+ - **Role Normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI providers; `system` โ†’ `user` for GLM/ERNIE @@ -372,7 +374,7 @@ Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code.. - **CLI Tools Dashboard** โ€” Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline - **GitHub Copilot Config Generator** โ€” Generates `chatLanguageModels.json` for VS Code with bulk model selection - **Onboarding Wizard** โ€” Guided 4-step setup for first-time users -- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 67+ providers +- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 60+ providers @@ -419,7 +421,7 @@ When a call fails, the dev doesn't know if it was a rate limit, expired token, w - **SQLite Proxy Logs** โ€” Persistent logs that survive server restarts - **Translator Playground** โ€” 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time) - **Request Telemetry** โ€” p50/p95/p99 latency + X-Request-Id tracing -- **File-Based Logging with Rotation** โ€” Console interceptor captures everything to JSON log with size-based rotation +- **File-Based Logging with Rotation** โ€” App logs rotate by size, retention days, and archive count; call log artifacts rotate by retention days and file count - **System Info Report** โ€” `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage. @@ -514,7 +516,7 @@ Developers who want all responses in a specific language, with a specific tone, - **System Prompt Injection** โ€” Global prompt applied to all requests - **Thinking Budget Validation** โ€” Reasoning token allocation control per request (passthrough, auto, custom, adaptive) -- **6 Routing Strategies** โ€” Global strategies that determine how requests are distributed +- **9 Routing Strategies** โ€” Global strategies that determine how requests are distributed - **Wildcard Router** โ€” `provider/*` patterns route dynamically to any provider - **Combo Enable/Disable Toggle** โ€” Toggle combos directly from the dashboard - **Provider Toggle** โ€” Enable/disable all connections for a provider with one click @@ -581,7 +583,7 @@ Different clients should have least-privilege access to tool categories. **How OmniRoute solves it:** -- 9 granular MCP scopes for controlled tool access +- 10 granular MCP scopes for controlled tool access - Scope enforcement and visibility in MCP management UI - Safe default posture for operational tooling @@ -1325,19 +1327,19 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. ### ๐Ÿค– Agent & Protocol Operations (v2.0) -| Feature | What It Does | -| ------------------------------------- | -------------------------------------------------------------------------------------------------- | -| ๐Ÿ”ง **MCP Server (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) | -| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | -| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | -| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | -| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | -| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | -| ๐Ÿ” **MCP Scope Enforcement** | 9 granular scope permissions for controlled tool access | -| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | -| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | -| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | -| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | +| Feature | What It Does | +| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| ๐Ÿ”ง **MCP Server (25 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools | +| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | +| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | +| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | +| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | +| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | +| ๐Ÿ” **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access | +| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | +| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | +| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | +| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | ### ๐Ÿง  Routing & Intelligence @@ -1348,7 +1350,7 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. | ๐Ÿ”„ **Format Translation** | OpenAI โ†” Claude โ†” Gemini โ†” Responses with schema-safe conversions | | ๐Ÿ‘ฅ **Multi-Account Support** | Multiple accounts per provider with intelligent selection | | ๐Ÿ”„ **Auto Token Refresh** | OAuth tokens refresh automatically with retry | -| ๐ŸŽจ **Custom Combos** | 6 balancing strategies + fallback chain control | +| ๐ŸŽจ **Custom Combos** | 9 balancing strategies + fallback chain control | | ๐ŸŒ **Wildcard Router** | `provider/*` dynamic routing | | ๐Ÿง  **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits | | ๐Ÿ”€ **Model Aliases** | Built-in + custom model aliasing and migration safety | @@ -1949,6 +1951,7 @@ opencode - Request artifacts are written to `DATA_DIR/call_logs/` as one JSON file per request - Enable pipeline capture from Dashboard โ†’ Logs โ†’ Request Logs if you need detailed per-stage payloads - Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log` +- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed **Connection test shows "Invalid" for OpenAI-compatible providers** diff --git a/docs/i18n/pt-BR/RELEASE_CHECKLIST.md b/docs/i18n/pt-BR/RELEASE_CHECKLIST.md deleted file mode 100644 index 903e812c3f..0000000000 --- a/docs/i18n/pt-BR/RELEASE_CHECKLIST.md +++ /dev/null @@ -1,37 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/RELEASE_CHECKLIST.md) - ---- - -# Release Checklist - -Use this checklist before tagging or publishing a new OmniRoute release. - -## Version and Changelog - -1. Bump `package.json` version (`x.y.z`) in the release branch. -2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: - - `## [x.y.z] โ€” YYYY-MM-DD` -3. Keep `## [Unreleased]` as the first changelog section for upcoming work. -4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. - -## API Docs - -1. Update `docs/openapi.yaml`: - - `info.version` must equal `package.json` version. -2. Validate endpoint examples if API contracts changed. - -## Runtime Docs - -1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. -2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. -3. Update localized docs if source docs changed significantly. - -## Automated Check - -Run the sync guard locally before opening PR: - -```bash -npm run check:docs-sync -``` - -CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/pt-BR/SECURITY.md b/docs/i18n/pt-BR/SECURITY.md new file mode 100644 index 0000000000..3fe3f66790 --- /dev/null +++ b/docs/i18n/pt-BR/SECURITY.md @@ -0,0 +1,179 @@ +# Security Policy (Portuguรชs (Brasil)) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../SECURITY.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/SECURITY.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/SECURITY.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/SECURITY.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/SECURITY.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/SECURITY.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/SECURITY.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/SECURITY.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/SECURITY.md) + +--- + +## 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 | +| ------- | -------------- | +| 3.4.x | โœ… Active | +| 3.0.x | โœ… Security | +| < 3.0.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 | +| **MCP Scopes** | 10 granular scopes for MCP tool access control | + +### ๐Ÿ›ก๏ธ 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:::` +- 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** | Allowlist/blocklist IP ranges in dashboard | +| **Rate Limiting** | Per-provider rate limits with automatic backoff | +| **Anti-Thundering Herd** | Mutex + per-connection locking prevents cascading 502s | +| **TLS Fingerprint** | Browser-like TLS fingerprint spoofing to reduce bot detection | +| **CLI Fingerprint** | Per-provider header/body ordering to match native CLI signatures | + +### ๐Ÿ”Œ Resilience & Availability + +| 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 `CALL_LOG_RETENTION_DAYS` | +| **No-Log Opt-out** | Per API key `noLog` flag disables request logging | +| **Audit Log** | Administrative actions tracked in `audit_log` table | +| **MCP Audit** | SQLite-backed audit logging for all MCP tool calls | +| **Zod Validation** | All API inputs validated with Zod v4 schemas at module load | + +--- + +## 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 +- Provider constants validated at module load via Zod (`src/shared/validation/providerSchema.ts`) diff --git a/docs/i18n/pt-BR/TROUBLESHOOTING.md b/docs/i18n/pt-BR/TROUBLESHOOTING.md deleted file mode 100644 index 63c148000a..0000000000 --- a/docs/i18n/pt-BR/TROUBLESHOOTING.md +++ /dev/null @@ -1,258 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/TROUBLESHOOTING.md) - ---- - -# Troubleshooting - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/TROUBLESHOOTING.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/TROUBLESHOOTING.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/TROUBLESHOOTING.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/TROUBLESHOOTING.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/TROUBLESHOOTING.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/TROUBLESHOOTING.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/TROUBLESHOOTING.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/TROUBLESHOOTING.md) - -Common problems and solutions for OmniRoute. - ---- - -## Quick Fixes - -| Problem | Solution | -| ----------------------------- | ------------------------------------------------------------------ | -| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | -| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | -| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | -| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | -| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | - ---- - -## Provider Issues - -### "Language model did not provide messages" - -**Cause:** Provider quota exhausted. - -**Fix:** - -1. 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, Qoder) 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}/storage.sqlite` (providers, combos, aliases, keys, settings) -- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` -- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) - ---- - -## Circuit Breaker Issues - -### Provider stuck in OPEN state - -When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. - -**Fix:** - -1. 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 -- **SDK returns raw string instead of object** โ€” Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures -- **GLM/ERNIE rejects `system` role** โ€” Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models -- **`developer` role not recognized** โ€” Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers -- **`json_schema` not working with Gemini** โ€” Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` - ---- - -## Resilience Settings - -### Auto rate-limit not triggering - -- 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. - ---- - -## Optional RAG / LLM failure taxonomy (16 problems) - -Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. - -In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. - -If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: - -- retrieval drift and broken context boundaries -- empty or stale indexes and vector stores -- embedding versus semantic mismatch -- prompt assembly and context window issues -- logic collapse and overconfident answers -- long chain and agent coordination failures -- multi agent memory and role drift -- deployment and bootstrap ordering problems - -The idea is simple: - -1. When you investigate a bad response, capture: - - user task and request - - route or provider combo in OmniRoute - - any RAG context used downstream (retrieved documents, tool calls, etc) -2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` โ€ฆ `No.16`). -3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. -4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. - -Full text and concrete recipes live here (MIT license, text only): - -[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) - -You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. - ---- - -## Still Stuck? - -- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details -- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints -- **Health Dashboard**: Check **Dashboard โ†’ Health** for real-time system status -- **Translator**: Use **Dashboard โ†’ Translator** to debug format issues diff --git a/docs/i18n/pt-BR/USER_GUIDE.md b/docs/i18n/pt-BR/USER_GUIDE.md deleted file mode 100644 index 5d986cb689..0000000000 --- a/docs/i18n/pt-BR/USER_GUIDE.md +++ /dev/null @@ -1,913 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/USER_GUIDE.md) - ---- - -# User Guide - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](USER_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/USER_GUIDE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/USER_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/USER_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/USER_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/USER_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/USER_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/USER_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/USER_GUIDE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/USER_GUIDE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/USER_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/USER_GUIDE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/USER_GUIDE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/USER_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/USER_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/USER_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/USER_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/USER_GUIDE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/USER_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/USER_GUIDE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/USER_GUIDE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/USER_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/USER_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/USER_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/USER_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/USER_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/USER_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/USER_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/USER_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/USER_GUIDE.md) - -Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute. - ---- - -## Table of Contents - -- [Pricing at a Glance](#-pricing-at-a-glance) -- [Use Cases](#-use-cases) -- [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** | Qoder | $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) + Qoder (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 - -#### Qoder (8 FREE models) - -```bash -Dashboard โ†’ Connect Qoder โ†’ 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 - -### Global npm install (Recommended) - -```bash -npm install -g omniroute - -# Create config directory -mkdir -p ~/.omniroute - -# Create .env file (see .env.example) -cp .env.example ~/.omniroute/.env - -# Start server -omniroute -# Or with custom port: -omniroute --port 3000 -``` - -The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`. - -### VPS Deployment - -```bash -git clone https://github.com/diegosouzapw/OmniRoute.git -cd OmniRoute && npm install && npm run build - -export JWT_SECRET="your-secure-secret-change-this" -export INITIAL_PASSWORD="your-password" -export DATA_DIR="/var/lib/omniroute" -export PORT="20128" -export HOSTNAME="0.0.0.0" -export NODE_ENV="production" -export NEXT_PUBLIC_BASE_URL="http://localhost:20128" -export API_KEY_SECRET="endpoint-proxy-api-key-secret" - -npm run start -# Or: pm2 start npm --name omniroute -- start -``` - -### PM2 Deployment (Low Memory) - -For servers with limited RAM, use the memory limit option: - -```bash -# With 512MB limit (default) -pm2 start npm --name omniroute -- start - -# Or with custom memory limit -OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start - -# Or using ecosystem.config.js -pm2 start ecosystem.config.js -``` - -Create `ecosystem.config.js`: - -```javascript -module.exports = { - apps: [ - { - name: "omniroute", - script: "npm", - args: "start", - env: { - NODE_ENV: "production", - OMNIROUTE_MEMORY_MB: "512", - JWT_SECRET: "your-secret", - INITIAL_PASSWORD: "your-password", - }, - node_args: "--max-old-space-size=512", - max_memory_restart: "300M", - }, - ], -}; -``` - -### Docker - -```bash -# Build image (default = runner-cli with codex/claude/droid preinstalled) -docker build -t omniroute:cli . - -# Portable mode (recommended) -docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli -``` - -For host-integrated mode with CLI binaries, see the Docker section in the main docs. - -### Void Linux (xbps-src) - -Usuรกrios do Void Linux podem empacotar e instalar o OmniRoute nativamente usando o framework de compilaรงรฃo cruzada `xbps-src`. Isso automatiza a compilaรงรฃo do bundle standalone do Node.js juntamente com os bindings nativos necessรกrios do `better-sqlite3`. - -
-Ver template do xbps-src - -```bash -# Template file for 'omniroute' -pkgname=omniroute -version=3.2.4 -revision=1 -hostmakedepends="nodejs python3 make" -depends="openssl" -short_desc="Universal AI gateway with smart routing for multiple LLM providers" -maintainer="zenobit " -license="MIT" -homepage="https://github.com/diegosouzapw/OmniRoute" -distfiles="https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz" -checksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b -system_accounts="_omniroute" -omniroute_homedir="/var/lib/omniroute" -export NODE_ENV=production -export npm_config_engine_strict=false -export npm_config_loglevel=error -export npm_config_fund=false -export npm_config_audit=false - -do_build() { - # Determine target CPU arch for node-gyp - local _gyp_arch - case "$XBPS_TARGET_MACHINE" in - aarch64*) _gyp_arch=arm64 ;; - armv7*|armv6*) _gyp_arch=arm ;; - i686*) _gyp_arch=ia32 ;; - *) _gyp_arch=x64 ;; - esac - - # 1) Install all deps โ€“ skip scripts - NODE_ENV=development npm ci --ignore-scripts - - # 2) Build the Next.js standalone bundle - npm run build - - # 3) Copy static assets into standalone - cp -r .next/static .next/standalone/.next/static - [ -d public ] && cp -r public .next/standalone/public || true - - # 4) Compile better-sqlite3 native binding - local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js - (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch") - - # 5) Place the compiled binding into the standalone bundle - local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release - mkdir -p "$_bs3_release" - cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/" - - # 6) Remove arch-specific sharp bundles - rm -rf .next/standalone/node_modules/@img - - # 7) Copy pino runtime deps omitted by Next.js static analysis: - for _mod in pino-abstract-transport split2 process-warning; do - cp -r "node_modules/$_mod" .next/standalone/node_modules/ - done -} - -do_check() { - npm run test:unit -} - -do_install() { - vmkdir usr/lib/omniroute/.next - vcopy .next/standalone/. usr/lib/omniroute/.next/standalone - - # Prevent removal of empty Next.js app router dirs by the post-install hook - for _d in \ - .next/standalone/.next/server/app/dashboard \ - .next/standalone/.next/server/app/dashboard/settings \ - .next/standalone/.next/server/app/dashboard/providers; do - touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep" - done - - cat > "${WRKDIR}/omniroute" <<'EOF' -#!/bin/sh -export PORT="${PORT:-20128}" -export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}" -export LOG_TO_FILE="${LOG_TO_FILE:-false}" -mkdir -p "${DATA_DIR}" -exec node /usr/lib/omniroute/.next/standalone/server.js "$@" -EOF - vbin "${WRKDIR}/omniroute" -} - -post_install() { - vlicense LICENSE -} -``` - -
- -### Environment Variables - -| Variable | Default | Description | -| ------------------------- | ------------------------------------ | ------------------------------------------------------- | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | -| `INITIAL_PASSWORD` | `123456` | First login password | -| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | -| `PORT` | framework default | Service port (`20128` in examples) | -| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | -| `NODE_ENV` | runtime default | Set `production` for deploy | -| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | -| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | -| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | -| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | -| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | -| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | -| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | -| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | - -For the full environment variable reference, see the [README](../README.md). - ---- - -## ๐Ÿ“Š Available Models - -
-View all available models - -**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` - -**Qoder (`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` - -
- ---- - -## ๐Ÿงฉ 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, IP Access Control, API auth for `/models`, and Provider Blocking | -| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | -| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | -| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats | -| **Advanced** | Global proxy configuration (HTTP/SOCKS5) | - ---- - -### Costs & Budget Management - -Access via **Dashboard โ†’ Costs**. - -| 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. - ---- - -## ๐Ÿ–ฅ๏ธ Desktop Application (Electron) - -OmniRoute is available as a native desktop application for Windows, macOS, and Linux. - -### Installation - -```bash -# From the electron directory: -cd electron -npm install - -# Development mode (connect to running Next.js dev server): -npm run dev - -# Production mode (uses standalone build): -npm start -``` - -### Building Installers - -```bash -cd electron -npm run build # Current platform -npm run build:win # Windows (.exe NSIS) -npm run build:mac # macOS (.dmg universal) -npm run build:linux # Linux (.AppImage) -``` - -Output โ†’ `electron/dist-electron/` - -### Key Features - -| Feature | Description | -| --------------------------- | ---------------------------------------------------- | -| **Server Readiness** | Polls server before showing window (no blank screen) | -| **System Tray** | Minimize to tray, change port, quit from tray menu | -| **Port Management** | Change server port from tray (auto-restarts server) | -| **Content Security Policy** | Restrictive CSP via session headers | -| **Single Instance** | Only one app instance can run at a time | -| **Offline Mode** | Bundled Next.js server works without internet | - -### Environment Variables - -| Variable | Default | Description | -| --------------------- | ------- | -------------------------------- | -| `OMNIROUTE_PORT` | `20128` | Server port | -| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64โ€“16384 MB) | - -๐Ÿ“– Full documentation: [`electron/README.md`](../electron/README.md) diff --git a/docs/i18n/pt-BR/docs/A2A-SERVER.md b/docs/i18n/pt-BR/docs/A2A-SERVER.md new file mode 100644 index 0000000000..0aedd3f892 --- /dev/null +++ b/docs/i18n/pt-BR/docs/A2A-SERVER.md @@ -0,0 +1,200 @@ +# OmniRoute A2A Server Documentation (Portuguรชs (Brasil)) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/A2A-SERVER.md) + +--- + +> Agent-to-Agent Protocol v0.3 โ€” OmniRoute as an intelligent routing agent + +## Agent Discovery + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements. + +--- + +## Authentication + +All `/a2a` requests require an API key via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server, authentication is bypassed. + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Sends a message to a skill and waits for the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a hello world in Python"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "uuid", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "..." }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}} + +: heartbeat 2026-03-03T17:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Available Skills + +| Skill | Description | +| :----------------- | :------------------------------------------------------------------------------------------------------------------------------ | +| `smart-routing` | Routes prompts through OmniRoute's intelligent pipeline. Returns response with routing explanation, cost, and resilience trace. | +| `quota-management` | Answers natural-language queries about provider quotas, suggests free combos, and provides quota rankings. | + +--- + +## Task Lifecycle + +``` +submitted โ†’ working โ†’ completed + โ†’ failed + โ†’ cancelled +``` + +- Tasks expire after 5 minutes (configurable) +- Terminal states: `completed`, `failed`, `cancelled` +- Event log tracks every state transition + +--- + +## Error Codes + +| Code | Meaning | +| :----- | :----------------------------- | +| -32700 | Parse error (invalid JSON) | +| -32600 | Invalid request / Unauthorized | +| -32601 | Method or skill not found | +| -32602 | Invalid params | +| -32603 | Internal error | + +--- + +## Integration Examples + +### Python (requests) + +```python +import requests + +resp = requests.post("http://localhost:20128/a2a", json={ + "jsonrpc": "2.0", "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Hello"}] + } +}, headers={"Authorization": "Bearer YOUR_KEY"}) + +result = resp.json()["result"] +print(result["artifacts"][0]["content"]) +print(result["metadata"]["routing_explanation"]) +``` + +### TypeScript (fetch) + +```typescript +const resp = await fetch("http://localhost:20128/a2a", { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: "Bearer YOUR_KEY", + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "1", + method: "message/send", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Hello" }], + }, + }), +}); +const { result } = await resp.json(); +console.log(result.metadata.routing_explanation); +``` diff --git a/docs/i18n/pt-BR/docs/API_REFERENCE.md b/docs/i18n/pt-BR/docs/API_REFERENCE.md new file mode 100644 index 0000000000..a7a0d0c0a5 --- /dev/null +++ b/docs/i18n/pt-BR/docs/API_REFERENCE.md @@ -0,0 +1,465 @@ +# API Reference (Portuguรชs (Brasil)) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/API_REFERENCE.md) + +--- + +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 | +| `X-Session-Id` | Request | Sticky session key for external session affinity | +| `x_session_id` | Request | Underscore variant also accepted (direct HTTP) | +| `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 | +| `X-OmniRoute-Session-Id` | Response | Effective session ID used by OmniRoute | + +> Nginx note: if you rely on underscore headers (for example `x_session_id`), enable `underscores_in_headers 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/stats + +# Clear all caches +DELETE /api/cache/stats +``` + +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/PATCH | 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 + provider summary (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`) | +| `/api/cache/stats` | 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 | + +### Tunnels + +| Endpoint | Method | Description | +| -------------------------- | ------ | ----------------------------------------------------------------------- | +| `/api/tunnels/cloudflared` | GET | Read Cloudflare Quick Tunnel install/runtime status for the dashboard | +| `/api/tunnels/cloudflared` | POST | Enable or disable the Cloudflare Quick Tunnel (`action=enable/disable`) | + +### 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`. + +### ACP Agents + +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | + +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). + +### Resilience & Rate Limits + +| Endpoint | Method | Description | +| ----------------------- | --------- | ------------------------------- | +| `/api/resilience` | GET/PATCH | 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` diff --git a/docs/i18n/pt-BR/docs/ARCHITECTURE.md b/docs/i18n/pt-BR/docs/ARCHITECTURE.md new file mode 100644 index 0000000000..4c1c6d73db --- /dev/null +++ b/docs/i18n/pt-BR/docs/ARCHITECTURE.md @@ -0,0 +1,814 @@ +# OmniRoute Architecture (Portuguรชs (Brasil)) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/ARCHITECTURE.md) + +--- + +_Last updated: 2026-03-28_ + +## 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 (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developerโ†’system, systemโ†’user) for cross-provider compatibility +- Structured output conversion (json_schema โ†’ Gemini responseSchema) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) +- Global system prompt injection +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout โ†’ budget โ†’ fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) + +Primary runtime model: + +- Next.js 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.) + +## Dashboard Surface (Current) + +Main pages under `src/app/(dashboard)/dashboard/`: + +- `/dashboard` โ€” quick start + provider overview +- `/dashboard/endpoint` โ€” endpoint proxy + MCP + A2A + API endpoint tabs +- `/dashboard/providers` โ€” provider connections and credentials +- `/dashboard/combos` โ€” combo strategies, templates, model routing rules +- `/dashboard/costs` โ€” cost aggregation and pricing visibility +- `/dashboard/analytics` โ€” usage analytics and evaluations +- `/dashboard/limits` โ€” quota/rate controls +- `/dashboard/cli-tools` โ€” CLI onboarding, runtime detection, config generation +- `/dashboard/agents` โ€” detected ACP agents + custom agent registration +- `/dashboard/media` โ€” image/video/music playground +- `/dashboard/search-tools` โ€” search provider testing and history +- `/dashboard/health` โ€” uptime, circuit breakers, rate limits +- `/dashboard/logs` โ€” request/proxy/audit/console logs +- `/dashboard/settings` โ€” system settings tabs (general, routing, combo defaults, etc.) +- `/dashboard/api-manager` โ€” API key lifecycle and model permissions + +## 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[(storage.sqlite)] + UDB[(usage tables + log artifacts)] + end + + subgraph Upstreams[Upstream Providers] + P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/Qoder/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/route.ts` (GET) +- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- OAuth: `src/app/api/oauth/*` +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` +- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI tooling helpers: `src/app/api/cli-tools/*` +- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) +- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) โ€” provider profiles, circuit breaker, rate limit state +- Resilience reset: `src/app/api/resilience/reset` (POST) โ€” reset breakers + cooldowns +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) +- Telemetry: `src/app/api/telemetry/summary` (GET) +- Budget: `src/app/api/usage/budget` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Policies: `src/app/api/policies` (GET/POST) + +## 2) SSE + 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` +- Response sanitization: `open-sse/handlers/responseSanitizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.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`, `qoder.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 (SQLite): + +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** + +Usage persistence: + +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present + +Domain State DB (SQLite): + +- `src/lib/db/domainState.ts` โ€” CRUD operations 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`, `src/shared/services/modelSyncScheduler.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Periodic task: `src/shared/services/modelSyncScheduler.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. Combo routing adds one extra guard: provider-scoped 400s such as upstream content-block and role-validation failures are treated as model-local failures so later combo targets can still run. + +## 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: + +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` + +## Deployment Topology + +```mermaid +flowchart LR + 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[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] + end + + subgraph External[External Services] + Providers[AI Providers] + SyncCloud[Cloud Sync Service] + end + + CLI --> Next + Browser --> Next + Next --> Core + Next --> MainDB + Core --> MainDB + Core --> UsageDB + Core --> Providers + Next --> SyncCloud +``` + +## Module Mapping (Decision-Critical) + +### Route and API Modules + +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle +- `src/app/api/models/alias`: alias management +- `src/app/api/combos*`: fallback combo management +- `src/app/api/pricing`: pricing overrides for cost calculation +- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers +- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) +- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) +- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) +- `src/app/api/sessions`: active session listing (GET) +- `src/app/api/rate-limits`: per-account rate limit status (GET) + +### Routing and Execution Core + +- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior + +### Translation Registry and Format Converters + +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` +- Format constants: `open-sse/translator/formats.ts` + +### Persistence + +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables + +## Provider Executor Coverage (Strategy Pattern) + +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. + +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, Qoder, 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 | +| Qoder | openai | OAuth (Basic) | โœ… | โœ… | โœ… | โš ๏ธ Per request | +| OpenRouter | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| GLM/Kimi/MiniMax | claude | API Key | โœ… | โœ… | โŒ | โŒ | +| DeepSeek | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Groq | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| xAI (Grok) | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Mistral | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Perplexity | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Together AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Fireworks AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Cerebras | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Cohere | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| NVIDIA NIM | openai | API Key | โœ… | โœ… | โŒ | โŒ | + +## Format Translation Coverage + +Detected source formats include: + +- `openai` +- `openai-responses` +- `claude` +- `gemini` + +Target formats include: + +- OpenAI chat/Responses +- Claude +- Gemini/Gemini-CLI/Antigravity envelope +- Kiro +- Cursor + +Translations use **OpenAI as the hub format** โ€” all conversions go through OpenAI as intermediate: + +``` +Source Format โ†’ OpenAI (hub) โ†’ Target Format +``` + +Translations are selected dynamically based on source payload shape and provider target format. + +Additional processing layers in the translation pipeline: + +- **Response sanitization** โ€” Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI targets; merges `system` โ†’ `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** โ€” Parses `...` blocks from content into `reasoning_content` field +- **Structured output** โ€” Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` + +## Supported API Endpoints + +| 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` | Provider Models | Provider model metadata backing custom and managed available models | + +## 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 `/logs//` 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 + +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON โ†’ SQLite migration compatibility path + +## Observability and Operational Signals + +Runtime visibility sources: + +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- four-stage detailed payload captures in SQLite (`request_detail_logs`) when `settings.detailed_logs_enabled=true` +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption + +Detailed request payload capture stores up to four JSON payload stages per routed call: + +- raw request received from the client +- translated request actually sent upstream +- provider response reconstructed as JSON; streamed responses are compacted to the final summary plus stream metadata +- final client response returned by OmniRoute; streamed responses are stored in the same compact summary form + +## Security-Sensitive Boundaries + +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics + +## Environment and Runtime Matrix + +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` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). + +## Operational Verification Checklist + +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: +- `GET /api/settings` +- `GET /api/v1/models` +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/pt-BR/docs/AUTO-COMBO.md b/docs/i18n/pt-BR/docs/AUTO-COMBO.md new file mode 100644 index 0000000000..b918f64e08 --- /dev/null +++ b/docs/i18n/pt-BR/docs/AUTO-COMBO.md @@ -0,0 +1,67 @@ +# OmniRoute Auto-Combo Engine (Portuguรชs (Brasil)) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/AUTO-COMBO.md) + +--- + +> Self-managing model chains with adaptive scoring + +## How It Works + +The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**: + +| Factor | Weight | Description | +| :--------- | :----- | :---------------------------------------------- | +| Quota | 0.20 | Remaining capacity [0..1] | +| Health | 0.25 | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 | +| CostInv | 0.20 | Inverse cost (cheaper = higher score) | +| LatencyInv | 0.15 | Inverse p95 latency (faster = higher) | +| TaskFit | 0.10 | Model ร— task type fitness score | +| Stability | 0.10 | Low variance in latency/errors | + +## Mode Packs + +| Pack | Focus | Key Weight | +| :---------------------- | :----------- | :--------------- | +| ๐Ÿš€ **Ship Fast** | Speed | latencyInv: 0.35 | +| ๐Ÿ’ฐ **Cost Saver** | Economy | costInv: 0.40 | +| ๐ŸŽฏ **Quality First** | Best model | taskFit: 0.40 | +| ๐Ÿ“ก **Offline Friendly** | Availability | quota: 0.40 | + +## Self-Healing + +- **Temporary exclusion**: Score < 0.2 โ†’ excluded for 5 min (progressive backoff, max 30 min) +- **Circuit breaker awareness**: OPEN โ†’ auto-excluded; HALF_OPEN โ†’ probe requests +- **Incident mode**: >50% OPEN โ†’ disable exploration, maximize stability +- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout + +## Bandit Exploration + +5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode. + +## API + +```bash +# Create auto-combo +curl -X POST http://localhost:20128/api/combos/auto \ + -H "Content-Type: application/json" \ + -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}' + +# List auto-combos +curl http://localhost:20128/api/combos/auto +``` + +## Task Fitness + +30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` โ†’ high coding score). + +## Files + +| File | Purpose | +| :------------------------------------------- | :------------------------------------ | +| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization | +| `open-sse/services/autoCombo/taskFitness.ts` | Model ร— task fitness lookup | +| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap | +| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode | +| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles | +| `src/app/api/combos/auto/route.ts` | REST API | diff --git a/docs/i18n/pt-BR/docs/CLI-TOOLS.md b/docs/i18n/pt-BR/docs/CLI-TOOLS.md new file mode 100644 index 0000000000..48a4f0a6a5 --- /dev/null +++ b/docs/i18n/pt-BR/docs/CLI-TOOLS.md @@ -0,0 +1,348 @@ +# CLI Tools Setup Guide โ€” OmniRoute (Portuguรชs (Brasil)) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CLI-TOOLS.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CLI-TOOLS.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CLI-TOOLS.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CLI-TOOLS.md) + +--- + +This guide explains how to install and configure all supported AI coding CLI tools +to use **OmniRoute** as the unified backend, giving you centralized key management, +cost tracking, model switching, and request logging across every tool. + +--- + +## How It Works + +``` +Claude / Codex / OpenCode / Cline / KiloCode / Continue / Kiro / Cursor / Copilot + โ”‚ + โ–ผ (all point to OmniRoute) + http://YOUR_SERVER:20128/v1 + โ”‚ + โ–ผ (OmniRoute routes to the right provider) + Anthropic / OpenAI / Gemini / DeepSeek / Groq / Mistral / ... +``` + +**Benefits:** + +- One API key to manage all tools +- Cost tracking across all CLIs in the dashboard +- Model switching without reconfiguring every tool +- Works locally and on remote servers (VPS) + +--- + +## Supported Tools (Dashboard Source of Truth) + +The dashboard cards in `/dashboard/cli-tools` are generated from `src/shared/constants/cliTools.ts`. +Current list (v3.0.0-rc.16): + +| Tool | ID | Command | Setup Mode | Install Method | +| ------------------ | ------------- | ---------- | ---------- | -------------- | +| **Claude Code** | `claude` | `claude` | env | npm | +| **OpenAI Codex** | `codex` | `codex` | custom | npm | +| **Factory Droid** | `droid` | `droid` | custom | bundled/CLI | +| **OpenClaw** | `openclaw` | `openclaw` | custom | bundled/CLI | +| **Cursor** | `cursor` | app | guide | desktop app | +| **Cline** | `cline` | `cline` | custom | npm | +| **Kilo Code** | `kilo` | `kilocode` | custom | npm | +| **Continue** | `continue` | extension | guide | VS Code | +| **Antigravity** | `antigravity` | internal | mitm | OmniRoute | +| **GitHub Copilot** | `copilot` | extension | custom | VS Code | +| **OpenCode** | `opencode` | `opencode` | guide | npm | +| **Kiro AI** | `kiro` | app/cli | mitm | desktop/CLI | + +### CLI fingerprint sync (Agents + Settings) + +`/dashboard/agents` and `Settings > CLI Fingerprint` use `src/shared/constants/cliCompatProviders.ts`. +This keeps provider IDs aligned with CLI cards and legacy IDs. + +| CLI ID | Fingerprint Provider ID | +| ---------------------------------------------------------------------------------------------------- | ----------------------- | +| `kilo` | `kilocode` | +| `copilot` | `github` | +| `claude` / `codex` / `antigravity` / `kiro` / `cursor` / `cline` / `opencode` / `droid` / `openclaw` | same ID | + +Legacy IDs still accepted for compatibility: `copilot`, `kimi-coding`, `qwen`. + +--- + +## Step 1 โ€” Get an OmniRoute API Key + +1. Open the OmniRoute dashboard โ†’ **API Manager** (`/dashboard/api-manager`) +2. Click **Create API Key** +3. Give it a name (e.g. `cli-tools`) and select all permissions +4. Copy the key โ€” you'll need it for every CLI below + +> Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` + +--- + +## Step 2 โ€” Install CLI Tools + +All npm-based tools require Node.js 18+: + +```bash +# Claude Code (Anthropic) +npm install -g @anthropic-ai/claude-code + +# OpenAI Codex +npm install -g @openai/codex + +# OpenCode +npm install -g opencode-ai + +# Cline +npm install -g cline + +# KiloCode +npm install -g kilocode + +# Kiro CLI (Amazon โ€” requires curl + unzip) +apt-get install -y unzip # on Debian/Ubuntu +curl -fsSL https://cli.kiro.dev/install | bash +export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc +``` + +**Verify:** + +```bash +claude --version # 2.x.x +codex --version # 0.x.x +opencode --version # x.x.x +cline --version # 2.x.x +kilocode --version # x.x.x (or: kilo --version) +kiro-cli --version # 1.x.x +``` + +--- + +## Step 3 โ€” Set Global Environment Variables + +Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`: + +```bash +# OmniRoute Universal Endpoint +export OPENAI_BASE_URL="http://localhost:20128/v1" +export OPENAI_API_KEY="sk-your-omniroute-key" +export ANTHROPIC_BASE_URL="http://localhost:20128/v1" +export ANTHROPIC_API_KEY="sk-your-omniroute-key" +export GEMINI_BASE_URL="http://localhost:20128/v1" +export GEMINI_API_KEY="sk-your-omniroute-key" +``` + +> For a **remote server** replace `localhost:20128` with the server IP or domain, +> e.g. `http://192.168.0.15:20128`. + +--- + +## Step 4 โ€” Configure Each Tool + +### Claude Code + +```bash +# Via CLI: +claude config set --global api-base-url http://localhost:20128/v1 + +# Or create ~/.claude/settings.json: +mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF +{ + "apiBaseUrl": "http://localhost:20128/v1", + "apiKey": "sk-your-omniroute-key" +} +EOF +``` + +**Test:** `claude "say hello"` + +--- + +### OpenAI Codex + +```bash +mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF +model: auto +apiKey: sk-your-omniroute-key +apiBaseUrl: http://localhost:20128/v1 +EOF +``` + +**Test:** `codex "what is 2+2?"` + +--- + +### OpenCode + +```bash +mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF +[provider.openai] +base_url = "http://localhost:20128/v1" +api_key = "sk-your-omniroute-key" +EOF +``` + +**Test:** `opencode` + +--- + +### Cline (CLI or VS Code) + +**CLI mode:** + +```bash +mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF +{ + "apiProvider": "openai", + "openAiBaseUrl": "http://localhost:20128/v1", + "openAiApiKey": "sk-your-omniroute-key" +} +EOF +``` + +**VS Code mode:** +Cline extension settings โ†’ API Provider: `OpenAI Compatible` โ†’ Base URL: `http://localhost:20128/v1` + +Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ Cline โ†’ Apply Config**. + +--- + +### KiloCode (CLI or VS Code) + +**CLI mode:** + +```bash +kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key +``` + +**VS Code settings:** + +```json +{ + "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", + "kilo-code.apiKey": "sk-your-omniroute-key" +} +``` + +Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ KiloCode โ†’ Apply Config**. + +--- + +### Continue (VS Code Extension) + +Edit `~/.continue/config.yaml`: + +```yaml +models: + - name: OmniRoute + provider: openai + model: auto + apiBase: http://localhost:20128/v1 + apiKey: sk-your-omniroute-key + default: true +``` + +Restart VS Code after editing. + +--- + +### Kiro CLI (Amazon) + +```bash +# Login to your AWS/Kiro account: +kiro-cli login + +# The CLI uses its own auth โ€” OmniRoute is not needed as backend for Kiro CLI itself. +# Use kiro-cli alongside OmniRoute for other tools. +kiro-cli status +``` + +--- + +### Cursor (Desktop App) + +> **Note:** Cursor routes requests through its cloud. For OmniRoute integration, +> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL. + +Via GUI: **Settings โ†’ Models โ†’ OpenAI API Key** + +- Base URL: `https://your-domain.com/v1` +- API Key: your OmniRoute key + +--- + +## Dashboard Auto-Configuration + +The OmniRoute dashboard automates configuration for most tools: + +1. Go to `http://localhost:20128/dashboard/cli-tools` +2. Expand any tool card +3. Select your API key from the dropdown +4. Click **Apply Config** (if tool is detected as installed) +5. Or copy the generated config snippet manually + +--- + +## Built-in Agents: Droid & OpenClaw + +**Droid** and **OpenClaw** are AI agents built directly into OmniRoute โ€” no installation needed. +They run as internal routes and use OmniRoute's model routing automatically. + +- Access: `http://localhost:20128/dashboard/agents` +- Configure: same combos and providers as all other tools +- No API key or CLI install required + +--- + +## Available API Endpoints + +| Endpoint | Description | Use For | +| -------------------------- | ----------------------------- | --------------------------- | +| `/v1/chat/completions` | Standard chat (all providers) | All modern tools | +| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows | +| `/v1/completions` | Legacy text completions | Older tools using `prompt:` | +| `/v1/embeddings` | Text embeddings | RAG, search | +| `/v1/images/generations` | Image generation | DALL-E, Flux, etc. | +| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS | +| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI | + +--- + +## Soluรงรฃo de Problemas + +| Error | Cause | Fix | +| ------------------------- | ----------------------- | ------------------------------------------ | +| `Connection refused` | OmniRoute not running | `pm2 start omniroute` | +| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` | +| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` | +| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` | +| CLI shows "not installed" | Binary not in PATH | Check `which ` | +| `kiro-cli: not found` | Not in PATH | `export PATH="$HOME/.local/bin:$PATH"` | + +--- + +## Quick Setup Script (One Command) + +```bash +# Install all CLIs and configure for OmniRoute (replace with your key and server URL) +OMNIROUTE_URL="http://localhost:20128/v1" +OMNIROUTE_KEY="sk-your-omniroute-key" + +npm install -g @anthropic-ai/claude-code @openai/codex opencode-ai cline kilocode + +# Kiro CLI +apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash + +# Write configs +mkdir -p ~/.claude ~/.codex ~/.config/opencode ~/.continue + +cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" +cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" +cat >> ~/.bashrc << EOF +export OPENAI_BASE_URL="$OMNIROUTE_URL" +export OPENAI_API_KEY="$OMNIROUTE_KEY" +export ANTHROPIC_BASE_URL="$OMNIROUTE_URL" +export ANTHROPIC_API_KEY="$OMNIROUTE_KEY" +EOF + +source ~/.bashrc +echo "โœ… All CLIs installed and configured for OmniRoute" +``` diff --git a/docs/i18n/pt-BR/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/pt-BR/docs/CODEBASE_DOCUMENTATION.md new file mode 100644 index 0000000000..275c0466c3 --- /dev/null +++ b/docs/i18n/pt-BR/docs/CODEBASE_DOCUMENTATION.md @@ -0,0 +1,591 @@ +# omniroute โ€” Codebase Documentation (Portuguรชs (Brasil)) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CODEBASE_DOCUMENTATION.md) + +--- + +> 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
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, Qoder, 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. + +#### Arquitetura + +```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 | +| Qoder | 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"] +``` diff --git a/docs/i18n/pt-BR/docs/COVERAGE_PLAN.md b/docs/i18n/pt-BR/docs/COVERAGE_PLAN.md new file mode 100644 index 0000000000..c74a8106bd --- /dev/null +++ b/docs/i18n/pt-BR/docs/COVERAGE_PLAN.md @@ -0,0 +1,170 @@ +# Test Coverage Plan (Portuguรชs (Brasil)) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/COVERAGE_PLAN.md) + +--- + +Last updated: 2026-03-28 + +## Baseline + +There are multiple coverage numbers depending on how the report is computed. For planning, only one of them is useful. + +| Metric | Scope | Statements / Lines | Branches | Functions | Notes | +| -------------------- | ----------------------------------------------------- | -----------------: | -------: | --------: | --------------------------------------------------- | +| Legacy | Old `npm run test:coverage` | 79.42% | 75.15% | 67.94% | Inflated: counts test files and excludes `open-sse` | +| Diagnostic | Source-only, excluding tests and excluding `open-sse` | 68.16% | 63.55% | 64.06% | Useful only to isolate `src/**` | +| Recommended baseline | Source-only, excluding tests and including `open-sse` | 56.95% | 66.05% | 57.80% | This is the project-wide baseline to improve | + +The recommended baseline is the number to optimize against. + +## Rules + +- Coverage targets apply to source files, not to `tests/**`. +- `open-sse/**` is part of the product and must remain in scope. +- New code should not reduce coverage in touched areas. +- Prefer testing behavior and branch outcomes over implementation details. +- Prefer temp SQLite databases and small fixtures over broad mocks for `src/lib/db/**`. + +## Current command set + +- `npm run test:coverage` + - Main source coverage gate for the unit test suite + - Generates `text-summary`, `html`, `json-summary`, and `lcov` +- `npm run coverage:report` + - Detailed file-by-file report from the latest run +- `npm run test:coverage:legacy` + - Historical comparison only + +## Milestones + +| Phase | Target | Focus | +| ------- | ---------------------: | ------------------------------------------------- | +| Phase 1 | 60% statements / lines | Quick wins and low-risk utility coverage | +| Phase 2 | 65% statements / lines | DB and route foundations | +| Phase 3 | 70% statements / lines | Provider validation and usage analytics | +| Phase 4 | 75% statements / lines | `open-sse` translators and helpers | +| Phase 5 | 80% statements / lines | `open-sse` handlers and executor branches | +| Phase 6 | 85% statements / lines | Harder edge cases, branch debt, regression suites | +| Phase 7 | 90% statements / lines | Final sweep, gap closure, strict ratchet | + +Branches and functions should ratchet upward with each phase, but the primary hard target is statements / lines. + +## Priority hotspots + +These files or areas offer the best return for the next phases: + +1. `open-sse/handlers` + - `chatCore.ts` at 7.57% + - Overall directory at 29.07% +2. `open-sse/translator/request` + - Overall directory at 36.39% + - Many translators are still near single-digit coverage +3. `open-sse/translator/response` + - Overall directory at 8.07% +4. `open-sse/executors` + - Overall directory at 36.62% +5. `src/lib/db` + - `models.ts` at 20.66% + - `registeredKeys.ts` at 34.46% + - `modelComboMappings.ts` at 36.25% + - `settings.ts` at 46.40% + - `webhooks.ts` at 33.33% +6. `src/lib/usage` + - `usageHistory.ts` at 21.12% + - `usageStats.ts` at 9.56% + - `costCalculator.ts` at 30.00% +7. `src/lib/providers` + - `validation.ts` at 41.16% +8. Low-risk utility and API files for early gains + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/api/errorResponse.ts` + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +## Execution checklist + +### Phase 1: 56.95% -> 60% + +- [x] Fix coverage metric so it reflects source code instead of test files +- [x] Keep a legacy coverage script for comparison +- [x] Record the baseline and hotspots in-repo +- [ ] Add focused tests for low-risk utilities: + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/fetchTimeout.ts` + - `src/lib/api/errorResponse.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/display/names.ts` +- [ ] Add route tests for: + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +### Phase 2: 60% -> 65% + +- [ ] Add DB-backed tests for: + - `src/lib/db/modelComboMappings.ts` + - `src/lib/db/settings.ts` + - `src/lib/db/registeredKeys.ts` +- [ ] Cover branch behavior in: + - `src/lib/providers/validation.ts` + - `src/app/api/v1/embeddings/route.ts` + - `src/app/api/v1/moderations/route.ts` + +### Phase 3: 65% -> 70% + +- [ ] Add usage analytics tests for: + - `src/lib/usage/usageHistory.ts` + - `src/lib/usage/usageStats.ts` + - `src/lib/usage/costCalculator.ts` +- [ ] Expand route coverage for proxy management and settings branches + +### Phase 4: 70% -> 75% + +- [ ] Cover translator helpers and central translation paths: + - `open-sse/translator/index.ts` + - `open-sse/translator/helpers/*` + - `open-sse/translator/request/*` + - `open-sse/translator/response/*` + +### Phase 5: 75% -> 80% + +- [ ] Add handler-level tests for: + - `open-sse/handlers/chatCore.ts` + - `open-sse/handlers/responsesHandler.js` + - `open-sse/handlers/imageGeneration.js` + - `open-sse/handlers/embeddings.js` +- [ ] Add executor branch coverage for provider-specific auth, retries, and endpoint overrides + +### Phase 6: 80% -> 85% + +- [ ] Merge more edge-case suites into the main coverage path +- [ ] Increase function coverage for DB modules with weak constructor/helper coverage +- [ ] Close branch gaps in `settings.ts`, `registeredKeys.ts`, `validation.ts`, and translator helpers + +### Phase 7: 85% -> 90% + +- [ ] Treat the remaining low-coverage files as blockers +- [ ] Add regression tests for every uncovered production bug fixed during the push to 90% +- [ ] Raise the coverage gate in CI only after the local baseline is stable for at least two consecutive runs + +## Ratchet policy + +Update `npm run test:coverage` thresholds only after the project actually exceeds the next milestone with a comfortable buffer. + +Recommended ratchet sequence: + +1. 55/60/55 +2. 60/62/58 +3. 65/64/62 +4. 70/66/66 +5. 75/70/72 +6. 80/75/78 +7. 85/80/84 +8. 90/85/88 + +Order is `statements-lines / branches / functions`. + +## Known gap + +The current coverage command measures the main Node unit suite and includes source reached from it, including `open-sse`. It does not yet merge Vitest coverage into a single unified report. That merge is worth doing later, but it is not a blocker for starting the 60% -> 80% climb. diff --git a/docs/i18n/pt-BR/docs/FEATURES.md b/docs/i18n/pt-BR/docs/FEATURES.md index 378264e56e..767168d69e 100644 --- a/docs/i18n/pt-BR/docs/FEATURES.md +++ b/docs/i18n/pt-BR/docs/FEATURES.md @@ -1,6 +1,6 @@ # OmniRoute โ€” Dashboard Features Gallery (Portuguรชs (Brasil)) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/FEATURES.md) --- @@ -10,7 +10,7 @@ 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). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. ![Providers Dashboard](screenshots/01-providers.png) diff --git a/docs/i18n/pt-BR/docs/MCP-SERVER.md b/docs/i18n/pt-BR/docs/MCP-SERVER.md new file mode 100644 index 0000000000..b67678f371 --- /dev/null +++ b/docs/i18n/pt-BR/docs/MCP-SERVER.md @@ -0,0 +1,87 @@ +# OmniRoute MCP Server Documentation (Portuguรชs (Brasil)) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/MCP-SERVER.md) + +--- + +> Model Context Protocol server with 16 intelligent tools + +## Instalar + +OmniRoute MCP is built-in. Start it with: + +```bash +omniroute --mcp +``` + +Or via the open-sse transport: + +```bash +# HTTP streamable transport (port 20130) +omniroute --dev # MCP auto-starts on /mcp endpoint +``` + +## IDE Configuration + +See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup. + +--- + +## Essential Tools (8) + +| Tool | Description | +| :------------------------------ | :--------------------------------------- | +| `omniroute_get_health` | Gateway health, circuit breakers, uptime | +| `omniroute_list_combos` | All configured combos with models | +| `omniroute_get_combo_metrics` | Performance metrics for a specific combo | +| `omniroute_switch_combo` | Switch active combo by ID/name | +| `omniroute_check_quota` | Quota status per provider or all | +| `omniroute_route_request` | Send a chat completion through OmniRoute | +| `omniroute_cost_report` | Cost analytics for a time period | +| `omniroute_list_models_catalog` | Full model catalog with capabilities | + +## Advanced Tools (8) + +| Tool | Description | +| :--------------------------------- | :---------------------------------------------------------- | +| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | +| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | +| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | +| `omniroute_test_combo` | Live-test all models in a combo via a real upstream request | +| `omniroute_get_provider_metrics` | Detailed metrics for one provider | +| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | +| `omniroute_explain_route` | Explain a past routing decision | +| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | + +## Authentication + +MCP tools are authenticated via API key scopes. Each tool requires specific scopes: + +| Scope | Tools | +| :------------- | :----------------------------------------------- | +| `read:health` | get_health, get_provider_metrics | +| `read:combos` | list_combos, get_combo_metrics | +| `write:combos` | switch_combo | +| `read:quota` | check_quota | +| `write:route` | route_request, simulate_route, test_combo | +| `read:usage` | cost_report, get_session_snapshot, explain_route | +| `write:config` | set_budget_guard, set_resilience_profile | +| `read:models` | list_models_catalog, best_combo_for_task | + +## Audit Logging + +Every tool call is logged to `mcp_tool_audit` with: + +- Tool name, arguments, result +- Duration (ms), success/failure +- API key hash, timestamp + +## Files + +| File | Purpose | +| :------------------------------------------- | :------------------------------------------ | +| `open-sse/mcp-server/server.ts` | MCP server creation + 16 tool registrations | +| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport | +| `open-sse/mcp-server/auth.ts` | API key + scope validation | +| `open-sse/mcp-server/audit.ts` | Tool call audit logging | +| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers | diff --git a/docs/i18n/pt-BR/docs/RELEASE_CHECKLIST.md b/docs/i18n/pt-BR/docs/RELEASE_CHECKLIST.md new file mode 100644 index 0000000000..7cd8816b0f --- /dev/null +++ b/docs/i18n/pt-BR/docs/RELEASE_CHECKLIST.md @@ -0,0 +1,37 @@ +# Release Checklist (Portuguรชs (Brasil)) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/RELEASE_CHECKLIST.md) + +--- + +Use this checklist before tagging or publishing a new OmniRoute release. + +## Version and Changelog + +1. Bump `package.json` version (`x.y.z`) in the release branch. +2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: + - `## [x.y.z] โ€” YYYY-MM-DD` +3. Keep `## [Unreleased]` as the first changelog section for upcoming work. +4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. + +## API Docs + +1. Update `docs/openapi.yaml`: + - `info.version` must equal `package.json` version. +2. Validate endpoint examples if API contracts changed. + +## Runtime Docs + +1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. +2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. +3. Update localized docs if source docs changed significantly. + +## Automated Check + +Run the sync guard locally before opening PR: + +```bash +npm run check:docs-sync +``` + +CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/pt-BR/docs/TROUBLESHOOTING.md b/docs/i18n/pt-BR/docs/TROUBLESHOOTING.md new file mode 100644 index 0000000000..71896a6b9d --- /dev/null +++ b/docs/i18n/pt-BR/docs/TROUBLESHOOTING.md @@ -0,0 +1,256 @@ +# Troubleshooting (Portuguรชs (Brasil)) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/TROUBLESHOOTING.md) + +--- + +Common problems and solutions for OmniRoute. + +--- + +## Quick Fixes + +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | + +--- + +## Provider Issues + +### "Language model did not provide messages" + +**Cause:** Provider quota exhausted. + +**Fix:** + +1. 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, Qoder) 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}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) + +--- + +## Circuit Breaker Issues + +### Provider stuck in OPEN state + +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. + +**Fix:** + +1. 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 +- **SDK returns raw string instead of object** โ€” Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** โ€” Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** โ€” Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** โ€” Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` + +--- + +## Resilience Settings + +### Auto rate-limit not triggering + +- 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. + +--- + +## Optional RAG / LLM failure taxonomy (16 problems) + +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` โ€ฆ `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard โ†’ Health** for real-time system status +- **Translator**: Use **Dashboard โ†’ Translator** to debug format issues diff --git a/docs/i18n/pt-BR/docs/USER_GUIDE.md b/docs/i18n/pt-BR/docs/USER_GUIDE.md new file mode 100644 index 0000000000..a938798116 --- /dev/null +++ b/docs/i18n/pt-BR/docs/USER_GUIDE.md @@ -0,0 +1,944 @@ +# User Guide (Portuguรชs (Brasil)) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/USER_GUIDE.md) + +--- + +Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute. + +--- + +## Table of Contents + +- [Pricing at a Glance](#-pricing-at-a-glance) +- [Use Cases](#-use-cases) +- [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** | Qoder | $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) + Qoder (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 + +#### Qoder (8 FREE models) + +```bash +Dashboard โ†’ Connect Qoder โ†’ 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 +``` + +--- + +## Deploy + +### Global npm install (Recommended) + +```bash +npm install -g omniroute + +# Create config directory +mkdir -p ~/.omniroute + +# Create .env file (see .env.example) +cp .env.example ~/.omniroute/.env + +# Start server +omniroute +# Or with custom port: +omniroute --port 3000 +``` + +The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`. + +### VPS Deployment + +```bash +git clone https://github.com/diegosouzapw/OmniRoute.git +cd OmniRoute && npm install && npm run build + +export JWT_SECRET="your-secure-secret-change-this" +export INITIAL_PASSWORD="your-password" +export DATA_DIR="/var/lib/omniroute" +export PORT="20128" +export HOSTNAME="0.0.0.0" +export NODE_ENV="production" +export NEXT_PUBLIC_BASE_URL="http://localhost:20128" +export API_KEY_SECRET="endpoint-proxy-api-key-secret" + +npm run start +# Or: pm2 start npm --name omniroute -- start +``` + +### PM2 Deployment (Low Memory) + +For servers with limited RAM, use the memory limit option: + +```bash +# With 512MB limit (default) +pm2 start npm --name omniroute -- start + +# Or with custom memory limit +OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start + +# Or using ecosystem.config.js +pm2 start ecosystem.config.js +``` + +Create `ecosystem.config.js`: + +```javascript +module.exports = { + apps: [ + { + name: "omniroute", + script: "npm", + args: "start", + env: { + NODE_ENV: "production", + OMNIROUTE_MEMORY_MB: "512", + JWT_SECRET: "your-secret", + INITIAL_PASSWORD: "your-password", + }, + node_args: "--max-old-space-size=512", + max_memory_restart: "300M", + }, + ], +}; +``` + +### Docker + +```bash +# Build image (default = runner-cli with codex/claude/droid preinstalled) +docker build -t omniroute:cli . + +# Portable mode (recommended) +docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli +``` + +For host-integrated mode with CLI binaries, see the Docker section in the main docs. + +### Void Linux (xbps-src) + +Void Linux users can package and install OmniRoute natively using the `xbps-src` cross-compilation framework. This automates the Node.js standalone build along with the required `better-sqlite3` native bindings. + +
+View xbps-src template + +```bash +# Template file for 'omniroute' +pkgname=omniroute +version=3.2.4 +revision=1 +hostmakedepends="nodejs python3 make" +depends="openssl" +short_desc="Universal AI gateway with smart routing for multiple LLM providers" +maintainer="zenobit " +license="MIT" +homepage="https://github.com/diegosouzapw/OmniRoute" +distfiles="https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz" +checksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b +system_accounts="_omniroute" +omniroute_homedir="/var/lib/omniroute" +export NODE_ENV=production +export npm_config_engine_strict=false +export npm_config_loglevel=error +export npm_config_fund=false +export npm_config_audit=false + +do_build() { + # Determine target CPU arch for node-gyp + local _gyp_arch + case "$XBPS_TARGET_MACHINE" in + aarch64*) _gyp_arch=arm64 ;; + armv7*|armv6*) _gyp_arch=arm ;; + i686*) _gyp_arch=ia32 ;; + *) _gyp_arch=x64 ;; + esac + + # 1) Install all deps โ€“ skip scripts + NODE_ENV=development npm ci --ignore-scripts + + # 2) Build the Next.js standalone bundle + npm run build + + # 3) Copy static assets into standalone + cp -r .next/static .next/standalone/.next/static + [ -d public ] && cp -r public .next/standalone/public || true + + # 4) Compile better-sqlite3 native binding + local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js + (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch") + + # 5) Place the compiled binding into the standalone bundle + local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release + mkdir -p "$_bs3_release" + cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/" + + # 6) Remove arch-specific sharp bundles + rm -rf .next/standalone/node_modules/@img + + # 7) Copy pino runtime deps omitted by Next.js static analysis: + for _mod in pino-abstract-transport split2 process-warning; do + cp -r "node_modules/$_mod" .next/standalone/node_modules/ + done +} + +do_check() { + npm run test:unit +} + +do_install() { + vmkdir usr/lib/omniroute/.next + vcopy .next/standalone/. usr/lib/omniroute/.next/standalone + + # Prevent removal of empty Next.js app router dirs by the post-install hook + for _d in \ + .next/standalone/.next/server/app/dashboard \ + .next/standalone/.next/server/app/dashboard/settings \ + .next/standalone/.next/server/app/dashboard/providers; do + touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep" + done + + cat > "${WRKDIR}/omniroute" <<'EOF' +#!/bin/sh +export PORT="${PORT:-20128}" +export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}" +export LOG_TO_FILE="${LOG_TO_FILE:-false}" +mkdir -p "${DATA_DIR}" +exec node /usr/lib/omniroute/.next/standalone/server.js "$@" +EOF + vbin "${WRKDIR}/omniroute" +} + +post_install() { + vlicense LICENSE +} +``` + +
+ +### 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/*` | +| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand | +| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | + +For the full environment variable reference, see the [README](../README.md). + +--- + +## ๐Ÿ“Š Available Models + +
+View all available models + +**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` + +**Qoder (`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` + +
+ +--- + +## ๐Ÿงฉ 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**. + +Notes: + +- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers. +- The **Custom Models** section is intended for providers that do not expose managed available-model imports. + +### 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 + +### Cloudflare Quick Tunnel + +- Available in **Dashboard โ†’ Endpoints** for Docker and other self-hosted deployments +- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint +- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary +- Tunnel URLs are ephemeral and change every time you stop/start the tunnel +- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download + +### 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 | + +#### External Sticky Session Header + +For external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send: + +```http +X-Session-Id: your-session-key +``` + +OmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`. + +If you use Nginx and send underscore-form headers, enable: + +```nginx +underscores_in_headers on; +``` + +#### 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 unless `DISABLE_SQLITE_AUTO_BACKUP=true` | + +```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 6 tabs for easy navigation: + +| Tab | Contents | +| -------------- | ---------------------------------------------------------------------------------------------- | +| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility | +| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | +| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | +| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | +| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats | +| **Advanced** | Global proxy configuration (HTTP/SOCKS5) | + +--- + +### Costs & Budget Management + +Access via **Dashboard โ†’ Costs**. + +| 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. + +--- + +## ๐Ÿ–ฅ๏ธ Desktop Application (Electron) + +OmniRoute is available as a native desktop application for Windows, macOS, and Linux. + +### Instalar + +```bash +# From the electron directory: +cd electron +npm install + +# Development mode (connect to running Next.js dev server): +npm run dev + +# Production mode (uses standalone build): +npm start +``` + +### Building Installers + +```bash +cd electron +npm run build # Current platform +npm run build:win # Windows (.exe NSIS) +npm run build:mac # macOS (.dmg universal) +npm run build:linux # Linux (.AppImage) +``` + +Output โ†’ `electron/dist-electron/` + +### Key Features + +| Feature | Description | +| --------------------------- | ---------------------------------------------------- | +| **Server Readiness** | Polls server before showing window (no blank screen) | +| **System Tray** | Minimize to tray, change port, quit from tray menu | +| **Port Management** | Change server port from tray (auto-restarts server) | +| **Content Security Policy** | Restrictive CSP via session headers | +| **Single Instance** | Only one app instance can run at a time | +| **Offline Mode** | Bundled Next.js server works without internet | + +### Environment Variables + +| Variable | Default | Description | +| --------------------- | ------- | -------------------------------- | +| `OMNIROUTE_PORT` | `20128` | Server port | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64โ€“16384 MB) | + +๐Ÿ“– Full documentation: [`electron/README.md`](../electron/README.md) diff --git a/docs/i18n/pt-BR/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/pt-BR/docs/VM_DEPLOYMENT_GUIDE.md new file mode 100644 index 0000000000..4cc9fb596f --- /dev/null +++ b/docs/i18n/pt-BR/docs/VM_DEPLOYMENT_GUIDE.md @@ -0,0 +1,403 @@ +# OmniRoute โ€” Deployment Guide on VM with Cloudflare (Portuguรชs (Brasil)) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/VM_DEPLOYMENT_GUIDE.md) + +--- + +Complete guide to install and configure OmniRoute on a VM (VPS) with domain managed via Cloudflare. + +--- + +## Prerequisites + +| Item | Minimum | Recommended | +| ---------- | ------------------------ | ---------------- | +| **CPU** | 1 vCPU | 2 vCPU | +| **RAM** | 1 GB | 2 GB | +| **Disk** | 10 GB SSD | 25 GB SSD | +| **OS** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS | +| **Domain** | Registered on Cloudflare | โ€” | +| **Docker** | Docker Engine 24+ | Docker 27+ | + +**Tested providers**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. + +--- + +## 1. Configure the VM + +### 1.1 Create the instance + +On your preferred VPS provider: + +- Choose Ubuntu 24.04 LTS +- Select the minimum plan (1 vCPU / 1 GB RAM) +- Set a strong root password or configure SSH key +- Note the **public IP** (e.g., `203.0.113.10`) + +### 1.2 Connect via SSH + +```bash +ssh root@203.0.113.10 +``` + +### 1.3 Update the system + +```bash +apt update && apt upgrade -y +``` + +### 1.4 Install Docker + +```bash +# Install dependencies +apt install -y ca-certificates curl gnupg + +# Add official Docker repository +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 Install nginx + +```bash +apt install -y nginx +``` + +### 1.6 Configure 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 +``` + +> **Tip**: For maximum security, restrict ports 80 and 443 to Cloudflare IPs only. See the [Advanced Security](#advanced-security) section. + +--- + +## 2. Install OmniRoute + +### 2.1 Create configuration directory + +```bash +mkdir -p /opt/omniroute +``` + +### 2.2 Create environment variables file + +```bash +cat > /opt/omniroute/.env << โ€˜EOFโ€™ +# === Security === +JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY +INITIAL_PASSWORD=YourSecurePassword123! +API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY +STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY +STORAGE_ENCRYPTION_KEY_VERSION=v1 +MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT + +# === 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 (change to your domain) === +BASE_URL=https://llms.seudominio.com +NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com + +# === Cloud Sync (optional) === +# CLOUD_URL=https://cloud.omniroute.online +# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online +EOF +``` + +> โš ๏ธ **IMPORTANT**: Generate unique secret keys! Use `openssl rand -hex 32` for each key. + +### 2.3 Start the 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 Verify that it is running + +```bash +docker ps | grep omniroute +docker logs omniroute --tail 20 +``` + +It should display: `[DB] SQLite database ready` and `listening on port 20128`. + +--- + +## 3. Configure nginx (Reverse Proxy) + +### 3.1 Generate SSL certificate (Cloudflare Origin) + +In the Cloudflare dashboard: + +1. Go to **SSL/TLS โ†’ Origin Server** +2. Click **Create Certificate** +3. Keep the defaults (15 years, \*.yourdomain.com) +4. Copy the **Origin Certificate** and the **Private Key** + +```bash +mkdir -p /etc/nginx/ssl + +# Paste the certificate +nano /etc/nginx/ssl/origin.crt + +# Paste the private key +nano /etc/nginx/ssl/origin.key + +chmod 600 /etc/nginx/ssl/origin.key +``` + +### 3.2 Nginx Configuration + +```bash +cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ +# Default server โ€” blocks direct access via 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.yourdomain.com; # Change to your domain + + 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.yourdomain.com; + return 301 https://$server_name$request_uri; +} +NGINX +``` + +### 3.3 Enable and Test + +```bash +# Remove default configuration +rm -f /etc/nginx/sites-enabled/default + +# Enable OmniRoute +ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute + +# Test and reload +nginx -t && systemctl reload nginx +``` + +--- + +## 4. Configure Cloudflare DNS + +### 4.1 Add DNS record + +In the Cloudflare dashboard โ†’ DNS: + +| Type | Name | Content | Proxy | +| ---- | ------ | ---------------------- | ---------- | +| A | `llms` | `203.0.113.10` (VM IP) | โœ… Proxied | + +### 4.2 Configure SSL + +Under **SSL/TLS โ†’ Overview**: + +- Mode: **Full (Strict)** + +Under **SSL/TLS โ†’ Edge Certificates**: + +- Always Use HTTPS: โœ… On +- Minimum TLS Version: TLS 1.2 +- Automatic HTTPS Rewrites: โœ… On + +### 4.3 Testing + +```bash +curl -sI https://llms.seudominio.com/health +# Should return HTTP/2 200 +``` + +--- + +## 5. Operations and Maintenance + +### Upgrade to a new version + +```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 +``` + +### View logs + +```bash +docker logs -f omniroute # Real-time stream +docker logs omniroute --tail 50 # Last 50 lines +``` + +### Manual database backup + +```bash +# Copy data from the volume to the host +docker cp omniroute:/app/data ./backup-$(date +%F) + +# Or compress the entire volume +docker run --rm -v omniroute-data:/data -v $(pwd):/backup \ + alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data +``` + +### Restore from 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. Advanced Security + +### Restrict nginx to Cloudflare IPs + +```bash +cat > /etc/nginx/cloudflare-ips.conf << โ€˜CFโ€™ +# Cloudflare IPv4 ranges โ€” update periodically +# 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 +``` + +Add the following to `nginx.conf` inside the `http {}` block: + +```nginx +include /etc/nginx/cloudflare-ips.conf; +``` + +### Install fail2ban + +```bash +apt install -y fail2ban +systemctl enable fail2ban +systemctl start fail2ban + +# Check status +fail2ban-client status sshd +``` + +### Block direct access to the Docker port + +```bash +# Prevent direct external access to port 20128 +iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP +iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT + +# Persist the rules +apt install -y iptables-persistent +netfilter-persistent save +``` + +--- + +## 7. Deploy to Cloudflare Workers (Optional) + +For remote access via Cloudflare Workers (without exposing the VM directly): + +```bash +# In the local repository +cd omnirouteCloud +npm install +npx wrangler login +npx wrangler deploy +``` + +See the full documentation at [omnirouteCloud/README.md](../omnirouteCloud/README.md). + +--- + +## Port Summary + +| Port | Service | Access | +| ----- | ----------- | -------------------------- | +| 22 | SSH | Public (with fail2ban) | +| 80 | nginx HTTP | Redirect โ†’ HTTPS | +| 443 | nginx HTTPS | Via Cloudflare Proxy | +| 20128 | OmniRoute | Localhost only (via nginx) | diff --git a/docs/i18n/pt-BR/src/lib/a2a/README.md b/docs/i18n/pt-BR/src/lib/a2a/README.md new file mode 100644 index 0000000000..c2aba3481c --- /dev/null +++ b/docs/i18n/pt-BR/src/lib/a2a/README.md @@ -0,0 +1,752 @@ +# OmniRoute A2A Server (Portuguรชs (Brasil)) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../../../src/lib/a2a/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../../../es/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../../../fr/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../../../de/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../../../it/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../../../ru/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../../../zh-CN/src/lib/a2a/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../../../ja/src/lib/a2a/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../../../ko/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../../../ar/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../../../in/src/lib/a2a/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../../../th/src/lib/a2a/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../../../vi/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../../../id/src/lib/a2a/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../../../ms/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../../../nl/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../../../pl/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../../../sv/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../../../no/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../../../da/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../../../fi/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../../../pt/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../../../ro/src/lib/a2a/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../../../hu/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../../../bg/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../../../sk/src/lib/a2a/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../../../uk-UA/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../../../he/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../../../phi/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../../../pt-BR/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../../../cs/src/lib/a2a/README.md) + +--- + +> **Agent-to-Agent Protocol v0.3** โ€” Enables any AI agent to use OmniRoute as an intelligent routing agent via JSON-RPC 2.0. + +The A2A Server exposes OmniRoute as a **first-class agent** that other agents can discover, delegate tasks to, and collaborate with using the [A2A Protocol](https://google.github.io/A2A/). + +--- + +## Arquitetura + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Orchestrator Agent โ”‚ +โ”‚ (LangChain, CrewAI, AutoGen, Custom Agent) โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ 1. GET /.well-known/agent.json (discover) + โ”‚ 2. POST /a2a (JSON-RPC 2.0) + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ OmniRoute A2A Server โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Task Manager โ”‚ โ”‚ Skill Engine โ”‚ โ”‚ SSE Streaming โ”‚ โ”‚ +โ”‚ โ”‚ (lifecycle) โ”‚โ”€โ”€โ”‚ (registry) โ”‚โ”€โ”€โ”‚ (real-time) โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ +โ”‚ Skills: โ”‚ โ”‚ +โ”‚ โ”œโ”€ smart-routing โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ””โ”€ quota-management โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ Routing Decision Logger โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ OmniRoute Gateway (internal) + /v1/chat/completions, /api/combos, /api/usage/quota +``` + +--- + +## Inรญcio Rรกpido + +### Agent Discovery + +Every A2A-compatible agent exposes an **Agent Card** at `/.well-known/agent.json`: + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +**Response:** + +```json +{ + "name": "OmniRoute", + "description": "Intelligent AI gateway with auto-routing across 50+ providers", + "url": "http://localhost:20128/a2a", + "version": "1.8.1", + "capabilities": { + "streaming": true, + "pushNotifications": false + }, + "skills": [ + { + "id": "smart-routing", + "name": "Smart Routing", + "description": "Routes prompts through OmniRoute intelligent pipeline", + "tags": ["routing", "llm", "multi-provider", "cost-optimization"], + "examples": [ + "Write a hello world in Python", + "Explain quantum computing using the cheapest provider" + ] + }, + { + "id": "quota-management", + "name": "Quota Management", + "description": "Natural-language queries about provider quotas", + "tags": ["quota", "analytics", "cost"], + "examples": [ + "Which provider has the most quota remaining?", + "Suggest a free combo for coding" + ] + } + ], + "authentication": { + "schemes": ["bearer"], + "apiKeyHeader": "Authorization" + } +} +``` + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Send a message to a skill and receive the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python hello world"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "a1b2c3d4-...", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "print('Hello, World!')" }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.0030)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "2026-03-04T..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"Quantum computing..."}}} + +: heartbeat 2026-03-04T21:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Running Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Skills Reference + +### `smart-routing` + +Routes prompts through OmniRoute's intelligent pipeline with full observability. + +**Parameters (in `metadata`):** + +| Parameter | Type | Default | Description | +| --------- | -------- | ------------ | ---------------------------------------------------------------------------------------- | +| `model` | `string` | `"auto"` | Target model (e.g., `claude-sonnet-4`, `gpt-4o`, `auto`) | +| `combo` | `string` | active combo | Specific combo to route through | +| `budget` | `number` | none | Maximum cost in USD for this request | +| `role` | `string` | none | Task role hint: `coding`, `review`, `planning`, `analysis`, `debugging`, `documentation` | + +**Returns:** + +| Field | Description | +| ------------------------------ | --------------------------------------------------------- | +| `artifacts[].content` | The LLM response text | +| `metadata.routing_explanation` | Human-readable explanation of routing decision | +| `metadata.cost_envelope` | Estimated vs actual cost with currency | +| `metadata.resilience_trace` | Array of events (primary_selected, fallback_needed, etc.) | +| `metadata.policy_verdict` | Whether the request was allowed and why | + +### `quota-management` + +Answers natural-language queries about provider quotas. + +**Query types (inferred from message content):** + +| Query Pattern | Response Type | +| ---------------------------------------------- | -------------------------------------------------------- | +| Contains `"ranking"`, `"most quota"`, `"best"` | Providers ranked by remaining quota | +| Contains `"free"`, `"suggest"` | Lists free combos or suggests free-tier providers | +| Default | Full quota summary with warnings for low-quota providers | + +--- + +## Task Lifecycle + +``` +submitted โ”€โ”€โ†’ working โ”€โ”€โ†’ completed + โ”€โ”€โ†’ failed + โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ†’ cancelled +``` + +| State | Description | +| ----------- | ----------------------------------------------------- | +| `submitted` | Task created, queued for execution | +| `working` | Skill handler is executing | +| `completed` | Execution succeeded, artifacts available | +| `failed` | Execution failed or task expired (TTL: 5 min default) | +| `cancelled` | Cancelled by client via `tasks/cancel` | + +- Terminal states: `completed`, `failed`, `cancelled` (no further transitions) +- Expired tasks in `submitted` or `working` are auto-marked as `failed` +- Tasks are garbage-collected after 2ร— TTL + +--- + +## Client Examples + +### Python โ€” Orchestrator Agent + +```python +""" +A2A Client โ€” Python example. +Discovers OmniRoute agent, sends a task, and processes the result. +""" +import requests +import json + +BASE_URL = "http://localhost:20128" +API_KEY = "your-api-key" +HEADERS = { + "Content-Type": "application/json", + "Authorization": f"Bearer {API_KEY}", +} + +# 1. Discover agent capabilities +agent_card = requests.get(f"{BASE_URL}/.well-known/agent.json").json() +print(f"Agent: {agent_card['name']} v{agent_card['version']}") +print(f"Skills: {[s['id'] for s in agent_card['skills']]}") + +# 2. Send a smart-routing task +response = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python quicksort implementation"}], + "metadata": { + "model": "auto", + "combo": "fast-coding", + "budget": 0.10, + } + } +}) +result = response.json()["result"] +print(f"\n๐Ÿ“ Response: {result['artifacts'][0]['content'][:200]}...") +print(f"๐Ÿ”€ Routing: {result['metadata']['routing_explanation']}") +print(f"๐Ÿ’ฐ Cost: ${result['metadata']['cost_envelope']['actual']}") +print(f"๐Ÿ›ก๏ธ Policy: {result['metadata']['policy_verdict']['reason']}") + +# 3. Query quota status +quota_resp = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-2", + "method": "message/send", + "params": { + "skill": "quota-management", + "messages": [{"role": "user", "content": "Which provider has the most quota remaining?"}], + } +}) +quota_result = quota_resp.json()["result"] +print(f"\n๐Ÿ“Š Quota: {quota_result['artifacts'][0]['content']}") +``` + +### TypeScript โ€” Multi-Agent Orchestrator + +```typescript +/** + * A2A Client โ€” TypeScript example. + * Shows agent discovery, task delegation, and streaming. + */ + +const BASE_URL = "http://localhost:20128"; +const API_KEY = "your-api-key"; + +interface JsonRpcResponse { + jsonrpc: "2.0"; + id: string | number; + result?: T; + error?: { code: number; message: string }; +} + +async function a2aCall(method: string, params: Record): Promise { + const resp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: `${method}-${Date.now()}`, + method, + params, + }), + }); + const json: JsonRpcResponse = await resp.json(); + if (json.error) throw new Error(`[${json.error.code}] ${json.error.message}`); + return json.result!; +} + +// โ”€โ”€ Agent Discovery โ”€โ”€ +const agentCard = await fetch(`${BASE_URL}/.well-known/agent.json`).then((r) => r.json()); +console.log(`Connected to: ${agentCard.name} (${agentCard.skills.length} skills)`); + +// โ”€โ”€ Smart Routing: Send a coding task โ”€โ”€ +const routingResult = await a2aCall("message/send", { + skill: "smart-routing", + messages: [{ role: "user", content: "Implement a Redis cache wrapper in TypeScript" }], + metadata: { model: "claude-sonnet-4", role: "coding" }, +}); +console.log("Response:", routingResult.artifacts[0].content); +console.log("Provider:", routingResult.metadata.routing_explanation); + +// โ”€โ”€ Quota Management: Find free alternatives โ”€โ”€ +const quotaResult = await a2aCall("message/send", { + skill: "quota-management", + messages: [{ role: "user", content: "Suggest free combos for documentation" }], +}); +console.log("Free combos:", quotaResult.artifacts[0].content); + +// โ”€โ”€ Streaming: Real-time response โ”€โ”€ +const streamResp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "stream-1", + method: "message/stream", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Explain microservices architecture" }], + }, + }), +}); + +const reader = streamResp.body!.getReader(); +const decoder = new TextDecoder(); +while (true) { + const { done, value } = await reader.read(); + if (done) break; + const chunk = decoder.decode(value); + for (const line of chunk.split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + if (event.params.chunk) { + process.stdout.write(event.params.chunk.content); + } + if (event.params.task.state === "completed") { + console.log("\nโœ… Stream completed"); + } + } + } +} +``` + +### Python โ€” LangChain A2A Integration + +```python +""" +LangChain integration โ€” Use OmniRoute A2A as a custom LLM. +""" +from langchain.llms.base import BaseLLM +from langchain.schema import LLMResult, Generation +import requests +from typing import List, Optional + +class OmniRouteA2A(BaseLLM): + base_url: str = "http://localhost:20128" + api_key: str = "" + model: str = "auto" + combo: Optional[str] = None + + @property + def _llm_type(self) -> str: + return "omniroute-a2a" + + def _call(self, prompt: str, stop: Optional[List[str]] = None, **kwargs) -> str: + response = requests.post( + f"{self.base_url}/a2a", + headers={ + "Content-Type": "application/json", + "Authorization": f"Bearer {self.api_key}", + }, + json={ + "jsonrpc": "2.0", + "id": "langchain-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": prompt}], + "metadata": { + "model": self.model, + **({"combo": self.combo} if self.combo else {}), + }, + }, + }, + ) + result = response.json()["result"] + return result["artifacts"][0]["content"] + + def _generate(self, prompts: List[str], stop=None, **kwargs) -> LLMResult: + return LLMResult( + generations=[[Generation(text=self._call(p, stop))] for p in prompts] + ) + +# Usage +llm = OmniRouteA2A( + base_url="http://localhost:20128", + api_key="your-key", + model="auto", + combo="fast-coding", +) +result = llm("Write a Python function to merge two sorted lists") +print(result) +``` + +### Go โ€” A2A Client + +```go +package main + +import ( + "bytes" + "encoding/json" + "fmt" + "io" + "net/http" +) + +const baseURL = "http://localhost:20128" +const apiKey = "your-api-key" + +type JsonRpcRequest struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Method string `json:"method"` + Params interface{} `json:"params"` +} + +type JsonRpcResponse struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Result interface{} `json:"result"` + Error *struct { + Code int `json:"code"` + Message string `json:"message"` + } `json:"error"` +} + +func a2aCall(method string, params interface{}) (*JsonRpcResponse, error) { + body, _ := json.Marshal(JsonRpcRequest{ + Jsonrpc: "2.0", + ID: "go-1", + Method: method, + Params: params, + }) + + req, _ := http.NewRequest("POST", baseURL+"/a2a", bytes.NewReader(body)) + req.Header.Set("Content-Type", "application/json") + req.Header.Set("Authorization", "Bearer "+apiKey) + + resp, err := http.DefaultClient.Do(req) + if err != nil { + return nil, err + } + defer resp.Body.Close() + data, _ := io.ReadAll(resp.Body) + + var result JsonRpcResponse + json.Unmarshal(data, &result) + return &result, nil +} + +func main() { + // Discover agent + resp, _ := http.Get(baseURL + "/.well-known/agent.json") + defer resp.Body.Close() + body, _ := io.ReadAll(resp.Body) + fmt.Println("Agent Card:", string(body)) + + // Send smart-routing task + result, _ := a2aCall("message/send", map[string]interface{}{ + "skill": "smart-routing", + "messages": []map[string]string{{"role": "user", "content": "Hello from Go!"}}, + "metadata": map[string]interface{}{"model": "auto"}, + }) + out, _ := json.MarshalIndent(result.Result, "", " ") + fmt.Println("Result:", string(out)) +} +``` + +--- + +## Use Cases + +### ๐Ÿค– Use Case 1: Multi-Agent Coding Pipeline + +An orchestrator agent delegates code generation to OmniRoute, then passes the output to a review agent. + +```python +def coding_pipeline(task: str): + # Step 1: Generate code via OmniRoute A2A + code_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Write production-quality code: {task}"} + ], metadata={"model": "auto", "role": "coding"}) + code = code_result["artifacts"][0]["content"] + + # Step 2: Review the code via OmniRoute A2A (different model) + review_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Review this code for bugs and improvements:\n\n{code}"} + ], metadata={"model": "auto", "role": "review"}) + review = review_result["artifacts"][0]["content"] + + # Step 3: Check costs + print(f"Code cost: ${code_result['metadata']['cost_envelope']['actual']}") + print(f"Review cost: ${review_result['metadata']['cost_envelope']['actual']}") + + return {"code": code, "review": review} +``` + +### ๐Ÿ’ก Use Case 2: Quota-Aware Agent Swarm + +Multiple agents share quota through OmniRoute, using the quota skill to coordinate. + +```python +async def quota_aware_agent(agent_name: str, task: str): + # Check quota before starting + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Which provider has the most quota remaining?"} + ]) + print(f"[{agent_name}] {quota['artifacts'][0]['content']}") + + # Send request with budget constraint + result = a2a_send("smart-routing", [ + {"role": "user", "content": task} + ], metadata={"budget": 0.05}) + + policy = result["metadata"]["policy_verdict"] + if not policy["allowed"]: + print(f"[{agent_name}] โš ๏ธ Budget exceeded: {policy['reason']}") + # Fall back to free combo + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Suggest free combos"} + ]) + print(f"[{agent_name}] Free alternatives: {quota['artifacts'][0]['content']}") + + return result +``` + +### ๐Ÿ“Š Use Case 3: Real-Time Streaming Dashboard + +A monitoring agent streams responses and displays progress in real-time. + +```typescript +async function streamingDashboard(prompt: string) { + const response = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { "Content-Type": "application/json", Authorization: `Bearer ${API_KEY}` }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "dash-1", + method: "message/stream", + params: { skill: "smart-routing", messages: [{ role: "user", content: prompt }] }, + }), + }); + + let totalChunks = 0; + const reader = response.body!.getReader(); + const decoder = new TextDecoder(); + + while (true) { + const { done, value } = await reader.read(); + if (done) break; + + for (const line of decoder.decode(value).split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + const state = event.params.task.state; + + if (state === "working" && event.params.chunk) { + totalChunks++; + process.stdout.write( + `\r[Chunk ${totalChunks}] ${event.params.chunk.content.slice(0, 50)}...` + ); + } + if (state === "completed") { + const meta = event.params.metadata; + console.log( + `\nโœ… Done | Cost: $${meta?.cost_envelope?.actual || 0} | Route: ${meta?.routing_explanation || "N/A"}` + ); + } + if (state === "failed") { + console.error(`\nโŒ Failed: ${event.params.metadata?.error}`); + } + } + } + } +} +``` + +### ๐Ÿ” Use Case 4: Task Polling Pattern + +For long-running tasks, poll the task status instead of waiting synchronously. + +```python +import time + +def poll_task(task_id: str, timeout: int = 60): + """Poll task status until completion or timeout.""" + start = time.time() + while time.time() - start < timeout: + result = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "poll-1", + "method": "tasks/get", + "params": {"taskId": task_id}, + }).json() + + task = result["result"]["task"] + state = task["state"] + print(f" Task {task_id[:8]}... state={state}") + + if state in ("completed", "failed", "cancelled"): + return task + time.sleep(2) + + # Timeout โ€” cancel the task + requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "cancel-1", + "method": "tasks/cancel", + "params": {"taskId": task_id}, + }) + raise TimeoutError(f"Task {task_id} timed out after {timeout}s") +``` + +--- + +## Error Codes + +| Code | Constant | Meaning | +| ------ | ------------------------ | ---------------------------------------- | +| -32700 | โ€” | Parse error (invalid JSON) | +| -32600 | `INVALID_REQUEST` | Invalid JSON-RPC request or unauthorized | +| -32601 | `METHOD_NOT_FOUND` | Unknown method or skill | +| -32602 | `INVALID_PARAMS` | Missing or invalid parameters | +| -32603 | `INTERNAL_ERROR` | Skill execution failed | +| -32001 | `TASK_NOT_FOUND` | Task ID not found | +| -32002 | `TASK_ALREADY_COMPLETED` | Cannot modify a completed task | +| -32003 | `UNAUTHORIZED` | Invalid or missing API key | +| -32004 | `BUDGET_EXCEEDED` | Request exceeds configured budget | +| -32005 | `PROVIDER_UNAVAILABLE` | No available providers | + +--- + +## Authentication + +All `/a2a` requests require a Bearer token via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server (`OMNIROUTE_API_KEY` is empty), authentication is bypassed. + +--- + +## File Structure + +``` +src/lib/a2a/ +โ”œโ”€โ”€ taskManager.ts # Task lifecycle (create/update/cancel/list), TTL, cleanup +โ”œโ”€โ”€ taskExecution.ts # Generic task executor with state management +โ”œโ”€โ”€ streaming.ts # SSE stream formatting, heartbeat, chunk/completion events +โ”œโ”€โ”€ routingLogger.ts # Routing decision logger (stats, history, retention) +โ””โ”€โ”€ skills/ + โ”œโ”€โ”€ smartRouting.ts # Smart routing skill (routes via /v1/chat/completions) + โ””โ”€โ”€ quotaManagement.ts # Quota management skill (natural-language quota queries) + +src/app/a2a/ +โ””โ”€โ”€ route.ts # Next.js API route handler (JSON-RPC 2.0 dispatch) + +open-sse/mcp-server/ +โ””โ”€โ”€ schemas/a2a.ts # Zod schemas (AgentCard, Task, JSON-RPC, SSE events) +``` + +--- + +## Comparison: MCP vs A2A + +| Feature | MCP Server | A2A Server | +| ----------------- | ---------------------------- | ------------------------------------------------- | +| **Protocol** | Model Context Protocol | Agent-to-Agent Protocol v0.3 | +| **Transport** | stdio / HTTP | HTTP (JSON-RPC 2.0) | +| **Discovery** | Tool listing via MCP | `/.well-known/agent.json` | +| **Granularity** | 16 individual tools | 2 high-level skills | +| **Best for** | IDE agents (Cursor, VS Code) | Multi-agent systems (LangChain, CrewAI) | +| **Streaming** | Not supported | SSE via `message/stream` | +| **Task tracking** | No | Full lifecycle (submitted โ†’ completed) | +| **Observability** | Audit log per tool call | Cost envelope + resilience trace + policy verdict | + +--- + +## Licenรงa + +Part of [OmniRoute](https://github.com/diegosouzapw/OmniRoute) โ€” MIT License. diff --git a/docs/i18n/pt/A2A-SERVER.md b/docs/i18n/pt/A2A-SERVER.md deleted file mode 100644 index 01531ff482..0000000000 --- a/docs/i18n/pt/A2A-SERVER.md +++ /dev/null @@ -1,200 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/A2A-SERVER.md) - ---- - -# OmniRoute A2A Server Documentation - -> Agent-to-Agent Protocol v0.3 โ€” OmniRoute as an intelligent routing agent - -## Agent Discovery - -```bash -curl http://localhost:20128/.well-known/agent.json -``` - -Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements. - ---- - -## Authentication - -All `/a2a` requests require an API key via the `Authorization` header: - -``` -Authorization: Bearer YOUR_OMNIROUTE_API_KEY -``` - -If no API key is configured on the server, authentication is bypassed. - ---- - -## JSON-RPC 2.0 Methods - -### `message/send` โ€” Synchronous Execution - -Sends a message to a skill and waits for the complete response. - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{ - "jsonrpc": "2.0", - "id": "1", - "method": "message/send", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Write a hello world in Python"}], - "metadata": {"model": "auto", "combo": "fast-coding"} - } - }' -``` - -**Response:** - -```json -{ - "jsonrpc": "2.0", - "id": "1", - "result": { - "task": { "id": "uuid", "state": "completed" }, - "artifacts": [{ "type": "text", "content": "..." }], - "metadata": { - "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)", - "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, - "resilience_trace": [ - { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." } - ], - "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } - } - } -} -``` - -### `message/stream` โ€” SSE Streaming - -Same as `message/send` but returns Server-Sent Events for real-time streaming. - -```bash -curl -N -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{ - "jsonrpc": "2.0", - "id": "1", - "method": "message/stream", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Explain quantum computing"}] - } - }' -``` - -**SSE Events:** - -``` -data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}} - -: heartbeat 2026-03-03T17:00:00Z - -data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} -``` - -### `tasks/get` โ€” Query Task Status - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' -``` - -### `tasks/cancel` โ€” Cancel a Task - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' -``` - ---- - -## Available Skills - -| Skill | Description | -| :----------------- | :------------------------------------------------------------------------------------------------------------------------------ | -| `smart-routing` | Routes prompts through OmniRoute's intelligent pipeline. Returns response with routing explanation, cost, and resilience trace. | -| `quota-management` | Answers natural-language queries about provider quotas, suggests free combos, and provides quota rankings. | - ---- - -## Task Lifecycle - -``` -submitted โ†’ working โ†’ completed - โ†’ failed - โ†’ cancelled -``` - -- Tasks expire after 5 minutes (configurable) -- Terminal states: `completed`, `failed`, `cancelled` -- Event log tracks every state transition - ---- - -## Error Codes - -| Code | Meaning | -| :----- | :----------------------------- | -| -32700 | Parse error (invalid JSON) | -| -32600 | Invalid request / Unauthorized | -| -32601 | Method or skill not found | -| -32602 | Invalid params | -| -32603 | Internal error | - ---- - -## Integration Examples - -### Python (requests) - -```python -import requests - -resp = requests.post("http://localhost:20128/a2a", json={ - "jsonrpc": "2.0", "id": "1", - "method": "message/send", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Hello"}] - } -}, headers={"Authorization": "Bearer YOUR_KEY"}) - -result = resp.json()["result"] -print(result["artifacts"][0]["content"]) -print(result["metadata"]["routing_explanation"]) -``` - -### TypeScript (fetch) - -```typescript -const resp = await fetch("http://localhost:20128/a2a", { - method: "POST", - headers: { - "Content-Type": "application/json", - Authorization: "Bearer YOUR_KEY", - }, - body: JSON.stringify({ - jsonrpc: "2.0", - id: "1", - method: "message/send", - params: { - skill: "smart-routing", - messages: [{ role: "user", content: "Hello" }], - }, - }), -}); -const { result } = await resp.json(); -console.log(result.metadata.routing_explanation); -``` diff --git a/docs/i18n/pt/API_REFERENCE.md b/docs/i18n/pt/API_REFERENCE.md deleted file mode 100644 index b878605221..0000000000 --- a/docs/i18n/pt/API_REFERENCE.md +++ /dev/null @@ -1,455 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/API_REFERENCE.md) - ---- - -# API Reference - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/API_REFERENCE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/API_REFERENCE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/API_REFERENCE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/API_REFERENCE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/API_REFERENCE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/API_REFERENCE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/API_REFERENCE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/API_REFERENCE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/API_REFERENCE.md) - -Complete reference for all OmniRoute API endpoints. - ---- - -## Table of Contents - -- [Chat Completions](#chat-completions) -- [Embeddings](#embeddings) -- [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`. - -### ACP Agents - -| Endpoint | Method | Description | -| ----------------- | ------ | -------------------------------------------------------- | -| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | -| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | -| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | - -GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). - -### Resilience & Rate Limits - -| Endpoint | Method | Description | -| ----------------------- | ------- | ------------------------------- | -| `/api/resilience` | 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` diff --git a/docs/i18n/pt/ARCHITECTURE.md b/docs/i18n/pt/ARCHITECTURE.md deleted file mode 100644 index 4ea06a29f2..0000000000 --- a/docs/i18n/pt/ARCHITECTURE.md +++ /dev/null @@ -1,787 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/ARCHITECTURE.md) - ---- - -# OmniRoute Architecture - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/ARCHITECTURE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/ARCHITECTURE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/ARCHITECTURE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/ARCHITECTURE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/ARCHITECTURE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/ARCHITECTURE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/ARCHITECTURE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/ARCHITECTURE.md) - -_Last updated: 2026-03-04_ - -## 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 (`...`) for reasoning models -- Response sanitization for strict OpenAI SDK compatibility -- Role normalization (developerโ†’system, systemโ†’user) for cross-provider compatibility -- Structured output conversion (json_schema โ†’ Gemini responseSchema) -- Local persistence for providers, keys, aliases, combos, settings, pricing -- Usage/cost tracking and request logging -- Optional cloud sync for multi-device/state sync -- IP allowlist/blocklist for API access control -- Thinking budget management (passthrough/auto/custom/adaptive) -- Global system prompt injection -- Session tracking and fingerprinting -- Per-account enhanced rate limiting with provider-specific profiles -- Circuit breaker pattern for provider resilience -- Anti-thundering herd protection with mutex locking -- Signature-based request deduplication cache -- Domain layer: model availability, cost rules, fallback policy, lockout policy -- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) -- Policy engine for centralized request evaluation (lockout โ†’ budget โ†’ fallback) -- Request telemetry with p50/p95/p99 latency aggregation -- Correlation ID (X-Request-Id) for end-to-end tracing -- Compliance audit logging with opt-out per API key -- Eval framework for LLM quality assurance -- Resilience UI dashboard with real-time circuit breaker status -- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) - -Primary runtime model: - -- Next.js 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[(storage.sqlite)] - UDB[(usage tables + log artifacts)] - end - - subgraph Upstreams[Upstream Providers] - P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/Qoder/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/route.ts` (GET) -- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) -- OAuth: `src/app/api/oauth/*` -- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` -- Usage: `src/app/api/usage/*` -- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` -- CLI tooling helpers: `src/app/api/cli-tools/*` -- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) -- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) -- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) -- Sessions: `src/app/api/sessions` (GET) -- Rate limits: `src/app/api/rate-limits` (GET) -- Resilience: `src/app/api/resilience` (GET/PATCH) โ€” provider profiles, circuit breaker, rate limit state -- Resilience reset: `src/app/api/resilience/reset` (POST) โ€” reset breakers + cooldowns -- Cache stats: `src/app/api/cache/stats` (GET/DELETE) -- Model availability: `src/app/api/models/availability` (GET/POST) -- Telemetry: `src/app/api/telemetry/summary` (GET) -- Budget: `src/app/api/usage/budget` (GET/POST) -- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) -- Compliance audit: `src/app/api/compliance/audit-log` (GET) -- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) -- Policies: `src/app/api/policies` (GET/POST) - -## 2) SSE + 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` -- Response sanitization: `open-sse/handlers/responseSanitizer.ts` -- Role normalization: `open-sse/services/roleNormalizer.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`, `qoder.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 (SQLite): - -- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) -- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) -- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) -- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** - -Usage persistence: - -- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) -- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` -- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) -- legacy JSON files are migrated to SQLite by startup migrations when present - -Domain State DB (SQLite): - -- `src/lib/db/domainState.ts` โ€” CRUD operations 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: - -- primary runtime DB: `${DATA_DIR}/storage.sqlite` -- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) -- structured call payload archives: `${DATA_DIR}/call_logs/` -- optional translator/request debug sessions: `/logs/...` - -## Deployment Topology - -```mermaid -flowchart LR - 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[(storage.sqlite)] - UsageDB[(usage tables + log artifacts)] - end - - subgraph External[External Services] - Providers[AI Providers] - SyncCloud[Cloud Sync Service] - end - - CLI --> Next - Browser --> Next - Next --> Core - Next --> MainDB - Core --> MainDB - Core --> UsageDB - Core --> Providers - Next --> SyncCloud -``` - -## Module Mapping (Decision-Critical) - -### Route and API Modules - -- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs -- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) -- `src/app/api/providers*`: provider CRUD, validation, testing -- `src/app/api/provider-nodes*`: custom compatible node management -- `src/app/api/provider-models`: custom model management (CRUD) -- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) -- `src/app/api/oauth/*`: OAuth/device-code flows -- `src/app/api/keys*`: local API key lifecycle -- `src/app/api/models/alias`: alias management -- `src/app/api/combos*`: fallback combo management -- `src/app/api/pricing`: pricing overrides for cost calculation -- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) -- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) -- `src/app/api/usage/*`: usage and logs APIs -- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers -- `src/app/api/cli-tools/*`: local CLI config writers/checkers -- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) -- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) -- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) -- `src/app/api/sessions`: active session listing (GET) -- `src/app/api/rate-limits`: per-account rate limit status (GET) - -### Routing and Execution Core - -- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop -- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup -- `open-sse/executors/*`: provider-specific network and format behavior - -### Translation Registry and Format Converters - -- `open-sse/translator/index.ts`: translator registry and orchestration -- Request translators: `open-sse/translator/request/*` -- Response translators: `open-sse/translator/response/*` -- Format constants: `open-sse/translator/formats.ts` - -### Persistence - -- `src/lib/db/*`: persistent config/state and domain persistence on SQLite -- `src/lib/localDb.ts`: compatibility re-export for DB modules -- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables - -## Provider Executor Coverage (Strategy Pattern) - -Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. - -| Executor | Provider(s) | Special Handling | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | -| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, Qoder, 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 | -| Qoder | openai | OAuth (Basic) | โœ… | โœ… | โœ… | โš ๏ธ Per request | -| OpenRouter | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| GLM/Kimi/MiniMax | claude | API Key | โœ… | โœ… | โŒ | โŒ | -| DeepSeek | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Groq | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| xAI (Grok) | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Mistral | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Perplexity | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Together AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Fireworks AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Cerebras | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Cohere | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| NVIDIA NIM | openai | API Key | โœ… | โœ… | โŒ | โŒ | - -## Format Translation Coverage - -Detected source formats include: - -- `openai` -- `openai-responses` -- `claude` -- `gemini` - -Target formats include: - -- OpenAI chat/Responses -- Claude -- Gemini/Gemini-CLI/Antigravity envelope -- Kiro -- Cursor - -Translations use **OpenAI as the hub format** โ€” all conversions go through OpenAI as intermediate: - -``` -Source Format โ†’ OpenAI (hub) โ†’ Target Format -``` - -Translations are selected dynamically based on source payload shape and provider target format. - -Additional processing layers in the translation pipeline: - -- **Response sanitization** โ€” Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance -- **Role normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI targets; merges `system` โ†’ `user` for models that reject the system role (GLM, ERNIE) -- **Think tag extraction** โ€” Parses `...` blocks from content into `reasoning_content` field -- **Structured output** โ€” Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` - -## Supported API Endpoints - -| 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 `/logs//` 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 - -- SQLite schema migrations and auto-upgrade hooks at startup -- legacy JSON โ†’ SQLite migration compatibility path - -## Observability and Operational Signals - -Runtime visibility sources: - -- console logs from `src/sse/utils/logger.ts` -- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) -- textual request status log in `log.txt` (optional/compat) -- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` -- dashboard usage endpoints (`/api/usage/*`) for UI consumption - -## Security-Sensitive Boundaries - -- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing -- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning -- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format -- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level -- Cloud sync endpoints rely on API key auth + machine id semantics - -## Environment and Runtime Matrix - -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` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. -2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. -3. Request logger writes full headers/body when enabled; treat log directory as sensitive. -4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. -5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. -6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). -7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). -8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). - -## Operational Verification Checklist - -- Build from source: `npm run build` -- Build Docker image: `docker build -t omniroute .` -- Start service and verify: -- `GET /api/settings` -- `GET /api/v1/models` -- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/pt/AUTO-COMBO.md b/docs/i18n/pt/AUTO-COMBO.md deleted file mode 100644 index 2166e41dff..0000000000 --- a/docs/i18n/pt/AUTO-COMBO.md +++ /dev/null @@ -1,67 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/AUTO-COMBO.md) - ---- - -# OmniRoute Auto-Combo Engine - -> Self-managing model chains with adaptive scoring - -## How It Works - -The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**: - -| Factor | Weight | Description | -| :--------- | :----- | :---------------------------------------------- | -| Quota | 0.20 | Remaining capacity [0..1] | -| Health | 0.25 | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 | -| CostInv | 0.20 | Inverse cost (cheaper = higher score) | -| LatencyInv | 0.15 | Inverse p95 latency (faster = higher) | -| TaskFit | 0.10 | Model ร— task type fitness score | -| Stability | 0.10 | Low variance in latency/errors | - -## Mode Packs - -| Pack | Focus | Key Weight | -| :---------------------- | :----------- | :--------------- | -| ๐Ÿš€ **Ship Fast** | Speed | latencyInv: 0.35 | -| ๐Ÿ’ฐ **Cost Saver** | Economy | costInv: 0.40 | -| ๐ŸŽฏ **Quality First** | Best model | taskFit: 0.40 | -| ๐Ÿ“ก **Offline Friendly** | Availability | quota: 0.40 | - -## Self-Healing - -- **Temporary exclusion**: Score < 0.2 โ†’ excluded for 5 min (progressive backoff, max 30 min) -- **Circuit breaker awareness**: OPEN โ†’ auto-excluded; HALF_OPEN โ†’ probe requests -- **Incident mode**: >50% OPEN โ†’ disable exploration, maximize stability -- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout - -## Bandit Exploration - -5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode. - -## API - -```bash -# Create auto-combo -curl -X POST http://localhost:20128/api/combos/auto \ - -H "Content-Type: application/json" \ - -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}' - -# List auto-combos -curl http://localhost:20128/api/combos/auto -``` - -## Task Fitness - -30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` โ†’ high coding score). - -## Files - -| File | Purpose | -| :------------------------------------------- | :------------------------------------ | -| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization | -| `open-sse/services/autoCombo/taskFitness.ts` | Model ร— task fitness lookup | -| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap | -| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode | -| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles | -| `src/app/api/combos/auto/route.ts` | REST API | diff --git a/docs/i18n/pt/CHANGELOG.md b/docs/i18n/pt/CHANGELOG.md index f815ae46b3..3ee20a90ea 100644 --- a/docs/i18n/pt/CHANGELOG.md +++ b/docs/i18n/pt/CHANGELOG.md @@ -1,12 +1,92 @@ # Changelog (Portuguรชs (Portugal)) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CHANGELOG.md) --- - ## [Unreleased] +### ๐Ÿ› ๏ธ Maintenance + +- **AGENTS.md rewrite:** Condensed from 297โ†’153 lines. Added build/lint/test commands (including single-test execution), code style guidelines (Prettier, TypeScript, ESLint, naming, imports, error handling, security), and trimmed verbose architecture tables for AI agent consumption. + +## [3.4.2] - 2026-04-01 + +### ๐Ÿ› Bug Fixes + +- **CI Stabilization:** Fixed failing analytics/settings Playwright selectors and request assertions so GitHub Actions E2E runs pass reliably across localized UIs and switch-based controls. +- **Deterministic Tests:** Removed date-sensitive quota fixtures from Copilot usage tests and aligned idempotency/model catalog tests with the merged runtime behavior. +- **MCP Type Hardening:** Removed zero-budget explicit `any` regressions from the MCP server tool registration path, restoring the `check:any-budget:t11` workflow gate. + +### ๐Ÿ› ๏ธ Maintenance + +- **Release Branch Integration:** Consolidated the active feature branches into `release/v3.4.2` on top of current `main` and validated the branch with lint, unit, coverage, build, and CI-mode E2E runs. + +## [3.4.1] - 2026-03-31 + +> [!WARNING] +> **BREAKING CHANGE: request logging, retention, and logging environment variables have been redesigned.** +> On the first startup after upgrading, OmniRoute archives legacy request logs from `DATA_DIR/logs/`, legacy `DATA_DIR/call_logs/`, and `DATA_DIR/log.txt` into `DATA_DIR/log_archives/*.zip`, then removes the deprecated layout and switches to the new unified artifact format under `DATA_DIR/call_logs/`. + +### โœจ New Features + +- **.ENV Migration Utility:** Included `scripts/migrate-env.mjs` to seamlessly migrate ` Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` - ---- - -## Step 2 โ€” Install CLI Tools - -All npm-based tools require Node.js 18+: - -```bash -# Claude Code (Anthropic) -npm install -g @anthropic-ai/claude-code - -# OpenAI Codex -npm install -g @openai/codex - -# Gemini CLI (Google) -npm install -g @google/gemini-cli - -# OpenCode -npm install -g opencode-ai - -# Cline -npm install -g cline - -# KiloCode -npm install -g kilecode - -# Kiro CLI (Amazon โ€” requires curl + unzip) -apt-get install -y unzip # on Debian/Ubuntu -curl -fsSL https://cli.kiro.dev/install | bash -export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc -``` - -**Verify:** - -```bash -claude --version # 2.x.x -codex --version # 0.x.x -gemini --version # 0.x.x -opencode --version # x.x.x -cline --version # 2.x.x -kilocode --version # x.x.x (or: kilo --version) -kiro-cli --version # 1.x.x -``` - ---- - -## Step 3 โ€” Set Global Environment Variables - -Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`: - -```bash -# OmniRoute Universal Endpoint -export OPENAI_BASE_URL="http://localhost:20128/v1" -export OPENAI_API_KEY="sk-your-omniroute-key" -export ANTHROPIC_BASE_URL="http://localhost:20128/v1" -export ANTHROPIC_API_KEY="sk-your-omniroute-key" -export GEMINI_BASE_URL="http://localhost:20128/v1" -export GEMINI_API_KEY="sk-your-omniroute-key" -``` - -> For a **remote server** replace `localhost:20128` with the server IP or domain, -> e.g. `http://192.168.0.15:20128`. - ---- - -## Step 4 โ€” Configure Each Tool - -### Claude Code - -```bash -# Via CLI: -claude config set --global api-base-url http://localhost:20128/v1 - -# Or create ~/.claude/settings.json: -mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF -{ - "apiBaseUrl": "http://localhost:20128/v1", - "apiKey": "sk-your-omniroute-key" -} -EOF -``` - -**Test:** `claude "say hello"` - ---- - -### OpenAI Codex - -```bash -mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF -model: auto -apiKey: sk-your-omniroute-key -apiBaseUrl: http://localhost:20128/v1 -EOF -``` - -**Test:** `codex "what is 2+2?"` - ---- - -### Gemini CLI - -```bash -mkdir -p ~/.gemini && cat > ~/.gemini/settings.json << EOF -{ - "apiKey": "sk-your-omniroute-key", - "baseUrl": "http://localhost:20128/v1" -} -EOF -``` - -**Test:** `gemini "hello"` - ---- - -### OpenCode - -```bash -mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF -[provider.openai] -base_url = "http://localhost:20128/v1" -api_key = "sk-your-omniroute-key" -EOF -``` - -**Test:** `opencode` - ---- - -### Cline (CLI or VS Code) - -**CLI mode:** - -```bash -mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF -{ - "apiProvider": "openai", - "openAiBaseUrl": "http://localhost:20128/v1", - "openAiApiKey": "sk-your-omniroute-key" -} -EOF -``` - -**VS Code mode:** -Cline extension settings โ†’ API Provider: `OpenAI Compatible` โ†’ Base URL: `http://localhost:20128/v1` - -Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ Cline โ†’ Apply Config**. - ---- - -### KiloCode (CLI or VS Code) - -**CLI mode:** - -```bash -kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key -``` - -**VS Code settings:** - -```json -{ - "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", - "kilo-code.apiKey": "sk-your-omniroute-key" -} -``` - -Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ KiloCode โ†’ Apply Config**. - ---- - -### Continue (VS Code Extension) - -Edit `~/.continue/config.yaml`: - -```yaml -models: - - name: OmniRoute - provider: openai - model: auto - apiBase: http://localhost:20128/v1 - apiKey: sk-your-omniroute-key - default: true -``` - -Restart VS Code after editing. - ---- - -### Kiro CLI (Amazon) - -```bash -# Login to your AWS/Kiro account: -kiro-cli login - -# The CLI uses its own auth โ€” OmniRoute is not needed as backend for Kiro CLI itself. -# Use kiro-cli alongside OmniRoute for other tools. -kiro-cli status -``` - ---- - -### Cursor (Desktop App) - -> **Note:** Cursor routes requests through its cloud. For OmniRoute integration, -> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL. - -Via GUI: **Settings โ†’ Models โ†’ OpenAI API Key** - -- Base URL: `https://your-domain.com/v1` -- API Key: your OmniRoute key - ---- - -## Dashboard Auto-Configuration - -The OmniRoute dashboard automates configuration for most tools: - -1. Go to `http://localhost:20128/dashboard/cli-tools` -2. Expand any tool card -3. Select your API key from the dropdown -4. Click **Apply Config** (if tool is detected as installed) -5. Or copy the generated config snippet manually - ---- - -## Built-in Agents: Droid & OpenClaw - -**Droid** and **OpenClaw** are AI agents built directly into OmniRoute โ€” no installation needed. -They run as internal routes and use OmniRoute's model routing automatically. - -- Access: `http://localhost:20128/dashboard/agents` -- Configure: same combos and providers as all other tools -- No API key or CLI install required - ---- - -## Available API Endpoints - -| Endpoint | Description | Use For | -| -------------------------- | ----------------------------- | --------------------------- | -| `/v1/chat/completions` | Standard chat (all providers) | All modern tools | -| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows | -| `/v1/completions` | Legacy text completions | Older tools using `prompt:` | -| `/v1/embeddings` | Text embeddings | RAG, search | -| `/v1/images/generations` | Image generation | DALL-E, Flux, etc. | -| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS | -| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI | - ---- - -## Troubleshooting - -| Error | Cause | Fix | -| ------------------------- | ----------------------- | ------------------------------------------ | -| `Connection refused` | OmniRoute not running | `pm2 start omniroute` | -| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` | -| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` | -| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` | -| CLI shows "not installed" | Binary not in PATH | Check `which ` | -| `kiro-cli: not found` | Not in PATH | `export PATH="$HOME/.local/bin:$PATH"` | - ---- - -## Quick Setup Script (One Command) - -```bash -# Install all CLIs and configure for OmniRoute (replace with your key and server URL) -OMNIROUTE_URL="http://localhost:20128/v1" -OMNIROUTE_KEY="sk-your-omniroute-key" - -npm install -g @anthropic-ai/claude-code @openai/codex @google/gemini-cli opencode-ai cline kilecode - -# Kiro CLI -apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash - -# Write configs -mkdir -p ~/.claude ~/.codex ~/.gemini ~/.config/opencode ~/.continue - -cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" -cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" -cat > ~/.gemini/settings.json <<< "{\"apiKey\":\"$OMNIROUTE_KEY\",\"baseUrl\":\"$OMNIROUTE_URL\"}" -cat >> ~/.bashrc << EOF -export OPENAI_BASE_URL="$OMNIROUTE_URL" -export OPENAI_API_KEY="$OMNIROUTE_KEY" -export ANTHROPIC_BASE_URL="$OMNIROUTE_URL" -export ANTHROPIC_API_KEY="$OMNIROUTE_KEY" -EOF - -source ~/.bashrc -echo "โœ… All CLIs installed and configured for OmniRoute" -``` diff --git a/docs/i18n/pt/CODEBASE_DOCUMENTATION.md b/docs/i18n/pt/CODEBASE_DOCUMENTATION.md deleted file mode 100644 index e2d7950052..0000000000 --- a/docs/i18n/pt/CODEBASE_DOCUMENTATION.md +++ /dev/null @@ -1,593 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CODEBASE_DOCUMENTATION.md) - ---- - -# omniroute โ€” Codebase Documentation - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) - -> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. - ---- - -## 1. 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
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, Qoder, 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 | -| Qoder | 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"] -``` diff --git a/docs/i18n/pt/CONTRIBUTING.md b/docs/i18n/pt/CONTRIBUTING.md new file mode 100644 index 0000000000..641baf44b1 --- /dev/null +++ b/docs/i18n/pt/CONTRIBUTING.md @@ -0,0 +1,299 @@ +# Contributing to OmniRoute (Portuguรชs (Portugal)) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CONTRIBUTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CONTRIBUTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CONTRIBUTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CONTRIBUTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CONTRIBUTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CONTRIBUTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CONTRIBUTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CONTRIBUTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CONTRIBUTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CONTRIBUTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CONTRIBUTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CONTRIBUTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CONTRIBUTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CONTRIBUTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CONTRIBUTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CONTRIBUTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CONTRIBUTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CONTRIBUTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CONTRIBUTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CONTRIBUTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CONTRIBUTING.md) + +--- + +Thank you for your interest in contributing! This guide covers everything you need to get started. + +--- + +## Development Setup + +### Prerequisites + +- **Node.js** >= 18 < 24 (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` | `20128` | Server port | +| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | Base URL for frontend | +| `JWT_SECRET` | (generate above) | JWT signing secret | +| `INITIAL_PASSWORD` | `CHANGEME` | First login password | +| `APP_LOG_LEVEL` | `info` | Log verbosity level | + +### Dashboard Settings + +The dashboard provides UI toggles for features that can also be configured via environment variables: + +| Setting Location | Toggle | Description | +| ------------------- | ------------------ | ------------------------------ | +| Settings โ†’ Advanced | Debug Mode | Enable debug request logs (UI) | +| Settings โ†’ General | Sidebar Visibility | Show/hide sidebar sections | + +These settings are stored in the database and persist across restarts, overriding env var defaults when set. + +### 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:20128/dashboard` +- **API**: `http://localhost:20128/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`, `mcp`, `a2a`, `memory`, `skills`. + +--- + +## Running Tests + +```bash +# All tests (unit + vitest + ecosystem + e2e) +npm run test:all + +# Single test file (Node.js native test runner โ€” most tests use this) +node --import tsx/esm --test tests/unit/your-file.test.mjs + +# Vitest (MCP server, autoCombo, cache) +npm run test:vitest + +# E2E tests (requires Playwright) +npm run test:e2e + +# Protocol clients E2E (MCP transports, A2A) +npm run test:protocols:e2e + +# Ecosystem compatibility tests +npm run test:ecosystem + +# Coverage (55% min statements/lines/functions; 60% branches) +npm run test:coverage +npm run coverage:report + +# Lint + format check +npm run lint +npm run check +``` + +Coverage notes: + +- `npm run test:coverage` measures source coverage for the main unit test suite, excludes `tests/**`, and includes `open-sse/**` +- `npm run coverage:report` prints the detailed file-by-file report from the latest coverage run +- `npm run test:coverage:legacy` preserves the older metric for historical comparison +- See `docs/COVERAGE_PLAN.md` for the phased coverage improvement roadmap + +Current test status: **122 unit test files** covering: + +- Provider translators and format conversion +- Rate limiting, circuit breaker, and resilience +- Semantic cache, idempotency, progress tracking +- Database operations and schema (21 DB modules) +- OAuth flows and authentication +- API endpoint validation (Zod v4) +- MCP server tools and scope enforcement +- Memory and Skills systems + +--- + +## Code Style + +- **ESLint** โ€” Run `npm run lint` before committing +- **Prettier** โ€” Auto-formatted via `lint-staged` on commit (2 spaces, semicolons, double quotes, 100 char width, es5 trailing commas) +- **TypeScript** โ€” All `src/` code uses `.ts`/`.tsx`; `open-sse/` uses `.ts`/`.js`; document with TSDoc (`@param`, `@returns`, `@throws`) +- **No `eval()`** โ€” ESLint enforces `no-eval`, `no-implied-eval`, `no-new-func` +- **Zod validation** โ€” Use Zod v4 schemas for all API input validation +- **Naming**: Files = camelCase/kebab-case, components = PascalCase, constants = UPPER_SNAKE + +--- + +## Project Structure + +``` +src/ # TypeScript (.ts / .tsx) +โ”œโ”€โ”€ app/ # Next.js 16 App Router +โ”‚ โ”œโ”€โ”€ (dashboard)/ # Dashboard pages (23 sections) +โ”‚ โ”œโ”€โ”€ api/ # API routes (51 directories) +โ”‚ โ””โ”€โ”€ login/ # Auth pages (.tsx) +โ”œโ”€โ”€ domain/ # Policy engine (policyEngine, comboResolver, costRules, etc.) +โ”œโ”€โ”€ lib/ # Core business logic (.ts) +โ”‚ โ”œโ”€โ”€ a2a/ # Agent-to-Agent v0.3 protocol server +โ”‚ โ”œโ”€โ”€ acp/ # Agent Communication Protocol registry +โ”‚ โ”œโ”€โ”€ compliance/ # Compliance policy engine +โ”‚ โ”œโ”€โ”€ db/ # SQLite database layer (21 modules + 16 migrations) +โ”‚ โ”œโ”€โ”€ memory/ # Persistent conversational memory +โ”‚ โ”œโ”€โ”€ oauth/ # OAuth providers, services, and utilities +โ”‚ โ”œโ”€โ”€ skills/ # Extensible skill framework +โ”‚ โ”œโ”€โ”€ usage/ # Usage tracking and cost calculation +โ”‚ โ””โ”€โ”€ localDb.ts # Re-export layer only โ€” never add logic here +โ”œโ”€โ”€ middleware/ # Request middleware (promptInjectionGuard) +โ”œโ”€โ”€ mitm/ # MITM proxy (cert, DNS, target routing) +โ”œโ”€โ”€ shared/ +โ”‚ โ”œโ”€โ”€ components/ # React components (.tsx) +โ”‚ โ”œโ”€โ”€ constants/ # Provider definitions (60+), MCP scopes, routing strategies +โ”‚ โ”œโ”€โ”€ utils/ # Circuit breaker, sanitizer, auth helpers +โ”‚ โ””โ”€โ”€ validation/ # Zod v4 schemas +โ””โ”€โ”€ sse/ # SSE proxy pipeline + +open-sse/ # @omniroute/open-sse workspace +โ”œโ”€โ”€ executors/ # 14 provider-specific request executors +โ”œโ”€โ”€ handlers/ # 11 request handlers (chat, responses, embeddings, images, etc.) +โ”œโ”€โ”€ mcp-server/ # MCP server (25 tools, 3 transports, 10 scopes) +โ”œโ”€โ”€ services/ # 36+ services (combo, autoCombo, rateLimitManager, etc.) +โ”œโ”€โ”€ translator/ # Format translators (OpenAI โ†” Claude โ†” Gemini โ†” Responses โ†” Ollama) +โ”œโ”€โ”€ transformer/ # Responses API transformer +โ””โ”€โ”€ utils/ # 22 utility modules (stream, TLS, proxy, logging) + +electron/ # Electron desktop app (cross-platform) + +tests/ +โ”œโ”€โ”€ unit/ # Node.js test runner (122 test files) +โ”œโ”€โ”€ integration/ # Integration tests +โ”œโ”€โ”€ e2e/ # Playwright tests +โ”œโ”€โ”€ security/ # Security tests +โ”œโ”€โ”€ translator/ # Translator-specific tests +โ””โ”€โ”€ load/ # Load tests + +docs/ # Documentation +โ”œโ”€โ”€ ARCHITECTURE.md # System architecture +โ”œโ”€โ”€ API_REFERENCE.md # All endpoints +โ”œโ”€โ”€ USER_GUIDE.md # Provider setup, CLI integration +โ”œโ”€โ”€ TROUBLESHOOTING.md # Common issues +โ”œโ”€โ”€ MCP-SERVER.md # MCP server (25 tools) +โ”œโ”€โ”€ A2A-SERVER.md # A2A agent protocol +โ”œโ”€โ”€ AUTO-COMBO.md # Auto-combo engine +โ”œโ”€โ”€ CLI-TOOLS.md # CLI tools integration +โ”œโ”€โ”€ COVERAGE_PLAN.md # Test coverage improvement plan +โ”œโ”€โ”€ openapi.yaml # OpenAPI specification +โ””โ”€โ”€ adr/ # Architecture Decision Records +``` + +--- + +## Adding a New Provider + +### Step 1: Register Provider Constants + +Add to `src/shared/constants/providers.ts` โ€” Zod-validated at module load. + +### Step 2: Add Executor (if custom logic needed) + +Create executor in `open-sse/executors/your-provider.ts` extending the base executor. + +### Step 3: Add Translator (if non-OpenAI format) + +Create request/response translators in `open-sse/translator/`. + +### Step 4: Add OAuth Config (if OAuth-based) + +Add OAuth credentials in `src/lib/oauth/constants/oauth.ts` and service in `src/lib/oauth/services/`. + +### Step 5: Register Models + +Add model definitions in `open-sse/config/providerRegistry.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 +- [ ] All inputs validated with Zod schemas +- [ ] CHANGELOG updated (if user-facing change) +- [ ] Documentation updated (if applicable) + +--- + +## Releasing + +Releases are managed via the `/generate-release` workflow. When a new GitHub Release is created, the package is **automatically published to npm** via GitHub Actions. + +--- + +## Getting Help + +- **Architecture**: See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) +- **API Reference**: See [`docs/API_REFERENCE.md`](docs/API_REFERENCE.md) +- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **ADRs**: See `docs/adr/` for architectural decision records diff --git a/docs/i18n/pt/FEATURES.md b/docs/i18n/pt/FEATURES.md deleted file mode 100644 index 7c501e9bae..0000000000 --- a/docs/i18n/pt/FEATURES.md +++ /dev/null @@ -1,147 +0,0 @@ -# OmniRoute โ€” Dashboard Features Gallery (Portuguรชs (Portugal)) - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) - -> ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../docs/FEATURES.md) - ---- - -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 (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. - -![Providers Dashboard](screenshots/01-providers.png) - ---- - -## ๐ŸŽจ Combos - -Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. - -![Combos Dashboard](screenshots/02-combos.png) - ---- - -## ๐Ÿ“Š Analytics - -Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. - -![Analytics Dashboard](screenshots/03-analytics.png) - ---- - -## ๐Ÿฅ System Health - -Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. - -![Health Dashboard](screenshots/04-health.png) - ---- - -## ๐Ÿ”ง Translator Playground - -Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). - -![Translator Playground](screenshots/05-translator.png) - ---- - -## ๐ŸŽฎ Model Playground _(v2.0.9+)_ - -Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. - ---- - -## ๐ŸŽจ Themes _(v2.0.5+)_ - -Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. - ---- - -## โš™๏ธ Settings - -Comprehensive settings panel with tabs: - -- **General** โ€” System storage, backup management (export/import database) -- **Appearance** โ€” Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls -- **Security** โ€” API endpoint protection, custom provider blocking, IP filtering, session info -- **Routing** โ€” Model aliases, background task degradation -- **Resilience** โ€” Rate limit persistence, circuit breaker tuning -- **Advanced** โ€” Configuration overrides - -![Settings Dashboard](screenshots/06-settings.png) - ---- - -## ๐Ÿ”ง CLI Tools - -One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. - -![CLI Tools Dashboard](screenshots/07-cli-tools.png) - ---- - -## ๐Ÿค– CLI Agents _(v2.0.11+)_ - -Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: - -- **Installation status** โ€” Installed / Not Found with version detection -- **Protocol badges** โ€” stdio, HTTP, etc. -- **Custom agents** โ€” Register any CLI tool via form (name, binary, version command, spawn args) -- **CLI Fingerprint Matching** โ€” Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP - ---- - -## ๐Ÿ–ผ๏ธ Media _(v2.0.3+)_ - -Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. - ---- - -## ๐Ÿ“ Request Logs - -Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. - -![Usage Logs](screenshots/08-usage.png) - ---- - -## ๐ŸŒ API Endpoint - -Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. - -![Endpoint Dashboard](screenshots/09-endpoint.png) - ---- - -## ๐Ÿ”‘ API Key Management - -Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. - ---- - -## ๐Ÿ“‹ Audit Log - -Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. - ---- - -## ๐Ÿ–ฅ๏ธ Desktop Application - -Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. - -Key features: - -- Server readiness polling (no blank screen on cold start) -- System tray with port management -- Content Security Policy -- Single-instance lock -- Auto-update on restart -- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) -- Hardened Electron build packaging โ€” symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+) - -๐Ÿ“– See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/pt/MCP-SERVER.md b/docs/i18n/pt/MCP-SERVER.md deleted file mode 100644 index 829acd30b1..0000000000 --- a/docs/i18n/pt/MCP-SERVER.md +++ /dev/null @@ -1,87 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/MCP-SERVER.md) - ---- - -# OmniRoute MCP Server Documentation - -> Model Context Protocol server with 16 intelligent tools - -## Installation - -OmniRoute MCP is built-in. Start it with: - -```bash -omniroute --mcp -``` - -Or via the open-sse transport: - -```bash -# HTTP streamable transport (port 20130) -omniroute --dev # MCP auto-starts on /mcp endpoint -``` - -## IDE Configuration - -See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup. - ---- - -## Essential Tools (8) - -| Tool | Description | -| :------------------------------ | :--------------------------------------- | -| `omniroute_get_health` | Gateway health, circuit breakers, uptime | -| `omniroute_list_combos` | All configured combos with models | -| `omniroute_get_combo_metrics` | Performance metrics for a specific combo | -| `omniroute_switch_combo` | Switch active combo by ID/name | -| `omniroute_check_quota` | Quota status per provider or all | -| `omniroute_route_request` | Send a chat completion through OmniRoute | -| `omniroute_cost_report` | Cost analytics for a time period | -| `omniroute_list_models_catalog` | Full model catalog with capabilities | - -## Advanced Tools (8) - -| Tool | Description | -| :--------------------------------- | :---------------------------------------------- | -| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | -| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | -| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | -| `omniroute_test_combo` | Live-test all models in a combo | -| `omniroute_get_provider_metrics` | Detailed metrics for one provider | -| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | -| `omniroute_explain_route` | Explain a past routing decision | -| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | - -## Authentication - -MCP tools are authenticated via API key scopes. Each tool requires specific scopes: - -| Scope | Tools | -| :------------- | :----------------------------------------------- | -| `read:health` | get_health, get_provider_metrics | -| `read:combos` | list_combos, get_combo_metrics | -| `write:combos` | switch_combo | -| `read:quota` | check_quota | -| `write:route` | route_request, simulate_route, test_combo | -| `read:usage` | cost_report, get_session_snapshot, explain_route | -| `write:config` | set_budget_guard, set_resilience_profile | -| `read:models` | list_models_catalog, best_combo_for_task | - -## Audit Logging - -Every tool call is logged to `mcp_tool_audit` with: - -- Tool name, arguments, result -- Duration (ms), success/failure -- API key hash, timestamp - -## Files - -| File | Purpose | -| :------------------------------------------- | :------------------------------------------ | -| `open-sse/mcp-server/server.ts` | MCP server creation + 16 tool registrations | -| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport | -| `open-sse/mcp-server/auth.ts` | API key + scope validation | -| `open-sse/mcp-server/audit.ts` | Tool call audit logging | -| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers | diff --git a/docs/i18n/pt/README.md b/docs/i18n/pt/README.md index 029cf26761..badc6d4fdf 100644 --- a/docs/i18n/pt/README.md +++ b/docs/i18n/pt/README.md @@ -1,12 +1,12 @@ # ๐Ÿš€ OmniRoute โ€” The Free AI Gateway (Portuguรชs (Portugal)) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/README.md) --- ### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback. -_Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._ +_Your universal API proxy โ€” one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._ **Chat Completions โ€ข Embeddings โ€ข Image Generation โ€ข Video โ€ข Music โ€ข Audio โ€ข Reranking โ€ข **Web Search** โ€ข MCP Server โ€ข A2A Protocol โ€ข 100% TypeScript** @@ -46,15 +46,17 @@ _Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now wi > - `APP_LOG_FILE_PATH` > - `APP_LOG_MAX_FILE_SIZE` > - `APP_LOG_RETENTION_DAYS` +> - `APP_LOG_MAX_FILES` > - `APP_LOG_LEVEL` > - `APP_LOG_FORMAT` > - `CALL_LOG_RETENTION_DAYS` +> - `CALL_LOG_MAX_ENTRIES` > > For release details and upgrade notes, see the [CHANGELOG](CHANGELOG.md). --- -## ๐Ÿ†• What's New in v3.0.0 +## ๐Ÿ†• What's New > **Upgrading from v2.9.5?** โ€” See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes. @@ -274,7 +276,7 @@ Developers pay $20โ€“200/month for Claude Pro, Codex Pro, or GitHub Copilot. Eve - **Smart 4-Tier Fallback** โ€” If subscription quota runs out, automatically redirects to API Key โ†’ Cheap โ†’ Free with zero manual intervention - **Real-Time Quota Tracking** โ€” Shows token consumption in real-time with reset countdown (5h, daily, weekly) - **Multi-Account Support** โ€” Multiple accounts per provider with auto round-robin โ€” when one runs out, switches to the next -- **Custom Combos** โ€” Customizable fallback chains with 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Custom Combos** โ€” Customizable fallback chains with 9 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random) - **Codex Business Quotas** โ€” Business/Team workspace quota monitoring directly in the dashboard @@ -286,7 +288,7 @@ OpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If **How OmniRoute solves it:** -- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 67+ providers +- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 60+ providers - **Format Translation** โ€” Automatic and transparent: OpenAI โ†” Claude โ†” Gemini โ†” Responses API - **Response Sanitization** โ€” Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+ - **Role Normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI providers; `system` โ†’ `user` for GLM/ERNIE @@ -372,7 +374,7 @@ Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code.. - **CLI Tools Dashboard** โ€” Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline - **GitHub Copilot Config Generator** โ€” Generates `chatLanguageModels.json` for VS Code with bulk model selection - **Onboarding Wizard** โ€” Guided 4-step setup for first-time users -- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 67+ providers +- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 60+ providers @@ -419,7 +421,7 @@ When a call fails, the dev doesn't know if it was a rate limit, expired token, w - **SQLite Proxy Logs** โ€” Persistent logs that survive server restarts - **Translator Playground** โ€” 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time) - **Request Telemetry** โ€” p50/p95/p99 latency + X-Request-Id tracing -- **File-Based Logging with Rotation** โ€” Console interceptor captures everything to JSON log with size-based rotation +- **File-Based Logging with Rotation** โ€” App logs rotate by size, retention days, and archive count; call log artifacts rotate by retention days and file count - **System Info Report** โ€” `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage. @@ -514,7 +516,7 @@ Developers who want all responses in a specific language, with a specific tone, - **System Prompt Injection** โ€” Global prompt applied to all requests - **Thinking Budget Validation** โ€” Reasoning token allocation control per request (passthrough, auto, custom, adaptive) -- **6 Routing Strategies** โ€” Global strategies that determine how requests are distributed +- **9 Routing Strategies** โ€” Global strategies that determine how requests are distributed - **Wildcard Router** โ€” `provider/*` patterns route dynamically to any provider - **Combo Enable/Disable Toggle** โ€” Toggle combos directly from the dashboard - **Provider Toggle** โ€” Enable/disable all connections for a provider with one click @@ -581,7 +583,7 @@ Different clients should have least-privilege access to tool categories. **How OmniRoute solves it:** -- 9 granular MCP scopes for controlled tool access +- 10 granular MCP scopes for controlled tool access - Scope enforcement and visibility in MCP management UI - Safe default posture for operational tooling @@ -1325,19 +1327,19 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. ### ๐Ÿค– Agent & Protocol Operations (v2.0) -| Feature | What It Does | -| ------------------------------------- | -------------------------------------------------------------------------------------------------- | -| ๐Ÿ”ง **MCP Server (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) | -| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | -| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | -| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | -| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | -| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | -| ๐Ÿ” **MCP Scope Enforcement** | 9 granular scope permissions for controlled tool access | -| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | -| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | -| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | -| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | +| Feature | What It Does | +| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| ๐Ÿ”ง **MCP Server (25 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools | +| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | +| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | +| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | +| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | +| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | +| ๐Ÿ” **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access | +| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | +| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | +| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | +| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | ### ๐Ÿง  Routing & Intelligence @@ -1348,7 +1350,7 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. | ๐Ÿ”„ **Format Translation** | OpenAI โ†” Claude โ†” Gemini โ†” Responses with schema-safe conversions | | ๐Ÿ‘ฅ **Multi-Account Support** | Multiple accounts per provider with intelligent selection | | ๐Ÿ”„ **Auto Token Refresh** | OAuth tokens refresh automatically with retry | -| ๐ŸŽจ **Custom Combos** | 6 balancing strategies + fallback chain control | +| ๐ŸŽจ **Custom Combos** | 9 balancing strategies + fallback chain control | | ๐ŸŒ **Wildcard Router** | `provider/*` dynamic routing | | ๐Ÿง  **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits | | ๐Ÿ”€ **Model Aliases** | Built-in + custom model aliasing and migration safety | @@ -1949,6 +1951,7 @@ opencode - Request artifacts are written to `DATA_DIR/call_logs/` as one JSON file per request - Enable pipeline capture from Dashboard โ†’ Logs โ†’ Request Logs if you need detailed per-stage payloads - Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log` +- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed **Connection test shows "Invalid" for OpenAI-compatible providers** diff --git a/docs/i18n/pt/RELEASE_CHECKLIST.md b/docs/i18n/pt/RELEASE_CHECKLIST.md deleted file mode 100644 index 903e812c3f..0000000000 --- a/docs/i18n/pt/RELEASE_CHECKLIST.md +++ /dev/null @@ -1,37 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/RELEASE_CHECKLIST.md) - ---- - -# Release Checklist - -Use this checklist before tagging or publishing a new OmniRoute release. - -## Version and Changelog - -1. Bump `package.json` version (`x.y.z`) in the release branch. -2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: - - `## [x.y.z] โ€” YYYY-MM-DD` -3. Keep `## [Unreleased]` as the first changelog section for upcoming work. -4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. - -## API Docs - -1. Update `docs/openapi.yaml`: - - `info.version` must equal `package.json` version. -2. Validate endpoint examples if API contracts changed. - -## Runtime Docs - -1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. -2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. -3. Update localized docs if source docs changed significantly. - -## Automated Check - -Run the sync guard locally before opening PR: - -```bash -npm run check:docs-sync -``` - -CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/pt/SECURITY.md b/docs/i18n/pt/SECURITY.md new file mode 100644 index 0000000000..6ee10275de --- /dev/null +++ b/docs/i18n/pt/SECURITY.md @@ -0,0 +1,179 @@ +# Security Policy (Portuguรชs (Portugal)) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../SECURITY.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/SECURITY.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/SECURITY.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/SECURITY.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/SECURITY.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/SECURITY.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/SECURITY.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/SECURITY.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/SECURITY.md) + +--- + +## 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 | +| ------- | -------------- | +| 3.4.x | โœ… Active | +| 3.0.x | โœ… Security | +| < 3.0.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 | +| **MCP Scopes** | 10 granular scopes for MCP tool access control | + +### ๐Ÿ›ก๏ธ 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:::` +- 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** | Allowlist/blocklist IP ranges in dashboard | +| **Rate Limiting** | Per-provider rate limits with automatic backoff | +| **Anti-Thundering Herd** | Mutex + per-connection locking prevents cascading 502s | +| **TLS Fingerprint** | Browser-like TLS fingerprint spoofing to reduce bot detection | +| **CLI Fingerprint** | Per-provider header/body ordering to match native CLI signatures | + +### ๐Ÿ”Œ Resilience & Availability + +| 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 `CALL_LOG_RETENTION_DAYS` | +| **No-Log Opt-out** | Per API key `noLog` flag disables request logging | +| **Audit Log** | Administrative actions tracked in `audit_log` table | +| **MCP Audit** | SQLite-backed audit logging for all MCP tool calls | +| **Zod Validation** | All API inputs validated with Zod v4 schemas at module load | + +--- + +## 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 +- Provider constants validated at module load via Zod (`src/shared/validation/providerSchema.ts`) diff --git a/docs/i18n/pt/TROUBLESHOOTING.md b/docs/i18n/pt/TROUBLESHOOTING.md deleted file mode 100644 index 63c148000a..0000000000 --- a/docs/i18n/pt/TROUBLESHOOTING.md +++ /dev/null @@ -1,258 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/TROUBLESHOOTING.md) - ---- - -# Troubleshooting - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/TROUBLESHOOTING.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/TROUBLESHOOTING.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/TROUBLESHOOTING.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/TROUBLESHOOTING.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/TROUBLESHOOTING.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/TROUBLESHOOTING.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/TROUBLESHOOTING.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/TROUBLESHOOTING.md) - -Common problems and solutions for OmniRoute. - ---- - -## Quick Fixes - -| Problem | Solution | -| ----------------------------- | ------------------------------------------------------------------ | -| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | -| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | -| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | -| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | -| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | - ---- - -## Provider Issues - -### "Language model did not provide messages" - -**Cause:** Provider quota exhausted. - -**Fix:** - -1. 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, Qoder) 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}/storage.sqlite` (providers, combos, aliases, keys, settings) -- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` -- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) - ---- - -## Circuit Breaker Issues - -### Provider stuck in OPEN state - -When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. - -**Fix:** - -1. 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 -- **SDK returns raw string instead of object** โ€” Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures -- **GLM/ERNIE rejects `system` role** โ€” Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models -- **`developer` role not recognized** โ€” Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers -- **`json_schema` not working with Gemini** โ€” Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` - ---- - -## Resilience Settings - -### Auto rate-limit not triggering - -- 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. - ---- - -## Optional RAG / LLM failure taxonomy (16 problems) - -Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. - -In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. - -If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: - -- retrieval drift and broken context boundaries -- empty or stale indexes and vector stores -- embedding versus semantic mismatch -- prompt assembly and context window issues -- logic collapse and overconfident answers -- long chain and agent coordination failures -- multi agent memory and role drift -- deployment and bootstrap ordering problems - -The idea is simple: - -1. When you investigate a bad response, capture: - - user task and request - - route or provider combo in OmniRoute - - any RAG context used downstream (retrieved documents, tool calls, etc) -2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` โ€ฆ `No.16`). -3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. -4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. - -Full text and concrete recipes live here (MIT license, text only): - -[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) - -You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. - ---- - -## Still Stuck? - -- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details -- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints -- **Health Dashboard**: Check **Dashboard โ†’ Health** for real-time system status -- **Translator**: Use **Dashboard โ†’ Translator** to debug format issues diff --git a/docs/i18n/pt/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/pt/VM_DEPLOYMENT_GUIDE.md deleted file mode 100644 index 56e39fa56e..0000000000 --- a/docs/i18n/pt/VM_DEPLOYMENT_GUIDE.md +++ /dev/null @@ -1,401 +0,0 @@ -# OmniRoute โ€” Guia de implantaรงรฃo em VM com Cloudflare - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](../pt-BR/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](../es/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](../fr/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](../it/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](../ru/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](../zh-CN/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](../de/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](../in/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](../th/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](../uk-UA/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](../ar/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](../ja/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](../vi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](../bg/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](../da/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](../fi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](../he/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](../hu/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](../id/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](../ko/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](../ms/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](../nl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](../no/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](../pt/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](../ro/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](../pl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](../sk/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](../sv/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](../phi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](../cs/VM_DEPLOYMENT_GUIDE.md) - -Guia completo para instalar e configurar OmniRoute em uma VM (VPS) com domรญnio gerenciado via Cloudflare. - ---- - -## Prรฉ-requisitos - -| Artigo | Mรญnimo | Recomendado | -| ----------- | ------------------------ | --------------- | -| **CPU** | 1 vCPU | 2 vCPUs | -| **RAM** | 1 GB | 2 GB | -| **Disco** | SSD de 10 GB | SSD de 25 GB | -| **SO** | Ubuntu 22.04LTS | Ubuntu 24.04LTS | -| **Domรญnio** | Registrado na Cloudflare | โ€” | -| **Docker** | Motor Docker 24+ | Docker 27+ | - -**Provedores testados**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. - ---- - -## 1. Configure a VM - -### 1.1 Crie a instรขncia - -No seu provedor VPS preferido: - -- Escolha Ubuntu 24.04 LTS -- Selecione o plano mรญnimo (1 vCPU / 1 GB RAM) -- Defina uma senha root forte ou configure a chave SSH -- Observe o **IP pรบblico** (por exemplo, `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 o Docker - -```bash -# Install dependencies -apt install -y ca-certificates curl gnupg - -# Add official Docker repository -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 Instale o 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 aos IPs da Cloudflare. Consulte a seรงรฃo [Advanced Security](#advanced-security). - ---- - -## 2. Instale 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โ€™ -# === Security === -JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY -INITIAL_PASSWORD=YourSecurePassword123! -API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY -STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY -STORAGE_ENCRYPTION_KEY_VERSION=v1 -MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT - -# === 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 (change to your domain) === -BASE_URL=https://llms.seudominio.com -NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com - -# === Cloud Sync (optional) === -# CLOUD_URL=https://cloud.omniroute.online -# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online -EOF -``` - -> โš ๏ธ **IMPORTANTE**: Gere chaves secretas exclusivas! Use `openssl rand -hex 32` para cada chave. - -### 2.3 Inicie o contรชiner - -```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 Verifique se estรก em execuรงรฃo - -```bash -docker ps | grep omniroute -docker logs omniroute --tail 20 -``` - -Deve exibir: `[DB] SQLite database ready` e `listening on port 20128`. - ---- - -## 3. Configurar nginx (proxy reverso) - -### 3.1 Gerar certificado SSL (Origem Cloudflare) - -No painel da Cloudflare: - -1. Vรก para **SSL/TLS โ†’ Servidor de Origem** -2. Clique em **Criar certificado** -3. Mantenha os padrรตes (15 anos, \*.seudominio.com) -4. Copie o **Certificado de Origem** e a **Chave Privada** - -```bash -mkdir -p /etc/nginx/ssl - -# Paste the certificate -nano /etc/nginx/ssl/origin.crt - -# Paste the private key -nano /etc/nginx/ssl/origin.key - -chmod 600 /etc/nginx/ssl/origin.key -``` - -### 3.2 Configuraรงรฃo Nginx - -```bash -cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ -# Default server โ€” blocks direct access via 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.yourdomain.com; # Change to your domain - - 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.yourdomain.com; - return 301 https://$server_name$request_uri; -} -NGINX -``` - -### 3.3 Habilitar e testar - -```bash -# Remove default configuration -rm -f /etc/nginx/sites-enabled/default - -# Enable OmniRoute -ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute - -# Test and reload -nginx -t && systemctl reload nginx -``` - ---- - -## 4. Configurar DNS da Cloudflare - -### 4.1 Adicionar registro DNS - -No painel Cloudflare โ†’ DNS: - -| Tipo | Nome | Conteรบdo | Procuraรงรฃo | -| ---- | ------ | ------------------------- | ------------ | -| Um | `llms` | `203.0.113.10` (IP da VM) | โœ… Procurado | - -### 4.2 Configurar SSL - -Em **SSL/TLS โ†’ Visรฃo geral**: - -- Modo: **Completo (estrito)** - -Em **SSL/TLS โ†’ Certificados Edge**: - -- Sempre use HTTPS: โœ… Ligado -- Versรฃo mรญnima do TLS: TLS 1.2 -- Reescritas automรกticas de HTTPS: โœ… Ativado - -### 4.3 Teste - -```bash -curl -sI https://llms.seudominio.com/health -# Should return HTTP/2 200 -``` - ---- - -## 5. Operaรงรตes e Manutenรงรฃo - -### Atualize para uma 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 registros - -```bash -docker logs -f omniroute # Real-time stream -docker logs omniroute --tail 50 # Last 50 lines -``` - -### Backup manual do banco de dados - -```bash -# Copy data from the volume to the host -docker cp omniroute:/app/data ./backup-$(date +%F) - -# Or compress the entire volume -docker run --rm -v omniroute-data:/data -v $(pwd):/backup \ - alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data -``` - -### Restaurar do 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 o nginx aos IPs da Cloudflare - -```bash -cat > /etc/nginx/cloudflare-ips.conf << โ€˜CFโ€™ -# Cloudflare IPv4 ranges โ€” update periodically -# 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 -``` - -Adicione o seguinte a `nginx.conf` dentro do bloco `http {}`: - -```nginx -include /etc/nginx/cloudflare-ips.conf; -``` - -### Instale o fail2ban - -```bash -apt install -y fail2ban -systemctl enable fail2ban -systemctl start fail2ban - -# Check status -fail2ban-client status sshd -``` - -### Bloqueie o acesso direto ร  porta Docker - -```bash -# Prevent direct external access to port 20128 -iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP -iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT - -# Persist the rules -apt install -y iptables-persistent -netfilter-persistent save -``` - ---- - -## 7. Implantar em Cloudflare Workers (opcional) - -Para acesso remoto via Cloudflare Workers (sem expor a VM diretamente): - -```bash -# In the local repository -cd omnirouteCloud -npm install -npx wrangler login -npx wrangler deploy -``` - -Veja a documentaรงรฃo completa em [omnirouteCloud/README.md](../omnirouteCloud/README.md). - ---- - -## Resumo da porta - -| Porto | Serviรงo | Acesso | -| ----- | ----------- | ---------------------------- | -| 22 | SSH | Pรบblico (com fail2ban) | -| 80 | HTTP nginx | Redirecionar โ†’ HTTPS | -| 443 | HTTPS nginx | Atravรฉs do proxy Cloudflare | -| 20128 | OmniRoute | Apenas localhost (via nginx) | diff --git a/docs/i18n/pt/docs/A2A-SERVER.md b/docs/i18n/pt/docs/A2A-SERVER.md new file mode 100644 index 0000000000..4273196ad9 --- /dev/null +++ b/docs/i18n/pt/docs/A2A-SERVER.md @@ -0,0 +1,200 @@ +# OmniRoute A2A Server Documentation (Portuguรชs (Portugal)) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/A2A-SERVER.md) + +--- + +> Agent-to-Agent Protocol v0.3 โ€” OmniRoute as an intelligent routing agent + +## Agent Discovery + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements. + +--- + +## Authentication + +All `/a2a` requests require an API key via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server, authentication is bypassed. + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Sends a message to a skill and waits for the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a hello world in Python"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "uuid", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "..." }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}} + +: heartbeat 2026-03-03T17:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Available Skills + +| Skill | Description | +| :----------------- | :------------------------------------------------------------------------------------------------------------------------------ | +| `smart-routing` | Routes prompts through OmniRoute's intelligent pipeline. Returns response with routing explanation, cost, and resilience trace. | +| `quota-management` | Answers natural-language queries about provider quotas, suggests free combos, and provides quota rankings. | + +--- + +## Task Lifecycle + +``` +submitted โ†’ working โ†’ completed + โ†’ failed + โ†’ cancelled +``` + +- Tasks expire after 5 minutes (configurable) +- Terminal states: `completed`, `failed`, `cancelled` +- Event log tracks every state transition + +--- + +## Error Codes + +| Code | Meaning | +| :----- | :----------------------------- | +| -32700 | Parse error (invalid JSON) | +| -32600 | Invalid request / Unauthorized | +| -32601 | Method or skill not found | +| -32602 | Invalid params | +| -32603 | Internal error | + +--- + +## Integration Examples + +### Python (requests) + +```python +import requests + +resp = requests.post("http://localhost:20128/a2a", json={ + "jsonrpc": "2.0", "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Hello"}] + } +}, headers={"Authorization": "Bearer YOUR_KEY"}) + +result = resp.json()["result"] +print(result["artifacts"][0]["content"]) +print(result["metadata"]["routing_explanation"]) +``` + +### TypeScript (fetch) + +```typescript +const resp = await fetch("http://localhost:20128/a2a", { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: "Bearer YOUR_KEY", + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "1", + method: "message/send", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Hello" }], + }, + }), +}); +const { result } = await resp.json(); +console.log(result.metadata.routing_explanation); +``` diff --git a/docs/i18n/pt/docs/API_REFERENCE.md b/docs/i18n/pt/docs/API_REFERENCE.md new file mode 100644 index 0000000000..8bc6145fde --- /dev/null +++ b/docs/i18n/pt/docs/API_REFERENCE.md @@ -0,0 +1,465 @@ +# API Reference (Portuguรชs (Portugal)) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/API_REFERENCE.md) + +--- + +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 | +| `X-Session-Id` | Request | Sticky session key for external session affinity | +| `x_session_id` | Request | Underscore variant also accepted (direct HTTP) | +| `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 | +| `X-OmniRoute-Session-Id` | Response | Effective session ID used by OmniRoute | + +> Nginx note: if you rely on underscore headers (for example `x_session_id`), enable `underscores_in_headers 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/stats + +# Clear all caches +DELETE /api/cache/stats +``` + +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/PATCH | 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 + provider summary (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`) | +| `/api/cache/stats` | 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 | + +### Tunnels + +| Endpoint | Method | Description | +| -------------------------- | ------ | ----------------------------------------------------------------------- | +| `/api/tunnels/cloudflared` | GET | Read Cloudflare Quick Tunnel install/runtime status for the dashboard | +| `/api/tunnels/cloudflared` | POST | Enable or disable the Cloudflare Quick Tunnel (`action=enable/disable`) | + +### 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`. + +### ACP Agents + +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | + +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). + +### Resilience & Rate Limits + +| Endpoint | Method | Description | +| ----------------------- | --------- | ------------------------------- | +| `/api/resilience` | GET/PATCH | 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` diff --git a/docs/i18n/pt/docs/ARCHITECTURE.md b/docs/i18n/pt/docs/ARCHITECTURE.md new file mode 100644 index 0000000000..92ceab33fa --- /dev/null +++ b/docs/i18n/pt/docs/ARCHITECTURE.md @@ -0,0 +1,814 @@ +# OmniRoute Architecture (Portuguรชs (Portugal)) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/ARCHITECTURE.md) + +--- + +_Last updated: 2026-03-28_ + +## 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 (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developerโ†’system, systemโ†’user) for cross-provider compatibility +- Structured output conversion (json_schema โ†’ Gemini responseSchema) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) +- Global system prompt injection +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout โ†’ budget โ†’ fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) + +Primary runtime model: + +- Next.js 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.) + +## Dashboard Surface (Current) + +Main pages under `src/app/(dashboard)/dashboard/`: + +- `/dashboard` โ€” quick start + provider overview +- `/dashboard/endpoint` โ€” endpoint proxy + MCP + A2A + API endpoint tabs +- `/dashboard/providers` โ€” provider connections and credentials +- `/dashboard/combos` โ€” combo strategies, templates, model routing rules +- `/dashboard/costs` โ€” cost aggregation and pricing visibility +- `/dashboard/analytics` โ€” usage analytics and evaluations +- `/dashboard/limits` โ€” quota/rate controls +- `/dashboard/cli-tools` โ€” CLI onboarding, runtime detection, config generation +- `/dashboard/agents` โ€” detected ACP agents + custom agent registration +- `/dashboard/media` โ€” image/video/music playground +- `/dashboard/search-tools` โ€” search provider testing and history +- `/dashboard/health` โ€” uptime, circuit breakers, rate limits +- `/dashboard/logs` โ€” request/proxy/audit/console logs +- `/dashboard/settings` โ€” system settings tabs (general, routing, combo defaults, etc.) +- `/dashboard/api-manager` โ€” API key lifecycle and model permissions + +## 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[(storage.sqlite)] + UDB[(usage tables + log artifacts)] + end + + subgraph Upstreams[Upstream Providers] + P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/Qoder/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/route.ts` (GET) +- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- OAuth: `src/app/api/oauth/*` +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` +- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI tooling helpers: `src/app/api/cli-tools/*` +- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) +- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) โ€” provider profiles, circuit breaker, rate limit state +- Resilience reset: `src/app/api/resilience/reset` (POST) โ€” reset breakers + cooldowns +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) +- Telemetry: `src/app/api/telemetry/summary` (GET) +- Budget: `src/app/api/usage/budget` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Policies: `src/app/api/policies` (GET/POST) + +## 2) SSE + 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` +- Response sanitization: `open-sse/handlers/responseSanitizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.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`, `qoder.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 (SQLite): + +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** + +Usage persistence: + +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present + +Domain State DB (SQLite): + +- `src/lib/db/domainState.ts` โ€” CRUD operations 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`, `src/shared/services/modelSyncScheduler.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Periodic task: `src/shared/services/modelSyncScheduler.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. Combo routing adds one extra guard: provider-scoped 400s such as upstream content-block and role-validation failures are treated as model-local failures so later combo targets can still run. + +## 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: + +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` + +## Deployment Topology + +```mermaid +flowchart LR + 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[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] + end + + subgraph External[External Services] + Providers[AI Providers] + SyncCloud[Cloud Sync Service] + end + + CLI --> Next + Browser --> Next + Next --> Core + Next --> MainDB + Core --> MainDB + Core --> UsageDB + Core --> Providers + Next --> SyncCloud +``` + +## Module Mapping (Decision-Critical) + +### Route and API Modules + +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle +- `src/app/api/models/alias`: alias management +- `src/app/api/combos*`: fallback combo management +- `src/app/api/pricing`: pricing overrides for cost calculation +- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers +- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) +- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) +- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) +- `src/app/api/sessions`: active session listing (GET) +- `src/app/api/rate-limits`: per-account rate limit status (GET) + +### Routing and Execution Core + +- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior + +### Translation Registry and Format Converters + +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` +- Format constants: `open-sse/translator/formats.ts` + +### Persistence + +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables + +## Provider Executor Coverage (Strategy Pattern) + +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. + +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, Qoder, 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 | +| Qoder | openai | OAuth (Basic) | โœ… | โœ… | โœ… | โš ๏ธ Per request | +| OpenRouter | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| GLM/Kimi/MiniMax | claude | API Key | โœ… | โœ… | โŒ | โŒ | +| DeepSeek | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Groq | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| xAI (Grok) | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Mistral | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Perplexity | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Together AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Fireworks AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Cerebras | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Cohere | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| NVIDIA NIM | openai | API Key | โœ… | โœ… | โŒ | โŒ | + +## Format Translation Coverage + +Detected source formats include: + +- `openai` +- `openai-responses` +- `claude` +- `gemini` + +Target formats include: + +- OpenAI chat/Responses +- Claude +- Gemini/Gemini-CLI/Antigravity envelope +- Kiro +- Cursor + +Translations use **OpenAI as the hub format** โ€” all conversions go through OpenAI as intermediate: + +``` +Source Format โ†’ OpenAI (hub) โ†’ Target Format +``` + +Translations are selected dynamically based on source payload shape and provider target format. + +Additional processing layers in the translation pipeline: + +- **Response sanitization** โ€” Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI targets; merges `system` โ†’ `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** โ€” Parses `...` blocks from content into `reasoning_content` field +- **Structured output** โ€” Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` + +## Supported API Endpoints + +| 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` | Provider Models | Provider model metadata backing custom and managed available models | + +## 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 `/logs//` 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 + +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON โ†’ SQLite migration compatibility path + +## Observability and Operational Signals + +Runtime visibility sources: + +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- four-stage detailed payload captures in SQLite (`request_detail_logs`) when `settings.detailed_logs_enabled=true` +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption + +Detailed request payload capture stores up to four JSON payload stages per routed call: + +- raw request received from the client +- translated request actually sent upstream +- provider response reconstructed as JSON; streamed responses are compacted to the final summary plus stream metadata +- final client response returned by OmniRoute; streamed responses are stored in the same compact summary form + +## Security-Sensitive Boundaries + +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics + +## Environment and Runtime Matrix + +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` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). + +## Operational Verification Checklist + +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: +- `GET /api/settings` +- `GET /api/v1/models` +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/pt/docs/AUTO-COMBO.md b/docs/i18n/pt/docs/AUTO-COMBO.md new file mode 100644 index 0000000000..0cd7db22dd --- /dev/null +++ b/docs/i18n/pt/docs/AUTO-COMBO.md @@ -0,0 +1,67 @@ +# OmniRoute Auto-Combo Engine (Portuguรชs (Portugal)) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/AUTO-COMBO.md) + +--- + +> Self-managing model chains with adaptive scoring + +## How It Works + +The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**: + +| Factor | Weight | Description | +| :--------- | :----- | :---------------------------------------------- | +| Quota | 0.20 | Remaining capacity [0..1] | +| Health | 0.25 | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 | +| CostInv | 0.20 | Inverse cost (cheaper = higher score) | +| LatencyInv | 0.15 | Inverse p95 latency (faster = higher) | +| TaskFit | 0.10 | Model ร— task type fitness score | +| Stability | 0.10 | Low variance in latency/errors | + +## Mode Packs + +| Pack | Focus | Key Weight | +| :---------------------- | :----------- | :--------------- | +| ๐Ÿš€ **Ship Fast** | Speed | latencyInv: 0.35 | +| ๐Ÿ’ฐ **Cost Saver** | Economy | costInv: 0.40 | +| ๐ŸŽฏ **Quality First** | Best model | taskFit: 0.40 | +| ๐Ÿ“ก **Offline Friendly** | Availability | quota: 0.40 | + +## Self-Healing + +- **Temporary exclusion**: Score < 0.2 โ†’ excluded for 5 min (progressive backoff, max 30 min) +- **Circuit breaker awareness**: OPEN โ†’ auto-excluded; HALF_OPEN โ†’ probe requests +- **Incident mode**: >50% OPEN โ†’ disable exploration, maximize stability +- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout + +## Bandit Exploration + +5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode. + +## API + +```bash +# Create auto-combo +curl -X POST http://localhost:20128/api/combos/auto \ + -H "Content-Type: application/json" \ + -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}' + +# List auto-combos +curl http://localhost:20128/api/combos/auto +``` + +## Task Fitness + +30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` โ†’ high coding score). + +## Files + +| File | Purpose | +| :------------------------------------------- | :------------------------------------ | +| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization | +| `open-sse/services/autoCombo/taskFitness.ts` | Model ร— task fitness lookup | +| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap | +| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode | +| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles | +| `src/app/api/combos/auto/route.ts` | REST API | diff --git a/docs/i18n/pt/docs/CLI-TOOLS.md b/docs/i18n/pt/docs/CLI-TOOLS.md new file mode 100644 index 0000000000..bf6ef86b9d --- /dev/null +++ b/docs/i18n/pt/docs/CLI-TOOLS.md @@ -0,0 +1,348 @@ +# CLI Tools Setup Guide โ€” OmniRoute (Portuguรชs (Portugal)) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CLI-TOOLS.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CLI-TOOLS.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CLI-TOOLS.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CLI-TOOLS.md) + +--- + +This guide explains how to install and configure all supported AI coding CLI tools +to use **OmniRoute** as the unified backend, giving you centralized key management, +cost tracking, model switching, and request logging across every tool. + +--- + +## How It Works + +``` +Claude / Codex / OpenCode / Cline / KiloCode / Continue / Kiro / Cursor / Copilot + โ”‚ + โ–ผ (all point to OmniRoute) + http://YOUR_SERVER:20128/v1 + โ”‚ + โ–ผ (OmniRoute routes to the right provider) + Anthropic / OpenAI / Gemini / DeepSeek / Groq / Mistral / ... +``` + +**Benefits:** + +- One API key to manage all tools +- Cost tracking across all CLIs in the dashboard +- Model switching without reconfiguring every tool +- Works locally and on remote servers (VPS) + +--- + +## Supported Tools (Dashboard Source of Truth) + +The dashboard cards in `/dashboard/cli-tools` are generated from `src/shared/constants/cliTools.ts`. +Current list (v3.0.0-rc.16): + +| Tool | ID | Command | Setup Mode | Install Method | +| ------------------ | ------------- | ---------- | ---------- | -------------- | +| **Claude Code** | `claude` | `claude` | env | npm | +| **OpenAI Codex** | `codex` | `codex` | custom | npm | +| **Factory Droid** | `droid` | `droid` | custom | bundled/CLI | +| **OpenClaw** | `openclaw` | `openclaw` | custom | bundled/CLI | +| **Cursor** | `cursor` | app | guide | desktop app | +| **Cline** | `cline` | `cline` | custom | npm | +| **Kilo Code** | `kilo` | `kilocode` | custom | npm | +| **Continue** | `continue` | extension | guide | VS Code | +| **Antigravity** | `antigravity` | internal | mitm | OmniRoute | +| **GitHub Copilot** | `copilot` | extension | custom | VS Code | +| **OpenCode** | `opencode` | `opencode` | guide | npm | +| **Kiro AI** | `kiro` | app/cli | mitm | desktop/CLI | + +### CLI fingerprint sync (Agents + Settings) + +`/dashboard/agents` and `Settings > CLI Fingerprint` use `src/shared/constants/cliCompatProviders.ts`. +This keeps provider IDs aligned with CLI cards and legacy IDs. + +| CLI ID | Fingerprint Provider ID | +| ---------------------------------------------------------------------------------------------------- | ----------------------- | +| `kilo` | `kilocode` | +| `copilot` | `github` | +| `claude` / `codex` / `antigravity` / `kiro` / `cursor` / `cline` / `opencode` / `droid` / `openclaw` | same ID | + +Legacy IDs still accepted for compatibility: `copilot`, `kimi-coding`, `qwen`. + +--- + +## Step 1 โ€” Get an OmniRoute API Key + +1. Open the OmniRoute dashboard โ†’ **API Manager** (`/dashboard/api-manager`) +2. Click **Create API Key** +3. Give it a name (e.g. `cli-tools`) and select all permissions +4. Copy the key โ€” you'll need it for every CLI below + +> Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` + +--- + +## Step 2 โ€” Install CLI Tools + +All npm-based tools require Node.js 18+: + +```bash +# Claude Code (Anthropic) +npm install -g @anthropic-ai/claude-code + +# OpenAI Codex +npm install -g @openai/codex + +# OpenCode +npm install -g opencode-ai + +# Cline +npm install -g cline + +# KiloCode +npm install -g kilocode + +# Kiro CLI (Amazon โ€” requires curl + unzip) +apt-get install -y unzip # on Debian/Ubuntu +curl -fsSL https://cli.kiro.dev/install | bash +export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc +``` + +**Verify:** + +```bash +claude --version # 2.x.x +codex --version # 0.x.x +opencode --version # x.x.x +cline --version # 2.x.x +kilocode --version # x.x.x (or: kilo --version) +kiro-cli --version # 1.x.x +``` + +--- + +## Step 3 โ€” Set Global Environment Variables + +Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`: + +```bash +# OmniRoute Universal Endpoint +export OPENAI_BASE_URL="http://localhost:20128/v1" +export OPENAI_API_KEY="sk-your-omniroute-key" +export ANTHROPIC_BASE_URL="http://localhost:20128/v1" +export ANTHROPIC_API_KEY="sk-your-omniroute-key" +export GEMINI_BASE_URL="http://localhost:20128/v1" +export GEMINI_API_KEY="sk-your-omniroute-key" +``` + +> For a **remote server** replace `localhost:20128` with the server IP or domain, +> e.g. `http://192.168.0.15:20128`. + +--- + +## Step 4 โ€” Configure Each Tool + +### Claude Code + +```bash +# Via CLI: +claude config set --global api-base-url http://localhost:20128/v1 + +# Or create ~/.claude/settings.json: +mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF +{ + "apiBaseUrl": "http://localhost:20128/v1", + "apiKey": "sk-your-omniroute-key" +} +EOF +``` + +**Test:** `claude "say hello"` + +--- + +### OpenAI Codex + +```bash +mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF +model: auto +apiKey: sk-your-omniroute-key +apiBaseUrl: http://localhost:20128/v1 +EOF +``` + +**Test:** `codex "what is 2+2?"` + +--- + +### OpenCode + +```bash +mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF +[provider.openai] +base_url = "http://localhost:20128/v1" +api_key = "sk-your-omniroute-key" +EOF +``` + +**Test:** `opencode` + +--- + +### Cline (CLI or VS Code) + +**CLI mode:** + +```bash +mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF +{ + "apiProvider": "openai", + "openAiBaseUrl": "http://localhost:20128/v1", + "openAiApiKey": "sk-your-omniroute-key" +} +EOF +``` + +**VS Code mode:** +Cline extension settings โ†’ API Provider: `OpenAI Compatible` โ†’ Base URL: `http://localhost:20128/v1` + +Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ Cline โ†’ Apply Config**. + +--- + +### KiloCode (CLI or VS Code) + +**CLI mode:** + +```bash +kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key +``` + +**VS Code settings:** + +```json +{ + "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", + "kilo-code.apiKey": "sk-your-omniroute-key" +} +``` + +Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ KiloCode โ†’ Apply Config**. + +--- + +### Continue (VS Code Extension) + +Edit `~/.continue/config.yaml`: + +```yaml +models: + - name: OmniRoute + provider: openai + model: auto + apiBase: http://localhost:20128/v1 + apiKey: sk-your-omniroute-key + default: true +``` + +Restart VS Code after editing. + +--- + +### Kiro CLI (Amazon) + +```bash +# Login to your AWS/Kiro account: +kiro-cli login + +# The CLI uses its own auth โ€” OmniRoute is not needed as backend for Kiro CLI itself. +# Use kiro-cli alongside OmniRoute for other tools. +kiro-cli status +``` + +--- + +### Cursor (Desktop App) + +> **Note:** Cursor routes requests through its cloud. For OmniRoute integration, +> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL. + +Via GUI: **Settings โ†’ Models โ†’ OpenAI API Key** + +- Base URL: `https://your-domain.com/v1` +- API Key: your OmniRoute key + +--- + +## Dashboard Auto-Configuration + +The OmniRoute dashboard automates configuration for most tools: + +1. Go to `http://localhost:20128/dashboard/cli-tools` +2. Expand any tool card +3. Select your API key from the dropdown +4. Click **Apply Config** (if tool is detected as installed) +5. Or copy the generated config snippet manually + +--- + +## Built-in Agents: Droid & OpenClaw + +**Droid** and **OpenClaw** are AI agents built directly into OmniRoute โ€” no installation needed. +They run as internal routes and use OmniRoute's model routing automatically. + +- Access: `http://localhost:20128/dashboard/agents` +- Configure: same combos and providers as all other tools +- No API key or CLI install required + +--- + +## Available API Endpoints + +| Endpoint | Description | Use For | +| -------------------------- | ----------------------------- | --------------------------- | +| `/v1/chat/completions` | Standard chat (all providers) | All modern tools | +| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows | +| `/v1/completions` | Legacy text completions | Older tools using `prompt:` | +| `/v1/embeddings` | Text embeddings | RAG, search | +| `/v1/images/generations` | Image generation | DALL-E, Flux, etc. | +| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS | +| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI | + +--- + +## Resoluรงรฃo de Problemas + +| Error | Cause | Fix | +| ------------------------- | ----------------------- | ------------------------------------------ | +| `Connection refused` | OmniRoute not running | `pm2 start omniroute` | +| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` | +| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` | +| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` | +| CLI shows "not installed" | Binary not in PATH | Check `which ` | +| `kiro-cli: not found` | Not in PATH | `export PATH="$HOME/.local/bin:$PATH"` | + +--- + +## Quick Setup Script (One Command) + +```bash +# Install all CLIs and configure for OmniRoute (replace with your key and server URL) +OMNIROUTE_URL="http://localhost:20128/v1" +OMNIROUTE_KEY="sk-your-omniroute-key" + +npm install -g @anthropic-ai/claude-code @openai/codex opencode-ai cline kilocode + +# Kiro CLI +apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash + +# Write configs +mkdir -p ~/.claude ~/.codex ~/.config/opencode ~/.continue + +cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" +cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" +cat >> ~/.bashrc << EOF +export OPENAI_BASE_URL="$OMNIROUTE_URL" +export OPENAI_API_KEY="$OMNIROUTE_KEY" +export ANTHROPIC_BASE_URL="$OMNIROUTE_URL" +export ANTHROPIC_API_KEY="$OMNIROUTE_KEY" +EOF + +source ~/.bashrc +echo "โœ… All CLIs installed and configured for OmniRoute" +``` diff --git a/docs/i18n/pt/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/pt/docs/CODEBASE_DOCUMENTATION.md new file mode 100644 index 0000000000..486e6311cc --- /dev/null +++ b/docs/i18n/pt/docs/CODEBASE_DOCUMENTATION.md @@ -0,0 +1,591 @@ +# omniroute โ€” Codebase Documentation (Portuguรชs (Portugal)) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CODEBASE_DOCUMENTATION.md) + +--- + +> 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
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, Qoder, 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. + +#### Arquitetura + +```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 | +| Qoder | 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"] +``` diff --git a/docs/i18n/pt/docs/COVERAGE_PLAN.md b/docs/i18n/pt/docs/COVERAGE_PLAN.md new file mode 100644 index 0000000000..8024b7e664 --- /dev/null +++ b/docs/i18n/pt/docs/COVERAGE_PLAN.md @@ -0,0 +1,170 @@ +# Test Coverage Plan (Portuguรชs (Portugal)) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/COVERAGE_PLAN.md) + +--- + +Last updated: 2026-03-28 + +## Baseline + +There are multiple coverage numbers depending on how the report is computed. For planning, only one of them is useful. + +| Metric | Scope | Statements / Lines | Branches | Functions | Notes | +| -------------------- | ----------------------------------------------------- | -----------------: | -------: | --------: | --------------------------------------------------- | +| Legacy | Old `npm run test:coverage` | 79.42% | 75.15% | 67.94% | Inflated: counts test files and excludes `open-sse` | +| Diagnostic | Source-only, excluding tests and excluding `open-sse` | 68.16% | 63.55% | 64.06% | Useful only to isolate `src/**` | +| Recommended baseline | Source-only, excluding tests and including `open-sse` | 56.95% | 66.05% | 57.80% | This is the project-wide baseline to improve | + +The recommended baseline is the number to optimize against. + +## Rules + +- Coverage targets apply to source files, not to `tests/**`. +- `open-sse/**` is part of the product and must remain in scope. +- New code should not reduce coverage in touched areas. +- Prefer testing behavior and branch outcomes over implementation details. +- Prefer temp SQLite databases and small fixtures over broad mocks for `src/lib/db/**`. + +## Current command set + +- `npm run test:coverage` + - Main source coverage gate for the unit test suite + - Generates `text-summary`, `html`, `json-summary`, and `lcov` +- `npm run coverage:report` + - Detailed file-by-file report from the latest run +- `npm run test:coverage:legacy` + - Historical comparison only + +## Milestones + +| Phase | Target | Focus | +| ------- | ---------------------: | ------------------------------------------------- | +| Phase 1 | 60% statements / lines | Quick wins and low-risk utility coverage | +| Phase 2 | 65% statements / lines | DB and route foundations | +| Phase 3 | 70% statements / lines | Provider validation and usage analytics | +| Phase 4 | 75% statements / lines | `open-sse` translators and helpers | +| Phase 5 | 80% statements / lines | `open-sse` handlers and executor branches | +| Phase 6 | 85% statements / lines | Harder edge cases, branch debt, regression suites | +| Phase 7 | 90% statements / lines | Final sweep, gap closure, strict ratchet | + +Branches and functions should ratchet upward with each phase, but the primary hard target is statements / lines. + +## Priority hotspots + +These files or areas offer the best return for the next phases: + +1. `open-sse/handlers` + - `chatCore.ts` at 7.57% + - Overall directory at 29.07% +2. `open-sse/translator/request` + - Overall directory at 36.39% + - Many translators are still near single-digit coverage +3. `open-sse/translator/response` + - Overall directory at 8.07% +4. `open-sse/executors` + - Overall directory at 36.62% +5. `src/lib/db` + - `models.ts` at 20.66% + - `registeredKeys.ts` at 34.46% + - `modelComboMappings.ts` at 36.25% + - `settings.ts` at 46.40% + - `webhooks.ts` at 33.33% +6. `src/lib/usage` + - `usageHistory.ts` at 21.12% + - `usageStats.ts` at 9.56% + - `costCalculator.ts` at 30.00% +7. `src/lib/providers` + - `validation.ts` at 41.16% +8. Low-risk utility and API files for early gains + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/api/errorResponse.ts` + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +## Execution checklist + +### Phase 1: 56.95% -> 60% + +- [x] Fix coverage metric so it reflects source code instead of test files +- [x] Keep a legacy coverage script for comparison +- [x] Record the baseline and hotspots in-repo +- [ ] Add focused tests for low-risk utilities: + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/fetchTimeout.ts` + - `src/lib/api/errorResponse.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/display/names.ts` +- [ ] Add route tests for: + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +### Phase 2: 60% -> 65% + +- [ ] Add DB-backed tests for: + - `src/lib/db/modelComboMappings.ts` + - `src/lib/db/settings.ts` + - `src/lib/db/registeredKeys.ts` +- [ ] Cover branch behavior in: + - `src/lib/providers/validation.ts` + - `src/app/api/v1/embeddings/route.ts` + - `src/app/api/v1/moderations/route.ts` + +### Phase 3: 65% -> 70% + +- [ ] Add usage analytics tests for: + - `src/lib/usage/usageHistory.ts` + - `src/lib/usage/usageStats.ts` + - `src/lib/usage/costCalculator.ts` +- [ ] Expand route coverage for proxy management and settings branches + +### Phase 4: 70% -> 75% + +- [ ] Cover translator helpers and central translation paths: + - `open-sse/translator/index.ts` + - `open-sse/translator/helpers/*` + - `open-sse/translator/request/*` + - `open-sse/translator/response/*` + +### Phase 5: 75% -> 80% + +- [ ] Add handler-level tests for: + - `open-sse/handlers/chatCore.ts` + - `open-sse/handlers/responsesHandler.js` + - `open-sse/handlers/imageGeneration.js` + - `open-sse/handlers/embeddings.js` +- [ ] Add executor branch coverage for provider-specific auth, retries, and endpoint overrides + +### Phase 6: 80% -> 85% + +- [ ] Merge more edge-case suites into the main coverage path +- [ ] Increase function coverage for DB modules with weak constructor/helper coverage +- [ ] Close branch gaps in `settings.ts`, `registeredKeys.ts`, `validation.ts`, and translator helpers + +### Phase 7: 85% -> 90% + +- [ ] Treat the remaining low-coverage files as blockers +- [ ] Add regression tests for every uncovered production bug fixed during the push to 90% +- [ ] Raise the coverage gate in CI only after the local baseline is stable for at least two consecutive runs + +## Ratchet policy + +Update `npm run test:coverage` thresholds only after the project actually exceeds the next milestone with a comfortable buffer. + +Recommended ratchet sequence: + +1. 55/60/55 +2. 60/62/58 +3. 65/64/62 +4. 70/66/66 +5. 75/70/72 +6. 80/75/78 +7. 85/80/84 +8. 90/85/88 + +Order is `statements-lines / branches / functions`. + +## Known gap + +The current coverage command measures the main Node unit suite and includes source reached from it, including `open-sse`. It does not yet merge Vitest coverage into a single unified report. That merge is worth doing later, but it is not a blocker for starting the 60% -> 80% climb. diff --git a/docs/i18n/pt/docs/FEATURES.md b/docs/i18n/pt/docs/FEATURES.md index 9c02a98122..b2ae84bf3c 100644 --- a/docs/i18n/pt/docs/FEATURES.md +++ b/docs/i18n/pt/docs/FEATURES.md @@ -1,6 +1,6 @@ # OmniRoute โ€” Dashboard Features Gallery (Portuguรชs (Portugal)) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/FEATURES.md) --- @@ -10,7 +10,7 @@ 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). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. ![Providers Dashboard](screenshots/01-providers.png) diff --git a/docs/i18n/pt/docs/MCP-SERVER.md b/docs/i18n/pt/docs/MCP-SERVER.md new file mode 100644 index 0000000000..534b548f3a --- /dev/null +++ b/docs/i18n/pt/docs/MCP-SERVER.md @@ -0,0 +1,87 @@ +# OmniRoute MCP Server Documentation (Portuguรชs (Portugal)) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/MCP-SERVER.md) + +--- + +> Model Context Protocol server with 16 intelligent tools + +## Instalar + +OmniRoute MCP is built-in. Start it with: + +```bash +omniroute --mcp +``` + +Or via the open-sse transport: + +```bash +# HTTP streamable transport (port 20130) +omniroute --dev # MCP auto-starts on /mcp endpoint +``` + +## IDE Configuration + +See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup. + +--- + +## Essential Tools (8) + +| Tool | Description | +| :------------------------------ | :--------------------------------------- | +| `omniroute_get_health` | Gateway health, circuit breakers, uptime | +| `omniroute_list_combos` | All configured combos with models | +| `omniroute_get_combo_metrics` | Performance metrics for a specific combo | +| `omniroute_switch_combo` | Switch active combo by ID/name | +| `omniroute_check_quota` | Quota status per provider or all | +| `omniroute_route_request` | Send a chat completion through OmniRoute | +| `omniroute_cost_report` | Cost analytics for a time period | +| `omniroute_list_models_catalog` | Full model catalog with capabilities | + +## Advanced Tools (8) + +| Tool | Description | +| :--------------------------------- | :---------------------------------------------------------- | +| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | +| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | +| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | +| `omniroute_test_combo` | Live-test all models in a combo via a real upstream request | +| `omniroute_get_provider_metrics` | Detailed metrics for one provider | +| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | +| `omniroute_explain_route` | Explain a past routing decision | +| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | + +## Authentication + +MCP tools are authenticated via API key scopes. Each tool requires specific scopes: + +| Scope | Tools | +| :------------- | :----------------------------------------------- | +| `read:health` | get_health, get_provider_metrics | +| `read:combos` | list_combos, get_combo_metrics | +| `write:combos` | switch_combo | +| `read:quota` | check_quota | +| `write:route` | route_request, simulate_route, test_combo | +| `read:usage` | cost_report, get_session_snapshot, explain_route | +| `write:config` | set_budget_guard, set_resilience_profile | +| `read:models` | list_models_catalog, best_combo_for_task | + +## Audit Logging + +Every tool call is logged to `mcp_tool_audit` with: + +- Tool name, arguments, result +- Duration (ms), success/failure +- API key hash, timestamp + +## Files + +| File | Purpose | +| :------------------------------------------- | :------------------------------------------ | +| `open-sse/mcp-server/server.ts` | MCP server creation + 16 tool registrations | +| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport | +| `open-sse/mcp-server/auth.ts` | API key + scope validation | +| `open-sse/mcp-server/audit.ts` | Tool call audit logging | +| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers | diff --git a/docs/i18n/pt/docs/RELEASE_CHECKLIST.md b/docs/i18n/pt/docs/RELEASE_CHECKLIST.md new file mode 100644 index 0000000000..d9259d46c1 --- /dev/null +++ b/docs/i18n/pt/docs/RELEASE_CHECKLIST.md @@ -0,0 +1,37 @@ +# Release Checklist (Portuguรชs (Portugal)) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/RELEASE_CHECKLIST.md) + +--- + +Use this checklist before tagging or publishing a new OmniRoute release. + +## Version and Changelog + +1. Bump `package.json` version (`x.y.z`) in the release branch. +2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: + - `## [x.y.z] โ€” YYYY-MM-DD` +3. Keep `## [Unreleased]` as the first changelog section for upcoming work. +4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. + +## API Docs + +1. Update `docs/openapi.yaml`: + - `info.version` must equal `package.json` version. +2. Validate endpoint examples if API contracts changed. + +## Runtime Docs + +1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. +2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. +3. Update localized docs if source docs changed significantly. + +## Automated Check + +Run the sync guard locally before opening PR: + +```bash +npm run check:docs-sync +``` + +CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/pt/docs/TROUBLESHOOTING.md b/docs/i18n/pt/docs/TROUBLESHOOTING.md new file mode 100644 index 0000000000..b4ebc54f42 --- /dev/null +++ b/docs/i18n/pt/docs/TROUBLESHOOTING.md @@ -0,0 +1,256 @@ +# Troubleshooting (Portuguรชs (Portugal)) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/TROUBLESHOOTING.md) + +--- + +Common problems and solutions for OmniRoute. + +--- + +## Quick Fixes + +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | + +--- + +## Provider Issues + +### "Language model did not provide messages" + +**Cause:** Provider quota exhausted. + +**Fix:** + +1. 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, Qoder) 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}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) + +--- + +## Circuit Breaker Issues + +### Provider stuck in OPEN state + +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. + +**Fix:** + +1. 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 +- **SDK returns raw string instead of object** โ€” Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** โ€” Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** โ€” Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** โ€” Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` + +--- + +## Resilience Settings + +### Auto rate-limit not triggering + +- 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. + +--- + +## Optional RAG / LLM failure taxonomy (16 problems) + +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` โ€ฆ `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard โ†’ Health** for real-time system status +- **Translator**: Use **Dashboard โ†’ Translator** to debug format issues diff --git a/docs/i18n/pt/USER_GUIDE.md b/docs/i18n/pt/docs/USER_GUIDE.md similarity index 82% rename from docs/i18n/pt/USER_GUIDE.md rename to docs/i18n/pt/docs/USER_GUIDE.md index de358c65f7..c89666932f 100644 --- a/docs/i18n/pt/USER_GUIDE.md +++ b/docs/i18n/pt/docs/USER_GUIDE.md @@ -1,8 +1,6 @@ # User Guide (Portuguรชs (Portugal)) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/USER_GUIDE.md) - -> ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/USER_GUIDE.md) --- @@ -320,7 +318,7 @@ Model: cc/claude-opus-4-6 --- -## ๐Ÿš€ Deployment +## Implantaรงรฃo ### Global npm install (Recommended) @@ -511,23 +509,26 @@ post_install() { ### Environment Variables -| Variable | Default | Description | -| ------------------------- | ------------------------------------ | ------------------------------------------------------- | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | -| `INITIAL_PASSWORD` | `123456` | First login password | -| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | -| `PORT` | framework default | Service port (`20128` in examples) | -| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | -| `NODE_ENV` | runtime default | Set `production` for deploy | -| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | -| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | -| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | -| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | -| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | -| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | -| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | -| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | +| 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/*` | +| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand | +| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | For the full environment variable reference, see the [README](../README.md). @@ -598,6 +599,11 @@ curl -X POST http://localhost:20128/api/provider-models \ Or use Dashboard: **Providers โ†’ [Provider] โ†’ Custom Models**. +Notes: + +- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers. +- The **Custom Models** section is intended for providers that do not expose managed available-model imports. + ### Dedicated Provider Routes Route requests directly to a specific provider with model validation: @@ -642,6 +648,14 @@ Returns models grouped by provider with types (`chat`, `embedding`, `image`). - Automatic background sync with timeout + fail-fast - Prefer server-side `BASE_URL`/`CLOUD_URL` in production +### Cloudflare Quick Tunnel + +- Available in **Dashboard โ†’ Endpoints** for Docker and other self-hosted deployments +- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint +- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary +- Tunnel URLs are ephemeral and change every time you stop/start the tunnel +- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download + ### LLM Gateway Intelligence (Phase 9) - **Semantic Cache** โ€” Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) @@ -757,11 +771,11 @@ OmniRoute implements provider-level resilience with four components: 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 | +| 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 unless `DISABLE_SQLITE_AUTO_BACKUP=true` | ```bash # API: Export database @@ -787,10 +801,11 @@ curl -X POST http://localhost:20128/api/db-backups/import \ ### Settings Dashboard -The settings page is organized into 5 tabs for easy navigation: +The settings page is organized into 6 tabs for easy navigation: | Tab | Contents | | -------------- | ---------------------------------------------------------------------------------------------- | +| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility | | **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | | **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | | **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | diff --git a/docs/i18n/pt/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/pt/docs/VM_DEPLOYMENT_GUIDE.md new file mode 100644 index 0000000000..e564d07540 --- /dev/null +++ b/docs/i18n/pt/docs/VM_DEPLOYMENT_GUIDE.md @@ -0,0 +1,403 @@ +# OmniRoute โ€” Deployment Guide on VM with Cloudflare (Portuguรชs (Portugal)) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/VM_DEPLOYMENT_GUIDE.md) + +--- + +Complete guide to install and configure OmniRoute on a VM (VPS) with domain managed via Cloudflare. + +--- + +## Prerequisites + +| Item | Minimum | Recommended | +| ---------- | ------------------------ | ---------------- | +| **CPU** | 1 vCPU | 2 vCPU | +| **RAM** | 1 GB | 2 GB | +| **Disk** | 10 GB SSD | 25 GB SSD | +| **OS** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS | +| **Domain** | Registered on Cloudflare | โ€” | +| **Docker** | Docker Engine 24+ | Docker 27+ | + +**Tested providers**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. + +--- + +## 1. Configure the VM + +### 1.1 Create the instance + +On your preferred VPS provider: + +- Choose Ubuntu 24.04 LTS +- Select the minimum plan (1 vCPU / 1 GB RAM) +- Set a strong root password or configure SSH key +- Note the **public IP** (e.g., `203.0.113.10`) + +### 1.2 Connect via SSH + +```bash +ssh root@203.0.113.10 +``` + +### 1.3 Update the system + +```bash +apt update && apt upgrade -y +``` + +### 1.4 Install Docker + +```bash +# Install dependencies +apt install -y ca-certificates curl gnupg + +# Add official Docker repository +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 Install nginx + +```bash +apt install -y nginx +``` + +### 1.6 Configure 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 +``` + +> **Tip**: For maximum security, restrict ports 80 and 443 to Cloudflare IPs only. See the [Advanced Security](#advanced-security) section. + +--- + +## 2. Install OmniRoute + +### 2.1 Create configuration directory + +```bash +mkdir -p /opt/omniroute +``` + +### 2.2 Create environment variables file + +```bash +cat > /opt/omniroute/.env << โ€˜EOFโ€™ +# === Security === +JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY +INITIAL_PASSWORD=YourSecurePassword123! +API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY +STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY +STORAGE_ENCRYPTION_KEY_VERSION=v1 +MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT + +# === 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 (change to your domain) === +BASE_URL=https://llms.seudominio.com +NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com + +# === Cloud Sync (optional) === +# CLOUD_URL=https://cloud.omniroute.online +# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online +EOF +``` + +> โš ๏ธ **IMPORTANT**: Generate unique secret keys! Use `openssl rand -hex 32` for each key. + +### 2.3 Start the 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 Verify that it is running + +```bash +docker ps | grep omniroute +docker logs omniroute --tail 20 +``` + +It should display: `[DB] SQLite database ready` and `listening on port 20128`. + +--- + +## 3. Configure nginx (Reverse Proxy) + +### 3.1 Generate SSL certificate (Cloudflare Origin) + +In the Cloudflare dashboard: + +1. Go to **SSL/TLS โ†’ Origin Server** +2. Click **Create Certificate** +3. Keep the defaults (15 years, \*.yourdomain.com) +4. Copy the **Origin Certificate** and the **Private Key** + +```bash +mkdir -p /etc/nginx/ssl + +# Paste the certificate +nano /etc/nginx/ssl/origin.crt + +# Paste the private key +nano /etc/nginx/ssl/origin.key + +chmod 600 /etc/nginx/ssl/origin.key +``` + +### 3.2 Nginx Configuration + +```bash +cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ +# Default server โ€” blocks direct access via 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.yourdomain.com; # Change to your domain + + 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.yourdomain.com; + return 301 https://$server_name$request_uri; +} +NGINX +``` + +### 3.3 Enable and Test + +```bash +# Remove default configuration +rm -f /etc/nginx/sites-enabled/default + +# Enable OmniRoute +ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute + +# Test and reload +nginx -t && systemctl reload nginx +``` + +--- + +## 4. Configure Cloudflare DNS + +### 4.1 Add DNS record + +In the Cloudflare dashboard โ†’ DNS: + +| Type | Name | Content | Proxy | +| ---- | ------ | ---------------------- | ---------- | +| A | `llms` | `203.0.113.10` (VM IP) | โœ… Proxied | + +### 4.2 Configure SSL + +Under **SSL/TLS โ†’ Overview**: + +- Mode: **Full (Strict)** + +Under **SSL/TLS โ†’ Edge Certificates**: + +- Always Use HTTPS: โœ… On +- Minimum TLS Version: TLS 1.2 +- Automatic HTTPS Rewrites: โœ… On + +### 4.3 Testing + +```bash +curl -sI https://llms.seudominio.com/health +# Should return HTTP/2 200 +``` + +--- + +## 5. Operations and Maintenance + +### Upgrade to a new version + +```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 +``` + +### View logs + +```bash +docker logs -f omniroute # Real-time stream +docker logs omniroute --tail 50 # Last 50 lines +``` + +### Manual database backup + +```bash +# Copy data from the volume to the host +docker cp omniroute:/app/data ./backup-$(date +%F) + +# Or compress the entire volume +docker run --rm -v omniroute-data:/data -v $(pwd):/backup \ + alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data +``` + +### Restore from 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. Advanced Security + +### Restrict nginx to Cloudflare IPs + +```bash +cat > /etc/nginx/cloudflare-ips.conf << โ€˜CFโ€™ +# Cloudflare IPv4 ranges โ€” update periodically +# 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 +``` + +Add the following to `nginx.conf` inside the `http {}` block: + +```nginx +include /etc/nginx/cloudflare-ips.conf; +``` + +### Install fail2ban + +```bash +apt install -y fail2ban +systemctl enable fail2ban +systemctl start fail2ban + +# Check status +fail2ban-client status sshd +``` + +### Block direct access to the Docker port + +```bash +# Prevent direct external access to port 20128 +iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP +iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT + +# Persist the rules +apt install -y iptables-persistent +netfilter-persistent save +``` + +--- + +## 7. Deploy to Cloudflare Workers (Optional) + +For remote access via Cloudflare Workers (without exposing the VM directly): + +```bash +# In the local repository +cd omnirouteCloud +npm install +npx wrangler login +npx wrangler deploy +``` + +See the full documentation at [omnirouteCloud/README.md](../omnirouteCloud/README.md). + +--- + +## Port Summary + +| Port | Service | Access | +| ----- | ----------- | -------------------------- | +| 22 | SSH | Public (with fail2ban) | +| 80 | nginx HTTP | Redirect โ†’ HTTPS | +| 443 | nginx HTTPS | Via Cloudflare Proxy | +| 20128 | OmniRoute | Localhost only (via nginx) | diff --git a/docs/i18n/pt/src/lib/a2a/README.md b/docs/i18n/pt/src/lib/a2a/README.md new file mode 100644 index 0000000000..b6c415594a --- /dev/null +++ b/docs/i18n/pt/src/lib/a2a/README.md @@ -0,0 +1,752 @@ +# OmniRoute A2A Server (Portuguรชs (Portugal)) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../../../src/lib/a2a/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../../../es/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../../../fr/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../../../de/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../../../it/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../../../ru/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../../../zh-CN/src/lib/a2a/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../../../ja/src/lib/a2a/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../../../ko/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../../../ar/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../../../in/src/lib/a2a/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../../../th/src/lib/a2a/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../../../vi/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../../../id/src/lib/a2a/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../../../ms/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../../../nl/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../../../pl/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../../../sv/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../../../no/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../../../da/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../../../fi/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../../../pt/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../../../ro/src/lib/a2a/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../../../hu/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../../../bg/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../../../sk/src/lib/a2a/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../../../uk-UA/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../../../he/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../../../phi/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../../../pt-BR/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../../../cs/src/lib/a2a/README.md) + +--- + +> **Agent-to-Agent Protocol v0.3** โ€” Enables any AI agent to use OmniRoute as an intelligent routing agent via JSON-RPC 2.0. + +The A2A Server exposes OmniRoute as a **first-class agent** that other agents can discover, delegate tasks to, and collaborate with using the [A2A Protocol](https://google.github.io/A2A/). + +--- + +## Arquitetura + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Orchestrator Agent โ”‚ +โ”‚ (LangChain, CrewAI, AutoGen, Custom Agent) โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ 1. GET /.well-known/agent.json (discover) + โ”‚ 2. POST /a2a (JSON-RPC 2.0) + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ OmniRoute A2A Server โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Task Manager โ”‚ โ”‚ Skill Engine โ”‚ โ”‚ SSE Streaming โ”‚ โ”‚ +โ”‚ โ”‚ (lifecycle) โ”‚โ”€โ”€โ”‚ (registry) โ”‚โ”€โ”€โ”‚ (real-time) โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ +โ”‚ Skills: โ”‚ โ”‚ +โ”‚ โ”œโ”€ smart-routing โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ””โ”€ quota-management โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ Routing Decision Logger โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ OmniRoute Gateway (internal) + /v1/chat/completions, /api/combos, /api/usage/quota +``` + +--- + +## Inรญcio Rรกpido + +### Agent Discovery + +Every A2A-compatible agent exposes an **Agent Card** at `/.well-known/agent.json`: + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +**Response:** + +```json +{ + "name": "OmniRoute", + "description": "Intelligent AI gateway with auto-routing across 50+ providers", + "url": "http://localhost:20128/a2a", + "version": "1.8.1", + "capabilities": { + "streaming": true, + "pushNotifications": false + }, + "skills": [ + { + "id": "smart-routing", + "name": "Smart Routing", + "description": "Routes prompts through OmniRoute intelligent pipeline", + "tags": ["routing", "llm", "multi-provider", "cost-optimization"], + "examples": [ + "Write a hello world in Python", + "Explain quantum computing using the cheapest provider" + ] + }, + { + "id": "quota-management", + "name": "Quota Management", + "description": "Natural-language queries about provider quotas", + "tags": ["quota", "analytics", "cost"], + "examples": [ + "Which provider has the most quota remaining?", + "Suggest a free combo for coding" + ] + } + ], + "authentication": { + "schemes": ["bearer"], + "apiKeyHeader": "Authorization" + } +} +``` + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Send a message to a skill and receive the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python hello world"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "a1b2c3d4-...", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "print('Hello, World!')" }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.0030)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "2026-03-04T..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"Quantum computing..."}}} + +: heartbeat 2026-03-04T21:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Running Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Skills Reference + +### `smart-routing` + +Routes prompts through OmniRoute's intelligent pipeline with full observability. + +**Parameters (in `metadata`):** + +| Parameter | Type | Default | Description | +| --------- | -------- | ------------ | ---------------------------------------------------------------------------------------- | +| `model` | `string` | `"auto"` | Target model (e.g., `claude-sonnet-4`, `gpt-4o`, `auto`) | +| `combo` | `string` | active combo | Specific combo to route through | +| `budget` | `number` | none | Maximum cost in USD for this request | +| `role` | `string` | none | Task role hint: `coding`, `review`, `planning`, `analysis`, `debugging`, `documentation` | + +**Returns:** + +| Field | Description | +| ------------------------------ | --------------------------------------------------------- | +| `artifacts[].content` | The LLM response text | +| `metadata.routing_explanation` | Human-readable explanation of routing decision | +| `metadata.cost_envelope` | Estimated vs actual cost with currency | +| `metadata.resilience_trace` | Array of events (primary_selected, fallback_needed, etc.) | +| `metadata.policy_verdict` | Whether the request was allowed and why | + +### `quota-management` + +Answers natural-language queries about provider quotas. + +**Query types (inferred from message content):** + +| Query Pattern | Response Type | +| ---------------------------------------------- | -------------------------------------------------------- | +| Contains `"ranking"`, `"most quota"`, `"best"` | Providers ranked by remaining quota | +| Contains `"free"`, `"suggest"` | Lists free combos or suggests free-tier providers | +| Default | Full quota summary with warnings for low-quota providers | + +--- + +## Task Lifecycle + +``` +submitted โ”€โ”€โ†’ working โ”€โ”€โ†’ completed + โ”€โ”€โ†’ failed + โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ†’ cancelled +``` + +| State | Description | +| ----------- | ----------------------------------------------------- | +| `submitted` | Task created, queued for execution | +| `working` | Skill handler is executing | +| `completed` | Execution succeeded, artifacts available | +| `failed` | Execution failed or task expired (TTL: 5 min default) | +| `cancelled` | Cancelled by client via `tasks/cancel` | + +- Terminal states: `completed`, `failed`, `cancelled` (no further transitions) +- Expired tasks in `submitted` or `working` are auto-marked as `failed` +- Tasks are garbage-collected after 2ร— TTL + +--- + +## Client Examples + +### Python โ€” Orchestrator Agent + +```python +""" +A2A Client โ€” Python example. +Discovers OmniRoute agent, sends a task, and processes the result. +""" +import requests +import json + +BASE_URL = "http://localhost:20128" +API_KEY = "your-api-key" +HEADERS = { + "Content-Type": "application/json", + "Authorization": f"Bearer {API_KEY}", +} + +# 1. Discover agent capabilities +agent_card = requests.get(f"{BASE_URL}/.well-known/agent.json").json() +print(f"Agent: {agent_card['name']} v{agent_card['version']}") +print(f"Skills: {[s['id'] for s in agent_card['skills']]}") + +# 2. Send a smart-routing task +response = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python quicksort implementation"}], + "metadata": { + "model": "auto", + "combo": "fast-coding", + "budget": 0.10, + } + } +}) +result = response.json()["result"] +print(f"\n๐Ÿ“ Response: {result['artifacts'][0]['content'][:200]}...") +print(f"๐Ÿ”€ Routing: {result['metadata']['routing_explanation']}") +print(f"๐Ÿ’ฐ Cost: ${result['metadata']['cost_envelope']['actual']}") +print(f"๐Ÿ›ก๏ธ Policy: {result['metadata']['policy_verdict']['reason']}") + +# 3. Query quota status +quota_resp = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-2", + "method": "message/send", + "params": { + "skill": "quota-management", + "messages": [{"role": "user", "content": "Which provider has the most quota remaining?"}], + } +}) +quota_result = quota_resp.json()["result"] +print(f"\n๐Ÿ“Š Quota: {quota_result['artifacts'][0]['content']}") +``` + +### TypeScript โ€” Multi-Agent Orchestrator + +```typescript +/** + * A2A Client โ€” TypeScript example. + * Shows agent discovery, task delegation, and streaming. + */ + +const BASE_URL = "http://localhost:20128"; +const API_KEY = "your-api-key"; + +interface JsonRpcResponse { + jsonrpc: "2.0"; + id: string | number; + result?: T; + error?: { code: number; message: string }; +} + +async function a2aCall(method: string, params: Record): Promise { + const resp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: `${method}-${Date.now()}`, + method, + params, + }), + }); + const json: JsonRpcResponse = await resp.json(); + if (json.error) throw new Error(`[${json.error.code}] ${json.error.message}`); + return json.result!; +} + +// โ”€โ”€ Agent Discovery โ”€โ”€ +const agentCard = await fetch(`${BASE_URL}/.well-known/agent.json`).then((r) => r.json()); +console.log(`Connected to: ${agentCard.name} (${agentCard.skills.length} skills)`); + +// โ”€โ”€ Smart Routing: Send a coding task โ”€โ”€ +const routingResult = await a2aCall("message/send", { + skill: "smart-routing", + messages: [{ role: "user", content: "Implement a Redis cache wrapper in TypeScript" }], + metadata: { model: "claude-sonnet-4", role: "coding" }, +}); +console.log("Response:", routingResult.artifacts[0].content); +console.log("Provider:", routingResult.metadata.routing_explanation); + +// โ”€โ”€ Quota Management: Find free alternatives โ”€โ”€ +const quotaResult = await a2aCall("message/send", { + skill: "quota-management", + messages: [{ role: "user", content: "Suggest free combos for documentation" }], +}); +console.log("Free combos:", quotaResult.artifacts[0].content); + +// โ”€โ”€ Streaming: Real-time response โ”€โ”€ +const streamResp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "stream-1", + method: "message/stream", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Explain microservices architecture" }], + }, + }), +}); + +const reader = streamResp.body!.getReader(); +const decoder = new TextDecoder(); +while (true) { + const { done, value } = await reader.read(); + if (done) break; + const chunk = decoder.decode(value); + for (const line of chunk.split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + if (event.params.chunk) { + process.stdout.write(event.params.chunk.content); + } + if (event.params.task.state === "completed") { + console.log("\nโœ… Stream completed"); + } + } + } +} +``` + +### Python โ€” LangChain A2A Integration + +```python +""" +LangChain integration โ€” Use OmniRoute A2A as a custom LLM. +""" +from langchain.llms.base import BaseLLM +from langchain.schema import LLMResult, Generation +import requests +from typing import List, Optional + +class OmniRouteA2A(BaseLLM): + base_url: str = "http://localhost:20128" + api_key: str = "" + model: str = "auto" + combo: Optional[str] = None + + @property + def _llm_type(self) -> str: + return "omniroute-a2a" + + def _call(self, prompt: str, stop: Optional[List[str]] = None, **kwargs) -> str: + response = requests.post( + f"{self.base_url}/a2a", + headers={ + "Content-Type": "application/json", + "Authorization": f"Bearer {self.api_key}", + }, + json={ + "jsonrpc": "2.0", + "id": "langchain-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": prompt}], + "metadata": { + "model": self.model, + **({"combo": self.combo} if self.combo else {}), + }, + }, + }, + ) + result = response.json()["result"] + return result["artifacts"][0]["content"] + + def _generate(self, prompts: List[str], stop=None, **kwargs) -> LLMResult: + return LLMResult( + generations=[[Generation(text=self._call(p, stop))] for p in prompts] + ) + +# Usage +llm = OmniRouteA2A( + base_url="http://localhost:20128", + api_key="your-key", + model="auto", + combo="fast-coding", +) +result = llm("Write a Python function to merge two sorted lists") +print(result) +``` + +### Go โ€” A2A Client + +```go +package main + +import ( + "bytes" + "encoding/json" + "fmt" + "io" + "net/http" +) + +const baseURL = "http://localhost:20128" +const apiKey = "your-api-key" + +type JsonRpcRequest struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Method string `json:"method"` + Params interface{} `json:"params"` +} + +type JsonRpcResponse struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Result interface{} `json:"result"` + Error *struct { + Code int `json:"code"` + Message string `json:"message"` + } `json:"error"` +} + +func a2aCall(method string, params interface{}) (*JsonRpcResponse, error) { + body, _ := json.Marshal(JsonRpcRequest{ + Jsonrpc: "2.0", + ID: "go-1", + Method: method, + Params: params, + }) + + req, _ := http.NewRequest("POST", baseURL+"/a2a", bytes.NewReader(body)) + req.Header.Set("Content-Type", "application/json") + req.Header.Set("Authorization", "Bearer "+apiKey) + + resp, err := http.DefaultClient.Do(req) + if err != nil { + return nil, err + } + defer resp.Body.Close() + data, _ := io.ReadAll(resp.Body) + + var result JsonRpcResponse + json.Unmarshal(data, &result) + return &result, nil +} + +func main() { + // Discover agent + resp, _ := http.Get(baseURL + "/.well-known/agent.json") + defer resp.Body.Close() + body, _ := io.ReadAll(resp.Body) + fmt.Println("Agent Card:", string(body)) + + // Send smart-routing task + result, _ := a2aCall("message/send", map[string]interface{}{ + "skill": "smart-routing", + "messages": []map[string]string{{"role": "user", "content": "Hello from Go!"}}, + "metadata": map[string]interface{}{"model": "auto"}, + }) + out, _ := json.MarshalIndent(result.Result, "", " ") + fmt.Println("Result:", string(out)) +} +``` + +--- + +## Use Cases + +### ๐Ÿค– Use Case 1: Multi-Agent Coding Pipeline + +An orchestrator agent delegates code generation to OmniRoute, then passes the output to a review agent. + +```python +def coding_pipeline(task: str): + # Step 1: Generate code via OmniRoute A2A + code_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Write production-quality code: {task}"} + ], metadata={"model": "auto", "role": "coding"}) + code = code_result["artifacts"][0]["content"] + + # Step 2: Review the code via OmniRoute A2A (different model) + review_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Review this code for bugs and improvements:\n\n{code}"} + ], metadata={"model": "auto", "role": "review"}) + review = review_result["artifacts"][0]["content"] + + # Step 3: Check costs + print(f"Code cost: ${code_result['metadata']['cost_envelope']['actual']}") + print(f"Review cost: ${review_result['metadata']['cost_envelope']['actual']}") + + return {"code": code, "review": review} +``` + +### ๐Ÿ’ก Use Case 2: Quota-Aware Agent Swarm + +Multiple agents share quota through OmniRoute, using the quota skill to coordinate. + +```python +async def quota_aware_agent(agent_name: str, task: str): + # Check quota before starting + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Which provider has the most quota remaining?"} + ]) + print(f"[{agent_name}] {quota['artifacts'][0]['content']}") + + # Send request with budget constraint + result = a2a_send("smart-routing", [ + {"role": "user", "content": task} + ], metadata={"budget": 0.05}) + + policy = result["metadata"]["policy_verdict"] + if not policy["allowed"]: + print(f"[{agent_name}] โš ๏ธ Budget exceeded: {policy['reason']}") + # Fall back to free combo + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Suggest free combos"} + ]) + print(f"[{agent_name}] Free alternatives: {quota['artifacts'][0]['content']}") + + return result +``` + +### ๐Ÿ“Š Use Case 3: Real-Time Streaming Dashboard + +A monitoring agent streams responses and displays progress in real-time. + +```typescript +async function streamingDashboard(prompt: string) { + const response = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { "Content-Type": "application/json", Authorization: `Bearer ${API_KEY}` }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "dash-1", + method: "message/stream", + params: { skill: "smart-routing", messages: [{ role: "user", content: prompt }] }, + }), + }); + + let totalChunks = 0; + const reader = response.body!.getReader(); + const decoder = new TextDecoder(); + + while (true) { + const { done, value } = await reader.read(); + if (done) break; + + for (const line of decoder.decode(value).split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + const state = event.params.task.state; + + if (state === "working" && event.params.chunk) { + totalChunks++; + process.stdout.write( + `\r[Chunk ${totalChunks}] ${event.params.chunk.content.slice(0, 50)}...` + ); + } + if (state === "completed") { + const meta = event.params.metadata; + console.log( + `\nโœ… Done | Cost: $${meta?.cost_envelope?.actual || 0} | Route: ${meta?.routing_explanation || "N/A"}` + ); + } + if (state === "failed") { + console.error(`\nโŒ Failed: ${event.params.metadata?.error}`); + } + } + } + } +} +``` + +### ๐Ÿ” Use Case 4: Task Polling Pattern + +For long-running tasks, poll the task status instead of waiting synchronously. + +```python +import time + +def poll_task(task_id: str, timeout: int = 60): + """Poll task status until completion or timeout.""" + start = time.time() + while time.time() - start < timeout: + result = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "poll-1", + "method": "tasks/get", + "params": {"taskId": task_id}, + }).json() + + task = result["result"]["task"] + state = task["state"] + print(f" Task {task_id[:8]}... state={state}") + + if state in ("completed", "failed", "cancelled"): + return task + time.sleep(2) + + # Timeout โ€” cancel the task + requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "cancel-1", + "method": "tasks/cancel", + "params": {"taskId": task_id}, + }) + raise TimeoutError(f"Task {task_id} timed out after {timeout}s") +``` + +--- + +## Error Codes + +| Code | Constant | Meaning | +| ------ | ------------------------ | ---------------------------------------- | +| -32700 | โ€” | Parse error (invalid JSON) | +| -32600 | `INVALID_REQUEST` | Invalid JSON-RPC request or unauthorized | +| -32601 | `METHOD_NOT_FOUND` | Unknown method or skill | +| -32602 | `INVALID_PARAMS` | Missing or invalid parameters | +| -32603 | `INTERNAL_ERROR` | Skill execution failed | +| -32001 | `TASK_NOT_FOUND` | Task ID not found | +| -32002 | `TASK_ALREADY_COMPLETED` | Cannot modify a completed task | +| -32003 | `UNAUTHORIZED` | Invalid or missing API key | +| -32004 | `BUDGET_EXCEEDED` | Request exceeds configured budget | +| -32005 | `PROVIDER_UNAVAILABLE` | No available providers | + +--- + +## Authentication + +All `/a2a` requests require a Bearer token via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server (`OMNIROUTE_API_KEY` is empty), authentication is bypassed. + +--- + +## File Structure + +``` +src/lib/a2a/ +โ”œโ”€โ”€ taskManager.ts # Task lifecycle (create/update/cancel/list), TTL, cleanup +โ”œโ”€โ”€ taskExecution.ts # Generic task executor with state management +โ”œโ”€โ”€ streaming.ts # SSE stream formatting, heartbeat, chunk/completion events +โ”œโ”€โ”€ routingLogger.ts # Routing decision logger (stats, history, retention) +โ””โ”€โ”€ skills/ + โ”œโ”€โ”€ smartRouting.ts # Smart routing skill (routes via /v1/chat/completions) + โ””โ”€โ”€ quotaManagement.ts # Quota management skill (natural-language quota queries) + +src/app/a2a/ +โ””โ”€โ”€ route.ts # Next.js API route handler (JSON-RPC 2.0 dispatch) + +open-sse/mcp-server/ +โ””โ”€โ”€ schemas/a2a.ts # Zod schemas (AgentCard, Task, JSON-RPC, SSE events) +``` + +--- + +## Comparison: MCP vs A2A + +| Feature | MCP Server | A2A Server | +| ----------------- | ---------------------------- | ------------------------------------------------- | +| **Protocol** | Model Context Protocol | Agent-to-Agent Protocol v0.3 | +| **Transport** | stdio / HTTP | HTTP (JSON-RPC 2.0) | +| **Discovery** | Tool listing via MCP | `/.well-known/agent.json` | +| **Granularity** | 16 individual tools | 2 high-level skills | +| **Best for** | IDE agents (Cursor, VS Code) | Multi-agent systems (LangChain, CrewAI) | +| **Streaming** | Not supported | SSE via `message/stream` | +| **Task tracking** | No | Full lifecycle (submitted โ†’ completed) | +| **Observability** | Audit log per tool call | Cost envelope + resilience trace + policy verdict | + +--- + +## Licenรงa + +Part of [OmniRoute](https://github.com/diegosouzapw/OmniRoute) โ€” MIT License. diff --git a/docs/i18n/ro/A2A-SERVER.md b/docs/i18n/ro/A2A-SERVER.md deleted file mode 100644 index 01531ff482..0000000000 --- a/docs/i18n/ro/A2A-SERVER.md +++ /dev/null @@ -1,200 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/A2A-SERVER.md) - ---- - -# OmniRoute A2A Server Documentation - -> Agent-to-Agent Protocol v0.3 โ€” OmniRoute as an intelligent routing agent - -## Agent Discovery - -```bash -curl http://localhost:20128/.well-known/agent.json -``` - -Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements. - ---- - -## Authentication - -All `/a2a` requests require an API key via the `Authorization` header: - -``` -Authorization: Bearer YOUR_OMNIROUTE_API_KEY -``` - -If no API key is configured on the server, authentication is bypassed. - ---- - -## JSON-RPC 2.0 Methods - -### `message/send` โ€” Synchronous Execution - -Sends a message to a skill and waits for the complete response. - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{ - "jsonrpc": "2.0", - "id": "1", - "method": "message/send", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Write a hello world in Python"}], - "metadata": {"model": "auto", "combo": "fast-coding"} - } - }' -``` - -**Response:** - -```json -{ - "jsonrpc": "2.0", - "id": "1", - "result": { - "task": { "id": "uuid", "state": "completed" }, - "artifacts": [{ "type": "text", "content": "..." }], - "metadata": { - "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)", - "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, - "resilience_trace": [ - { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." } - ], - "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } - } - } -} -``` - -### `message/stream` โ€” SSE Streaming - -Same as `message/send` but returns Server-Sent Events for real-time streaming. - -```bash -curl -N -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{ - "jsonrpc": "2.0", - "id": "1", - "method": "message/stream", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Explain quantum computing"}] - } - }' -``` - -**SSE Events:** - -``` -data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}} - -: heartbeat 2026-03-03T17:00:00Z - -data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} -``` - -### `tasks/get` โ€” Query Task Status - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' -``` - -### `tasks/cancel` โ€” Cancel a Task - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' -``` - ---- - -## Available Skills - -| Skill | Description | -| :----------------- | :------------------------------------------------------------------------------------------------------------------------------ | -| `smart-routing` | Routes prompts through OmniRoute's intelligent pipeline. Returns response with routing explanation, cost, and resilience trace. | -| `quota-management` | Answers natural-language queries about provider quotas, suggests free combos, and provides quota rankings. | - ---- - -## Task Lifecycle - -``` -submitted โ†’ working โ†’ completed - โ†’ failed - โ†’ cancelled -``` - -- Tasks expire after 5 minutes (configurable) -- Terminal states: `completed`, `failed`, `cancelled` -- Event log tracks every state transition - ---- - -## Error Codes - -| Code | Meaning | -| :----- | :----------------------------- | -| -32700 | Parse error (invalid JSON) | -| -32600 | Invalid request / Unauthorized | -| -32601 | Method or skill not found | -| -32602 | Invalid params | -| -32603 | Internal error | - ---- - -## Integration Examples - -### Python (requests) - -```python -import requests - -resp = requests.post("http://localhost:20128/a2a", json={ - "jsonrpc": "2.0", "id": "1", - "method": "message/send", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Hello"}] - } -}, headers={"Authorization": "Bearer YOUR_KEY"}) - -result = resp.json()["result"] -print(result["artifacts"][0]["content"]) -print(result["metadata"]["routing_explanation"]) -``` - -### TypeScript (fetch) - -```typescript -const resp = await fetch("http://localhost:20128/a2a", { - method: "POST", - headers: { - "Content-Type": "application/json", - Authorization: "Bearer YOUR_KEY", - }, - body: JSON.stringify({ - jsonrpc: "2.0", - id: "1", - method: "message/send", - params: { - skill: "smart-routing", - messages: [{ role: "user", content: "Hello" }], - }, - }), -}); -const { result } = await resp.json(); -console.log(result.metadata.routing_explanation); -``` diff --git a/docs/i18n/ro/API_REFERENCE.md b/docs/i18n/ro/API_REFERENCE.md deleted file mode 100644 index b878605221..0000000000 --- a/docs/i18n/ro/API_REFERENCE.md +++ /dev/null @@ -1,455 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/API_REFERENCE.md) - ---- - -# API Reference - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/API_REFERENCE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/API_REFERENCE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/API_REFERENCE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/API_REFERENCE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/API_REFERENCE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/API_REFERENCE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/API_REFERENCE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/API_REFERENCE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/API_REFERENCE.md) - -Complete reference for all OmniRoute API endpoints. - ---- - -## Table of Contents - -- [Chat Completions](#chat-completions) -- [Embeddings](#embeddings) -- [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`. - -### ACP Agents - -| Endpoint | Method | Description | -| ----------------- | ------ | -------------------------------------------------------- | -| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | -| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | -| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | - -GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). - -### Resilience & Rate Limits - -| Endpoint | Method | Description | -| ----------------------- | ------- | ------------------------------- | -| `/api/resilience` | 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` diff --git a/docs/i18n/ro/ARCHITECTURE.md b/docs/i18n/ro/ARCHITECTURE.md deleted file mode 100644 index 4ea06a29f2..0000000000 --- a/docs/i18n/ro/ARCHITECTURE.md +++ /dev/null @@ -1,787 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/ARCHITECTURE.md) - ---- - -# OmniRoute Architecture - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/ARCHITECTURE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/ARCHITECTURE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/ARCHITECTURE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/ARCHITECTURE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/ARCHITECTURE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/ARCHITECTURE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/ARCHITECTURE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/ARCHITECTURE.md) - -_Last updated: 2026-03-04_ - -## 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 (`...`) for reasoning models -- Response sanitization for strict OpenAI SDK compatibility -- Role normalization (developerโ†’system, systemโ†’user) for cross-provider compatibility -- Structured output conversion (json_schema โ†’ Gemini responseSchema) -- Local persistence for providers, keys, aliases, combos, settings, pricing -- Usage/cost tracking and request logging -- Optional cloud sync for multi-device/state sync -- IP allowlist/blocklist for API access control -- Thinking budget management (passthrough/auto/custom/adaptive) -- Global system prompt injection -- Session tracking and fingerprinting -- Per-account enhanced rate limiting with provider-specific profiles -- Circuit breaker pattern for provider resilience -- Anti-thundering herd protection with mutex locking -- Signature-based request deduplication cache -- Domain layer: model availability, cost rules, fallback policy, lockout policy -- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) -- Policy engine for centralized request evaluation (lockout โ†’ budget โ†’ fallback) -- Request telemetry with p50/p95/p99 latency aggregation -- Correlation ID (X-Request-Id) for end-to-end tracing -- Compliance audit logging with opt-out per API key -- Eval framework for LLM quality assurance -- Resilience UI dashboard with real-time circuit breaker status -- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) - -Primary runtime model: - -- Next.js 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[(storage.sqlite)] - UDB[(usage tables + log artifacts)] - end - - subgraph Upstreams[Upstream Providers] - P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/Qoder/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/route.ts` (GET) -- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) -- OAuth: `src/app/api/oauth/*` -- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` -- Usage: `src/app/api/usage/*` -- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` -- CLI tooling helpers: `src/app/api/cli-tools/*` -- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) -- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) -- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) -- Sessions: `src/app/api/sessions` (GET) -- Rate limits: `src/app/api/rate-limits` (GET) -- Resilience: `src/app/api/resilience` (GET/PATCH) โ€” provider profiles, circuit breaker, rate limit state -- Resilience reset: `src/app/api/resilience/reset` (POST) โ€” reset breakers + cooldowns -- Cache stats: `src/app/api/cache/stats` (GET/DELETE) -- Model availability: `src/app/api/models/availability` (GET/POST) -- Telemetry: `src/app/api/telemetry/summary` (GET) -- Budget: `src/app/api/usage/budget` (GET/POST) -- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) -- Compliance audit: `src/app/api/compliance/audit-log` (GET) -- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) -- Policies: `src/app/api/policies` (GET/POST) - -## 2) SSE + 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` -- Response sanitization: `open-sse/handlers/responseSanitizer.ts` -- Role normalization: `open-sse/services/roleNormalizer.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`, `qoder.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 (SQLite): - -- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) -- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) -- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) -- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** - -Usage persistence: - -- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) -- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` -- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) -- legacy JSON files are migrated to SQLite by startup migrations when present - -Domain State DB (SQLite): - -- `src/lib/db/domainState.ts` โ€” CRUD operations 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: - -- primary runtime DB: `${DATA_DIR}/storage.sqlite` -- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) -- structured call payload archives: `${DATA_DIR}/call_logs/` -- optional translator/request debug sessions: `/logs/...` - -## Deployment Topology - -```mermaid -flowchart LR - 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[(storage.sqlite)] - UsageDB[(usage tables + log artifacts)] - end - - subgraph External[External Services] - Providers[AI Providers] - SyncCloud[Cloud Sync Service] - end - - CLI --> Next - Browser --> Next - Next --> Core - Next --> MainDB - Core --> MainDB - Core --> UsageDB - Core --> Providers - Next --> SyncCloud -``` - -## Module Mapping (Decision-Critical) - -### Route and API Modules - -- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs -- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) -- `src/app/api/providers*`: provider CRUD, validation, testing -- `src/app/api/provider-nodes*`: custom compatible node management -- `src/app/api/provider-models`: custom model management (CRUD) -- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) -- `src/app/api/oauth/*`: OAuth/device-code flows -- `src/app/api/keys*`: local API key lifecycle -- `src/app/api/models/alias`: alias management -- `src/app/api/combos*`: fallback combo management -- `src/app/api/pricing`: pricing overrides for cost calculation -- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) -- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) -- `src/app/api/usage/*`: usage and logs APIs -- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers -- `src/app/api/cli-tools/*`: local CLI config writers/checkers -- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) -- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) -- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) -- `src/app/api/sessions`: active session listing (GET) -- `src/app/api/rate-limits`: per-account rate limit status (GET) - -### Routing and Execution Core - -- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop -- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup -- `open-sse/executors/*`: provider-specific network and format behavior - -### Translation Registry and Format Converters - -- `open-sse/translator/index.ts`: translator registry and orchestration -- Request translators: `open-sse/translator/request/*` -- Response translators: `open-sse/translator/response/*` -- Format constants: `open-sse/translator/formats.ts` - -### Persistence - -- `src/lib/db/*`: persistent config/state and domain persistence on SQLite -- `src/lib/localDb.ts`: compatibility re-export for DB modules -- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables - -## Provider Executor Coverage (Strategy Pattern) - -Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. - -| Executor | Provider(s) | Special Handling | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | -| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, Qoder, 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 | -| Qoder | openai | OAuth (Basic) | โœ… | โœ… | โœ… | โš ๏ธ Per request | -| OpenRouter | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| GLM/Kimi/MiniMax | claude | API Key | โœ… | โœ… | โŒ | โŒ | -| DeepSeek | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Groq | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| xAI (Grok) | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Mistral | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Perplexity | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Together AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Fireworks AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Cerebras | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Cohere | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| NVIDIA NIM | openai | API Key | โœ… | โœ… | โŒ | โŒ | - -## Format Translation Coverage - -Detected source formats include: - -- `openai` -- `openai-responses` -- `claude` -- `gemini` - -Target formats include: - -- OpenAI chat/Responses -- Claude -- Gemini/Gemini-CLI/Antigravity envelope -- Kiro -- Cursor - -Translations use **OpenAI as the hub format** โ€” all conversions go through OpenAI as intermediate: - -``` -Source Format โ†’ OpenAI (hub) โ†’ Target Format -``` - -Translations are selected dynamically based on source payload shape and provider target format. - -Additional processing layers in the translation pipeline: - -- **Response sanitization** โ€” Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance -- **Role normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI targets; merges `system` โ†’ `user` for models that reject the system role (GLM, ERNIE) -- **Think tag extraction** โ€” Parses `...` blocks from content into `reasoning_content` field -- **Structured output** โ€” Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` - -## Supported API Endpoints - -| 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 `/logs//` 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 - -- SQLite schema migrations and auto-upgrade hooks at startup -- legacy JSON โ†’ SQLite migration compatibility path - -## Observability and Operational Signals - -Runtime visibility sources: - -- console logs from `src/sse/utils/logger.ts` -- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) -- textual request status log in `log.txt` (optional/compat) -- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` -- dashboard usage endpoints (`/api/usage/*`) for UI consumption - -## Security-Sensitive Boundaries - -- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing -- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning -- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format -- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level -- Cloud sync endpoints rely on API key auth + machine id semantics - -## Environment and Runtime Matrix - -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` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. -2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. -3. Request logger writes full headers/body when enabled; treat log directory as sensitive. -4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. -5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. -6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). -7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). -8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). - -## Operational Verification Checklist - -- Build from source: `npm run build` -- Build Docker image: `docker build -t omniroute .` -- Start service and verify: -- `GET /api/settings` -- `GET /api/v1/models` -- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/ro/AUTO-COMBO.md b/docs/i18n/ro/AUTO-COMBO.md deleted file mode 100644 index 2166e41dff..0000000000 --- a/docs/i18n/ro/AUTO-COMBO.md +++ /dev/null @@ -1,67 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/AUTO-COMBO.md) - ---- - -# OmniRoute Auto-Combo Engine - -> Self-managing model chains with adaptive scoring - -## How It Works - -The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**: - -| Factor | Weight | Description | -| :--------- | :----- | :---------------------------------------------- | -| Quota | 0.20 | Remaining capacity [0..1] | -| Health | 0.25 | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 | -| CostInv | 0.20 | Inverse cost (cheaper = higher score) | -| LatencyInv | 0.15 | Inverse p95 latency (faster = higher) | -| TaskFit | 0.10 | Model ร— task type fitness score | -| Stability | 0.10 | Low variance in latency/errors | - -## Mode Packs - -| Pack | Focus | Key Weight | -| :---------------------- | :----------- | :--------------- | -| ๐Ÿš€ **Ship Fast** | Speed | latencyInv: 0.35 | -| ๐Ÿ’ฐ **Cost Saver** | Economy | costInv: 0.40 | -| ๐ŸŽฏ **Quality First** | Best model | taskFit: 0.40 | -| ๐Ÿ“ก **Offline Friendly** | Availability | quota: 0.40 | - -## Self-Healing - -- **Temporary exclusion**: Score < 0.2 โ†’ excluded for 5 min (progressive backoff, max 30 min) -- **Circuit breaker awareness**: OPEN โ†’ auto-excluded; HALF_OPEN โ†’ probe requests -- **Incident mode**: >50% OPEN โ†’ disable exploration, maximize stability -- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout - -## Bandit Exploration - -5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode. - -## API - -```bash -# Create auto-combo -curl -X POST http://localhost:20128/api/combos/auto \ - -H "Content-Type: application/json" \ - -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}' - -# List auto-combos -curl http://localhost:20128/api/combos/auto -``` - -## Task Fitness - -30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` โ†’ high coding score). - -## Files - -| File | Purpose | -| :------------------------------------------- | :------------------------------------ | -| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization | -| `open-sse/services/autoCombo/taskFitness.ts` | Model ร— task fitness lookup | -| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap | -| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode | -| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles | -| `src/app/api/combos/auto/route.ts` | REST API | diff --git a/docs/i18n/ro/CHANGELOG.md b/docs/i18n/ro/CHANGELOG.md index 98956f57c7..a8275622ab 100644 --- a/docs/i18n/ro/CHANGELOG.md +++ b/docs/i18n/ro/CHANGELOG.md @@ -1,12 +1,92 @@ # Changelog (Romรขnฤƒ) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CHANGELOG.md) --- - ## [Unreleased] +### ๐Ÿ› ๏ธ Maintenance + +- **AGENTS.md rewrite:** Condensed from 297โ†’153 lines. Added build/lint/test commands (including single-test execution), code style guidelines (Prettier, TypeScript, ESLint, naming, imports, error handling, security), and trimmed verbose architecture tables for AI agent consumption. + +## [3.4.2] - 2026-04-01 + +### ๐Ÿ› Bug Fixes + +- **CI Stabilization:** Fixed failing analytics/settings Playwright selectors and request assertions so GitHub Actions E2E runs pass reliably across localized UIs and switch-based controls. +- **Deterministic Tests:** Removed date-sensitive quota fixtures from Copilot usage tests and aligned idempotency/model catalog tests with the merged runtime behavior. +- **MCP Type Hardening:** Removed zero-budget explicit `any` regressions from the MCP server tool registration path, restoring the `check:any-budget:t11` workflow gate. + +### ๐Ÿ› ๏ธ Maintenance + +- **Release Branch Integration:** Consolidated the active feature branches into `release/v3.4.2` on top of current `main` and validated the branch with lint, unit, coverage, build, and CI-mode E2E runs. + +## [3.4.1] - 2026-03-31 + +> [!WARNING] +> **BREAKING CHANGE: request logging, retention, and logging environment variables have been redesigned.** +> On the first startup after upgrading, OmniRoute archives legacy request logs from `DATA_DIR/logs/`, legacy `DATA_DIR/call_logs/`, and `DATA_DIR/log.txt` into `DATA_DIR/log_archives/*.zip`, then removes the deprecated layout and switches to the new unified artifact format under `DATA_DIR/call_logs/`. + +### โœจ New Features + +- **.ENV Migration Utility:** Included `scripts/migrate-env.mjs` to seamlessly migrate ` Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` - ---- - -## Step 2 โ€” Install CLI Tools - -All npm-based tools require Node.js 18+: - -```bash -# Claude Code (Anthropic) -npm install -g @anthropic-ai/claude-code - -# OpenAI Codex -npm install -g @openai/codex - -# Gemini CLI (Google) -npm install -g @google/gemini-cli - -# OpenCode -npm install -g opencode-ai - -# Cline -npm install -g cline - -# KiloCode -npm install -g kilecode - -# Kiro CLI (Amazon โ€” requires curl + unzip) -apt-get install -y unzip # on Debian/Ubuntu -curl -fsSL https://cli.kiro.dev/install | bash -export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc -``` - -**Verify:** - -```bash -claude --version # 2.x.x -codex --version # 0.x.x -gemini --version # 0.x.x -opencode --version # x.x.x -cline --version # 2.x.x -kilocode --version # x.x.x (or: kilo --version) -kiro-cli --version # 1.x.x -``` - ---- - -## Step 3 โ€” Set Global Environment Variables - -Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`: - -```bash -# OmniRoute Universal Endpoint -export OPENAI_BASE_URL="http://localhost:20128/v1" -export OPENAI_API_KEY="sk-your-omniroute-key" -export ANTHROPIC_BASE_URL="http://localhost:20128/v1" -export ANTHROPIC_API_KEY="sk-your-omniroute-key" -export GEMINI_BASE_URL="http://localhost:20128/v1" -export GEMINI_API_KEY="sk-your-omniroute-key" -``` - -> For a **remote server** replace `localhost:20128` with the server IP or domain, -> e.g. `http://192.168.0.15:20128`. - ---- - -## Step 4 โ€” Configure Each Tool - -### Claude Code - -```bash -# Via CLI: -claude config set --global api-base-url http://localhost:20128/v1 - -# Or create ~/.claude/settings.json: -mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF -{ - "apiBaseUrl": "http://localhost:20128/v1", - "apiKey": "sk-your-omniroute-key" -} -EOF -``` - -**Test:** `claude "say hello"` - ---- - -### OpenAI Codex - -```bash -mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF -model: auto -apiKey: sk-your-omniroute-key -apiBaseUrl: http://localhost:20128/v1 -EOF -``` - -**Test:** `codex "what is 2+2?"` - ---- - -### Gemini CLI - -```bash -mkdir -p ~/.gemini && cat > ~/.gemini/settings.json << EOF -{ - "apiKey": "sk-your-omniroute-key", - "baseUrl": "http://localhost:20128/v1" -} -EOF -``` - -**Test:** `gemini "hello"` - ---- - -### OpenCode - -```bash -mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF -[provider.openai] -base_url = "http://localhost:20128/v1" -api_key = "sk-your-omniroute-key" -EOF -``` - -**Test:** `opencode` - ---- - -### Cline (CLI or VS Code) - -**CLI mode:** - -```bash -mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF -{ - "apiProvider": "openai", - "openAiBaseUrl": "http://localhost:20128/v1", - "openAiApiKey": "sk-your-omniroute-key" -} -EOF -``` - -**VS Code mode:** -Cline extension settings โ†’ API Provider: `OpenAI Compatible` โ†’ Base URL: `http://localhost:20128/v1` - -Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ Cline โ†’ Apply Config**. - ---- - -### KiloCode (CLI or VS Code) - -**CLI mode:** - -```bash -kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key -``` - -**VS Code settings:** - -```json -{ - "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", - "kilo-code.apiKey": "sk-your-omniroute-key" -} -``` - -Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ KiloCode โ†’ Apply Config**. - ---- - -### Continue (VS Code Extension) - -Edit `~/.continue/config.yaml`: - -```yaml -models: - - name: OmniRoute - provider: openai - model: auto - apiBase: http://localhost:20128/v1 - apiKey: sk-your-omniroute-key - default: true -``` - -Restart VS Code after editing. - ---- - -### Kiro CLI (Amazon) - -```bash -# Login to your AWS/Kiro account: -kiro-cli login - -# The CLI uses its own auth โ€” OmniRoute is not needed as backend for Kiro CLI itself. -# Use kiro-cli alongside OmniRoute for other tools. -kiro-cli status -``` - ---- - -### Cursor (Desktop App) - -> **Note:** Cursor routes requests through its cloud. For OmniRoute integration, -> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL. - -Via GUI: **Settings โ†’ Models โ†’ OpenAI API Key** - -- Base URL: `https://your-domain.com/v1` -- API Key: your OmniRoute key - ---- - -## Dashboard Auto-Configuration - -The OmniRoute dashboard automates configuration for most tools: - -1. Go to `http://localhost:20128/dashboard/cli-tools` -2. Expand any tool card -3. Select your API key from the dropdown -4. Click **Apply Config** (if tool is detected as installed) -5. Or copy the generated config snippet manually - ---- - -## Built-in Agents: Droid & OpenClaw - -**Droid** and **OpenClaw** are AI agents built directly into OmniRoute โ€” no installation needed. -They run as internal routes and use OmniRoute's model routing automatically. - -- Access: `http://localhost:20128/dashboard/agents` -- Configure: same combos and providers as all other tools -- No API key or CLI install required - ---- - -## Available API Endpoints - -| Endpoint | Description | Use For | -| -------------------------- | ----------------------------- | --------------------------- | -| `/v1/chat/completions` | Standard chat (all providers) | All modern tools | -| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows | -| `/v1/completions` | Legacy text completions | Older tools using `prompt:` | -| `/v1/embeddings` | Text embeddings | RAG, search | -| `/v1/images/generations` | Image generation | DALL-E, Flux, etc. | -| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS | -| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI | - ---- - -## Troubleshooting - -| Error | Cause | Fix | -| ------------------------- | ----------------------- | ------------------------------------------ | -| `Connection refused` | OmniRoute not running | `pm2 start omniroute` | -| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` | -| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` | -| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` | -| CLI shows "not installed" | Binary not in PATH | Check `which ` | -| `kiro-cli: not found` | Not in PATH | `export PATH="$HOME/.local/bin:$PATH"` | - ---- - -## Quick Setup Script (One Command) - -```bash -# Install all CLIs and configure for OmniRoute (replace with your key and server URL) -OMNIROUTE_URL="http://localhost:20128/v1" -OMNIROUTE_KEY="sk-your-omniroute-key" - -npm install -g @anthropic-ai/claude-code @openai/codex @google/gemini-cli opencode-ai cline kilecode - -# Kiro CLI -apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash - -# Write configs -mkdir -p ~/.claude ~/.codex ~/.gemini ~/.config/opencode ~/.continue - -cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" -cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" -cat > ~/.gemini/settings.json <<< "{\"apiKey\":\"$OMNIROUTE_KEY\",\"baseUrl\":\"$OMNIROUTE_URL\"}" -cat >> ~/.bashrc << EOF -export OPENAI_BASE_URL="$OMNIROUTE_URL" -export OPENAI_API_KEY="$OMNIROUTE_KEY" -export ANTHROPIC_BASE_URL="$OMNIROUTE_URL" -export ANTHROPIC_API_KEY="$OMNIROUTE_KEY" -EOF - -source ~/.bashrc -echo "โœ… All CLIs installed and configured for OmniRoute" -``` diff --git a/docs/i18n/ro/CODEBASE_DOCUMENTATION.md b/docs/i18n/ro/CODEBASE_DOCUMENTATION.md deleted file mode 100644 index e2d7950052..0000000000 --- a/docs/i18n/ro/CODEBASE_DOCUMENTATION.md +++ /dev/null @@ -1,593 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CODEBASE_DOCUMENTATION.md) - ---- - -# omniroute โ€” Codebase Documentation - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) - -> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. - ---- - -## 1. 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
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, Qoder, 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 | -| Qoder | 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"] -``` diff --git a/docs/i18n/ro/CONTRIBUTING.md b/docs/i18n/ro/CONTRIBUTING.md new file mode 100644 index 0000000000..5fa664efa9 --- /dev/null +++ b/docs/i18n/ro/CONTRIBUTING.md @@ -0,0 +1,299 @@ +# Contributing to OmniRoute (Romรขnฤƒ) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CONTRIBUTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CONTRIBUTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CONTRIBUTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CONTRIBUTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CONTRIBUTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CONTRIBUTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CONTRIBUTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CONTRIBUTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CONTRIBUTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CONTRIBUTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CONTRIBUTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CONTRIBUTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CONTRIBUTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CONTRIBUTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CONTRIBUTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CONTRIBUTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CONTRIBUTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CONTRIBUTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CONTRIBUTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CONTRIBUTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CONTRIBUTING.md) + +--- + +Thank you for your interest in contributing! This guide covers everything you need to get started. + +--- + +## Development Setup + +### Prerequisites + +- **Node.js** >= 18 < 24 (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` | `20128` | Server port | +| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | Base URL for frontend | +| `JWT_SECRET` | (generate above) | JWT signing secret | +| `INITIAL_PASSWORD` | `CHANGEME` | First login password | +| `APP_LOG_LEVEL` | `info` | Log verbosity level | + +### Dashboard Settings + +The dashboard provides UI toggles for features that can also be configured via environment variables: + +| Setting Location | Toggle | Description | +| ------------------- | ------------------ | ------------------------------ | +| Settings โ†’ Advanced | Debug Mode | Enable debug request logs (UI) | +| Settings โ†’ General | Sidebar Visibility | Show/hide sidebar sections | + +These settings are stored in the database and persist across restarts, overriding env var defaults when set. + +### 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:20128/dashboard` +- **API**: `http://localhost:20128/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`, `mcp`, `a2a`, `memory`, `skills`. + +--- + +## Running Tests + +```bash +# All tests (unit + vitest + ecosystem + e2e) +npm run test:all + +# Single test file (Node.js native test runner โ€” most tests use this) +node --import tsx/esm --test tests/unit/your-file.test.mjs + +# Vitest (MCP server, autoCombo, cache) +npm run test:vitest + +# E2E tests (requires Playwright) +npm run test:e2e + +# Protocol clients E2E (MCP transports, A2A) +npm run test:protocols:e2e + +# Ecosystem compatibility tests +npm run test:ecosystem + +# Coverage (55% min statements/lines/functions; 60% branches) +npm run test:coverage +npm run coverage:report + +# Lint + format check +npm run lint +npm run check +``` + +Coverage notes: + +- `npm run test:coverage` measures source coverage for the main unit test suite, excludes `tests/**`, and includes `open-sse/**` +- `npm run coverage:report` prints the detailed file-by-file report from the latest coverage run +- `npm run test:coverage:legacy` preserves the older metric for historical comparison +- See `docs/COVERAGE_PLAN.md` for the phased coverage improvement roadmap + +Current test status: **122 unit test files** covering: + +- Provider translators and format conversion +- Rate limiting, circuit breaker, and resilience +- Semantic cache, idempotency, progress tracking +- Database operations and schema (21 DB modules) +- OAuth flows and authentication +- API endpoint validation (Zod v4) +- MCP server tools and scope enforcement +- Memory and Skills systems + +--- + +## Code Style + +- **ESLint** โ€” Run `npm run lint` before committing +- **Prettier** โ€” Auto-formatted via `lint-staged` on commit (2 spaces, semicolons, double quotes, 100 char width, es5 trailing commas) +- **TypeScript** โ€” All `src/` code uses `.ts`/`.tsx`; `open-sse/` uses `.ts`/`.js`; document with TSDoc (`@param`, `@returns`, `@throws`) +- **No `eval()`** โ€” ESLint enforces `no-eval`, `no-implied-eval`, `no-new-func` +- **Zod validation** โ€” Use Zod v4 schemas for all API input validation +- **Naming**: Files = camelCase/kebab-case, components = PascalCase, constants = UPPER_SNAKE + +--- + +## Project Structure + +``` +src/ # TypeScript (.ts / .tsx) +โ”œโ”€โ”€ app/ # Next.js 16 App Router +โ”‚ โ”œโ”€โ”€ (dashboard)/ # Dashboard pages (23 sections) +โ”‚ โ”œโ”€โ”€ api/ # API routes (51 directories) +โ”‚ โ””โ”€โ”€ login/ # Auth pages (.tsx) +โ”œโ”€โ”€ domain/ # Policy engine (policyEngine, comboResolver, costRules, etc.) +โ”œโ”€โ”€ lib/ # Core business logic (.ts) +โ”‚ โ”œโ”€โ”€ a2a/ # Agent-to-Agent v0.3 protocol server +โ”‚ โ”œโ”€โ”€ acp/ # Agent Communication Protocol registry +โ”‚ โ”œโ”€โ”€ compliance/ # Compliance policy engine +โ”‚ โ”œโ”€โ”€ db/ # SQLite database layer (21 modules + 16 migrations) +โ”‚ โ”œโ”€โ”€ memory/ # Persistent conversational memory +โ”‚ โ”œโ”€โ”€ oauth/ # OAuth providers, services, and utilities +โ”‚ โ”œโ”€โ”€ skills/ # Extensible skill framework +โ”‚ โ”œโ”€โ”€ usage/ # Usage tracking and cost calculation +โ”‚ โ””โ”€โ”€ localDb.ts # Re-export layer only โ€” never add logic here +โ”œโ”€โ”€ middleware/ # Request middleware (promptInjectionGuard) +โ”œโ”€โ”€ mitm/ # MITM proxy (cert, DNS, target routing) +โ”œโ”€โ”€ shared/ +โ”‚ โ”œโ”€โ”€ components/ # React components (.tsx) +โ”‚ โ”œโ”€โ”€ constants/ # Provider definitions (60+), MCP scopes, routing strategies +โ”‚ โ”œโ”€โ”€ utils/ # Circuit breaker, sanitizer, auth helpers +โ”‚ โ””โ”€โ”€ validation/ # Zod v4 schemas +โ””โ”€โ”€ sse/ # SSE proxy pipeline + +open-sse/ # @omniroute/open-sse workspace +โ”œโ”€โ”€ executors/ # 14 provider-specific request executors +โ”œโ”€โ”€ handlers/ # 11 request handlers (chat, responses, embeddings, images, etc.) +โ”œโ”€โ”€ mcp-server/ # MCP server (25 tools, 3 transports, 10 scopes) +โ”œโ”€โ”€ services/ # 36+ services (combo, autoCombo, rateLimitManager, etc.) +โ”œโ”€โ”€ translator/ # Format translators (OpenAI โ†” Claude โ†” Gemini โ†” Responses โ†” Ollama) +โ”œโ”€โ”€ transformer/ # Responses API transformer +โ””โ”€โ”€ utils/ # 22 utility modules (stream, TLS, proxy, logging) + +electron/ # Electron desktop app (cross-platform) + +tests/ +โ”œโ”€โ”€ unit/ # Node.js test runner (122 test files) +โ”œโ”€โ”€ integration/ # Integration tests +โ”œโ”€โ”€ e2e/ # Playwright tests +โ”œโ”€โ”€ security/ # Security tests +โ”œโ”€โ”€ translator/ # Translator-specific tests +โ””โ”€โ”€ load/ # Load tests + +docs/ # Documentation +โ”œโ”€โ”€ ARCHITECTURE.md # System architecture +โ”œโ”€โ”€ API_REFERENCE.md # All endpoints +โ”œโ”€โ”€ USER_GUIDE.md # Provider setup, CLI integration +โ”œโ”€โ”€ TROUBLESHOOTING.md # Common issues +โ”œโ”€โ”€ MCP-SERVER.md # MCP server (25 tools) +โ”œโ”€โ”€ A2A-SERVER.md # A2A agent protocol +โ”œโ”€โ”€ AUTO-COMBO.md # Auto-combo engine +โ”œโ”€โ”€ CLI-TOOLS.md # CLI tools integration +โ”œโ”€โ”€ COVERAGE_PLAN.md # Test coverage improvement plan +โ”œโ”€โ”€ openapi.yaml # OpenAPI specification +โ””โ”€โ”€ adr/ # Architecture Decision Records +``` + +--- + +## Adding a New Provider + +### Step 1: Register Provider Constants + +Add to `src/shared/constants/providers.ts` โ€” Zod-validated at module load. + +### Step 2: Add Executor (if custom logic needed) + +Create executor in `open-sse/executors/your-provider.ts` extending the base executor. + +### Step 3: Add Translator (if non-OpenAI format) + +Create request/response translators in `open-sse/translator/`. + +### Step 4: Add OAuth Config (if OAuth-based) + +Add OAuth credentials in `src/lib/oauth/constants/oauth.ts` and service in `src/lib/oauth/services/`. + +### Step 5: Register Models + +Add model definitions in `open-sse/config/providerRegistry.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 +- [ ] All inputs validated with Zod schemas +- [ ] CHANGELOG updated (if user-facing change) +- [ ] Documentation updated (if applicable) + +--- + +## Releasing + +Releases are managed via the `/generate-release` workflow. When a new GitHub Release is created, the package is **automatically published to npm** via GitHub Actions. + +--- + +## Getting Help + +- **Architecture**: See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) +- **API Reference**: See [`docs/API_REFERENCE.md`](docs/API_REFERENCE.md) +- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **ADRs**: See `docs/adr/` for architectural decision records diff --git a/docs/i18n/ro/FEATURES.md b/docs/i18n/ro/FEATURES.md deleted file mode 100644 index 854c5833d2..0000000000 --- a/docs/i18n/ro/FEATURES.md +++ /dev/null @@ -1,147 +0,0 @@ -# OmniRoute โ€” Dashboard Features Gallery (Romรขnฤƒ) - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) - -> ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../docs/FEATURES.md) - ---- - -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 (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. - -![Providers Dashboard](screenshots/01-providers.png) - ---- - -## ๐ŸŽจ Combos - -Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. - -![Combos Dashboard](screenshots/02-combos.png) - ---- - -## ๐Ÿ“Š Analytics - -Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. - -![Analytics Dashboard](screenshots/03-analytics.png) - ---- - -## ๐Ÿฅ System Health - -Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. - -![Health Dashboard](screenshots/04-health.png) - ---- - -## ๐Ÿ”ง Translator Playground - -Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). - -![Translator Playground](screenshots/05-translator.png) - ---- - -## ๐ŸŽฎ Model Playground _(v2.0.9+)_ - -Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. - ---- - -## ๐ŸŽจ Themes _(v2.0.5+)_ - -Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. - ---- - -## โš™๏ธ Settings - -Comprehensive settings panel with tabs: - -- **General** โ€” System storage, backup management (export/import database) -- **Appearance** โ€” Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls -- **Security** โ€” API endpoint protection, custom provider blocking, IP filtering, session info -- **Routing** โ€” Model aliases, background task degradation -- **Resilience** โ€” Rate limit persistence, circuit breaker tuning -- **Advanced** โ€” Configuration overrides - -![Settings Dashboard](screenshots/06-settings.png) - ---- - -## ๐Ÿ”ง CLI Tools - -One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. - -![CLI Tools Dashboard](screenshots/07-cli-tools.png) - ---- - -## ๐Ÿค– CLI Agents _(v2.0.11+)_ - -Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: - -- **Installation status** โ€” Installed / Not Found with version detection -- **Protocol badges** โ€” stdio, HTTP, etc. -- **Custom agents** โ€” Register any CLI tool via form (name, binary, version command, spawn args) -- **CLI Fingerprint Matching** โ€” Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP - ---- - -## ๐Ÿ–ผ๏ธ Media _(v2.0.3+)_ - -Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. - ---- - -## ๐Ÿ“ Request Logs - -Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. - -![Usage Logs](screenshots/08-usage.png) - ---- - -## ๐ŸŒ API Endpoint - -Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. - -![Endpoint Dashboard](screenshots/09-endpoint.png) - ---- - -## ๐Ÿ”‘ API Key Management - -Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. - ---- - -## ๐Ÿ“‹ Audit Log - -Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. - ---- - -## ๐Ÿ–ฅ๏ธ Desktop Application - -Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. - -Key features: - -- Server readiness polling (no blank screen on cold start) -- System tray with port management -- Content Security Policy -- Single-instance lock -- Auto-update on restart -- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) -- Hardened Electron build packaging โ€” symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+) - -๐Ÿ“– See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/ro/MCP-SERVER.md b/docs/i18n/ro/MCP-SERVER.md deleted file mode 100644 index 829acd30b1..0000000000 --- a/docs/i18n/ro/MCP-SERVER.md +++ /dev/null @@ -1,87 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/MCP-SERVER.md) - ---- - -# OmniRoute MCP Server Documentation - -> Model Context Protocol server with 16 intelligent tools - -## Installation - -OmniRoute MCP is built-in. Start it with: - -```bash -omniroute --mcp -``` - -Or via the open-sse transport: - -```bash -# HTTP streamable transport (port 20130) -omniroute --dev # MCP auto-starts on /mcp endpoint -``` - -## IDE Configuration - -See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup. - ---- - -## Essential Tools (8) - -| Tool | Description | -| :------------------------------ | :--------------------------------------- | -| `omniroute_get_health` | Gateway health, circuit breakers, uptime | -| `omniroute_list_combos` | All configured combos with models | -| `omniroute_get_combo_metrics` | Performance metrics for a specific combo | -| `omniroute_switch_combo` | Switch active combo by ID/name | -| `omniroute_check_quota` | Quota status per provider or all | -| `omniroute_route_request` | Send a chat completion through OmniRoute | -| `omniroute_cost_report` | Cost analytics for a time period | -| `omniroute_list_models_catalog` | Full model catalog with capabilities | - -## Advanced Tools (8) - -| Tool | Description | -| :--------------------------------- | :---------------------------------------------- | -| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | -| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | -| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | -| `omniroute_test_combo` | Live-test all models in a combo | -| `omniroute_get_provider_metrics` | Detailed metrics for one provider | -| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | -| `omniroute_explain_route` | Explain a past routing decision | -| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | - -## Authentication - -MCP tools are authenticated via API key scopes. Each tool requires specific scopes: - -| Scope | Tools | -| :------------- | :----------------------------------------------- | -| `read:health` | get_health, get_provider_metrics | -| `read:combos` | list_combos, get_combo_metrics | -| `write:combos` | switch_combo | -| `read:quota` | check_quota | -| `write:route` | route_request, simulate_route, test_combo | -| `read:usage` | cost_report, get_session_snapshot, explain_route | -| `write:config` | set_budget_guard, set_resilience_profile | -| `read:models` | list_models_catalog, best_combo_for_task | - -## Audit Logging - -Every tool call is logged to `mcp_tool_audit` with: - -- Tool name, arguments, result -- Duration (ms), success/failure -- API key hash, timestamp - -## Files - -| File | Purpose | -| :------------------------------------------- | :------------------------------------------ | -| `open-sse/mcp-server/server.ts` | MCP server creation + 16 tool registrations | -| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport | -| `open-sse/mcp-server/auth.ts` | API key + scope validation | -| `open-sse/mcp-server/audit.ts` | Tool call audit logging | -| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers | diff --git a/docs/i18n/ro/README.md b/docs/i18n/ro/README.md index 777f2d43d6..28baab7ec9 100644 --- a/docs/i18n/ro/README.md +++ b/docs/i18n/ro/README.md @@ -1,12 +1,12 @@ # ๐Ÿš€ OmniRoute โ€” The Free AI Gateway (Romรขnฤƒ) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/README.md) --- ### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback. -_Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._ +_Your universal API proxy โ€” one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._ **Chat Completions โ€ข Embeddings โ€ข Image Generation โ€ข Video โ€ข Music โ€ข Audio โ€ข Reranking โ€ข **Web Search** โ€ข MCP Server โ€ข A2A Protocol โ€ข 100% TypeScript** @@ -46,15 +46,17 @@ _Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now wi > - `APP_LOG_FILE_PATH` > - `APP_LOG_MAX_FILE_SIZE` > - `APP_LOG_RETENTION_DAYS` +> - `APP_LOG_MAX_FILES` > - `APP_LOG_LEVEL` > - `APP_LOG_FORMAT` > - `CALL_LOG_RETENTION_DAYS` +> - `CALL_LOG_MAX_ENTRIES` > > For release details and upgrade notes, see the [CHANGELOG](CHANGELOG.md). --- -## ๐Ÿ†• What's New in v3.0.0 +## ๐Ÿ†• What's New > **Upgrading from v2.9.5?** โ€” See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes. @@ -274,7 +276,7 @@ Developers pay $20โ€“200/month for Claude Pro, Codex Pro, or GitHub Copilot. Eve - **Smart 4-Tier Fallback** โ€” If subscription quota runs out, automatically redirects to API Key โ†’ Cheap โ†’ Free with zero manual intervention - **Real-Time Quota Tracking** โ€” Shows token consumption in real-time with reset countdown (5h, daily, weekly) - **Multi-Account Support** โ€” Multiple accounts per provider with auto round-robin โ€” when one runs out, switches to the next -- **Custom Combos** โ€” Customizable fallback chains with 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Custom Combos** โ€” Customizable fallback chains with 9 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random) - **Codex Business Quotas** โ€” Business/Team workspace quota monitoring directly in the dashboard @@ -286,7 +288,7 @@ OpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If **How OmniRoute solves it:** -- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 67+ providers +- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 60+ providers - **Format Translation** โ€” Automatic and transparent: OpenAI โ†” Claude โ†” Gemini โ†” Responses API - **Response Sanitization** โ€” Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+ - **Role Normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI providers; `system` โ†’ `user` for GLM/ERNIE @@ -372,7 +374,7 @@ Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code.. - **CLI Tools Dashboard** โ€” Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline - **GitHub Copilot Config Generator** โ€” Generates `chatLanguageModels.json` for VS Code with bulk model selection - **Onboarding Wizard** โ€” Guided 4-step setup for first-time users -- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 67+ providers +- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 60+ providers @@ -419,7 +421,7 @@ When a call fails, the dev doesn't know if it was a rate limit, expired token, w - **SQLite Proxy Logs** โ€” Persistent logs that survive server restarts - **Translator Playground** โ€” 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time) - **Request Telemetry** โ€” p50/p95/p99 latency + X-Request-Id tracing -- **File-Based Logging with Rotation** โ€” Console interceptor captures everything to JSON log with size-based rotation +- **File-Based Logging with Rotation** โ€” App logs rotate by size, retention days, and archive count; call log artifacts rotate by retention days and file count - **System Info Report** โ€” `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage. @@ -514,7 +516,7 @@ Developers who want all responses in a specific language, with a specific tone, - **System Prompt Injection** โ€” Global prompt applied to all requests - **Thinking Budget Validation** โ€” Reasoning token allocation control per request (passthrough, auto, custom, adaptive) -- **6 Routing Strategies** โ€” Global strategies that determine how requests are distributed +- **9 Routing Strategies** โ€” Global strategies that determine how requests are distributed - **Wildcard Router** โ€” `provider/*` patterns route dynamically to any provider - **Combo Enable/Disable Toggle** โ€” Toggle combos directly from the dashboard - **Provider Toggle** โ€” Enable/disable all connections for a provider with one click @@ -581,7 +583,7 @@ Different clients should have least-privilege access to tool categories. **How OmniRoute solves it:** -- 9 granular MCP scopes for controlled tool access +- 10 granular MCP scopes for controlled tool access - Scope enforcement and visibility in MCP management UI - Safe default posture for operational tooling @@ -1325,19 +1327,19 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. ### ๐Ÿค– Agent & Protocol Operations (v2.0) -| Feature | What It Does | -| ------------------------------------- | -------------------------------------------------------------------------------------------------- | -| ๐Ÿ”ง **MCP Server (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) | -| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | -| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | -| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | -| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | -| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | -| ๐Ÿ” **MCP Scope Enforcement** | 9 granular scope permissions for controlled tool access | -| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | -| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | -| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | -| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | +| Feature | What It Does | +| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| ๐Ÿ”ง **MCP Server (25 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools | +| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | +| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | +| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | +| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | +| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | +| ๐Ÿ” **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access | +| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | +| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | +| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | +| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | ### ๐Ÿง  Routing & Intelligence @@ -1348,7 +1350,7 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. | ๐Ÿ”„ **Format Translation** | OpenAI โ†” Claude โ†” Gemini โ†” Responses with schema-safe conversions | | ๐Ÿ‘ฅ **Multi-Account Support** | Multiple accounts per provider with intelligent selection | | ๐Ÿ”„ **Auto Token Refresh** | OAuth tokens refresh automatically with retry | -| ๐ŸŽจ **Custom Combos** | 6 balancing strategies + fallback chain control | +| ๐ŸŽจ **Custom Combos** | 9 balancing strategies + fallback chain control | | ๐ŸŒ **Wildcard Router** | `provider/*` dynamic routing | | ๐Ÿง  **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits | | ๐Ÿ”€ **Model Aliases** | Built-in + custom model aliasing and migration safety | @@ -1949,6 +1951,7 @@ opencode - Request artifacts are written to `DATA_DIR/call_logs/` as one JSON file per request - Enable pipeline capture from Dashboard โ†’ Logs โ†’ Request Logs if you need detailed per-stage payloads - Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log` +- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed **Connection test shows "Invalid" for OpenAI-compatible providers** diff --git a/docs/i18n/ro/RELEASE_CHECKLIST.md b/docs/i18n/ro/RELEASE_CHECKLIST.md deleted file mode 100644 index 903e812c3f..0000000000 --- a/docs/i18n/ro/RELEASE_CHECKLIST.md +++ /dev/null @@ -1,37 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/RELEASE_CHECKLIST.md) - ---- - -# Release Checklist - -Use this checklist before tagging or publishing a new OmniRoute release. - -## Version and Changelog - -1. Bump `package.json` version (`x.y.z`) in the release branch. -2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: - - `## [x.y.z] โ€” YYYY-MM-DD` -3. Keep `## [Unreleased]` as the first changelog section for upcoming work. -4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. - -## API Docs - -1. Update `docs/openapi.yaml`: - - `info.version` must equal `package.json` version. -2. Validate endpoint examples if API contracts changed. - -## Runtime Docs - -1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. -2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. -3. Update localized docs if source docs changed significantly. - -## Automated Check - -Run the sync guard locally before opening PR: - -```bash -npm run check:docs-sync -``` - -CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/ro/SECURITY.md b/docs/i18n/ro/SECURITY.md new file mode 100644 index 0000000000..7f9c3f518c --- /dev/null +++ b/docs/i18n/ro/SECURITY.md @@ -0,0 +1,179 @@ +# Security Policy (Romรขnฤƒ) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../SECURITY.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/SECURITY.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/SECURITY.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/SECURITY.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/SECURITY.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/SECURITY.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/SECURITY.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/SECURITY.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/SECURITY.md) + +--- + +## 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 | +| ------- | -------------- | +| 3.4.x | โœ… Active | +| 3.0.x | โœ… Security | +| < 3.0.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 | +| **MCP Scopes** | 10 granular scopes for MCP tool access control | + +### ๐Ÿ›ก๏ธ 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:::` +- 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** | Allowlist/blocklist IP ranges in dashboard | +| **Rate Limiting** | Per-provider rate limits with automatic backoff | +| **Anti-Thundering Herd** | Mutex + per-connection locking prevents cascading 502s | +| **TLS Fingerprint** | Browser-like TLS fingerprint spoofing to reduce bot detection | +| **CLI Fingerprint** | Per-provider header/body ordering to match native CLI signatures | + +### ๐Ÿ”Œ Resilience & Availability + +| 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 `CALL_LOG_RETENTION_DAYS` | +| **No-Log Opt-out** | Per API key `noLog` flag disables request logging | +| **Audit Log** | Administrative actions tracked in `audit_log` table | +| **MCP Audit** | SQLite-backed audit logging for all MCP tool calls | +| **Zod Validation** | All API inputs validated with Zod v4 schemas at module load | + +--- + +## 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 +- Provider constants validated at module load via Zod (`src/shared/validation/providerSchema.ts`) diff --git a/docs/i18n/ro/TROUBLESHOOTING.md b/docs/i18n/ro/TROUBLESHOOTING.md deleted file mode 100644 index 63c148000a..0000000000 --- a/docs/i18n/ro/TROUBLESHOOTING.md +++ /dev/null @@ -1,258 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/TROUBLESHOOTING.md) - ---- - -# Troubleshooting - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/TROUBLESHOOTING.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/TROUBLESHOOTING.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/TROUBLESHOOTING.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/TROUBLESHOOTING.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/TROUBLESHOOTING.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/TROUBLESHOOTING.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/TROUBLESHOOTING.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/TROUBLESHOOTING.md) - -Common problems and solutions for OmniRoute. - ---- - -## Quick Fixes - -| Problem | Solution | -| ----------------------------- | ------------------------------------------------------------------ | -| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | -| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | -| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | -| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | -| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | - ---- - -## Provider Issues - -### "Language model did not provide messages" - -**Cause:** Provider quota exhausted. - -**Fix:** - -1. 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, Qoder) 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}/storage.sqlite` (providers, combos, aliases, keys, settings) -- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` -- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) - ---- - -## Circuit Breaker Issues - -### Provider stuck in OPEN state - -When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. - -**Fix:** - -1. 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 -- **SDK returns raw string instead of object** โ€” Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures -- **GLM/ERNIE rejects `system` role** โ€” Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models -- **`developer` role not recognized** โ€” Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers -- **`json_schema` not working with Gemini** โ€” Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` - ---- - -## Resilience Settings - -### Auto rate-limit not triggering - -- 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. - ---- - -## Optional RAG / LLM failure taxonomy (16 problems) - -Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. - -In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. - -If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: - -- retrieval drift and broken context boundaries -- empty or stale indexes and vector stores -- embedding versus semantic mismatch -- prompt assembly and context window issues -- logic collapse and overconfident answers -- long chain and agent coordination failures -- multi agent memory and role drift -- deployment and bootstrap ordering problems - -The idea is simple: - -1. When you investigate a bad response, capture: - - user task and request - - route or provider combo in OmniRoute - - any RAG context used downstream (retrieved documents, tool calls, etc) -2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` โ€ฆ `No.16`). -3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. -4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. - -Full text and concrete recipes live here (MIT license, text only): - -[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) - -You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. - ---- - -## Still Stuck? - -- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details -- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints -- **Health Dashboard**: Check **Dashboard โ†’ Health** for real-time system status -- **Translator**: Use **Dashboard โ†’ Translator** to debug format issues diff --git a/docs/i18n/ro/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/ro/VM_DEPLOYMENT_GUIDE.md deleted file mode 100644 index eb05ebbeef..0000000000 --- a/docs/i18n/ro/VM_DEPLOYMENT_GUIDE.md +++ /dev/null @@ -1,401 +0,0 @@ -# OmniRoute โ€” Ghid de implementare pe VM cu Cloudflare - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](../pt-BR/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](../es/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](../fr/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](../it/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](../ru/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](../zh-CN/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](../de/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](../in/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](../th/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](../uk-UA/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](../ar/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](../ja/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](../vi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](../bg/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](../da/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](../fi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](../he/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](../hu/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](../id/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](../ko/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](../ms/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](../nl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](../no/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](../pt/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](../ro/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](../pl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](../sk/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](../sv/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](../phi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](../cs/VM_DEPLOYMENT_GUIDE.md) - -Ghid complet pentru instalarea ศ™i configurarea OmniRoute pe o VM (VPS) cu domeniu gestionat prin Cloudflare. - ---- - -## Cerinศ›e preliminare - -| Articol | Minimum | Recomandat | -| ----------- | ------------------------- | ---------------- | -| **CPU** | 1 vCPU | 2 vCPU | -| **RAM** | 1 GB | 2 GB | -| **Disc** | SSD de 10 GB | SSD de 25 GB | -| **OS** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS | -| **Domeniu** | รŽnregistrat pe Cloudflare | โ€” | -| **Docker** | Docker Engine 24+ | Docker 27+ | - -**Furnizori testaศ›i**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. - ---- - -## 1. Configuraศ›i VM - -### 1.1 Creaศ›i instanศ›a - -Pe furnizorul dvs. VPS preferat: - -- Alegeศ›i Ubuntu 24.04 LTS -- Selectaศ›i planul minim (1 vCPU / 1 GB RAM) -- Setaศ›i o parolฤƒ de root puternicฤƒ sau configuraศ›i cheia SSH -- Reศ›ineศ›i **IP-ul public** (de exemplu, `203.0.113.10`) - -### 1.2 Conectaศ›i-vฤƒ prin SSH - -```bash -ssh root@203.0.113.10 -``` - -### 1.3 Actualizaศ›i sistemul - -```bash -apt update && apt upgrade -y -``` - -### 1.4 Instalaศ›i Docker - -```bash -# Install dependencies -apt install -y ca-certificates curl gnupg - -# Add official Docker repository -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 Instalaศ›i nginx - -```bash -apt install -y nginx -``` - -### 1.6 Configuraศ›i 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 -``` - -> **Sfat**: pentru securitate maximฤƒ, restricศ›ionaศ›i porturile 80 ศ™i 443 doar la IP-uri Cloudflare. Consultaศ›i secศ›iunea [Advanced Security](#advanced-security). - ---- - -## 2. Instalaศ›i OmniRoute - -### 2.1 Creaศ›i directorul de configurare - -```bash -mkdir -p /opt/omniroute -``` - -### 2.2 Creaศ›i fiศ™ierul cu variabile de mediu - -```bash -cat > /opt/omniroute/.env << โ€˜EOFโ€™ -# === Security === -JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY -INITIAL_PASSWORD=YourSecurePassword123! -API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY -STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY -STORAGE_ENCRYPTION_KEY_VERSION=v1 -MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT - -# === 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 (change to your domain) === -BASE_URL=https://llms.seudominio.com -NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com - -# === Cloud Sync (optional) === -# CLOUD_URL=https://cloud.omniroute.online -# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online -EOF -``` - -> โš ๏ธ **IMPORTANT**: Generaศ›i chei secrete unice! Folosiศ›i `openssl rand -hex 32` pentru fiecare cheie. - -### 2.3 Porniศ›i containerul - -```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 Verificaศ›i dacฤƒ ruleazฤƒ - -```bash -docker ps | grep omniroute -docker logs omniroute --tail 20 -``` - -Ar trebui sฤƒ afiศ™eze: `[DB] SQLite database ready` ศ™i `listening on port 20128`. - ---- - -## 3. Configuraศ›i nginx (proxy invers) - -### 3.1 Generaศ›i certificat SSL (Cloudflare Origin) - -รŽn tabloul de bord Cloudflare: - -1. Accesaศ›i **SSL/TLS โ†’ Origin Server** -2. Faceศ›i clic pe **Creaศ›i certificat** -3. Pฤƒstreazฤƒ valorile implicite (15 ani, \*.domeniul tฤƒu.com) -4. Copiaศ›i **Certificatul de origine** ศ™i **Cheia privatฤƒ** - -```bash -mkdir -p /etc/nginx/ssl - -# Paste the certificate -nano /etc/nginx/ssl/origin.crt - -# Paste the private key -nano /etc/nginx/ssl/origin.key - -chmod 600 /etc/nginx/ssl/origin.key -``` - -### 3.2 Configurare Nginx - -```bash -cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ -# Default server โ€” blocks direct access via 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.yourdomain.com; # Change to your domain - - 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.yourdomain.com; - return 301 https://$server_name$request_uri; -} -NGINX -``` - -### 3.3 Activare ศ™i testare - -```bash -# Remove default configuration -rm -f /etc/nginx/sites-enabled/default - -# Enable OmniRoute -ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute - -# Test and reload -nginx -t && systemctl reload nginx -``` - ---- - -## 4. Configuraศ›i Cloudflare DNS - -### 4.1 Adฤƒugaศ›i รฎnregistrarea DNS - -รŽn tabloul de bord Cloudflare โ†’ DNS: - -| Tip | Nume | Conศ›inut | Proxy | -| --- | ------ | ---------------------- | -------- | -| A | `llms` | `203.0.113.10` (IP VM) | โœ… Proxy | - -### 4.2 Configuraศ›i SSL - -Sub **SSL/TLS โ†’ Prezentare generalฤƒ**: - -- Mod: **Complet (strict)** - -Sub **SSL/TLS โ†’ Certificate Edge**: - -- Utilizaศ›i รฎntotdeauna HTTPS: โœ… Activat -- Versiune TLS minimฤƒ: TLS 1.2 -- Rescrieri automate HTTPS: โœ… Activat - -### 4.3 Testare - -```bash -curl -sI https://llms.seudominio.com/health -# Should return HTTP/2 200 -``` - ---- - -## 5. Operaศ›iuni ศ™i รฎntreศ›inere - -### Faceศ›i upgrade la o versiune nouฤƒ - -```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 -``` - -### Vizualizaศ›i jurnalele - -```bash -docker logs -f omniroute # Real-time stream -docker logs omniroute --tail 50 # Last 50 lines -``` - -### Backup manual al bazei de date - -```bash -# Copy data from the volume to the host -docker cp omniroute:/app/data ./backup-$(date +%F) - -# Or compress the entire volume -docker run --rm -v omniroute-data:/data -v $(pwd):/backup \ - alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data -``` - -### Restauraศ›i din 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. Securitate avansatฤƒ - -### Restricศ›ionaศ›i nginx la IP-urile Cloudflare - -```bash -cat > /etc/nginx/cloudflare-ips.conf << โ€˜CFโ€™ -# Cloudflare IPv4 ranges โ€” update periodically -# 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 -``` - -Adฤƒugaศ›i urmฤƒtoarele la `nginx.conf` รฎn interiorul blocului `http {}`: - -```nginx -include /etc/nginx/cloudflare-ips.conf; -``` - -### Instalaศ›i fail2ban - -```bash -apt install -y fail2ban -systemctl enable fail2ban -systemctl start fail2ban - -# Check status -fail2ban-client status sshd -``` - -### Blocaศ›i accesul direct la portul Docker - -```bash -# Prevent direct external access to port 20128 -iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP -iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT - -# Persist the rules -apt install -y iptables-persistent -netfilter-persistent save -``` - ---- - -## 7. Implementaศ›i la lucrฤƒtorii Cloudflare (opศ›ional) - -Pentru acces la distanศ›ฤƒ prin Cloudflare Workers (fฤƒrฤƒ a expune VM-ul direct): - -```bash -# In the local repository -cd omnirouteCloud -npm install -npx wrangler login -npx wrangler deploy -``` - -Consultaศ›i documentaศ›ia completฤƒ la [omnirouteCloud/README.md](../omnirouteCloud/README.md). - ---- - -## Rezumatul portului - -| Port | Serviciu | Acces | -| ----- | ----------- | ---------------------------- | -| 22 | SSH | Public (cu fail2ban) | -| 80 | nginx HTTP | Redirecศ›ionare โ†’ HTTPS | -| 443 | nginx HTTPS | Prin Cloudflare Proxy | -| 20128 | OmniRoute | Numai Localhost (prin nginx) | diff --git a/docs/i18n/ro/docs/A2A-SERVER.md b/docs/i18n/ro/docs/A2A-SERVER.md new file mode 100644 index 0000000000..4a9798d9b3 --- /dev/null +++ b/docs/i18n/ro/docs/A2A-SERVER.md @@ -0,0 +1,200 @@ +# OmniRoute A2A Server Documentation (Romรขnฤƒ) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/A2A-SERVER.md) + +--- + +> Agent-to-Agent Protocol v0.3 โ€” OmniRoute as an intelligent routing agent + +## Agent Discovery + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements. + +--- + +## Authentication + +All `/a2a` requests require an API key via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server, authentication is bypassed. + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Sends a message to a skill and waits for the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a hello world in Python"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "uuid", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "..." }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}} + +: heartbeat 2026-03-03T17:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Available Skills + +| Skill | Description | +| :----------------- | :------------------------------------------------------------------------------------------------------------------------------ | +| `smart-routing` | Routes prompts through OmniRoute's intelligent pipeline. Returns response with routing explanation, cost, and resilience trace. | +| `quota-management` | Answers natural-language queries about provider quotas, suggests free combos, and provides quota rankings. | + +--- + +## Task Lifecycle + +``` +submitted โ†’ working โ†’ completed + โ†’ failed + โ†’ cancelled +``` + +- Tasks expire after 5 minutes (configurable) +- Terminal states: `completed`, `failed`, `cancelled` +- Event log tracks every state transition + +--- + +## Error Codes + +| Code | Meaning | +| :----- | :----------------------------- | +| -32700 | Parse error (invalid JSON) | +| -32600 | Invalid request / Unauthorized | +| -32601 | Method or skill not found | +| -32602 | Invalid params | +| -32603 | Internal error | + +--- + +## Integration Examples + +### Python (requests) + +```python +import requests + +resp = requests.post("http://localhost:20128/a2a", json={ + "jsonrpc": "2.0", "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Hello"}] + } +}, headers={"Authorization": "Bearer YOUR_KEY"}) + +result = resp.json()["result"] +print(result["artifacts"][0]["content"]) +print(result["metadata"]["routing_explanation"]) +``` + +### TypeScript (fetch) + +```typescript +const resp = await fetch("http://localhost:20128/a2a", { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: "Bearer YOUR_KEY", + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "1", + method: "message/send", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Hello" }], + }, + }), +}); +const { result } = await resp.json(); +console.log(result.metadata.routing_explanation); +``` diff --git a/docs/i18n/ro/docs/API_REFERENCE.md b/docs/i18n/ro/docs/API_REFERENCE.md new file mode 100644 index 0000000000..219edd86bd --- /dev/null +++ b/docs/i18n/ro/docs/API_REFERENCE.md @@ -0,0 +1,465 @@ +# API Reference (Romรขnฤƒ) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/API_REFERENCE.md) + +--- + +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 | +| `X-Session-Id` | Request | Sticky session key for external session affinity | +| `x_session_id` | Request | Underscore variant also accepted (direct HTTP) | +| `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 | +| `X-OmniRoute-Session-Id` | Response | Effective session ID used by OmniRoute | + +> Nginx note: if you rely on underscore headers (for example `x_session_id`), enable `underscores_in_headers 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/stats + +# Clear all caches +DELETE /api/cache/stats +``` + +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/PATCH | 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 + provider summary (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`) | +| `/api/cache/stats` | 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 | + +### Tunnels + +| Endpoint | Method | Description | +| -------------------------- | ------ | ----------------------------------------------------------------------- | +| `/api/tunnels/cloudflared` | GET | Read Cloudflare Quick Tunnel install/runtime status for the dashboard | +| `/api/tunnels/cloudflared` | POST | Enable or disable the Cloudflare Quick Tunnel (`action=enable/disable`) | + +### 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`. + +### ACP Agents + +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | + +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). + +### Resilience & Rate Limits + +| Endpoint | Method | Description | +| ----------------------- | --------- | ------------------------------- | +| `/api/resilience` | GET/PATCH | 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` diff --git a/docs/i18n/ro/docs/ARCHITECTURE.md b/docs/i18n/ro/docs/ARCHITECTURE.md new file mode 100644 index 0000000000..5860f818d6 --- /dev/null +++ b/docs/i18n/ro/docs/ARCHITECTURE.md @@ -0,0 +1,814 @@ +# OmniRoute Architecture (Romรขnฤƒ) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/ARCHITECTURE.md) + +--- + +_Last updated: 2026-03-28_ + +## 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 (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developerโ†’system, systemโ†’user) for cross-provider compatibility +- Structured output conversion (json_schema โ†’ Gemini responseSchema) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) +- Global system prompt injection +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout โ†’ budget โ†’ fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) + +Primary runtime model: + +- Next.js 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.) + +## Dashboard Surface (Current) + +Main pages under `src/app/(dashboard)/dashboard/`: + +- `/dashboard` โ€” quick start + provider overview +- `/dashboard/endpoint` โ€” endpoint proxy + MCP + A2A + API endpoint tabs +- `/dashboard/providers` โ€” provider connections and credentials +- `/dashboard/combos` โ€” combo strategies, templates, model routing rules +- `/dashboard/costs` โ€” cost aggregation and pricing visibility +- `/dashboard/analytics` โ€” usage analytics and evaluations +- `/dashboard/limits` โ€” quota/rate controls +- `/dashboard/cli-tools` โ€” CLI onboarding, runtime detection, config generation +- `/dashboard/agents` โ€” detected ACP agents + custom agent registration +- `/dashboard/media` โ€” image/video/music playground +- `/dashboard/search-tools` โ€” search provider testing and history +- `/dashboard/health` โ€” uptime, circuit breakers, rate limits +- `/dashboard/logs` โ€” request/proxy/audit/console logs +- `/dashboard/settings` โ€” system settings tabs (general, routing, combo defaults, etc.) +- `/dashboard/api-manager` โ€” API key lifecycle and model permissions + +## 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[(storage.sqlite)] + UDB[(usage tables + log artifacts)] + end + + subgraph Upstreams[Upstream Providers] + P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/Qoder/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/route.ts` (GET) +- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- OAuth: `src/app/api/oauth/*` +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` +- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI tooling helpers: `src/app/api/cli-tools/*` +- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) +- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) โ€” provider profiles, circuit breaker, rate limit state +- Resilience reset: `src/app/api/resilience/reset` (POST) โ€” reset breakers + cooldowns +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) +- Telemetry: `src/app/api/telemetry/summary` (GET) +- Budget: `src/app/api/usage/budget` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Policies: `src/app/api/policies` (GET/POST) + +## 2) SSE + 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` +- Response sanitization: `open-sse/handlers/responseSanitizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.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`, `qoder.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 (SQLite): + +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** + +Usage persistence: + +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present + +Domain State DB (SQLite): + +- `src/lib/db/domainState.ts` โ€” CRUD operations 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`, `src/shared/services/modelSyncScheduler.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Periodic task: `src/shared/services/modelSyncScheduler.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. Combo routing adds one extra guard: provider-scoped 400s such as upstream content-block and role-validation failures are treated as model-local failures so later combo targets can still run. + +## 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: + +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` + +## Deployment Topology + +```mermaid +flowchart LR + 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[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] + end + + subgraph External[External Services] + Providers[AI Providers] + SyncCloud[Cloud Sync Service] + end + + CLI --> Next + Browser --> Next + Next --> Core + Next --> MainDB + Core --> MainDB + Core --> UsageDB + Core --> Providers + Next --> SyncCloud +``` + +## Module Mapping (Decision-Critical) + +### Route and API Modules + +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle +- `src/app/api/models/alias`: alias management +- `src/app/api/combos*`: fallback combo management +- `src/app/api/pricing`: pricing overrides for cost calculation +- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers +- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) +- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) +- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) +- `src/app/api/sessions`: active session listing (GET) +- `src/app/api/rate-limits`: per-account rate limit status (GET) + +### Routing and Execution Core + +- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior + +### Translation Registry and Format Converters + +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` +- Format constants: `open-sse/translator/formats.ts` + +### Persistence + +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables + +## Provider Executor Coverage (Strategy Pattern) + +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. + +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, Qoder, 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 | +| Qoder | openai | OAuth (Basic) | โœ… | โœ… | โœ… | โš ๏ธ Per request | +| OpenRouter | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| GLM/Kimi/MiniMax | claude | API Key | โœ… | โœ… | โŒ | โŒ | +| DeepSeek | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Groq | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| xAI (Grok) | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Mistral | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Perplexity | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Together AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Fireworks AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Cerebras | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Cohere | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| NVIDIA NIM | openai | API Key | โœ… | โœ… | โŒ | โŒ | + +## Format Translation Coverage + +Detected source formats include: + +- `openai` +- `openai-responses` +- `claude` +- `gemini` + +Target formats include: + +- OpenAI chat/Responses +- Claude +- Gemini/Gemini-CLI/Antigravity envelope +- Kiro +- Cursor + +Translations use **OpenAI as the hub format** โ€” all conversions go through OpenAI as intermediate: + +``` +Source Format โ†’ OpenAI (hub) โ†’ Target Format +``` + +Translations are selected dynamically based on source payload shape and provider target format. + +Additional processing layers in the translation pipeline: + +- **Response sanitization** โ€” Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI targets; merges `system` โ†’ `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** โ€” Parses `...` blocks from content into `reasoning_content` field +- **Structured output** โ€” Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` + +## Supported API Endpoints + +| 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` | Provider Models | Provider model metadata backing custom and managed available models | + +## 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 `/logs//` 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 + +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON โ†’ SQLite migration compatibility path + +## Observability and Operational Signals + +Runtime visibility sources: + +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- four-stage detailed payload captures in SQLite (`request_detail_logs`) when `settings.detailed_logs_enabled=true` +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption + +Detailed request payload capture stores up to four JSON payload stages per routed call: + +- raw request received from the client +- translated request actually sent upstream +- provider response reconstructed as JSON; streamed responses are compacted to the final summary plus stream metadata +- final client response returned by OmniRoute; streamed responses are stored in the same compact summary form + +## Security-Sensitive Boundaries + +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics + +## Environment and Runtime Matrix + +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` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). + +## Operational Verification Checklist + +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: +- `GET /api/settings` +- `GET /api/v1/models` +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/ro/docs/AUTO-COMBO.md b/docs/i18n/ro/docs/AUTO-COMBO.md new file mode 100644 index 0000000000..66c17e842e --- /dev/null +++ b/docs/i18n/ro/docs/AUTO-COMBO.md @@ -0,0 +1,67 @@ +# OmniRoute Auto-Combo Engine (Romรขnฤƒ) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/AUTO-COMBO.md) + +--- + +> Self-managing model chains with adaptive scoring + +## How It Works + +The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**: + +| Factor | Weight | Description | +| :--------- | :----- | :---------------------------------------------- | +| Quota | 0.20 | Remaining capacity [0..1] | +| Health | 0.25 | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 | +| CostInv | 0.20 | Inverse cost (cheaper = higher score) | +| LatencyInv | 0.15 | Inverse p95 latency (faster = higher) | +| TaskFit | 0.10 | Model ร— task type fitness score | +| Stability | 0.10 | Low variance in latency/errors | + +## Mode Packs + +| Pack | Focus | Key Weight | +| :---------------------- | :----------- | :--------------- | +| ๐Ÿš€ **Ship Fast** | Speed | latencyInv: 0.35 | +| ๐Ÿ’ฐ **Cost Saver** | Economy | costInv: 0.40 | +| ๐ŸŽฏ **Quality First** | Best model | taskFit: 0.40 | +| ๐Ÿ“ก **Offline Friendly** | Availability | quota: 0.40 | + +## Self-Healing + +- **Temporary exclusion**: Score < 0.2 โ†’ excluded for 5 min (progressive backoff, max 30 min) +- **Circuit breaker awareness**: OPEN โ†’ auto-excluded; HALF_OPEN โ†’ probe requests +- **Incident mode**: >50% OPEN โ†’ disable exploration, maximize stability +- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout + +## Bandit Exploration + +5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode. + +## API + +```bash +# Create auto-combo +curl -X POST http://localhost:20128/api/combos/auto \ + -H "Content-Type: application/json" \ + -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}' + +# List auto-combos +curl http://localhost:20128/api/combos/auto +``` + +## Task Fitness + +30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` โ†’ high coding score). + +## Files + +| File | Purpose | +| :------------------------------------------- | :------------------------------------ | +| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization | +| `open-sse/services/autoCombo/taskFitness.ts` | Model ร— task fitness lookup | +| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap | +| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode | +| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles | +| `src/app/api/combos/auto/route.ts` | REST API | diff --git a/docs/i18n/ar/CLI-TOOLS.md b/docs/i18n/ro/docs/CLI-TOOLS.md similarity index 66% rename from docs/i18n/ar/CLI-TOOLS.md rename to docs/i18n/ro/docs/CLI-TOOLS.md index 1824f64067..9496719c09 100644 --- a/docs/i18n/ar/CLI-TOOLS.md +++ b/docs/i18n/ro/docs/CLI-TOOLS.md @@ -1,8 +1,8 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CLI-TOOLS.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CLI-TOOLS.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CLI-TOOLS.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CLI-TOOLS.md) +# CLI Tools Setup Guide โ€” OmniRoute (Romรขnฤƒ) -# ุฏู„ูŠู„ ุฅุนุฏุงุฏ ุฃุฏูˆุงุช CLI โ€” OmniRoute +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CLI-TOOLS.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CLI-TOOLS.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CLI-TOOLS.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CLI-TOOLS.md) -ูŠุดุฑุญ ู‡ุฐุง ุงู„ุฏู„ูŠู„ ูƒูŠููŠุฉ ุชุซุจูŠุช ูˆุชู‡ูŠุฆุฉ ุฌู…ูŠุน ุฃุฏูˆุงุช CLI ุงู„ู…ุฏุนูˆู…ุฉ ู„ุงุณุชุฎุฏุงู… **OmniRoute** ูƒุฎู„ููŠุฉ ู…ูˆุญุฏุฉ. +--- This guide explains how to install and configure all supported AI coding CLI tools to use **OmniRoute** as the unified backend, giving you centralized key management, @@ -13,7 +13,7 @@ cost tracking, model switching, and request logging across every tool. ## How It Works ``` -Claude / Codex / Gemini CLI / OpenCode / Cline / KiloCode / Continue / Kiro CLI +Claude / Codex / OpenCode / Cline / KiloCode / Continue / Kiro / Cursor / Copilot โ”‚ โ–ผ (all point to OmniRoute) http://YOUR_SERVER:20128/v1 @@ -31,21 +31,38 @@ Claude / Codex / Gemini CLI / OpenCode / Cline / KiloCode / Continue / Kiro CLI --- -## Supported Tools +## Supported Tools (Dashboard Source of Truth) -| Tool | Command | Type | Install Method | -| ---------------- | ------------------- | ----------------- | -------------- | -| **Claude Code** | `claude` | CLI | npm | -| **OpenAI Codex** | `codex` | CLI | npm | -| **Gemini CLI** | `gemini` | CLI | npm | -| **OpenCode** | `opencode` | CLI | npm | -| **Cline** | `cline` | CLI + VS Code ext | npm | -| **KiloCode** | `kilocode` / `kilo` | CLI + VS Code ext | npm | -| **Continue** | guide-based | VS Code ext | VS Code | -| **Kiro CLI** | `kiro-cli` | CLI | curl installer | -| **Cursor** | `cursor` | Desktop app | Download | -| **Droid** | web-based | Built-in agent | OmniRoute | -| **OpenClaw** | web-based | Built-in agent | OmniRoute | +The dashboard cards in `/dashboard/cli-tools` are generated from `src/shared/constants/cliTools.ts`. +Current list (v3.0.0-rc.16): + +| Tool | ID | Command | Setup Mode | Install Method | +| ------------------ | ------------- | ---------- | ---------- | -------------- | +| **Claude Code** | `claude` | `claude` | env | npm | +| **OpenAI Codex** | `codex` | `codex` | custom | npm | +| **Factory Droid** | `droid` | `droid` | custom | bundled/CLI | +| **OpenClaw** | `openclaw` | `openclaw` | custom | bundled/CLI | +| **Cursor** | `cursor` | app | guide | desktop app | +| **Cline** | `cline` | `cline` | custom | npm | +| **Kilo Code** | `kilo` | `kilocode` | custom | npm | +| **Continue** | `continue` | extension | guide | VS Code | +| **Antigravity** | `antigravity` | internal | mitm | OmniRoute | +| **GitHub Copilot** | `copilot` | extension | custom | VS Code | +| **OpenCode** | `opencode` | `opencode` | guide | npm | +| **Kiro AI** | `kiro` | app/cli | mitm | desktop/CLI | + +### CLI fingerprint sync (Agents + Settings) + +`/dashboard/agents` and `Settings > CLI Fingerprint` use `src/shared/constants/cliCompatProviders.ts`. +This keeps provider IDs aligned with CLI cards and legacy IDs. + +| CLI ID | Fingerprint Provider ID | +| ---------------------------------------------------------------------------------------------------- | ----------------------- | +| `kilo` | `kilocode` | +| `copilot` | `github` | +| `claude` / `codex` / `antigravity` / `kiro` / `cursor` / `cline` / `opencode` / `droid` / `openclaw` | same ID | + +Legacy IDs still accepted for compatibility: `copilot`, `kimi-coding`, `qwen`. --- @@ -71,9 +88,6 @@ npm install -g @anthropic-ai/claude-code # OpenAI Codex npm install -g @openai/codex -# Gemini CLI (Google) -npm install -g @google/gemini-cli - # OpenCode npm install -g opencode-ai @@ -81,7 +95,7 @@ npm install -g opencode-ai npm install -g cline # KiloCode -npm install -g kilecode +npm install -g kilocode # Kiro CLI (Amazon โ€” requires curl + unzip) apt-get install -y unzip # on Debian/Ubuntu @@ -94,7 +108,6 @@ export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc ```bash claude --version # 2.x.x codex --version # 0.x.x -gemini --version # 0.x.x opencode --version # x.x.x cline --version # 2.x.x kilocode --version # x.x.x (or: kilo --version) @@ -157,21 +170,6 @@ EOF --- -### Gemini CLI - -```bash -mkdir -p ~/.gemini && cat > ~/.gemini/settings.json << EOF -{ - "apiKey": "sk-your-omniroute-key", - "baseUrl": "http://localhost:20128/v1" -} -EOF -``` - -**Test:** `gemini "hello"` - ---- - ### OpenCode ```bash @@ -308,7 +306,7 @@ They run as internal routes and use OmniRoute's model routing automatically. --- -## Troubleshooting +## Depanare | Error | Cause | Fix | | ------------------------- | ----------------------- | ------------------------------------------ | @@ -328,17 +326,16 @@ They run as internal routes and use OmniRoute's model routing automatically. OMNIROUTE_URL="http://localhost:20128/v1" OMNIROUTE_KEY="sk-your-omniroute-key" -npm install -g @anthropic-ai/claude-code @openai/codex @google/gemini-cli opencode-ai cline kilecode +npm install -g @anthropic-ai/claude-code @openai/codex opencode-ai cline kilocode # Kiro CLI apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash # Write configs -mkdir -p ~/.claude ~/.codex ~/.gemini ~/.config/opencode ~/.continue +mkdir -p ~/.claude ~/.codex ~/.config/opencode ~/.continue cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" -cat > ~/.gemini/settings.json <<< "{\"apiKey\":\"$OMNIROUTE_KEY\",\"baseUrl\":\"$OMNIROUTE_URL\"}" cat >> ~/.bashrc << EOF export OPENAI_BASE_URL="$OMNIROUTE_URL" export OPENAI_API_KEY="$OMNIROUTE_KEY" diff --git a/docs/i18n/ro/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/ro/docs/CODEBASE_DOCUMENTATION.md new file mode 100644 index 0000000000..686703bf0f --- /dev/null +++ b/docs/i18n/ro/docs/CODEBASE_DOCUMENTATION.md @@ -0,0 +1,591 @@ +# omniroute โ€” Codebase Documentation (Romรขnฤƒ) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CODEBASE_DOCUMENTATION.md) + +--- + +> 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
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, Qoder, 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. + +#### Arhitecturฤƒ + +```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 | +| Qoder | 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"] +``` diff --git a/docs/i18n/ro/docs/COVERAGE_PLAN.md b/docs/i18n/ro/docs/COVERAGE_PLAN.md new file mode 100644 index 0000000000..92d3d4141a --- /dev/null +++ b/docs/i18n/ro/docs/COVERAGE_PLAN.md @@ -0,0 +1,170 @@ +# Test Coverage Plan (Romรขnฤƒ) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/COVERAGE_PLAN.md) + +--- + +Last updated: 2026-03-28 + +## Baseline + +There are multiple coverage numbers depending on how the report is computed. For planning, only one of them is useful. + +| Metric | Scope | Statements / Lines | Branches | Functions | Notes | +| -------------------- | ----------------------------------------------------- | -----------------: | -------: | --------: | --------------------------------------------------- | +| Legacy | Old `npm run test:coverage` | 79.42% | 75.15% | 67.94% | Inflated: counts test files and excludes `open-sse` | +| Diagnostic | Source-only, excluding tests and excluding `open-sse` | 68.16% | 63.55% | 64.06% | Useful only to isolate `src/**` | +| Recommended baseline | Source-only, excluding tests and including `open-sse` | 56.95% | 66.05% | 57.80% | This is the project-wide baseline to improve | + +The recommended baseline is the number to optimize against. + +## Rules + +- Coverage targets apply to source files, not to `tests/**`. +- `open-sse/**` is part of the product and must remain in scope. +- New code should not reduce coverage in touched areas. +- Prefer testing behavior and branch outcomes over implementation details. +- Prefer temp SQLite databases and small fixtures over broad mocks for `src/lib/db/**`. + +## Current command set + +- `npm run test:coverage` + - Main source coverage gate for the unit test suite + - Generates `text-summary`, `html`, `json-summary`, and `lcov` +- `npm run coverage:report` + - Detailed file-by-file report from the latest run +- `npm run test:coverage:legacy` + - Historical comparison only + +## Milestones + +| Phase | Target | Focus | +| ------- | ---------------------: | ------------------------------------------------- | +| Phase 1 | 60% statements / lines | Quick wins and low-risk utility coverage | +| Phase 2 | 65% statements / lines | DB and route foundations | +| Phase 3 | 70% statements / lines | Provider validation and usage analytics | +| Phase 4 | 75% statements / lines | `open-sse` translators and helpers | +| Phase 5 | 80% statements / lines | `open-sse` handlers and executor branches | +| Phase 6 | 85% statements / lines | Harder edge cases, branch debt, regression suites | +| Phase 7 | 90% statements / lines | Final sweep, gap closure, strict ratchet | + +Branches and functions should ratchet upward with each phase, but the primary hard target is statements / lines. + +## Priority hotspots + +These files or areas offer the best return for the next phases: + +1. `open-sse/handlers` + - `chatCore.ts` at 7.57% + - Overall directory at 29.07% +2. `open-sse/translator/request` + - Overall directory at 36.39% + - Many translators are still near single-digit coverage +3. `open-sse/translator/response` + - Overall directory at 8.07% +4. `open-sse/executors` + - Overall directory at 36.62% +5. `src/lib/db` + - `models.ts` at 20.66% + - `registeredKeys.ts` at 34.46% + - `modelComboMappings.ts` at 36.25% + - `settings.ts` at 46.40% + - `webhooks.ts` at 33.33% +6. `src/lib/usage` + - `usageHistory.ts` at 21.12% + - `usageStats.ts` at 9.56% + - `costCalculator.ts` at 30.00% +7. `src/lib/providers` + - `validation.ts` at 41.16% +8. Low-risk utility and API files for early gains + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/api/errorResponse.ts` + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +## Execution checklist + +### Phase 1: 56.95% -> 60% + +- [x] Fix coverage metric so it reflects source code instead of test files +- [x] Keep a legacy coverage script for comparison +- [x] Record the baseline and hotspots in-repo +- [ ] Add focused tests for low-risk utilities: + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/fetchTimeout.ts` + - `src/lib/api/errorResponse.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/display/names.ts` +- [ ] Add route tests for: + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +### Phase 2: 60% -> 65% + +- [ ] Add DB-backed tests for: + - `src/lib/db/modelComboMappings.ts` + - `src/lib/db/settings.ts` + - `src/lib/db/registeredKeys.ts` +- [ ] Cover branch behavior in: + - `src/lib/providers/validation.ts` + - `src/app/api/v1/embeddings/route.ts` + - `src/app/api/v1/moderations/route.ts` + +### Phase 3: 65% -> 70% + +- [ ] Add usage analytics tests for: + - `src/lib/usage/usageHistory.ts` + - `src/lib/usage/usageStats.ts` + - `src/lib/usage/costCalculator.ts` +- [ ] Expand route coverage for proxy management and settings branches + +### Phase 4: 70% -> 75% + +- [ ] Cover translator helpers and central translation paths: + - `open-sse/translator/index.ts` + - `open-sse/translator/helpers/*` + - `open-sse/translator/request/*` + - `open-sse/translator/response/*` + +### Phase 5: 75% -> 80% + +- [ ] Add handler-level tests for: + - `open-sse/handlers/chatCore.ts` + - `open-sse/handlers/responsesHandler.js` + - `open-sse/handlers/imageGeneration.js` + - `open-sse/handlers/embeddings.js` +- [ ] Add executor branch coverage for provider-specific auth, retries, and endpoint overrides + +### Phase 6: 80% -> 85% + +- [ ] Merge more edge-case suites into the main coverage path +- [ ] Increase function coverage for DB modules with weak constructor/helper coverage +- [ ] Close branch gaps in `settings.ts`, `registeredKeys.ts`, `validation.ts`, and translator helpers + +### Phase 7: 85% -> 90% + +- [ ] Treat the remaining low-coverage files as blockers +- [ ] Add regression tests for every uncovered production bug fixed during the push to 90% +- [ ] Raise the coverage gate in CI only after the local baseline is stable for at least two consecutive runs + +## Ratchet policy + +Update `npm run test:coverage` thresholds only after the project actually exceeds the next milestone with a comfortable buffer. + +Recommended ratchet sequence: + +1. 55/60/55 +2. 60/62/58 +3. 65/64/62 +4. 70/66/66 +5. 75/70/72 +6. 80/75/78 +7. 85/80/84 +8. 90/85/88 + +Order is `statements-lines / branches / functions`. + +## Known gap + +The current coverage command measures the main Node unit suite and includes source reached from it, including `open-sse`. It does not yet merge Vitest coverage into a single unified report. That merge is worth doing later, but it is not a blocker for starting the 60% -> 80% climb. diff --git a/docs/i18n/ro/docs/FEATURES.md b/docs/i18n/ro/docs/FEATURES.md index e45538e81a..91938e4f8a 100644 --- a/docs/i18n/ro/docs/FEATURES.md +++ b/docs/i18n/ro/docs/FEATURES.md @@ -1,6 +1,6 @@ # OmniRoute โ€” Dashboard Features Gallery (Romรขnฤƒ) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/FEATURES.md) --- @@ -10,7 +10,7 @@ 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). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. ![Providers Dashboard](screenshots/01-providers.png) diff --git a/docs/i18n/ro/docs/MCP-SERVER.md b/docs/i18n/ro/docs/MCP-SERVER.md new file mode 100644 index 0000000000..701ae91f1a --- /dev/null +++ b/docs/i18n/ro/docs/MCP-SERVER.md @@ -0,0 +1,87 @@ +# OmniRoute MCP Server Documentation (Romรขnฤƒ) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/MCP-SERVER.md) + +--- + +> Model Context Protocol server with 16 intelligent tools + +## Instalare + +OmniRoute MCP is built-in. Start it with: + +```bash +omniroute --mcp +``` + +Or via the open-sse transport: + +```bash +# HTTP streamable transport (port 20130) +omniroute --dev # MCP auto-starts on /mcp endpoint +``` + +## IDE Configuration + +See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup. + +--- + +## Essential Tools (8) + +| Tool | Description | +| :------------------------------ | :--------------------------------------- | +| `omniroute_get_health` | Gateway health, circuit breakers, uptime | +| `omniroute_list_combos` | All configured combos with models | +| `omniroute_get_combo_metrics` | Performance metrics for a specific combo | +| `omniroute_switch_combo` | Switch active combo by ID/name | +| `omniroute_check_quota` | Quota status per provider or all | +| `omniroute_route_request` | Send a chat completion through OmniRoute | +| `omniroute_cost_report` | Cost analytics for a time period | +| `omniroute_list_models_catalog` | Full model catalog with capabilities | + +## Advanced Tools (8) + +| Tool | Description | +| :--------------------------------- | :---------------------------------------------------------- | +| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | +| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | +| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | +| `omniroute_test_combo` | Live-test all models in a combo via a real upstream request | +| `omniroute_get_provider_metrics` | Detailed metrics for one provider | +| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | +| `omniroute_explain_route` | Explain a past routing decision | +| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | + +## Authentication + +MCP tools are authenticated via API key scopes. Each tool requires specific scopes: + +| Scope | Tools | +| :------------- | :----------------------------------------------- | +| `read:health` | get_health, get_provider_metrics | +| `read:combos` | list_combos, get_combo_metrics | +| `write:combos` | switch_combo | +| `read:quota` | check_quota | +| `write:route` | route_request, simulate_route, test_combo | +| `read:usage` | cost_report, get_session_snapshot, explain_route | +| `write:config` | set_budget_guard, set_resilience_profile | +| `read:models` | list_models_catalog, best_combo_for_task | + +## Audit Logging + +Every tool call is logged to `mcp_tool_audit` with: + +- Tool name, arguments, result +- Duration (ms), success/failure +- API key hash, timestamp + +## Files + +| File | Purpose | +| :------------------------------------------- | :------------------------------------------ | +| `open-sse/mcp-server/server.ts` | MCP server creation + 16 tool registrations | +| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport | +| `open-sse/mcp-server/auth.ts` | API key + scope validation | +| `open-sse/mcp-server/audit.ts` | Tool call audit logging | +| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers | diff --git a/docs/i18n/ro/docs/RELEASE_CHECKLIST.md b/docs/i18n/ro/docs/RELEASE_CHECKLIST.md new file mode 100644 index 0000000000..2085dfacbb --- /dev/null +++ b/docs/i18n/ro/docs/RELEASE_CHECKLIST.md @@ -0,0 +1,37 @@ +# Release Checklist (Romรขnฤƒ) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/RELEASE_CHECKLIST.md) + +--- + +Use this checklist before tagging or publishing a new OmniRoute release. + +## Version and Changelog + +1. Bump `package.json` version (`x.y.z`) in the release branch. +2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: + - `## [x.y.z] โ€” YYYY-MM-DD` +3. Keep `## [Unreleased]` as the first changelog section for upcoming work. +4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. + +## API Docs + +1. Update `docs/openapi.yaml`: + - `info.version` must equal `package.json` version. +2. Validate endpoint examples if API contracts changed. + +## Runtime Docs + +1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. +2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. +3. Update localized docs if source docs changed significantly. + +## Automated Check + +Run the sync guard locally before opening PR: + +```bash +npm run check:docs-sync +``` + +CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/ro/docs/TROUBLESHOOTING.md b/docs/i18n/ro/docs/TROUBLESHOOTING.md new file mode 100644 index 0000000000..e1a5a3bfdf --- /dev/null +++ b/docs/i18n/ro/docs/TROUBLESHOOTING.md @@ -0,0 +1,256 @@ +# Troubleshooting (Romรขnฤƒ) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/TROUBLESHOOTING.md) + +--- + +Common problems and solutions for OmniRoute. + +--- + +## Quick Fixes + +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | + +--- + +## Provider Issues + +### "Language model did not provide messages" + +**Cause:** Provider quota exhausted. + +**Fix:** + +1. 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, Qoder) 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}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) + +--- + +## Circuit Breaker Issues + +### Provider stuck in OPEN state + +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. + +**Fix:** + +1. 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 +- **SDK returns raw string instead of object** โ€” Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** โ€” Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** โ€” Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** โ€” Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` + +--- + +## Resilience Settings + +### Auto rate-limit not triggering + +- 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. + +--- + +## Optional RAG / LLM failure taxonomy (16 problems) + +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` โ€ฆ `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard โ†’ Health** for real-time system status +- **Translator**: Use **Dashboard โ†’ Translator** to debug format issues diff --git a/docs/i18n/ro/USER_GUIDE.md b/docs/i18n/ro/docs/USER_GUIDE.md similarity index 82% rename from docs/i18n/ro/USER_GUIDE.md rename to docs/i18n/ro/docs/USER_GUIDE.md index b275922816..f7d0d052bf 100644 --- a/docs/i18n/ro/USER_GUIDE.md +++ b/docs/i18n/ro/docs/USER_GUIDE.md @@ -1,8 +1,6 @@ # User Guide (Romรขnฤƒ) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/USER_GUIDE.md) - -> ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/USER_GUIDE.md) --- @@ -320,7 +318,7 @@ Model: cc/claude-opus-4-6 --- -## ๐Ÿš€ Deployment +## Implementare ### Global npm install (Recommended) @@ -511,23 +509,26 @@ post_install() { ### Environment Variables -| Variable | Default | Description | -| ------------------------- | ------------------------------------ | ------------------------------------------------------- | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | -| `INITIAL_PASSWORD` | `123456` | First login password | -| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | -| `PORT` | framework default | Service port (`20128` in examples) | -| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | -| `NODE_ENV` | runtime default | Set `production` for deploy | -| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | -| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | -| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | -| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | -| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | -| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | -| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | -| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | +| 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/*` | +| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand | +| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | For the full environment variable reference, see the [README](../README.md). @@ -598,6 +599,11 @@ curl -X POST http://localhost:20128/api/provider-models \ Or use Dashboard: **Providers โ†’ [Provider] โ†’ Custom Models**. +Notes: + +- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers. +- The **Custom Models** section is intended for providers that do not expose managed available-model imports. + ### Dedicated Provider Routes Route requests directly to a specific provider with model validation: @@ -642,6 +648,14 @@ Returns models grouped by provider with types (`chat`, `embedding`, `image`). - Automatic background sync with timeout + fail-fast - Prefer server-side `BASE_URL`/`CLOUD_URL` in production +### Cloudflare Quick Tunnel + +- Available in **Dashboard โ†’ Endpoints** for Docker and other self-hosted deployments +- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint +- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary +- Tunnel URLs are ephemeral and change every time you stop/start the tunnel +- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download + ### LLM Gateway Intelligence (Phase 9) - **Semantic Cache** โ€” Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) @@ -757,11 +771,11 @@ OmniRoute implements provider-level resilience with four components: 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 | +| 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 unless `DISABLE_SQLITE_AUTO_BACKUP=true` | ```bash # API: Export database @@ -787,10 +801,11 @@ curl -X POST http://localhost:20128/api/db-backups/import \ ### Settings Dashboard -The settings page is organized into 5 tabs for easy navigation: +The settings page is organized into 6 tabs for easy navigation: | Tab | Contents | | -------------- | ---------------------------------------------------------------------------------------------- | +| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility | | **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | | **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | | **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | diff --git a/docs/i18n/pt-BR/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/ro/docs/VM_DEPLOYMENT_GUIDE.md similarity index 54% rename from docs/i18n/pt-BR/VM_DEPLOYMENT_GUIDE.md rename to docs/i18n/ro/docs/VM_DEPLOYMENT_GUIDE.md index 56e39fa56e..8a75daa27d 100644 --- a/docs/i18n/pt-BR/VM_DEPLOYMENT_GUIDE.md +++ b/docs/i18n/ro/docs/VM_DEPLOYMENT_GUIDE.md @@ -1,50 +1,52 @@ -# OmniRoute โ€” Guia de implantaรงรฃo em VM com Cloudflare +# OmniRoute โ€” Deployment Guide on VM with Cloudflare (Romรขnฤƒ) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](../pt-BR/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](../es/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](../fr/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](../it/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](../ru/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](../zh-CN/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](../de/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](../in/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](../th/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](../uk-UA/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](../ar/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](../ja/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](../vi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](../bg/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](../da/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](../fi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](../he/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](../hu/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](../id/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](../ko/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](../ms/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](../nl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](../no/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](../pt/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](../ro/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](../pl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](../sk/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](../sv/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](../phi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](../cs/VM_DEPLOYMENT_GUIDE.md) - -Guia completo para instalar e configurar OmniRoute em uma VM (VPS) com domรญnio gerenciado via Cloudflare. +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/VM_DEPLOYMENT_GUIDE.md) --- -## Prรฉ-requisitos - -| Artigo | Mรญnimo | Recomendado | -| ----------- | ------------------------ | --------------- | -| **CPU** | 1 vCPU | 2 vCPUs | -| **RAM** | 1 GB | 2 GB | -| **Disco** | SSD de 10 GB | SSD de 25 GB | -| **SO** | Ubuntu 22.04LTS | Ubuntu 24.04LTS | -| **Domรญnio** | Registrado na Cloudflare | โ€” | -| **Docker** | Motor Docker 24+ | Docker 27+ | - -**Provedores testados**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. +Complete guide to install and configure OmniRoute on a VM (VPS) with domain managed via Cloudflare. --- -## 1. Configure a VM +## Prerequisites -### 1.1 Crie a instรขncia +| Item | Minimum | Recommended | +| ---------- | ------------------------ | ---------------- | +| **CPU** | 1 vCPU | 2 vCPU | +| **RAM** | 1 GB | 2 GB | +| **Disk** | 10 GB SSD | 25 GB SSD | +| **OS** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS | +| **Domain** | Registered on Cloudflare | โ€” | +| **Docker** | Docker Engine 24+ | Docker 27+ | -No seu provedor VPS preferido: +**Tested providers**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. -- Escolha Ubuntu 24.04 LTS -- Selecione o plano mรญnimo (1 vCPU / 1 GB RAM) -- Defina uma senha root forte ou configure a chave SSH -- Observe o **IP pรบblico** (por exemplo, `203.0.113.10`) +--- -### 1.2 Conectar via SSH +## 1. Configure the VM + +### 1.1 Create the instance + +On your preferred VPS provider: + +- Choose Ubuntu 24.04 LTS +- Select the minimum plan (1 vCPU / 1 GB RAM) +- Set a strong root password or configure SSH key +- Note the **public IP** (e.g., `203.0.113.10`) + +### 1.2 Connect via SSH ```bash ssh root@203.0.113.10 ``` -### 1.3 Atualizar o sistema +### 1.3 Update the system ```bash apt update && apt upgrade -y ``` -### 1.4 Instalar o Docker +### 1.4 Install Docker ```bash # Install dependencies @@ -59,13 +61,13 @@ apt update apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin ``` -### 1.5 Instale o nginx +### 1.5 Install nginx ```bash apt install -y nginx ``` -### 1.6 Configurar Firewall (UFW) +### 1.6 Configure Firewall (UFW) ```bash ufw default deny incoming @@ -76,19 +78,19 @@ ufw allow 443/tcp # HTTPS ufw enable ``` -> **Dica**: para seguranรงa mรกxima, restrinja as portas 80 e 443 apenas aos IPs da Cloudflare. Consulte a seรงรฃo [Advanced Security](#advanced-security). +> **Tip**: For maximum security, restrict ports 80 and 443 to Cloudflare IPs only. See the [Advanced Security](#advanced-security) section. --- -## 2. Instale o OmniRoute +## 2. Install OmniRoute -### 2.1 Criar diretรณrio de configuraรงรฃo +### 2.1 Create configuration directory ```bash mkdir -p /opt/omniroute ``` -### 2.2 Criar arquivo de variรกveis de ambiente +### 2.2 Create environment variables file ```bash cat > /opt/omniroute/.env << โ€˜EOFโ€™ @@ -120,9 +122,9 @@ NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com EOF ``` -> โš ๏ธ **IMPORTANTE**: Gere chaves secretas exclusivas! Use `openssl rand -hex 32` para cada chave. +> โš ๏ธ **IMPORTANT**: Generate unique secret keys! Use `openssl rand -hex 32` for each key. -### 2.3 Inicie o contรชiner +### 2.3 Start the container ```bash docker pull diegosouzapw/omniroute:latest @@ -136,27 +138,27 @@ docker run -d \ diegosouzapw/omniroute:latest ``` -### 2.4 Verifique se estรก em execuรงรฃo +### 2.4 Verify that it is running ```bash docker ps | grep omniroute docker logs omniroute --tail 20 ``` -Deve exibir: `[DB] SQLite database ready` e `listening on port 20128`. +It should display: `[DB] SQLite database ready` and `listening on port 20128`. --- -## 3. Configurar nginx (proxy reverso) +## 3. Configure nginx (Reverse Proxy) -### 3.1 Gerar certificado SSL (Origem Cloudflare) +### 3.1 Generate SSL certificate (Cloudflare Origin) -No painel da Cloudflare: +In the Cloudflare dashboard: -1. Vรก para **SSL/TLS โ†’ Servidor de Origem** -2. Clique em **Criar certificado** -3. Mantenha os padrรตes (15 anos, \*.seudominio.com) -4. Copie o **Certificado de Origem** e a **Chave Privada** +1. Go to **SSL/TLS โ†’ Origin Server** +2. Click **Create Certificate** +3. Keep the defaults (15 years, \*.yourdomain.com) +4. Copy the **Origin Certificate** and the **Private Key** ```bash mkdir -p /etc/nginx/ssl @@ -170,7 +172,7 @@ nano /etc/nginx/ssl/origin.key chmod 600 /etc/nginx/ssl/origin.key ``` -### 3.2 Configuraรงรฃo Nginx +### 3.2 Nginx Configuration ```bash cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ @@ -228,7 +230,7 @@ server { NGINX ``` -### 3.3 Habilitar e testar +### 3.3 Enable and Test ```bash # Remove default configuration @@ -243,29 +245,29 @@ nginx -t && systemctl reload nginx --- -## 4. Configurar DNS da Cloudflare +## 4. Configure Cloudflare DNS -### 4.1 Adicionar registro DNS +### 4.1 Add DNS record -No painel Cloudflare โ†’ DNS: +In the Cloudflare dashboard โ†’ DNS: -| Tipo | Nome | Conteรบdo | Procuraรงรฃo | -| ---- | ------ | ------------------------- | ------------ | -| Um | `llms` | `203.0.113.10` (IP da VM) | โœ… Procurado | +| Type | Name | Content | Proxy | +| ---- | ------ | ---------------------- | ---------- | +| A | `llms` | `203.0.113.10` (VM IP) | โœ… Proxied | -### 4.2 Configurar SSL +### 4.2 Configure SSL -Em **SSL/TLS โ†’ Visรฃo geral**: +Under **SSL/TLS โ†’ Overview**: -- Modo: **Completo (estrito)** +- Mode: **Full (Strict)** -Em **SSL/TLS โ†’ Certificados Edge**: +Under **SSL/TLS โ†’ Edge Certificates**: -- Sempre use HTTPS: โœ… Ligado -- Versรฃo mรญnima do TLS: TLS 1.2 -- Reescritas automรกticas de HTTPS: โœ… Ativado +- Always Use HTTPS: โœ… On +- Minimum TLS Version: TLS 1.2 +- Automatic HTTPS Rewrites: โœ… On -### 4.3 Teste +### 4.3 Testing ```bash curl -sI https://llms.seudominio.com/health @@ -274,9 +276,9 @@ curl -sI https://llms.seudominio.com/health --- -## 5. Operaรงรตes e Manutenรงรฃo +## 5. Operations and Maintenance -### Atualize para uma nova versรฃo +### Upgrade to a new version ```bash docker pull diegosouzapw/omniroute:latest @@ -288,14 +290,14 @@ docker run -d --name omniroute --restart unless-stopped \ diegosouzapw/omniroute:latest ``` -### Ver registros +### View logs ```bash docker logs -f omniroute # Real-time stream docker logs omniroute --tail 50 # Last 50 lines ``` -### Backup manual do banco de dados +### Manual database backup ```bash # Copy data from the volume to the host @@ -306,7 +308,7 @@ docker run --rm -v omniroute-data:/data -v $(pwd):/backup \ alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data ``` -### Restaurar do backup +### Restore from backup ```bash docker stop omniroute @@ -317,9 +319,9 @@ docker start omniroute --- -## 6. Seguranรงa Avanรงada +## 6. Advanced Security -### Restringir o nginx aos IPs da Cloudflare +### Restrict nginx to Cloudflare IPs ```bash cat > /etc/nginx/cloudflare-ips.conf << โ€˜CFโ€™ @@ -344,13 +346,13 @@ real_ip_header CF-Connecting-IP; CF ``` -Adicione o seguinte a `nginx.conf` dentro do bloco `http {}`: +Add the following to `nginx.conf` inside the `http {}` block: ```nginx include /etc/nginx/cloudflare-ips.conf; ``` -### Instale o fail2ban +### Install fail2ban ```bash apt install -y fail2ban @@ -361,7 +363,7 @@ systemctl start fail2ban fail2ban-client status sshd ``` -### Bloqueie o acesso direto ร  porta Docker +### Block direct access to the Docker port ```bash # Prevent direct external access to port 20128 @@ -375,9 +377,9 @@ netfilter-persistent save --- -## 7. Implantar em Cloudflare Workers (opcional) +## 7. Deploy to Cloudflare Workers (Optional) -Para acesso remoto via Cloudflare Workers (sem expor a VM diretamente): +For remote access via Cloudflare Workers (without exposing the VM directly): ```bash # In the local repository @@ -387,15 +389,15 @@ npx wrangler login npx wrangler deploy ``` -Veja a documentaรงรฃo completa em [omnirouteCloud/README.md](../omnirouteCloud/README.md). +See the full documentation at [omnirouteCloud/README.md](../omnirouteCloud/README.md). --- -## Resumo da porta +## Port Summary -| Porto | Serviรงo | Acesso | -| ----- | ----------- | ---------------------------- | -| 22 | SSH | Pรบblico (com fail2ban) | -| 80 | HTTP nginx | Redirecionar โ†’ HTTPS | -| 443 | HTTPS nginx | Atravรฉs do proxy Cloudflare | -| 20128 | OmniRoute | Apenas localhost (via nginx) | +| Port | Service | Access | +| ----- | ----------- | -------------------------- | +| 22 | SSH | Public (with fail2ban) | +| 80 | nginx HTTP | Redirect โ†’ HTTPS | +| 443 | nginx HTTPS | Via Cloudflare Proxy | +| 20128 | OmniRoute | Localhost only (via nginx) | diff --git a/docs/i18n/ro/src/lib/a2a/README.md b/docs/i18n/ro/src/lib/a2a/README.md new file mode 100644 index 0000000000..723e6f0370 --- /dev/null +++ b/docs/i18n/ro/src/lib/a2a/README.md @@ -0,0 +1,752 @@ +# OmniRoute A2A Server (Romรขnฤƒ) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../../../src/lib/a2a/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../../../es/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../../../fr/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../../../de/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../../../it/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../../../ru/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../../../zh-CN/src/lib/a2a/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../../../ja/src/lib/a2a/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../../../ko/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../../../ar/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../../../in/src/lib/a2a/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../../../th/src/lib/a2a/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../../../vi/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../../../id/src/lib/a2a/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../../../ms/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../../../nl/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../../../pl/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../../../sv/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../../../no/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../../../da/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../../../fi/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../../../pt/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../../../ro/src/lib/a2a/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../../../hu/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../../../bg/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../../../sk/src/lib/a2a/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../../../uk-UA/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../../../he/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../../../phi/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../../../pt-BR/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../../../cs/src/lib/a2a/README.md) + +--- + +> **Agent-to-Agent Protocol v0.3** โ€” Enables any AI agent to use OmniRoute as an intelligent routing agent via JSON-RPC 2.0. + +The A2A Server exposes OmniRoute as a **first-class agent** that other agents can discover, delegate tasks to, and collaborate with using the [A2A Protocol](https://google.github.io/A2A/). + +--- + +## Arhitecturฤƒ + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Orchestrator Agent โ”‚ +โ”‚ (LangChain, CrewAI, AutoGen, Custom Agent) โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ 1. GET /.well-known/agent.json (discover) + โ”‚ 2. POST /a2a (JSON-RPC 2.0) + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ OmniRoute A2A Server โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Task Manager โ”‚ โ”‚ Skill Engine โ”‚ โ”‚ SSE Streaming โ”‚ โ”‚ +โ”‚ โ”‚ (lifecycle) โ”‚โ”€โ”€โ”‚ (registry) โ”‚โ”€โ”€โ”‚ (real-time) โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ +โ”‚ Skills: โ”‚ โ”‚ +โ”‚ โ”œโ”€ smart-routing โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ””โ”€ quota-management โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ Routing Decision Logger โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ OmniRoute Gateway (internal) + /v1/chat/completions, /api/combos, /api/usage/quota +``` + +--- + +## Pornire rapidฤƒ + +### Agent Discovery + +Every A2A-compatible agent exposes an **Agent Card** at `/.well-known/agent.json`: + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +**Response:** + +```json +{ + "name": "OmniRoute", + "description": "Intelligent AI gateway with auto-routing across 50+ providers", + "url": "http://localhost:20128/a2a", + "version": "1.8.1", + "capabilities": { + "streaming": true, + "pushNotifications": false + }, + "skills": [ + { + "id": "smart-routing", + "name": "Smart Routing", + "description": "Routes prompts through OmniRoute intelligent pipeline", + "tags": ["routing", "llm", "multi-provider", "cost-optimization"], + "examples": [ + "Write a hello world in Python", + "Explain quantum computing using the cheapest provider" + ] + }, + { + "id": "quota-management", + "name": "Quota Management", + "description": "Natural-language queries about provider quotas", + "tags": ["quota", "analytics", "cost"], + "examples": [ + "Which provider has the most quota remaining?", + "Suggest a free combo for coding" + ] + } + ], + "authentication": { + "schemes": ["bearer"], + "apiKeyHeader": "Authorization" + } +} +``` + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Send a message to a skill and receive the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python hello world"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "a1b2c3d4-...", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "print('Hello, World!')" }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.0030)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "2026-03-04T..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"Quantum computing..."}}} + +: heartbeat 2026-03-04T21:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Running Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Skills Reference + +### `smart-routing` + +Routes prompts through OmniRoute's intelligent pipeline with full observability. + +**Parameters (in `metadata`):** + +| Parameter | Type | Default | Description | +| --------- | -------- | ------------ | ---------------------------------------------------------------------------------------- | +| `model` | `string` | `"auto"` | Target model (e.g., `claude-sonnet-4`, `gpt-4o`, `auto`) | +| `combo` | `string` | active combo | Specific combo to route through | +| `budget` | `number` | none | Maximum cost in USD for this request | +| `role` | `string` | none | Task role hint: `coding`, `review`, `planning`, `analysis`, `debugging`, `documentation` | + +**Returns:** + +| Field | Description | +| ------------------------------ | --------------------------------------------------------- | +| `artifacts[].content` | The LLM response text | +| `metadata.routing_explanation` | Human-readable explanation of routing decision | +| `metadata.cost_envelope` | Estimated vs actual cost with currency | +| `metadata.resilience_trace` | Array of events (primary_selected, fallback_needed, etc.) | +| `metadata.policy_verdict` | Whether the request was allowed and why | + +### `quota-management` + +Answers natural-language queries about provider quotas. + +**Query types (inferred from message content):** + +| Query Pattern | Response Type | +| ---------------------------------------------- | -------------------------------------------------------- | +| Contains `"ranking"`, `"most quota"`, `"best"` | Providers ranked by remaining quota | +| Contains `"free"`, `"suggest"` | Lists free combos or suggests free-tier providers | +| Default | Full quota summary with warnings for low-quota providers | + +--- + +## Task Lifecycle + +``` +submitted โ”€โ”€โ†’ working โ”€โ”€โ†’ completed + โ”€โ”€โ†’ failed + โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ†’ cancelled +``` + +| State | Description | +| ----------- | ----------------------------------------------------- | +| `submitted` | Task created, queued for execution | +| `working` | Skill handler is executing | +| `completed` | Execution succeeded, artifacts available | +| `failed` | Execution failed or task expired (TTL: 5 min default) | +| `cancelled` | Cancelled by client via `tasks/cancel` | + +- Terminal states: `completed`, `failed`, `cancelled` (no further transitions) +- Expired tasks in `submitted` or `working` are auto-marked as `failed` +- Tasks are garbage-collected after 2ร— TTL + +--- + +## Client Examples + +### Python โ€” Orchestrator Agent + +```python +""" +A2A Client โ€” Python example. +Discovers OmniRoute agent, sends a task, and processes the result. +""" +import requests +import json + +BASE_URL = "http://localhost:20128" +API_KEY = "your-api-key" +HEADERS = { + "Content-Type": "application/json", + "Authorization": f"Bearer {API_KEY}", +} + +# 1. Discover agent capabilities +agent_card = requests.get(f"{BASE_URL}/.well-known/agent.json").json() +print(f"Agent: {agent_card['name']} v{agent_card['version']}") +print(f"Skills: {[s['id'] for s in agent_card['skills']]}") + +# 2. Send a smart-routing task +response = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python quicksort implementation"}], + "metadata": { + "model": "auto", + "combo": "fast-coding", + "budget": 0.10, + } + } +}) +result = response.json()["result"] +print(f"\n๐Ÿ“ Response: {result['artifacts'][0]['content'][:200]}...") +print(f"๐Ÿ”€ Routing: {result['metadata']['routing_explanation']}") +print(f"๐Ÿ’ฐ Cost: ${result['metadata']['cost_envelope']['actual']}") +print(f"๐Ÿ›ก๏ธ Policy: {result['metadata']['policy_verdict']['reason']}") + +# 3. Query quota status +quota_resp = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-2", + "method": "message/send", + "params": { + "skill": "quota-management", + "messages": [{"role": "user", "content": "Which provider has the most quota remaining?"}], + } +}) +quota_result = quota_resp.json()["result"] +print(f"\n๐Ÿ“Š Quota: {quota_result['artifacts'][0]['content']}") +``` + +### TypeScript โ€” Multi-Agent Orchestrator + +```typescript +/** + * A2A Client โ€” TypeScript example. + * Shows agent discovery, task delegation, and streaming. + */ + +const BASE_URL = "http://localhost:20128"; +const API_KEY = "your-api-key"; + +interface JsonRpcResponse { + jsonrpc: "2.0"; + id: string | number; + result?: T; + error?: { code: number; message: string }; +} + +async function a2aCall(method: string, params: Record): Promise { + const resp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: `${method}-${Date.now()}`, + method, + params, + }), + }); + const json: JsonRpcResponse = await resp.json(); + if (json.error) throw new Error(`[${json.error.code}] ${json.error.message}`); + return json.result!; +} + +// โ”€โ”€ Agent Discovery โ”€โ”€ +const agentCard = await fetch(`${BASE_URL}/.well-known/agent.json`).then((r) => r.json()); +console.log(`Connected to: ${agentCard.name} (${agentCard.skills.length} skills)`); + +// โ”€โ”€ Smart Routing: Send a coding task โ”€โ”€ +const routingResult = await a2aCall("message/send", { + skill: "smart-routing", + messages: [{ role: "user", content: "Implement a Redis cache wrapper in TypeScript" }], + metadata: { model: "claude-sonnet-4", role: "coding" }, +}); +console.log("Response:", routingResult.artifacts[0].content); +console.log("Provider:", routingResult.metadata.routing_explanation); + +// โ”€โ”€ Quota Management: Find free alternatives โ”€โ”€ +const quotaResult = await a2aCall("message/send", { + skill: "quota-management", + messages: [{ role: "user", content: "Suggest free combos for documentation" }], +}); +console.log("Free combos:", quotaResult.artifacts[0].content); + +// โ”€โ”€ Streaming: Real-time response โ”€โ”€ +const streamResp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "stream-1", + method: "message/stream", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Explain microservices architecture" }], + }, + }), +}); + +const reader = streamResp.body!.getReader(); +const decoder = new TextDecoder(); +while (true) { + const { done, value } = await reader.read(); + if (done) break; + const chunk = decoder.decode(value); + for (const line of chunk.split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + if (event.params.chunk) { + process.stdout.write(event.params.chunk.content); + } + if (event.params.task.state === "completed") { + console.log("\nโœ… Stream completed"); + } + } + } +} +``` + +### Python โ€” LangChain A2A Integration + +```python +""" +LangChain integration โ€” Use OmniRoute A2A as a custom LLM. +""" +from langchain.llms.base import BaseLLM +from langchain.schema import LLMResult, Generation +import requests +from typing import List, Optional + +class OmniRouteA2A(BaseLLM): + base_url: str = "http://localhost:20128" + api_key: str = "" + model: str = "auto" + combo: Optional[str] = None + + @property + def _llm_type(self) -> str: + return "omniroute-a2a" + + def _call(self, prompt: str, stop: Optional[List[str]] = None, **kwargs) -> str: + response = requests.post( + f"{self.base_url}/a2a", + headers={ + "Content-Type": "application/json", + "Authorization": f"Bearer {self.api_key}", + }, + json={ + "jsonrpc": "2.0", + "id": "langchain-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": prompt}], + "metadata": { + "model": self.model, + **({"combo": self.combo} if self.combo else {}), + }, + }, + }, + ) + result = response.json()["result"] + return result["artifacts"][0]["content"] + + def _generate(self, prompts: List[str], stop=None, **kwargs) -> LLMResult: + return LLMResult( + generations=[[Generation(text=self._call(p, stop))] for p in prompts] + ) + +# Usage +llm = OmniRouteA2A( + base_url="http://localhost:20128", + api_key="your-key", + model="auto", + combo="fast-coding", +) +result = llm("Write a Python function to merge two sorted lists") +print(result) +``` + +### Go โ€” A2A Client + +```go +package main + +import ( + "bytes" + "encoding/json" + "fmt" + "io" + "net/http" +) + +const baseURL = "http://localhost:20128" +const apiKey = "your-api-key" + +type JsonRpcRequest struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Method string `json:"method"` + Params interface{} `json:"params"` +} + +type JsonRpcResponse struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Result interface{} `json:"result"` + Error *struct { + Code int `json:"code"` + Message string `json:"message"` + } `json:"error"` +} + +func a2aCall(method string, params interface{}) (*JsonRpcResponse, error) { + body, _ := json.Marshal(JsonRpcRequest{ + Jsonrpc: "2.0", + ID: "go-1", + Method: method, + Params: params, + }) + + req, _ := http.NewRequest("POST", baseURL+"/a2a", bytes.NewReader(body)) + req.Header.Set("Content-Type", "application/json") + req.Header.Set("Authorization", "Bearer "+apiKey) + + resp, err := http.DefaultClient.Do(req) + if err != nil { + return nil, err + } + defer resp.Body.Close() + data, _ := io.ReadAll(resp.Body) + + var result JsonRpcResponse + json.Unmarshal(data, &result) + return &result, nil +} + +func main() { + // Discover agent + resp, _ := http.Get(baseURL + "/.well-known/agent.json") + defer resp.Body.Close() + body, _ := io.ReadAll(resp.Body) + fmt.Println("Agent Card:", string(body)) + + // Send smart-routing task + result, _ := a2aCall("message/send", map[string]interface{}{ + "skill": "smart-routing", + "messages": []map[string]string{{"role": "user", "content": "Hello from Go!"}}, + "metadata": map[string]interface{}{"model": "auto"}, + }) + out, _ := json.MarshalIndent(result.Result, "", " ") + fmt.Println("Result:", string(out)) +} +``` + +--- + +## Use Cases + +### ๐Ÿค– Use Case 1: Multi-Agent Coding Pipeline + +An orchestrator agent delegates code generation to OmniRoute, then passes the output to a review agent. + +```python +def coding_pipeline(task: str): + # Step 1: Generate code via OmniRoute A2A + code_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Write production-quality code: {task}"} + ], metadata={"model": "auto", "role": "coding"}) + code = code_result["artifacts"][0]["content"] + + # Step 2: Review the code via OmniRoute A2A (different model) + review_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Review this code for bugs and improvements:\n\n{code}"} + ], metadata={"model": "auto", "role": "review"}) + review = review_result["artifacts"][0]["content"] + + # Step 3: Check costs + print(f"Code cost: ${code_result['metadata']['cost_envelope']['actual']}") + print(f"Review cost: ${review_result['metadata']['cost_envelope']['actual']}") + + return {"code": code, "review": review} +``` + +### ๐Ÿ’ก Use Case 2: Quota-Aware Agent Swarm + +Multiple agents share quota through OmniRoute, using the quota skill to coordinate. + +```python +async def quota_aware_agent(agent_name: str, task: str): + # Check quota before starting + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Which provider has the most quota remaining?"} + ]) + print(f"[{agent_name}] {quota['artifacts'][0]['content']}") + + # Send request with budget constraint + result = a2a_send("smart-routing", [ + {"role": "user", "content": task} + ], metadata={"budget": 0.05}) + + policy = result["metadata"]["policy_verdict"] + if not policy["allowed"]: + print(f"[{agent_name}] โš ๏ธ Budget exceeded: {policy['reason']}") + # Fall back to free combo + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Suggest free combos"} + ]) + print(f"[{agent_name}] Free alternatives: {quota['artifacts'][0]['content']}") + + return result +``` + +### ๐Ÿ“Š Use Case 3: Real-Time Streaming Dashboard + +A monitoring agent streams responses and displays progress in real-time. + +```typescript +async function streamingDashboard(prompt: string) { + const response = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { "Content-Type": "application/json", Authorization: `Bearer ${API_KEY}` }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "dash-1", + method: "message/stream", + params: { skill: "smart-routing", messages: [{ role: "user", content: prompt }] }, + }), + }); + + let totalChunks = 0; + const reader = response.body!.getReader(); + const decoder = new TextDecoder(); + + while (true) { + const { done, value } = await reader.read(); + if (done) break; + + for (const line of decoder.decode(value).split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + const state = event.params.task.state; + + if (state === "working" && event.params.chunk) { + totalChunks++; + process.stdout.write( + `\r[Chunk ${totalChunks}] ${event.params.chunk.content.slice(0, 50)}...` + ); + } + if (state === "completed") { + const meta = event.params.metadata; + console.log( + `\nโœ… Done | Cost: $${meta?.cost_envelope?.actual || 0} | Route: ${meta?.routing_explanation || "N/A"}` + ); + } + if (state === "failed") { + console.error(`\nโŒ Failed: ${event.params.metadata?.error}`); + } + } + } + } +} +``` + +### ๐Ÿ” Use Case 4: Task Polling Pattern + +For long-running tasks, poll the task status instead of waiting synchronously. + +```python +import time + +def poll_task(task_id: str, timeout: int = 60): + """Poll task status until completion or timeout.""" + start = time.time() + while time.time() - start < timeout: + result = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "poll-1", + "method": "tasks/get", + "params": {"taskId": task_id}, + }).json() + + task = result["result"]["task"] + state = task["state"] + print(f" Task {task_id[:8]}... state={state}") + + if state in ("completed", "failed", "cancelled"): + return task + time.sleep(2) + + # Timeout โ€” cancel the task + requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "cancel-1", + "method": "tasks/cancel", + "params": {"taskId": task_id}, + }) + raise TimeoutError(f"Task {task_id} timed out after {timeout}s") +``` + +--- + +## Error Codes + +| Code | Constant | Meaning | +| ------ | ------------------------ | ---------------------------------------- | +| -32700 | โ€” | Parse error (invalid JSON) | +| -32600 | `INVALID_REQUEST` | Invalid JSON-RPC request or unauthorized | +| -32601 | `METHOD_NOT_FOUND` | Unknown method or skill | +| -32602 | `INVALID_PARAMS` | Missing or invalid parameters | +| -32603 | `INTERNAL_ERROR` | Skill execution failed | +| -32001 | `TASK_NOT_FOUND` | Task ID not found | +| -32002 | `TASK_ALREADY_COMPLETED` | Cannot modify a completed task | +| -32003 | `UNAUTHORIZED` | Invalid or missing API key | +| -32004 | `BUDGET_EXCEEDED` | Request exceeds configured budget | +| -32005 | `PROVIDER_UNAVAILABLE` | No available providers | + +--- + +## Authentication + +All `/a2a` requests require a Bearer token via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server (`OMNIROUTE_API_KEY` is empty), authentication is bypassed. + +--- + +## File Structure + +``` +src/lib/a2a/ +โ”œโ”€โ”€ taskManager.ts # Task lifecycle (create/update/cancel/list), TTL, cleanup +โ”œโ”€โ”€ taskExecution.ts # Generic task executor with state management +โ”œโ”€โ”€ streaming.ts # SSE stream formatting, heartbeat, chunk/completion events +โ”œโ”€โ”€ routingLogger.ts # Routing decision logger (stats, history, retention) +โ””โ”€โ”€ skills/ + โ”œโ”€โ”€ smartRouting.ts # Smart routing skill (routes via /v1/chat/completions) + โ””โ”€โ”€ quotaManagement.ts # Quota management skill (natural-language quota queries) + +src/app/a2a/ +โ””โ”€โ”€ route.ts # Next.js API route handler (JSON-RPC 2.0 dispatch) + +open-sse/mcp-server/ +โ””โ”€โ”€ schemas/a2a.ts # Zod schemas (AgentCard, Task, JSON-RPC, SSE events) +``` + +--- + +## Comparison: MCP vs A2A + +| Feature | MCP Server | A2A Server | +| ----------------- | ---------------------------- | ------------------------------------------------- | +| **Protocol** | Model Context Protocol | Agent-to-Agent Protocol v0.3 | +| **Transport** | stdio / HTTP | HTTP (JSON-RPC 2.0) | +| **Discovery** | Tool listing via MCP | `/.well-known/agent.json` | +| **Granularity** | 16 individual tools | 2 high-level skills | +| **Best for** | IDE agents (Cursor, VS Code) | Multi-agent systems (LangChain, CrewAI) | +| **Streaming** | Not supported | SSE via `message/stream` | +| **Task tracking** | No | Full lifecycle (submitted โ†’ completed) | +| **Observability** | Audit log per tool call | Cost envelope + resilience trace + policy verdict | + +--- + +## Licenศ›ฤƒ + +Part of [OmniRoute](https://github.com/diegosouzapw/OmniRoute) โ€” MIT License. diff --git a/docs/i18n/ru/A2A-SERVER.md b/docs/i18n/ru/A2A-SERVER.md deleted file mode 100644 index 01531ff482..0000000000 --- a/docs/i18n/ru/A2A-SERVER.md +++ /dev/null @@ -1,200 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/A2A-SERVER.md) - ---- - -# OmniRoute A2A Server Documentation - -> Agent-to-Agent Protocol v0.3 โ€” OmniRoute as an intelligent routing agent - -## Agent Discovery - -```bash -curl http://localhost:20128/.well-known/agent.json -``` - -Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements. - ---- - -## Authentication - -All `/a2a` requests require an API key via the `Authorization` header: - -``` -Authorization: Bearer YOUR_OMNIROUTE_API_KEY -``` - -If no API key is configured on the server, authentication is bypassed. - ---- - -## JSON-RPC 2.0 Methods - -### `message/send` โ€” Synchronous Execution - -Sends a message to a skill and waits for the complete response. - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{ - "jsonrpc": "2.0", - "id": "1", - "method": "message/send", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Write a hello world in Python"}], - "metadata": {"model": "auto", "combo": "fast-coding"} - } - }' -``` - -**Response:** - -```json -{ - "jsonrpc": "2.0", - "id": "1", - "result": { - "task": { "id": "uuid", "state": "completed" }, - "artifacts": [{ "type": "text", "content": "..." }], - "metadata": { - "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)", - "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, - "resilience_trace": [ - { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." } - ], - "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } - } - } -} -``` - -### `message/stream` โ€” SSE Streaming - -Same as `message/send` but returns Server-Sent Events for real-time streaming. - -```bash -curl -N -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{ - "jsonrpc": "2.0", - "id": "1", - "method": "message/stream", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Explain quantum computing"}] - } - }' -``` - -**SSE Events:** - -``` -data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}} - -: heartbeat 2026-03-03T17:00:00Z - -data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} -``` - -### `tasks/get` โ€” Query Task Status - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' -``` - -### `tasks/cancel` โ€” Cancel a Task - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' -``` - ---- - -## Available Skills - -| Skill | Description | -| :----------------- | :------------------------------------------------------------------------------------------------------------------------------ | -| `smart-routing` | Routes prompts through OmniRoute's intelligent pipeline. Returns response with routing explanation, cost, and resilience trace. | -| `quota-management` | Answers natural-language queries about provider quotas, suggests free combos, and provides quota rankings. | - ---- - -## Task Lifecycle - -``` -submitted โ†’ working โ†’ completed - โ†’ failed - โ†’ cancelled -``` - -- Tasks expire after 5 minutes (configurable) -- Terminal states: `completed`, `failed`, `cancelled` -- Event log tracks every state transition - ---- - -## Error Codes - -| Code | Meaning | -| :----- | :----------------------------- | -| -32700 | Parse error (invalid JSON) | -| -32600 | Invalid request / Unauthorized | -| -32601 | Method or skill not found | -| -32602 | Invalid params | -| -32603 | Internal error | - ---- - -## Integration Examples - -### Python (requests) - -```python -import requests - -resp = requests.post("http://localhost:20128/a2a", json={ - "jsonrpc": "2.0", "id": "1", - "method": "message/send", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Hello"}] - } -}, headers={"Authorization": "Bearer YOUR_KEY"}) - -result = resp.json()["result"] -print(result["artifacts"][0]["content"]) -print(result["metadata"]["routing_explanation"]) -``` - -### TypeScript (fetch) - -```typescript -const resp = await fetch("http://localhost:20128/a2a", { - method: "POST", - headers: { - "Content-Type": "application/json", - Authorization: "Bearer YOUR_KEY", - }, - body: JSON.stringify({ - jsonrpc: "2.0", - id: "1", - method: "message/send", - params: { - skill: "smart-routing", - messages: [{ role: "user", content: "Hello" }], - }, - }), -}); -const { result } = await resp.json(); -console.log(result.metadata.routing_explanation); -``` diff --git a/docs/i18n/ru/API_REFERENCE.md b/docs/i18n/ru/API_REFERENCE.md deleted file mode 100644 index b878605221..0000000000 --- a/docs/i18n/ru/API_REFERENCE.md +++ /dev/null @@ -1,455 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/API_REFERENCE.md) - ---- - -# API Reference - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/API_REFERENCE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/API_REFERENCE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/API_REFERENCE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/API_REFERENCE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/API_REFERENCE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/API_REFERENCE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/API_REFERENCE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/API_REFERENCE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/API_REFERENCE.md) - -Complete reference for all OmniRoute API endpoints. - ---- - -## Table of Contents - -- [Chat Completions](#chat-completions) -- [Embeddings](#embeddings) -- [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`. - -### ACP Agents - -| Endpoint | Method | Description | -| ----------------- | ------ | -------------------------------------------------------- | -| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | -| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | -| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | - -GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). - -### Resilience & Rate Limits - -| Endpoint | Method | Description | -| ----------------------- | ------- | ------------------------------- | -| `/api/resilience` | 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` diff --git a/docs/i18n/ru/ARCHITECTURE.md b/docs/i18n/ru/ARCHITECTURE.md deleted file mode 100644 index 4ea06a29f2..0000000000 --- a/docs/i18n/ru/ARCHITECTURE.md +++ /dev/null @@ -1,787 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/ARCHITECTURE.md) - ---- - -# OmniRoute Architecture - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/ARCHITECTURE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/ARCHITECTURE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/ARCHITECTURE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/ARCHITECTURE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/ARCHITECTURE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/ARCHITECTURE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/ARCHITECTURE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/ARCHITECTURE.md) - -_Last updated: 2026-03-04_ - -## 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 (`...`) for reasoning models -- Response sanitization for strict OpenAI SDK compatibility -- Role normalization (developerโ†’system, systemโ†’user) for cross-provider compatibility -- Structured output conversion (json_schema โ†’ Gemini responseSchema) -- Local persistence for providers, keys, aliases, combos, settings, pricing -- Usage/cost tracking and request logging -- Optional cloud sync for multi-device/state sync -- IP allowlist/blocklist for API access control -- Thinking budget management (passthrough/auto/custom/adaptive) -- Global system prompt injection -- Session tracking and fingerprinting -- Per-account enhanced rate limiting with provider-specific profiles -- Circuit breaker pattern for provider resilience -- Anti-thundering herd protection with mutex locking -- Signature-based request deduplication cache -- Domain layer: model availability, cost rules, fallback policy, lockout policy -- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) -- Policy engine for centralized request evaluation (lockout โ†’ budget โ†’ fallback) -- Request telemetry with p50/p95/p99 latency aggregation -- Correlation ID (X-Request-Id) for end-to-end tracing -- Compliance audit logging with opt-out per API key -- Eval framework for LLM quality assurance -- Resilience UI dashboard with real-time circuit breaker status -- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) - -Primary runtime model: - -- Next.js 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[(storage.sqlite)] - UDB[(usage tables + log artifacts)] - end - - subgraph Upstreams[Upstream Providers] - P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/Qoder/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/route.ts` (GET) -- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) -- OAuth: `src/app/api/oauth/*` -- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` -- Usage: `src/app/api/usage/*` -- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` -- CLI tooling helpers: `src/app/api/cli-tools/*` -- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) -- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) -- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) -- Sessions: `src/app/api/sessions` (GET) -- Rate limits: `src/app/api/rate-limits` (GET) -- Resilience: `src/app/api/resilience` (GET/PATCH) โ€” provider profiles, circuit breaker, rate limit state -- Resilience reset: `src/app/api/resilience/reset` (POST) โ€” reset breakers + cooldowns -- Cache stats: `src/app/api/cache/stats` (GET/DELETE) -- Model availability: `src/app/api/models/availability` (GET/POST) -- Telemetry: `src/app/api/telemetry/summary` (GET) -- Budget: `src/app/api/usage/budget` (GET/POST) -- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) -- Compliance audit: `src/app/api/compliance/audit-log` (GET) -- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) -- Policies: `src/app/api/policies` (GET/POST) - -## 2) SSE + 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` -- Response sanitization: `open-sse/handlers/responseSanitizer.ts` -- Role normalization: `open-sse/services/roleNormalizer.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`, `qoder.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 (SQLite): - -- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) -- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) -- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) -- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** - -Usage persistence: - -- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) -- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` -- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) -- legacy JSON files are migrated to SQLite by startup migrations when present - -Domain State DB (SQLite): - -- `src/lib/db/domainState.ts` โ€” CRUD operations 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: - -- primary runtime DB: `${DATA_DIR}/storage.sqlite` -- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) -- structured call payload archives: `${DATA_DIR}/call_logs/` -- optional translator/request debug sessions: `/logs/...` - -## Deployment Topology - -```mermaid -flowchart LR - 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[(storage.sqlite)] - UsageDB[(usage tables + log artifacts)] - end - - subgraph External[External Services] - Providers[AI Providers] - SyncCloud[Cloud Sync Service] - end - - CLI --> Next - Browser --> Next - Next --> Core - Next --> MainDB - Core --> MainDB - Core --> UsageDB - Core --> Providers - Next --> SyncCloud -``` - -## Module Mapping (Decision-Critical) - -### Route and API Modules - -- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs -- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) -- `src/app/api/providers*`: provider CRUD, validation, testing -- `src/app/api/provider-nodes*`: custom compatible node management -- `src/app/api/provider-models`: custom model management (CRUD) -- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) -- `src/app/api/oauth/*`: OAuth/device-code flows -- `src/app/api/keys*`: local API key lifecycle -- `src/app/api/models/alias`: alias management -- `src/app/api/combos*`: fallback combo management -- `src/app/api/pricing`: pricing overrides for cost calculation -- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) -- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) -- `src/app/api/usage/*`: usage and logs APIs -- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers -- `src/app/api/cli-tools/*`: local CLI config writers/checkers -- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) -- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) -- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) -- `src/app/api/sessions`: active session listing (GET) -- `src/app/api/rate-limits`: per-account rate limit status (GET) - -### Routing and Execution Core - -- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop -- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup -- `open-sse/executors/*`: provider-specific network and format behavior - -### Translation Registry and Format Converters - -- `open-sse/translator/index.ts`: translator registry and orchestration -- Request translators: `open-sse/translator/request/*` -- Response translators: `open-sse/translator/response/*` -- Format constants: `open-sse/translator/formats.ts` - -### Persistence - -- `src/lib/db/*`: persistent config/state and domain persistence on SQLite -- `src/lib/localDb.ts`: compatibility re-export for DB modules -- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables - -## Provider Executor Coverage (Strategy Pattern) - -Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. - -| Executor | Provider(s) | Special Handling | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | -| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, Qoder, 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 | -| Qoder | openai | OAuth (Basic) | โœ… | โœ… | โœ… | โš ๏ธ Per request | -| OpenRouter | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| GLM/Kimi/MiniMax | claude | API Key | โœ… | โœ… | โŒ | โŒ | -| DeepSeek | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Groq | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| xAI (Grok) | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Mistral | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Perplexity | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Together AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Fireworks AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Cerebras | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Cohere | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| NVIDIA NIM | openai | API Key | โœ… | โœ… | โŒ | โŒ | - -## Format Translation Coverage - -Detected source formats include: - -- `openai` -- `openai-responses` -- `claude` -- `gemini` - -Target formats include: - -- OpenAI chat/Responses -- Claude -- Gemini/Gemini-CLI/Antigravity envelope -- Kiro -- Cursor - -Translations use **OpenAI as the hub format** โ€” all conversions go through OpenAI as intermediate: - -``` -Source Format โ†’ OpenAI (hub) โ†’ Target Format -``` - -Translations are selected dynamically based on source payload shape and provider target format. - -Additional processing layers in the translation pipeline: - -- **Response sanitization** โ€” Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance -- **Role normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI targets; merges `system` โ†’ `user` for models that reject the system role (GLM, ERNIE) -- **Think tag extraction** โ€” Parses `...` blocks from content into `reasoning_content` field -- **Structured output** โ€” Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` - -## Supported API Endpoints - -| 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 `/logs//` 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 - -- SQLite schema migrations and auto-upgrade hooks at startup -- legacy JSON โ†’ SQLite migration compatibility path - -## Observability and Operational Signals - -Runtime visibility sources: - -- console logs from `src/sse/utils/logger.ts` -- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) -- textual request status log in `log.txt` (optional/compat) -- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` -- dashboard usage endpoints (`/api/usage/*`) for UI consumption - -## Security-Sensitive Boundaries - -- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing -- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning -- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format -- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level -- Cloud sync endpoints rely on API key auth + machine id semantics - -## Environment and Runtime Matrix - -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` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. -2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. -3. Request logger writes full headers/body when enabled; treat log directory as sensitive. -4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. -5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. -6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). -7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). -8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). - -## Operational Verification Checklist - -- Build from source: `npm run build` -- Build Docker image: `docker build -t omniroute .` -- Start service and verify: -- `GET /api/settings` -- `GET /api/v1/models` -- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/ru/AUTO-COMBO.md b/docs/i18n/ru/AUTO-COMBO.md deleted file mode 100644 index 2166e41dff..0000000000 --- a/docs/i18n/ru/AUTO-COMBO.md +++ /dev/null @@ -1,67 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/AUTO-COMBO.md) - ---- - -# OmniRoute Auto-Combo Engine - -> Self-managing model chains with adaptive scoring - -## How It Works - -The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**: - -| Factor | Weight | Description | -| :--------- | :----- | :---------------------------------------------- | -| Quota | 0.20 | Remaining capacity [0..1] | -| Health | 0.25 | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 | -| CostInv | 0.20 | Inverse cost (cheaper = higher score) | -| LatencyInv | 0.15 | Inverse p95 latency (faster = higher) | -| TaskFit | 0.10 | Model ร— task type fitness score | -| Stability | 0.10 | Low variance in latency/errors | - -## Mode Packs - -| Pack | Focus | Key Weight | -| :---------------------- | :----------- | :--------------- | -| ๐Ÿš€ **Ship Fast** | Speed | latencyInv: 0.35 | -| ๐Ÿ’ฐ **Cost Saver** | Economy | costInv: 0.40 | -| ๐ŸŽฏ **Quality First** | Best model | taskFit: 0.40 | -| ๐Ÿ“ก **Offline Friendly** | Availability | quota: 0.40 | - -## Self-Healing - -- **Temporary exclusion**: Score < 0.2 โ†’ excluded for 5 min (progressive backoff, max 30 min) -- **Circuit breaker awareness**: OPEN โ†’ auto-excluded; HALF_OPEN โ†’ probe requests -- **Incident mode**: >50% OPEN โ†’ disable exploration, maximize stability -- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout - -## Bandit Exploration - -5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode. - -## API - -```bash -# Create auto-combo -curl -X POST http://localhost:20128/api/combos/auto \ - -H "Content-Type: application/json" \ - -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}' - -# List auto-combos -curl http://localhost:20128/api/combos/auto -``` - -## Task Fitness - -30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` โ†’ high coding score). - -## Files - -| File | Purpose | -| :------------------------------------------- | :------------------------------------ | -| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization | -| `open-sse/services/autoCombo/taskFitness.ts` | Model ร— task fitness lookup | -| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap | -| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode | -| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles | -| `src/app/api/combos/auto/route.ts` | REST API | diff --git a/docs/i18n/ru/CHANGELOG.md b/docs/i18n/ru/CHANGELOG.md index 547ef57cc5..ac5b0d436f 100644 --- a/docs/i18n/ru/CHANGELOG.md +++ b/docs/i18n/ru/CHANGELOG.md @@ -1,12 +1,92 @@ # Changelog (ะ ัƒััะบะธะน) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CHANGELOG.md) --- - ## [Unreleased] +### ๐Ÿ› ๏ธ Maintenance + +- **AGENTS.md rewrite:** Condensed from 297โ†’153 lines. Added build/lint/test commands (including single-test execution), code style guidelines (Prettier, TypeScript, ESLint, naming, imports, error handling, security), and trimmed verbose architecture tables for AI agent consumption. + +## [3.4.2] - 2026-04-01 + +### ๐Ÿ› Bug Fixes + +- **CI Stabilization:** Fixed failing analytics/settings Playwright selectors and request assertions so GitHub Actions E2E runs pass reliably across localized UIs and switch-based controls. +- **Deterministic Tests:** Removed date-sensitive quota fixtures from Copilot usage tests and aligned idempotency/model catalog tests with the merged runtime behavior. +- **MCP Type Hardening:** Removed zero-budget explicit `any` regressions from the MCP server tool registration path, restoring the `check:any-budget:t11` workflow gate. + +### ๐Ÿ› ๏ธ Maintenance + +- **Release Branch Integration:** Consolidated the active feature branches into `release/v3.4.2` on top of current `main` and validated the branch with lint, unit, coverage, build, and CI-mode E2E runs. + +## [3.4.1] - 2026-03-31 + +> [!WARNING] +> **BREAKING CHANGE: request logging, retention, and logging environment variables have been redesigned.** +> On the first startup after upgrading, OmniRoute archives legacy request logs from `DATA_DIR/logs/`, legacy `DATA_DIR/call_logs/`, and `DATA_DIR/log.txt` into `DATA_DIR/log_archives/*.zip`, then removes the deprecated layout and switches to the new unified artifact format under `DATA_DIR/call_logs/`. + +### โœจ New Features + +- **.ENV Migration Utility:** Included `scripts/migrate-env.mjs` to seamlessly migrate ` Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` - ---- - -## Step 2 โ€” Install CLI Tools - -All npm-based tools require Node.js 18+: - -```bash -# Claude Code (Anthropic) -npm install -g @anthropic-ai/claude-code - -# OpenAI Codex -npm install -g @openai/codex - -# Gemini CLI (Google) -npm install -g @google/gemini-cli - -# OpenCode -npm install -g opencode-ai - -# Cline -npm install -g cline - -# KiloCode -npm install -g kilecode - -# Kiro CLI (Amazon โ€” requires curl + unzip) -apt-get install -y unzip # on Debian/Ubuntu -curl -fsSL https://cli.kiro.dev/install | bash -export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc -``` - -**Verify:** - -```bash -claude --version # 2.x.x -codex --version # 0.x.x -gemini --version # 0.x.x -opencode --version # x.x.x -cline --version # 2.x.x -kilocode --version # x.x.x (or: kilo --version) -kiro-cli --version # 1.x.x -``` - ---- - -## Step 3 โ€” Set Global Environment Variables - -Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`: - -```bash -# OmniRoute Universal Endpoint -export OPENAI_BASE_URL="http://localhost:20128/v1" -export OPENAI_API_KEY="sk-your-omniroute-key" -export ANTHROPIC_BASE_URL="http://localhost:20128/v1" -export ANTHROPIC_API_KEY="sk-your-omniroute-key" -export GEMINI_BASE_URL="http://localhost:20128/v1" -export GEMINI_API_KEY="sk-your-omniroute-key" -``` - -> For a **remote server** replace `localhost:20128` with the server IP or domain, -> e.g. `http://192.168.0.15:20128`. - ---- - -## Step 4 โ€” Configure Each Tool - -### Claude Code - -```bash -# Via CLI: -claude config set --global api-base-url http://localhost:20128/v1 - -# Or create ~/.claude/settings.json: -mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF -{ - "apiBaseUrl": "http://localhost:20128/v1", - "apiKey": "sk-your-omniroute-key" -} -EOF -``` - -**Test:** `claude "say hello"` - ---- - -### OpenAI Codex - -```bash -mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF -model: auto -apiKey: sk-your-omniroute-key -apiBaseUrl: http://localhost:20128/v1 -EOF -``` - -**Test:** `codex "what is 2+2?"` - ---- - -### Gemini CLI - -```bash -mkdir -p ~/.gemini && cat > ~/.gemini/settings.json << EOF -{ - "apiKey": "sk-your-omniroute-key", - "baseUrl": "http://localhost:20128/v1" -} -EOF -``` - -**Test:** `gemini "hello"` - ---- - -### OpenCode - -```bash -mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF -[provider.openai] -base_url = "http://localhost:20128/v1" -api_key = "sk-your-omniroute-key" -EOF -``` - -**Test:** `opencode` - ---- - -### Cline (CLI or VS Code) - -**CLI mode:** - -```bash -mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF -{ - "apiProvider": "openai", - "openAiBaseUrl": "http://localhost:20128/v1", - "openAiApiKey": "sk-your-omniroute-key" -} -EOF -``` - -**VS Code mode:** -Cline extension settings โ†’ API Provider: `OpenAI Compatible` โ†’ Base URL: `http://localhost:20128/v1` - -Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ Cline โ†’ Apply Config**. - ---- - -### KiloCode (CLI or VS Code) - -**CLI mode:** - -```bash -kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key -``` - -**VS Code settings:** - -```json -{ - "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", - "kilo-code.apiKey": "sk-your-omniroute-key" -} -``` - -Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ KiloCode โ†’ Apply Config**. - ---- - -### Continue (VS Code Extension) - -Edit `~/.continue/config.yaml`: - -```yaml -models: - - name: OmniRoute - provider: openai - model: auto - apiBase: http://localhost:20128/v1 - apiKey: sk-your-omniroute-key - default: true -``` - -Restart VS Code after editing. - ---- - -### Kiro CLI (Amazon) - -```bash -# Login to your AWS/Kiro account: -kiro-cli login - -# The CLI uses its own auth โ€” OmniRoute is not needed as backend for Kiro CLI itself. -# Use kiro-cli alongside OmniRoute for other tools. -kiro-cli status -``` - ---- - -### Cursor (Desktop App) - -> **Note:** Cursor routes requests through its cloud. For OmniRoute integration, -> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL. - -Via GUI: **Settings โ†’ Models โ†’ OpenAI API Key** - -- Base URL: `https://your-domain.com/v1` -- API Key: your OmniRoute key - ---- - -## Dashboard Auto-Configuration - -The OmniRoute dashboard automates configuration for most tools: - -1. Go to `http://localhost:20128/dashboard/cli-tools` -2. Expand any tool card -3. Select your API key from the dropdown -4. Click **Apply Config** (if tool is detected as installed) -5. Or copy the generated config snippet manually - ---- - -## Built-in Agents: Droid & OpenClaw - -**Droid** and **OpenClaw** are AI agents built directly into OmniRoute โ€” no installation needed. -They run as internal routes and use OmniRoute's model routing automatically. - -- Access: `http://localhost:20128/dashboard/agents` -- Configure: same combos and providers as all other tools -- No API key or CLI install required - ---- - -## Available API Endpoints - -| Endpoint | Description | Use For | -| -------------------------- | ----------------------------- | --------------------------- | -| `/v1/chat/completions` | Standard chat (all providers) | All modern tools | -| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows | -| `/v1/completions` | Legacy text completions | Older tools using `prompt:` | -| `/v1/embeddings` | Text embeddings | RAG, search | -| `/v1/images/generations` | Image generation | DALL-E, Flux, etc. | -| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS | -| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI | - ---- - -## Troubleshooting - -| Error | Cause | Fix | -| ------------------------- | ----------------------- | ------------------------------------------ | -| `Connection refused` | OmniRoute not running | `pm2 start omniroute` | -| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` | -| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` | -| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` | -| CLI shows "not installed" | Binary not in PATH | Check `which ` | -| `kiro-cli: not found` | Not in PATH | `export PATH="$HOME/.local/bin:$PATH"` | - ---- - -## Quick Setup Script (One Command) - -```bash -# Install all CLIs and configure for OmniRoute (replace with your key and server URL) -OMNIROUTE_URL="http://localhost:20128/v1" -OMNIROUTE_KEY="sk-your-omniroute-key" - -npm install -g @anthropic-ai/claude-code @openai/codex @google/gemini-cli opencode-ai cline kilecode - -# Kiro CLI -apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash - -# Write configs -mkdir -p ~/.claude ~/.codex ~/.gemini ~/.config/opencode ~/.continue - -cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" -cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" -cat > ~/.gemini/settings.json <<< "{\"apiKey\":\"$OMNIROUTE_KEY\",\"baseUrl\":\"$OMNIROUTE_URL\"}" -cat >> ~/.bashrc << EOF -export OPENAI_BASE_URL="$OMNIROUTE_URL" -export OPENAI_API_KEY="$OMNIROUTE_KEY" -export ANTHROPIC_BASE_URL="$OMNIROUTE_URL" -export ANTHROPIC_API_KEY="$OMNIROUTE_KEY" -EOF - -source ~/.bashrc -echo "โœ… All CLIs installed and configured for OmniRoute" -``` diff --git a/docs/i18n/ru/CODEBASE_DOCUMENTATION.md b/docs/i18n/ru/CODEBASE_DOCUMENTATION.md deleted file mode 100644 index e2d7950052..0000000000 --- a/docs/i18n/ru/CODEBASE_DOCUMENTATION.md +++ /dev/null @@ -1,593 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CODEBASE_DOCUMENTATION.md) - ---- - -# omniroute โ€” Codebase Documentation - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) - -> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. - ---- - -## 1. 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
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, Qoder, 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 | -| Qoder | 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"] -``` diff --git a/docs/i18n/ru/CONTRIBUTING.md b/docs/i18n/ru/CONTRIBUTING.md new file mode 100644 index 0000000000..8492a94d9a --- /dev/null +++ b/docs/i18n/ru/CONTRIBUTING.md @@ -0,0 +1,299 @@ +# Contributing to OmniRoute (ะ ัƒััะบะธะน) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CONTRIBUTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CONTRIBUTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CONTRIBUTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CONTRIBUTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CONTRIBUTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CONTRIBUTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CONTRIBUTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CONTRIBUTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CONTRIBUTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CONTRIBUTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CONTRIBUTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CONTRIBUTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CONTRIBUTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CONTRIBUTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CONTRIBUTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CONTRIBUTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CONTRIBUTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CONTRIBUTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CONTRIBUTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CONTRIBUTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CONTRIBUTING.md) + +--- + +Thank you for your interest in contributing! This guide covers everything you need to get started. + +--- + +## Development Setup + +### Prerequisites + +- **Node.js** >= 18 < 24 (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` | `20128` | Server port | +| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | Base URL for frontend | +| `JWT_SECRET` | (generate above) | JWT signing secret | +| `INITIAL_PASSWORD` | `CHANGEME` | First login password | +| `APP_LOG_LEVEL` | `info` | Log verbosity level | + +### Dashboard Settings + +The dashboard provides UI toggles for features that can also be configured via environment variables: + +| Setting Location | Toggle | Description | +| ------------------- | ------------------ | ------------------------------ | +| Settings โ†’ Advanced | Debug Mode | Enable debug request logs (UI) | +| Settings โ†’ General | Sidebar Visibility | Show/hide sidebar sections | + +These settings are stored in the database and persist across restarts, overriding env var defaults when set. + +### 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:20128/dashboard` +- **API**: `http://localhost:20128/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`, `mcp`, `a2a`, `memory`, `skills`. + +--- + +## Running Tests + +```bash +# All tests (unit + vitest + ecosystem + e2e) +npm run test:all + +# Single test file (Node.js native test runner โ€” most tests use this) +node --import tsx/esm --test tests/unit/your-file.test.mjs + +# Vitest (MCP server, autoCombo, cache) +npm run test:vitest + +# E2E tests (requires Playwright) +npm run test:e2e + +# Protocol clients E2E (MCP transports, A2A) +npm run test:protocols:e2e + +# Ecosystem compatibility tests +npm run test:ecosystem + +# Coverage (55% min statements/lines/functions; 60% branches) +npm run test:coverage +npm run coverage:report + +# Lint + format check +npm run lint +npm run check +``` + +Coverage notes: + +- `npm run test:coverage` measures source coverage for the main unit test suite, excludes `tests/**`, and includes `open-sse/**` +- `npm run coverage:report` prints the detailed file-by-file report from the latest coverage run +- `npm run test:coverage:legacy` preserves the older metric for historical comparison +- See `docs/COVERAGE_PLAN.md` for the phased coverage improvement roadmap + +Current test status: **122 unit test files** covering: + +- Provider translators and format conversion +- Rate limiting, circuit breaker, and resilience +- Semantic cache, idempotency, progress tracking +- Database operations and schema (21 DB modules) +- OAuth flows and authentication +- API endpoint validation (Zod v4) +- MCP server tools and scope enforcement +- Memory and Skills systems + +--- + +## Code Style + +- **ESLint** โ€” Run `npm run lint` before committing +- **Prettier** โ€” Auto-formatted via `lint-staged` on commit (2 spaces, semicolons, double quotes, 100 char width, es5 trailing commas) +- **TypeScript** โ€” All `src/` code uses `.ts`/`.tsx`; `open-sse/` uses `.ts`/`.js`; document with TSDoc (`@param`, `@returns`, `@throws`) +- **No `eval()`** โ€” ESLint enforces `no-eval`, `no-implied-eval`, `no-new-func` +- **Zod validation** โ€” Use Zod v4 schemas for all API input validation +- **Naming**: Files = camelCase/kebab-case, components = PascalCase, constants = UPPER_SNAKE + +--- + +## Project Structure + +``` +src/ # TypeScript (.ts / .tsx) +โ”œโ”€โ”€ app/ # Next.js 16 App Router +โ”‚ โ”œโ”€โ”€ (dashboard)/ # Dashboard pages (23 sections) +โ”‚ โ”œโ”€โ”€ api/ # API routes (51 directories) +โ”‚ โ””โ”€โ”€ login/ # Auth pages (.tsx) +โ”œโ”€โ”€ domain/ # Policy engine (policyEngine, comboResolver, costRules, etc.) +โ”œโ”€โ”€ lib/ # Core business logic (.ts) +โ”‚ โ”œโ”€โ”€ a2a/ # Agent-to-Agent v0.3 protocol server +โ”‚ โ”œโ”€โ”€ acp/ # Agent Communication Protocol registry +โ”‚ โ”œโ”€โ”€ compliance/ # Compliance policy engine +โ”‚ โ”œโ”€โ”€ db/ # SQLite database layer (21 modules + 16 migrations) +โ”‚ โ”œโ”€โ”€ memory/ # Persistent conversational memory +โ”‚ โ”œโ”€โ”€ oauth/ # OAuth providers, services, and utilities +โ”‚ โ”œโ”€โ”€ skills/ # Extensible skill framework +โ”‚ โ”œโ”€โ”€ usage/ # Usage tracking and cost calculation +โ”‚ โ””โ”€โ”€ localDb.ts # Re-export layer only โ€” never add logic here +โ”œโ”€โ”€ middleware/ # Request middleware (promptInjectionGuard) +โ”œโ”€โ”€ mitm/ # MITM proxy (cert, DNS, target routing) +โ”œโ”€โ”€ shared/ +โ”‚ โ”œโ”€โ”€ components/ # React components (.tsx) +โ”‚ โ”œโ”€โ”€ constants/ # Provider definitions (60+), MCP scopes, routing strategies +โ”‚ โ”œโ”€โ”€ utils/ # Circuit breaker, sanitizer, auth helpers +โ”‚ โ””โ”€โ”€ validation/ # Zod v4 schemas +โ””โ”€โ”€ sse/ # SSE proxy pipeline + +open-sse/ # @omniroute/open-sse workspace +โ”œโ”€โ”€ executors/ # 14 provider-specific request executors +โ”œโ”€โ”€ handlers/ # 11 request handlers (chat, responses, embeddings, images, etc.) +โ”œโ”€โ”€ mcp-server/ # MCP server (25 tools, 3 transports, 10 scopes) +โ”œโ”€โ”€ services/ # 36+ services (combo, autoCombo, rateLimitManager, etc.) +โ”œโ”€โ”€ translator/ # Format translators (OpenAI โ†” Claude โ†” Gemini โ†” Responses โ†” Ollama) +โ”œโ”€โ”€ transformer/ # Responses API transformer +โ””โ”€โ”€ utils/ # 22 utility modules (stream, TLS, proxy, logging) + +electron/ # Electron desktop app (cross-platform) + +tests/ +โ”œโ”€โ”€ unit/ # Node.js test runner (122 test files) +โ”œโ”€โ”€ integration/ # Integration tests +โ”œโ”€โ”€ e2e/ # Playwright tests +โ”œโ”€โ”€ security/ # Security tests +โ”œโ”€โ”€ translator/ # Translator-specific tests +โ””โ”€โ”€ load/ # Load tests + +docs/ # Documentation +โ”œโ”€โ”€ ARCHITECTURE.md # System architecture +โ”œโ”€โ”€ API_REFERENCE.md # All endpoints +โ”œโ”€โ”€ USER_GUIDE.md # Provider setup, CLI integration +โ”œโ”€โ”€ TROUBLESHOOTING.md # Common issues +โ”œโ”€โ”€ MCP-SERVER.md # MCP server (25 tools) +โ”œโ”€โ”€ A2A-SERVER.md # A2A agent protocol +โ”œโ”€โ”€ AUTO-COMBO.md # Auto-combo engine +โ”œโ”€โ”€ CLI-TOOLS.md # CLI tools integration +โ”œโ”€โ”€ COVERAGE_PLAN.md # Test coverage improvement plan +โ”œโ”€โ”€ openapi.yaml # OpenAPI specification +โ””โ”€โ”€ adr/ # Architecture Decision Records +``` + +--- + +## Adding a New Provider + +### Step 1: Register Provider Constants + +Add to `src/shared/constants/providers.ts` โ€” Zod-validated at module load. + +### Step 2: Add Executor (if custom logic needed) + +Create executor in `open-sse/executors/your-provider.ts` extending the base executor. + +### Step 3: Add Translator (if non-OpenAI format) + +Create request/response translators in `open-sse/translator/`. + +### Step 4: Add OAuth Config (if OAuth-based) + +Add OAuth credentials in `src/lib/oauth/constants/oauth.ts` and service in `src/lib/oauth/services/`. + +### Step 5: Register Models + +Add model definitions in `open-sse/config/providerRegistry.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 +- [ ] All inputs validated with Zod schemas +- [ ] CHANGELOG updated (if user-facing change) +- [ ] Documentation updated (if applicable) + +--- + +## Releasing + +Releases are managed via the `/generate-release` workflow. When a new GitHub Release is created, the package is **automatically published to npm** via GitHub Actions. + +--- + +## Getting Help + +- **Architecture**: See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) +- **API Reference**: See [`docs/API_REFERENCE.md`](docs/API_REFERENCE.md) +- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **ADRs**: See `docs/adr/` for architectural decision records diff --git a/docs/i18n/ru/FEATURES.md b/docs/i18n/ru/FEATURES.md deleted file mode 100644 index 1bc31bcc81..0000000000 --- a/docs/i18n/ru/FEATURES.md +++ /dev/null @@ -1,147 +0,0 @@ -# OmniRoute โ€” Dashboard Features Gallery (ะ ัƒััะบะธะน) - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) - -> ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../docs/FEATURES.md) - ---- - -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 (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. - -![Providers Dashboard](screenshots/01-providers.png) - ---- - -## ๐ŸŽจ Combos - -Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. - -![Combos Dashboard](screenshots/02-combos.png) - ---- - -## ๐Ÿ“Š Analytics - -Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. - -![Analytics Dashboard](screenshots/03-analytics.png) - ---- - -## ๐Ÿฅ System Health - -Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. - -![Health Dashboard](screenshots/04-health.png) - ---- - -## ๐Ÿ”ง Translator Playground - -Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). - -![Translator Playground](screenshots/05-translator.png) - ---- - -## ๐ŸŽฎ Model Playground _(v2.0.9+)_ - -Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. - ---- - -## ๐ŸŽจ Themes _(v2.0.5+)_ - -Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. - ---- - -## โš™๏ธ Settings - -Comprehensive settings panel with tabs: - -- **General** โ€” System storage, backup management (export/import database) -- **Appearance** โ€” Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls -- **Security** โ€” API endpoint protection, custom provider blocking, IP filtering, session info -- **Routing** โ€” Model aliases, background task degradation -- **Resilience** โ€” Rate limit persistence, circuit breaker tuning -- **Advanced** โ€” Configuration overrides - -![Settings Dashboard](screenshots/06-settings.png) - ---- - -## ๐Ÿ”ง CLI Tools - -One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. - -![CLI Tools Dashboard](screenshots/07-cli-tools.png) - ---- - -## ๐Ÿค– CLI Agents _(v2.0.11+)_ - -Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: - -- **Installation status** โ€” Installed / Not Found with version detection -- **Protocol badges** โ€” stdio, HTTP, etc. -- **Custom agents** โ€” Register any CLI tool via form (name, binary, version command, spawn args) -- **CLI Fingerprint Matching** โ€” Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP - ---- - -## ๐Ÿ–ผ๏ธ Media _(v2.0.3+)_ - -Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. - ---- - -## ๐Ÿ“ Request Logs - -Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. - -![Usage Logs](screenshots/08-usage.png) - ---- - -## ๐ŸŒ API Endpoint - -Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. - -![Endpoint Dashboard](screenshots/09-endpoint.png) - ---- - -## ๐Ÿ”‘ API Key Management - -Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. - ---- - -## ๐Ÿ“‹ Audit Log - -Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. - ---- - -## ๐Ÿ–ฅ๏ธ Desktop Application - -Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. - -Key features: - -- Server readiness polling (no blank screen on cold start) -- System tray with port management -- Content Security Policy -- Single-instance lock -- Auto-update on restart -- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) -- Hardened Electron build packaging โ€” symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+) - -๐Ÿ“– See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/ru/MCP-SERVER.md b/docs/i18n/ru/MCP-SERVER.md deleted file mode 100644 index 829acd30b1..0000000000 --- a/docs/i18n/ru/MCP-SERVER.md +++ /dev/null @@ -1,87 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/MCP-SERVER.md) - ---- - -# OmniRoute MCP Server Documentation - -> Model Context Protocol server with 16 intelligent tools - -## Installation - -OmniRoute MCP is built-in. Start it with: - -```bash -omniroute --mcp -``` - -Or via the open-sse transport: - -```bash -# HTTP streamable transport (port 20130) -omniroute --dev # MCP auto-starts on /mcp endpoint -``` - -## IDE Configuration - -See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup. - ---- - -## Essential Tools (8) - -| Tool | Description | -| :------------------------------ | :--------------------------------------- | -| `omniroute_get_health` | Gateway health, circuit breakers, uptime | -| `omniroute_list_combos` | All configured combos with models | -| `omniroute_get_combo_metrics` | Performance metrics for a specific combo | -| `omniroute_switch_combo` | Switch active combo by ID/name | -| `omniroute_check_quota` | Quota status per provider or all | -| `omniroute_route_request` | Send a chat completion through OmniRoute | -| `omniroute_cost_report` | Cost analytics for a time period | -| `omniroute_list_models_catalog` | Full model catalog with capabilities | - -## Advanced Tools (8) - -| Tool | Description | -| :--------------------------------- | :---------------------------------------------- | -| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | -| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | -| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | -| `omniroute_test_combo` | Live-test all models in a combo | -| `omniroute_get_provider_metrics` | Detailed metrics for one provider | -| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | -| `omniroute_explain_route` | Explain a past routing decision | -| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | - -## Authentication - -MCP tools are authenticated via API key scopes. Each tool requires specific scopes: - -| Scope | Tools | -| :------------- | :----------------------------------------------- | -| `read:health` | get_health, get_provider_metrics | -| `read:combos` | list_combos, get_combo_metrics | -| `write:combos` | switch_combo | -| `read:quota` | check_quota | -| `write:route` | route_request, simulate_route, test_combo | -| `read:usage` | cost_report, get_session_snapshot, explain_route | -| `write:config` | set_budget_guard, set_resilience_profile | -| `read:models` | list_models_catalog, best_combo_for_task | - -## Audit Logging - -Every tool call is logged to `mcp_tool_audit` with: - -- Tool name, arguments, result -- Duration (ms), success/failure -- API key hash, timestamp - -## Files - -| File | Purpose | -| :------------------------------------------- | :------------------------------------------ | -| `open-sse/mcp-server/server.ts` | MCP server creation + 16 tool registrations | -| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport | -| `open-sse/mcp-server/auth.ts` | API key + scope validation | -| `open-sse/mcp-server/audit.ts` | Tool call audit logging | -| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers | diff --git a/docs/i18n/ru/README.md b/docs/i18n/ru/README.md index 75ffdfd691..3c1c1ae345 100644 --- a/docs/i18n/ru/README.md +++ b/docs/i18n/ru/README.md @@ -1,12 +1,12 @@ # ๐Ÿš€ OmniRoute โ€” The Free AI Gateway (ะ ัƒััะบะธะน) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/README.md) --- ### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback. -_Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._ +_Your universal API proxy โ€” one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._ **Chat Completions โ€ข Embeddings โ€ข Image Generation โ€ข Video โ€ข Music โ€ข Audio โ€ข Reranking โ€ข **Web Search** โ€ข MCP Server โ€ข A2A Protocol โ€ข 100% TypeScript** @@ -46,15 +46,17 @@ _Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now wi > - `APP_LOG_FILE_PATH` > - `APP_LOG_MAX_FILE_SIZE` > - `APP_LOG_RETENTION_DAYS` +> - `APP_LOG_MAX_FILES` > - `APP_LOG_LEVEL` > - `APP_LOG_FORMAT` > - `CALL_LOG_RETENTION_DAYS` +> - `CALL_LOG_MAX_ENTRIES` > > For release details and upgrade notes, see the [CHANGELOG](CHANGELOG.md). --- -## ๐Ÿ†• What's New in v3.0.0 +## ๐Ÿ†• What's New > **Upgrading from v2.9.5?** โ€” See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes. @@ -274,7 +276,7 @@ Developers pay $20โ€“200/month for Claude Pro, Codex Pro, or GitHub Copilot. Eve - **Smart 4-Tier Fallback** โ€” If subscription quota runs out, automatically redirects to API Key โ†’ Cheap โ†’ Free with zero manual intervention - **Real-Time Quota Tracking** โ€” Shows token consumption in real-time with reset countdown (5h, daily, weekly) - **Multi-Account Support** โ€” Multiple accounts per provider with auto round-robin โ€” when one runs out, switches to the next -- **Custom Combos** โ€” Customizable fallback chains with 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Custom Combos** โ€” Customizable fallback chains with 9 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random) - **Codex Business Quotas** โ€” Business/Team workspace quota monitoring directly in the dashboard @@ -286,7 +288,7 @@ OpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If **How OmniRoute solves it:** -- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 67+ providers +- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 60+ providers - **Format Translation** โ€” Automatic and transparent: OpenAI โ†” Claude โ†” Gemini โ†” Responses API - **Response Sanitization** โ€” Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+ - **Role Normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI providers; `system` โ†’ `user` for GLM/ERNIE @@ -372,7 +374,7 @@ Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code.. - **CLI Tools Dashboard** โ€” Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline - **GitHub Copilot Config Generator** โ€” Generates `chatLanguageModels.json` for VS Code with bulk model selection - **Onboarding Wizard** โ€” Guided 4-step setup for first-time users -- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 67+ providers +- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 60+ providers @@ -419,7 +421,7 @@ When a call fails, the dev doesn't know if it was a rate limit, expired token, w - **SQLite Proxy Logs** โ€” Persistent logs that survive server restarts - **Translator Playground** โ€” 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time) - **Request Telemetry** โ€” p50/p95/p99 latency + X-Request-Id tracing -- **File-Based Logging with Rotation** โ€” Console interceptor captures everything to JSON log with size-based rotation +- **File-Based Logging with Rotation** โ€” App logs rotate by size, retention days, and archive count; call log artifacts rotate by retention days and file count - **System Info Report** โ€” `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage. @@ -514,7 +516,7 @@ Developers who want all responses in a specific language, with a specific tone, - **System Prompt Injection** โ€” Global prompt applied to all requests - **Thinking Budget Validation** โ€” Reasoning token allocation control per request (passthrough, auto, custom, adaptive) -- **6 Routing Strategies** โ€” Global strategies that determine how requests are distributed +- **9 Routing Strategies** โ€” Global strategies that determine how requests are distributed - **Wildcard Router** โ€” `provider/*` patterns route dynamically to any provider - **Combo Enable/Disable Toggle** โ€” Toggle combos directly from the dashboard - **Provider Toggle** โ€” Enable/disable all connections for a provider with one click @@ -581,7 +583,7 @@ Different clients should have least-privilege access to tool categories. **How OmniRoute solves it:** -- 9 granular MCP scopes for controlled tool access +- 10 granular MCP scopes for controlled tool access - Scope enforcement and visibility in MCP management UI - Safe default posture for operational tooling @@ -1325,19 +1327,19 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. ### ๐Ÿค– Agent & Protocol Operations (v2.0) -| Feature | What It Does | -| ------------------------------------- | -------------------------------------------------------------------------------------------------- | -| ๐Ÿ”ง **MCP Server (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) | -| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | -| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | -| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | -| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | -| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | -| ๐Ÿ” **MCP Scope Enforcement** | 9 granular scope permissions for controlled tool access | -| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | -| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | -| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | -| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | +| Feature | What It Does | +| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| ๐Ÿ”ง **MCP Server (25 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools | +| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | +| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | +| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | +| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | +| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | +| ๐Ÿ” **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access | +| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | +| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | +| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | +| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | ### ๐Ÿง  Routing & Intelligence @@ -1348,7 +1350,7 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. | ๐Ÿ”„ **Format Translation** | OpenAI โ†” Claude โ†” Gemini โ†” Responses with schema-safe conversions | | ๐Ÿ‘ฅ **Multi-Account Support** | Multiple accounts per provider with intelligent selection | | ๐Ÿ”„ **Auto Token Refresh** | OAuth tokens refresh automatically with retry | -| ๐ŸŽจ **Custom Combos** | 6 balancing strategies + fallback chain control | +| ๐ŸŽจ **Custom Combos** | 9 balancing strategies + fallback chain control | | ๐ŸŒ **Wildcard Router** | `provider/*` dynamic routing | | ๐Ÿง  **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits | | ๐Ÿ”€ **Model Aliases** | Built-in + custom model aliasing and migration safety | @@ -1949,6 +1951,7 @@ opencode - Request artifacts are written to `DATA_DIR/call_logs/` as one JSON file per request - Enable pipeline capture from Dashboard โ†’ Logs โ†’ Request Logs if you need detailed per-stage payloads - Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log` +- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed **Connection test shows "Invalid" for OpenAI-compatible providers** diff --git a/docs/i18n/ru/RELEASE_CHECKLIST.md b/docs/i18n/ru/RELEASE_CHECKLIST.md deleted file mode 100644 index 903e812c3f..0000000000 --- a/docs/i18n/ru/RELEASE_CHECKLIST.md +++ /dev/null @@ -1,37 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/RELEASE_CHECKLIST.md) - ---- - -# Release Checklist - -Use this checklist before tagging or publishing a new OmniRoute release. - -## Version and Changelog - -1. Bump `package.json` version (`x.y.z`) in the release branch. -2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: - - `## [x.y.z] โ€” YYYY-MM-DD` -3. Keep `## [Unreleased]` as the first changelog section for upcoming work. -4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. - -## API Docs - -1. Update `docs/openapi.yaml`: - - `info.version` must equal `package.json` version. -2. Validate endpoint examples if API contracts changed. - -## Runtime Docs - -1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. -2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. -3. Update localized docs if source docs changed significantly. - -## Automated Check - -Run the sync guard locally before opening PR: - -```bash -npm run check:docs-sync -``` - -CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/ru/SECURITY.md b/docs/i18n/ru/SECURITY.md new file mode 100644 index 0000000000..c239cacf5a --- /dev/null +++ b/docs/i18n/ru/SECURITY.md @@ -0,0 +1,179 @@ +# Security Policy (ะ ัƒััะบะธะน) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../SECURITY.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/SECURITY.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/SECURITY.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/SECURITY.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/SECURITY.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/SECURITY.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/SECURITY.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/SECURITY.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/SECURITY.md) + +--- + +## 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 | +| ------- | -------------- | +| 3.4.x | โœ… Active | +| 3.0.x | โœ… Security | +| < 3.0.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 | +| **MCP Scopes** | 10 granular scopes for MCP tool access control | + +### ๐Ÿ›ก๏ธ 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:::` +- 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** | Allowlist/blocklist IP ranges in dashboard | +| **Rate Limiting** | Per-provider rate limits with automatic backoff | +| **Anti-Thundering Herd** | Mutex + per-connection locking prevents cascading 502s | +| **TLS Fingerprint** | Browser-like TLS fingerprint spoofing to reduce bot detection | +| **CLI Fingerprint** | Per-provider header/body ordering to match native CLI signatures | + +### ๐Ÿ”Œ Resilience & Availability + +| 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 `CALL_LOG_RETENTION_DAYS` | +| **No-Log Opt-out** | Per API key `noLog` flag disables request logging | +| **Audit Log** | Administrative actions tracked in `audit_log` table | +| **MCP Audit** | SQLite-backed audit logging for all MCP tool calls | +| **Zod Validation** | All API inputs validated with Zod v4 schemas at module load | + +--- + +## 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 +- Provider constants validated at module load via Zod (`src/shared/validation/providerSchema.ts`) diff --git a/docs/i18n/ru/TROUBLESHOOTING.md b/docs/i18n/ru/TROUBLESHOOTING.md deleted file mode 100644 index 63c148000a..0000000000 --- a/docs/i18n/ru/TROUBLESHOOTING.md +++ /dev/null @@ -1,258 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/TROUBLESHOOTING.md) - ---- - -# Troubleshooting - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/TROUBLESHOOTING.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/TROUBLESHOOTING.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/TROUBLESHOOTING.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/TROUBLESHOOTING.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/TROUBLESHOOTING.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/TROUBLESHOOTING.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/TROUBLESHOOTING.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/TROUBLESHOOTING.md) - -Common problems and solutions for OmniRoute. - ---- - -## Quick Fixes - -| Problem | Solution | -| ----------------------------- | ------------------------------------------------------------------ | -| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | -| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | -| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | -| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | -| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | - ---- - -## Provider Issues - -### "Language model did not provide messages" - -**Cause:** Provider quota exhausted. - -**Fix:** - -1. 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, Qoder) 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}/storage.sqlite` (providers, combos, aliases, keys, settings) -- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` -- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) - ---- - -## Circuit Breaker Issues - -### Provider stuck in OPEN state - -When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. - -**Fix:** - -1. 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 -- **SDK returns raw string instead of object** โ€” Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures -- **GLM/ERNIE rejects `system` role** โ€” Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models -- **`developer` role not recognized** โ€” Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers -- **`json_schema` not working with Gemini** โ€” Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` - ---- - -## Resilience Settings - -### Auto rate-limit not triggering - -- 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. - ---- - -## Optional RAG / LLM failure taxonomy (16 problems) - -Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. - -In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. - -If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: - -- retrieval drift and broken context boundaries -- empty or stale indexes and vector stores -- embedding versus semantic mismatch -- prompt assembly and context window issues -- logic collapse and overconfident answers -- long chain and agent coordination failures -- multi agent memory and role drift -- deployment and bootstrap ordering problems - -The idea is simple: - -1. When you investigate a bad response, capture: - - user task and request - - route or provider combo in OmniRoute - - any RAG context used downstream (retrieved documents, tool calls, etc) -2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` โ€ฆ `No.16`). -3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. -4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. - -Full text and concrete recipes live here (MIT license, text only): - -[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) - -You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. - ---- - -## Still Stuck? - -- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details -- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints -- **Health Dashboard**: Check **Dashboard โ†’ Health** for real-time system status -- **Translator**: Use **Dashboard โ†’ Translator** to debug format issues diff --git a/docs/i18n/ru/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/ru/VM_DEPLOYMENT_GUIDE.md deleted file mode 100644 index acc6db698f..0000000000 --- a/docs/i18n/ru/VM_DEPLOYMENT_GUIDE.md +++ /dev/null @@ -1,401 +0,0 @@ -# OmniRoute โ€” ะ ัƒะบะพะฒะพะดัั‚ะฒะพ ะฟะพ ั€ะฐะทะฒะตั€ั‚ั‹ะฒะฐะฝะธัŽ ะฝะฐ ะฒะธั€ั‚ัƒะฐะปัŒะฝะพะน ะผะฐัˆะธะฝะต ั Cloudflare - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](../pt-BR/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](../es/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](../fr/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](../it/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](../ru/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](../zh-CN/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](../de/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](../in/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](../th/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](../uk-UA/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](../ar/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](../ja/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](../vi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](../bg/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](../da/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](../fi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](../he/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](../hu/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](../id/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](../ko/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](../ms/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](../nl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](../no/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](../pt/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](../ro/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](../pl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](../sk/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](../sv/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](../phi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](../cs/VM_DEPLOYMENT_GUIDE.md) - -ะŸะพะปะฝะพะต ั€ัƒะบะพะฒะพะดัั‚ะฒะพ ะฟะพ ัƒัั‚ะฐะฝะพะฒะบะต ะธ ะฝะฐัั‚ั€ะพะนะบะต OmniRoute ะฝะฐ ะฒะธั€ั‚ัƒะฐะปัŒะฝะพะน ะผะฐัˆะธะฝะต (VPS) ั ะดะพะผะตะฝะพะผ, ัƒะฟั€ะฐะฒะปัะตะผั‹ะผ ั‡ะตั€ะตะท Cloudflare. - ---- - -## ะŸั€ะตะดะฒะฐั€ะธั‚ะตะปัŒะฝั‹ะต ัƒัะปะพะฒะธั - -| ะขะพะฒะฐั€ | ะœะธะฝะธะผัƒะผ | ะ ะตะบะพะผะตะฝะดัƒะตั‚ัั | -| --------- | ------------------------------- | -------------------- | -| **ะฆะŸ** | 1 ะฒะธั€ั‚ัƒะฐะปัŒะฝั‹ะน ะฆะŸ | 2 ะฒะธั€ั‚ัƒะฐะปัŒะฝั‹ั… ะฆะŸ | -| **ะžะ—ะฃ** | 1 ะ“ะ‘ | 2 ะ“ะ‘ | -| **ะ”ะธัะบ** | SSD-ะฝะฐะบะพะฟะธั‚ะตะปัŒ ะฝะฐ 10 ะ“ะ‘ | SSD-ะฝะฐะบะพะฟะธั‚ะตะปัŒ 25 ะ“ะ‘ | -| **ะžะก** | ะฃะฑัƒะฝั‚ัƒ 22.04 ะ›ะขะก | ะฃะฑัƒะฝั‚ัƒ 24.04 ะ›ะขะก | -| **ะ”ะพะผะตะฝ** | ะ—ะฐั€ะตะณะธัั‚ั€ะธั€ะพะฒะฐะปัั ะฝะฐ Cloudflare | โ€” | -| **ะ”ะพะบะตั€** | ะ”ะพะบะตั€-ะดะฒะธะถะพะบ 24+ | ะ”ะพะบะตั€ 27+ | - -**ะŸั€ะพะฒะตั€ะตะฝะฝั‹ะต ะฟั€ะพะฒะฐะนะดะตั€ั‹**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. - ---- - -## 1. ะะฐัั‚ั€ะพะนั‚ะต ะฒะธั€ั‚ัƒะฐะปัŒะฝัƒัŽ ะผะฐัˆะธะฝัƒ - -### 1.1 ะกะพะทะดะฐะนั‚ะต ัะบะทะตะผะฟะปัั€ - -ะฃ ะฟั€ะตะดะฟะพั‡ะธั‚ะฐะตะผะพะณะพ ะฒะฐะผะธ VPS-ะฟั€ะพะฒะฐะนะดะตั€ะฐ: - -- ะ’ั‹ะฑะตั€ะธั‚ะต Ubuntu 24.04 LTS. -- ะ’ั‹ะฑะตั€ะธั‚ะต ะผะธะฝะธะผะฐะปัŒะฝั‹ะน ะฟะปะฐะฝ (1 ะฒะธั€ั‚ัƒะฐะปัŒะฝั‹ะน ะฆะŸ / 1 ะ“ะ‘ ะžะ—ะฃ) -- ะฃัั‚ะฐะฝะพะฒะธั‚ะต ะฝะฐะดะตะถะฝั‹ะน ะฟะฐั€ะพะปัŒ root ะธะปะธ ะฝะฐัั‚ั€ะพะนั‚ะต ะบะปัŽั‡ SSH. - โ€“ ะžะฑั€ะฐั‚ะธั‚ะต ะฒะฝะธะผะฐะฝะธะต ะฝะฐ **ะฟัƒะฑะปะธั‡ะฝั‹ะน IP-ะฐะดั€ะตั** (ะฝะฐะฟั€ะธะผะตั€, `203.0.113.10`). - -### 1.2 ะŸะพะดะบะปัŽั‡ะตะฝะธะต ั‡ะตั€ะตะท SSH - -```bash -ssh root@203.0.113.10 -``` - -###1.3 ะžะฑะฝะพะฒะธั‚ัŒ ัะธัั‚ะตะผัƒ - -```bash -apt update && apt upgrade -y -``` - -### 1.4 ะฃัั‚ะฐะฝะพะฒะธั‚ะต Docker - -```bash -# Install dependencies -apt install -y ca-certificates curl gnupg - -# Add official Docker repository -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 ะฃัั‚ะฐะฝะพะฒะธั‚ะต nginx - -```bash -apt install -y nginx -``` - -### 1.6 ะะฐัั‚ั€ะพะนะบะฐ ะฑั€ะฐะฝะดะผะฐัƒัั€ะฐ (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 -``` - -> **ะกะพะฒะตั‚**. ะ”ะปั ะผะฐะบัะธะผะฐะปัŒะฝะพะน ะฑะตะทะพะฟะฐัะฝะพัั‚ะธ ะพะณั€ะฐะฝะธั‡ัŒั‚ะต ะฟะพั€ั‚ั‹ 80 ะธ 443 ั‚ะพะปัŒะบะพ IP-ะฐะดั€ะตัะฐะผะธ Cloudflare. ะกะผ. ั€ะฐะทะดะตะป [Advanced Security](#advanced-security). - ---- - -## 2. ะฃัั‚ะฐะฝะพะฒะธั‚ะต OmniRoute - -### 2.1 ะกะพะทะดะฐะฝะธะต ะบะฐั‚ะฐะปะพะณะฐ ะบะพะฝั„ะธะณัƒั€ะฐั†ะธะธ - -```bash -mkdir -p /opt/omniroute -``` - -### 2.2 ะกะพะทะดะฐะฝะธะต ั„ะฐะนะปะฐ ะฟะตั€ะตะผะตะฝะฝั‹ั… ัั€ะตะดั‹ - -```bash -cat > /opt/omniroute/.env << โ€˜EOFโ€™ -# === Security === -JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY -INITIAL_PASSWORD=YourSecurePassword123! -API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY -STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY -STORAGE_ENCRYPTION_KEY_VERSION=v1 -MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT - -# === 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 (change to your domain) === -BASE_URL=https://llms.seudominio.com -NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com - -# === Cloud Sync (optional) === -# CLOUD_URL=https://cloud.omniroute.online -# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online -EOF -``` - -> โš ๏ธ **ะ’ะะ–ะะž**: ัะพะทะดะฐะฒะฐะนั‚ะต ัƒะฝะธะบะฐะปัŒะฝั‹ะต ัะตะบั€ะตั‚ะฝั‹ะต ะบะปัŽั‡ะธ! ะ˜ัะฟะพะปัŒะทัƒะนั‚ะต `openssl rand -hex 32` ะดะปั ะบะฐะถะดะพะณะพ ะบะปัŽั‡ะฐ. - -### 2.3 ะ—ะฐะฟัƒัะบะฐะตะผ ะบะพะฝั‚ะตะนะฝะตั€ - -```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 ะฃะฑะตะดะธั‚ะตััŒ, ั‡ั‚ะพ ะพะฝ ั€ะฐะฑะพั‚ะฐะตั‚ - -```bash -docker ps | grep omniroute -docker logs omniroute --tail 20 -``` - -ะ”ะพะปะถะฝะพ ะพั‚ะพะฑั€ะฐะถะฐั‚ัŒัั: `[DB] SQLite database ready` ะธ `listening on port 20128`. - ---- - -## 3. ะะฐัั‚ั€ะพะนั‚ะต nginx (ะพะฑั€ะฐั‚ะฝั‹ะน ะฟั€ะพะบัะธ) - -### 3.1 ะกะพะทะดะฐะฝะธะต SSL-ัะตั€ั‚ะธั„ะธะบะฐั‚ะฐ (Cloudflare Origin) - -ะ’ ะฟะฐะฝะตะปะธ ัƒะฟั€ะฐะฒะปะตะฝะธั Cloudflare: - -1. ะŸะตั€ะตะนะดะธั‚ะต ะฒ **SSL/TLS โ†’ ะ˜ัั…ะพะดะฝั‹ะน ัะตั€ะฒะตั€**. -2. ะะฐะถะผะธั‚ะต **ะกะพะทะดะฐั‚ัŒ ัะตั€ั‚ะธั„ะธะบะฐั‚**. -3. ะžัั‚ะฐะฒัŒั‚ะต ะฝะฐัั‚ั€ะพะนะบะธ ะฟะพ ัƒะผะพะปั‡ะฐะฝะธัŽ (15 ะปะตั‚, \*.yourdomain.com). -4. ะกะบะพะฟะธั€ัƒะนั‚ะต **ะกะตั€ั‚ะธั„ะธะบะฐั‚ ะฟั€ะพะธัั…ะพะถะดะตะฝะธั** ะธ **ะ—ะฐะบั€ั‹ั‚ั‹ะน ะบะปัŽั‡**. - -```bash -mkdir -p /etc/nginx/ssl - -# Paste the certificate -nano /etc/nginx/ssl/origin.crt - -# Paste the private key -nano /etc/nginx/ssl/origin.key - -chmod 600 /etc/nginx/ssl/origin.key -``` - -### 3.2 ะšะพะฝั„ะธะณัƒั€ะฐั†ะธั Nginx - -```bash -cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ -# Default server โ€” blocks direct access via 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.yourdomain.com; # Change to your domain - - 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.yourdomain.com; - return 301 https://$server_name$request_uri; -} -NGINX -``` - -### 3.3 ะ’ะบะปัŽั‡ะตะฝะธะต ะธ ั‚ะตัั‚ะธั€ะพะฒะฐะฝะธะต - -```bash -# Remove default configuration -rm -f /etc/nginx/sites-enabled/default - -# Enable OmniRoute -ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute - -# Test and reload -nginx -t && systemctl reload nginx -``` - ---- - -## 4. ะะฐัั‚ั€ะพะนั‚ะต DNS Cloudflare - -### 4.1 ะ”ะพะฑะฐะฒะปะตะฝะธะต DNS-ะทะฐะฟะธัะธ - -ะ’ ะฟะฐะฝะตะปะธ ัƒะฟั€ะฐะฒะปะตะฝะธั Cloudflare โ†’ DNS: - -| ะขะธะฟ | ะ˜ะผั | ะกะพะดะตั€ะถะฐะฝะธะต | ะŸั€ะพะบัะธ | -| --- | ------ | -------------------------------------------- | --------- | -| ะ | `llms` | `203.0.113.10` (IP-ะฐะดั€ะตั ะฒะธั€ั‚ัƒะฐะปัŒะฝะพะน ะผะฐัˆะธะฝั‹) | โœ… ะŸั€ะพะบัะธ | - -### 4.2 ะะฐัั‚ั€ะพะนะบะฐ SSL - -ะ’ ั€ะฐะทะดะตะปะต **SSL/TLS โ†’ ะžะฑะทะพั€**: - -- ะ ะตะถะธะผ: **ะŸะพะปะฝั‹ะน (ะกั‚ั€ะพะณะธะน)** - -ะ’ ั€ะฐะทะดะตะปะต **SSL/TLS โ†’ ะŸะพะณั€ะฐะฝะธั‡ะฝั‹ะต ัะตั€ั‚ะธั„ะธะบะฐั‚ั‹**: - -- ะ’ัะตะณะดะฐ ะธัะฟะพะปัŒะทัƒะนั‚ะต HTTPS: โœ… ะ’ะบะป. -- ะœะธะฝะธะผะฐะปัŒะฝะฐั ะฒะตั€ัะธั TLS: TLS 1.2. -- ะะฒั‚ะพะผะฐั‚ะธั‡ะตัะบะฐั ะฟะตั€ะตะทะฐะฟะธััŒ HTTPS: โœ… ะ’ะบะป. - -### 4.3 ะขะตัั‚ะธั€ะพะฒะฐะฝะธะต - -```bash -curl -sI https://llms.seudominio.com/health -# Should return HTTP/2 200 -``` - ---- - -## 5. ะญะบัะฟะปัƒะฐั‚ะฐั†ะธั ะธ ั‚ะตั…ะฝะธั‡ะตัะบะพะต ะพะฑัะปัƒะถะธะฒะฐะฝะธะต - -### ะžะฑะฝะพะฒะปะตะฝะธะต ะดะพ ะฝะพะฒะพะน ะฒะตั€ัะธะธ - -```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 -``` - -### ะŸั€ะพัะผะพั‚ั€ ะถัƒั€ะฝะฐะปะพะฒ - -```bash -docker logs -f omniroute # Real-time stream -docker logs omniroute --tail 50 # Last 50 lines -``` - -### ะ ะตะทะตั€ะฒะฝะพะต ะบะพะฟะธั€ะพะฒะฐะฝะธะต ะฑะฐะทั‹ ะดะฐะฝะฝั‹ั… ะฒั€ัƒั‡ะฝัƒัŽ - -```bash -# Copy data from the volume to the host -docker cp omniroute:/app/data ./backup-$(date +%F) - -# Or compress the entire volume -docker run --rm -v omniroute-data:/data -v $(pwd):/backup \ - alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data -``` - -### ะ’ะพััั‚ะฐะฝะพะฒะปะตะฝะธะต ะธะท ั€ะตะทะตั€ะฒะฝะพะน ะบะพะฟะธะธ - -```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. ะŸะพะฒั‹ัˆะตะฝะฝะฐั ะฑะตะทะพะฟะฐัะฝะพัั‚ัŒ - -### ะžะณั€ะฐะฝะธั‡ะธั‚ัŒ nginx IP-ะฐะดั€ะตัะฐะผะธ Cloudflare - -```bash -cat > /etc/nginx/cloudflare-ips.conf << โ€˜CFโ€™ -# Cloudflare IPv4 ranges โ€” update periodically -# 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 -``` - -ะ”ะพะฑะฐะฒัŒั‚ะต ัะปะตะดัƒัŽั‰ะตะต ะฒ `nginx.conf` ะฒะฝัƒั‚ั€ะธ ะฑะปะพะบะฐ `http {}`: - -```nginx -include /etc/nginx/cloudflare-ips.conf; -``` - -### ะฃัั‚ะฐะฝะพะฒะธั‚ัŒ Fail2ban - -```bash -apt install -y fail2ban -systemctl enable fail2ban -systemctl start fail2ban - -# Check status -fail2ban-client status sshd -``` - -### ะ‘ะปะพะบะธั€ัƒะตะผ ะฟั€ัะผะพะน ะดะพัั‚ัƒะฟ ะบ ะฟะพั€ั‚ัƒ Docker - -```bash -# Prevent direct external access to port 20128 -iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP -iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT - -# Persist the rules -apt install -y iptables-persistent -netfilter-persistent save -``` - ---- - -## 7. ะ ะฐะทะฒะตั€ั‚ั‹ะฒะฐะฝะธะต ะฒ ั€ะฐะฑะพั‡ะธั… ัั€ะตะดะฐั… Cloudflare (ะฝะตะพะฑัะทะฐั‚ะตะปัŒะฝะพ) - -ะ”ะปั ัƒะดะฐะปะตะฝะฝะพะณะพ ะดะพัั‚ัƒะฟะฐ ั‡ะตั€ะตะท Cloudflare Workers (ะฑะตะท ะฟั€ัะผะพะณะพ ะดะพัั‚ัƒะฟะฐ ะบ ะฒะธั€ั‚ัƒะฐะปัŒะฝะพะน ะผะฐัˆะธะฝะต): - -```bash -# In the local repository -cd omnirouteCloud -npm install -npx wrangler login -npx wrangler deploy -``` - -ะŸะพะปะฝัƒัŽ ะดะพะบัƒะผะตะฝั‚ะฐั†ะธัŽ ัะผะพั‚ั€ะธั‚ะต ะฝะฐ ัั‚ั€ะฐะฝะธั†ะต [omnirouteCloud/README.md](../omnirouteCloud/README.md). - ---- - -## ะกะฒะพะดะบะฐ ะฟะพั€ั‚ะพะฒ - -| ะŸะพั€ั‚ | ะกะตั€ะฒะธั | ะ”ะพัั‚ัƒะฟ | -| ----- | ----------- | ----------------------------------- | -| 22 | ะกะจ | ะŸัƒะฑะปะธั‡ะฝั‹ะน (ั Fail2ban) | -| 80 | nginx HTTP | ะŸะตั€ะตะฝะฐะฟั€ะฐะฒะปะตะฝะธะต โ†’ HTTPS | -| 443 | nginx HTTPS | ะงะตั€ะตะท ะฟั€ะพะบัะธ-ัะตั€ะฒะตั€ Cloudflare | -| 20128 | ะžะผะฝะธะ ะพัƒั‚ | ะขะพะปัŒะบะพ ะปะพะบะฐะปัŒะฝั‹ะน ั…ะพัั‚ (ั‡ะตั€ะตะท nginx) | diff --git a/docs/i18n/ru/docs/A2A-SERVER.md b/docs/i18n/ru/docs/A2A-SERVER.md new file mode 100644 index 0000000000..1d48883e32 --- /dev/null +++ b/docs/i18n/ru/docs/A2A-SERVER.md @@ -0,0 +1,200 @@ +# OmniRoute A2A Server Documentation (ะ ัƒััะบะธะน) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/A2A-SERVER.md) + +--- + +> Agent-to-Agent Protocol v0.3 โ€” OmniRoute as an intelligent routing agent + +## Agent Discovery + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements. + +--- + +## Authentication + +All `/a2a` requests require an API key via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server, authentication is bypassed. + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Sends a message to a skill and waits for the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a hello world in Python"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "uuid", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "..." }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}} + +: heartbeat 2026-03-03T17:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Available Skills + +| Skill | Description | +| :----------------- | :------------------------------------------------------------------------------------------------------------------------------ | +| `smart-routing` | Routes prompts through OmniRoute's intelligent pipeline. Returns response with routing explanation, cost, and resilience trace. | +| `quota-management` | Answers natural-language queries about provider quotas, suggests free combos, and provides quota rankings. | + +--- + +## Task Lifecycle + +``` +submitted โ†’ working โ†’ completed + โ†’ failed + โ†’ cancelled +``` + +- Tasks expire after 5 minutes (configurable) +- Terminal states: `completed`, `failed`, `cancelled` +- Event log tracks every state transition + +--- + +## Error Codes + +| Code | Meaning | +| :----- | :----------------------------- | +| -32700 | Parse error (invalid JSON) | +| -32600 | Invalid request / Unauthorized | +| -32601 | Method or skill not found | +| -32602 | Invalid params | +| -32603 | Internal error | + +--- + +## Integration Examples + +### Python (requests) + +```python +import requests + +resp = requests.post("http://localhost:20128/a2a", json={ + "jsonrpc": "2.0", "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Hello"}] + } +}, headers={"Authorization": "Bearer YOUR_KEY"}) + +result = resp.json()["result"] +print(result["artifacts"][0]["content"]) +print(result["metadata"]["routing_explanation"]) +``` + +### TypeScript (fetch) + +```typescript +const resp = await fetch("http://localhost:20128/a2a", { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: "Bearer YOUR_KEY", + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "1", + method: "message/send", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Hello" }], + }, + }), +}); +const { result } = await resp.json(); +console.log(result.metadata.routing_explanation); +``` diff --git a/docs/i18n/ru/docs/API_REFERENCE.md b/docs/i18n/ru/docs/API_REFERENCE.md new file mode 100644 index 0000000000..d2cd6ff21a --- /dev/null +++ b/docs/i18n/ru/docs/API_REFERENCE.md @@ -0,0 +1,465 @@ +# API Reference (ะ ัƒััะบะธะน) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/API_REFERENCE.md) + +--- + +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 | +| `X-Session-Id` | Request | Sticky session key for external session affinity | +| `x_session_id` | Request | Underscore variant also accepted (direct HTTP) | +| `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 | +| `X-OmniRoute-Session-Id` | Response | Effective session ID used by OmniRoute | + +> Nginx note: if you rely on underscore headers (for example `x_session_id`), enable `underscores_in_headers 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/stats + +# Clear all caches +DELETE /api/cache/stats +``` + +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/PATCH | 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 + provider summary (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`) | +| `/api/cache/stats` | 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 | + +### Tunnels + +| Endpoint | Method | Description | +| -------------------------- | ------ | ----------------------------------------------------------------------- | +| `/api/tunnels/cloudflared` | GET | Read Cloudflare Quick Tunnel install/runtime status for the dashboard | +| `/api/tunnels/cloudflared` | POST | Enable or disable the Cloudflare Quick Tunnel (`action=enable/disable`) | + +### 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`. + +### ACP Agents + +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | + +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). + +### Resilience & Rate Limits + +| Endpoint | Method | Description | +| ----------------------- | --------- | ------------------------------- | +| `/api/resilience` | GET/PATCH | 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` diff --git a/docs/i18n/ru/docs/ARCHITECTURE.md b/docs/i18n/ru/docs/ARCHITECTURE.md new file mode 100644 index 0000000000..dca830d61a --- /dev/null +++ b/docs/i18n/ru/docs/ARCHITECTURE.md @@ -0,0 +1,814 @@ +# OmniRoute Architecture (ะ ัƒััะบะธะน) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/ARCHITECTURE.md) + +--- + +_Last updated: 2026-03-28_ + +## 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 (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developerโ†’system, systemโ†’user) for cross-provider compatibility +- Structured output conversion (json_schema โ†’ Gemini responseSchema) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) +- Global system prompt injection +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout โ†’ budget โ†’ fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) + +Primary runtime model: + +- Next.js 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.) + +## Dashboard Surface (Current) + +Main pages under `src/app/(dashboard)/dashboard/`: + +- `/dashboard` โ€” quick start + provider overview +- `/dashboard/endpoint` โ€” endpoint proxy + MCP + A2A + API endpoint tabs +- `/dashboard/providers` โ€” provider connections and credentials +- `/dashboard/combos` โ€” combo strategies, templates, model routing rules +- `/dashboard/costs` โ€” cost aggregation and pricing visibility +- `/dashboard/analytics` โ€” usage analytics and evaluations +- `/dashboard/limits` โ€” quota/rate controls +- `/dashboard/cli-tools` โ€” CLI onboarding, runtime detection, config generation +- `/dashboard/agents` โ€” detected ACP agents + custom agent registration +- `/dashboard/media` โ€” image/video/music playground +- `/dashboard/search-tools` โ€” search provider testing and history +- `/dashboard/health` โ€” uptime, circuit breakers, rate limits +- `/dashboard/logs` โ€” request/proxy/audit/console logs +- `/dashboard/settings` โ€” system settings tabs (general, routing, combo defaults, etc.) +- `/dashboard/api-manager` โ€” API key lifecycle and model permissions + +## 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[(storage.sqlite)] + UDB[(usage tables + log artifacts)] + end + + subgraph Upstreams[Upstream Providers] + P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/Qoder/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/route.ts` (GET) +- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- OAuth: `src/app/api/oauth/*` +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` +- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI tooling helpers: `src/app/api/cli-tools/*` +- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) +- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) โ€” provider profiles, circuit breaker, rate limit state +- Resilience reset: `src/app/api/resilience/reset` (POST) โ€” reset breakers + cooldowns +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) +- Telemetry: `src/app/api/telemetry/summary` (GET) +- Budget: `src/app/api/usage/budget` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Policies: `src/app/api/policies` (GET/POST) + +## 2) SSE + 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` +- Response sanitization: `open-sse/handlers/responseSanitizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.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`, `qoder.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 (SQLite): + +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** + +Usage persistence: + +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present + +Domain State DB (SQLite): + +- `src/lib/db/domainState.ts` โ€” CRUD operations 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`, `src/shared/services/modelSyncScheduler.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Periodic task: `src/shared/services/modelSyncScheduler.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. Combo routing adds one extra guard: provider-scoped 400s such as upstream content-block and role-validation failures are treated as model-local failures so later combo targets can still run. + +## 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: + +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` + +## Deployment Topology + +```mermaid +flowchart LR + 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[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] + end + + subgraph External[External Services] + Providers[AI Providers] + SyncCloud[Cloud Sync Service] + end + + CLI --> Next + Browser --> Next + Next --> Core + Next --> MainDB + Core --> MainDB + Core --> UsageDB + Core --> Providers + Next --> SyncCloud +``` + +## Module Mapping (Decision-Critical) + +### Route and API Modules + +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle +- `src/app/api/models/alias`: alias management +- `src/app/api/combos*`: fallback combo management +- `src/app/api/pricing`: pricing overrides for cost calculation +- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers +- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) +- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) +- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) +- `src/app/api/sessions`: active session listing (GET) +- `src/app/api/rate-limits`: per-account rate limit status (GET) + +### Routing and Execution Core + +- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior + +### Translation Registry and Format Converters + +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` +- Format constants: `open-sse/translator/formats.ts` + +### Persistence + +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables + +## Provider Executor Coverage (Strategy Pattern) + +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. + +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, Qoder, 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 | +| Qoder | openai | OAuth (Basic) | โœ… | โœ… | โœ… | โš ๏ธ Per request | +| OpenRouter | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| GLM/Kimi/MiniMax | claude | API Key | โœ… | โœ… | โŒ | โŒ | +| DeepSeek | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Groq | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| xAI (Grok) | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Mistral | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Perplexity | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Together AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Fireworks AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Cerebras | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Cohere | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| NVIDIA NIM | openai | API Key | โœ… | โœ… | โŒ | โŒ | + +## Format Translation Coverage + +Detected source formats include: + +- `openai` +- `openai-responses` +- `claude` +- `gemini` + +Target formats include: + +- OpenAI chat/Responses +- Claude +- Gemini/Gemini-CLI/Antigravity envelope +- Kiro +- Cursor + +Translations use **OpenAI as the hub format** โ€” all conversions go through OpenAI as intermediate: + +``` +Source Format โ†’ OpenAI (hub) โ†’ Target Format +``` + +Translations are selected dynamically based on source payload shape and provider target format. + +Additional processing layers in the translation pipeline: + +- **Response sanitization** โ€” Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI targets; merges `system` โ†’ `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** โ€” Parses `...` blocks from content into `reasoning_content` field +- **Structured output** โ€” Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` + +## Supported API Endpoints + +| 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` | Provider Models | Provider model metadata backing custom and managed available models | + +## 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 `/logs//` 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 + +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON โ†’ SQLite migration compatibility path + +## Observability and Operational Signals + +Runtime visibility sources: + +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- four-stage detailed payload captures in SQLite (`request_detail_logs`) when `settings.detailed_logs_enabled=true` +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption + +Detailed request payload capture stores up to four JSON payload stages per routed call: + +- raw request received from the client +- translated request actually sent upstream +- provider response reconstructed as JSON; streamed responses are compacted to the final summary plus stream metadata +- final client response returned by OmniRoute; streamed responses are stored in the same compact summary form + +## Security-Sensitive Boundaries + +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics + +## Environment and Runtime Matrix + +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` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). + +## Operational Verification Checklist + +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: +- `GET /api/settings` +- `GET /api/v1/models` +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/ru/docs/AUTO-COMBO.md b/docs/i18n/ru/docs/AUTO-COMBO.md new file mode 100644 index 0000000000..df66d7b7f8 --- /dev/null +++ b/docs/i18n/ru/docs/AUTO-COMBO.md @@ -0,0 +1,67 @@ +# OmniRoute Auto-Combo Engine (ะ ัƒััะบะธะน) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/AUTO-COMBO.md) + +--- + +> Self-managing model chains with adaptive scoring + +## How It Works + +The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**: + +| Factor | Weight | Description | +| :--------- | :----- | :---------------------------------------------- | +| Quota | 0.20 | Remaining capacity [0..1] | +| Health | 0.25 | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 | +| CostInv | 0.20 | Inverse cost (cheaper = higher score) | +| LatencyInv | 0.15 | Inverse p95 latency (faster = higher) | +| TaskFit | 0.10 | Model ร— task type fitness score | +| Stability | 0.10 | Low variance in latency/errors | + +## Mode Packs + +| Pack | Focus | Key Weight | +| :---------------------- | :----------- | :--------------- | +| ๐Ÿš€ **Ship Fast** | Speed | latencyInv: 0.35 | +| ๐Ÿ’ฐ **Cost Saver** | Economy | costInv: 0.40 | +| ๐ŸŽฏ **Quality First** | Best model | taskFit: 0.40 | +| ๐Ÿ“ก **Offline Friendly** | Availability | quota: 0.40 | + +## Self-Healing + +- **Temporary exclusion**: Score < 0.2 โ†’ excluded for 5 min (progressive backoff, max 30 min) +- **Circuit breaker awareness**: OPEN โ†’ auto-excluded; HALF_OPEN โ†’ probe requests +- **Incident mode**: >50% OPEN โ†’ disable exploration, maximize stability +- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout + +## Bandit Exploration + +5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode. + +## API + +```bash +# Create auto-combo +curl -X POST http://localhost:20128/api/combos/auto \ + -H "Content-Type: application/json" \ + -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}' + +# List auto-combos +curl http://localhost:20128/api/combos/auto +``` + +## Task Fitness + +30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` โ†’ high coding score). + +## Files + +| File | Purpose | +| :------------------------------------------- | :------------------------------------ | +| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization | +| `open-sse/services/autoCombo/taskFitness.ts` | Model ร— task fitness lookup | +| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap | +| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode | +| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles | +| `src/app/api/combos/auto/route.ts` | REST API | diff --git a/docs/i18n/ru/docs/CLI-TOOLS.md b/docs/i18n/ru/docs/CLI-TOOLS.md new file mode 100644 index 0000000000..d0612745de --- /dev/null +++ b/docs/i18n/ru/docs/CLI-TOOLS.md @@ -0,0 +1,348 @@ +# CLI Tools Setup Guide โ€” OmniRoute (ะ ัƒััะบะธะน) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CLI-TOOLS.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CLI-TOOLS.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CLI-TOOLS.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CLI-TOOLS.md) + +--- + +This guide explains how to install and configure all supported AI coding CLI tools +to use **OmniRoute** as the unified backend, giving you centralized key management, +cost tracking, model switching, and request logging across every tool. + +--- + +## How It Works + +``` +Claude / Codex / OpenCode / Cline / KiloCode / Continue / Kiro / Cursor / Copilot + โ”‚ + โ–ผ (all point to OmniRoute) + http://YOUR_SERVER:20128/v1 + โ”‚ + โ–ผ (OmniRoute routes to the right provider) + Anthropic / OpenAI / Gemini / DeepSeek / Groq / Mistral / ... +``` + +**Benefits:** + +- One API key to manage all tools +- Cost tracking across all CLIs in the dashboard +- Model switching without reconfiguring every tool +- Works locally and on remote servers (VPS) + +--- + +## Supported Tools (Dashboard Source of Truth) + +The dashboard cards in `/dashboard/cli-tools` are generated from `src/shared/constants/cliTools.ts`. +Current list (v3.0.0-rc.16): + +| Tool | ID | Command | Setup Mode | Install Method | +| ------------------ | ------------- | ---------- | ---------- | -------------- | +| **Claude Code** | `claude` | `claude` | env | npm | +| **OpenAI Codex** | `codex` | `codex` | custom | npm | +| **Factory Droid** | `droid` | `droid` | custom | bundled/CLI | +| **OpenClaw** | `openclaw` | `openclaw` | custom | bundled/CLI | +| **Cursor** | `cursor` | app | guide | desktop app | +| **Cline** | `cline` | `cline` | custom | npm | +| **Kilo Code** | `kilo` | `kilocode` | custom | npm | +| **Continue** | `continue` | extension | guide | VS Code | +| **Antigravity** | `antigravity` | internal | mitm | OmniRoute | +| **GitHub Copilot** | `copilot` | extension | custom | VS Code | +| **OpenCode** | `opencode` | `opencode` | guide | npm | +| **Kiro AI** | `kiro` | app/cli | mitm | desktop/CLI | + +### CLI fingerprint sync (Agents + Settings) + +`/dashboard/agents` and `Settings > CLI Fingerprint` use `src/shared/constants/cliCompatProviders.ts`. +This keeps provider IDs aligned with CLI cards and legacy IDs. + +| CLI ID | Fingerprint Provider ID | +| ---------------------------------------------------------------------------------------------------- | ----------------------- | +| `kilo` | `kilocode` | +| `copilot` | `github` | +| `claude` / `codex` / `antigravity` / `kiro` / `cursor` / `cline` / `opencode` / `droid` / `openclaw` | same ID | + +Legacy IDs still accepted for compatibility: `copilot`, `kimi-coding`, `qwen`. + +--- + +## Step 1 โ€” Get an OmniRoute API Key + +1. Open the OmniRoute dashboard โ†’ **API Manager** (`/dashboard/api-manager`) +2. Click **Create API Key** +3. Give it a name (e.g. `cli-tools`) and select all permissions +4. Copy the key โ€” you'll need it for every CLI below + +> Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` + +--- + +## Step 2 โ€” Install CLI Tools + +All npm-based tools require Node.js 18+: + +```bash +# Claude Code (Anthropic) +npm install -g @anthropic-ai/claude-code + +# OpenAI Codex +npm install -g @openai/codex + +# OpenCode +npm install -g opencode-ai + +# Cline +npm install -g cline + +# KiloCode +npm install -g kilocode + +# Kiro CLI (Amazon โ€” requires curl + unzip) +apt-get install -y unzip # on Debian/Ubuntu +curl -fsSL https://cli.kiro.dev/install | bash +export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc +``` + +**Verify:** + +```bash +claude --version # 2.x.x +codex --version # 0.x.x +opencode --version # x.x.x +cline --version # 2.x.x +kilocode --version # x.x.x (or: kilo --version) +kiro-cli --version # 1.x.x +``` + +--- + +## Step 3 โ€” Set Global Environment Variables + +Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`: + +```bash +# OmniRoute Universal Endpoint +export OPENAI_BASE_URL="http://localhost:20128/v1" +export OPENAI_API_KEY="sk-your-omniroute-key" +export ANTHROPIC_BASE_URL="http://localhost:20128/v1" +export ANTHROPIC_API_KEY="sk-your-omniroute-key" +export GEMINI_BASE_URL="http://localhost:20128/v1" +export GEMINI_API_KEY="sk-your-omniroute-key" +``` + +> For a **remote server** replace `localhost:20128` with the server IP or domain, +> e.g. `http://192.168.0.15:20128`. + +--- + +## Step 4 โ€” Configure Each Tool + +### Claude Code + +```bash +# Via CLI: +claude config set --global api-base-url http://localhost:20128/v1 + +# Or create ~/.claude/settings.json: +mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF +{ + "apiBaseUrl": "http://localhost:20128/v1", + "apiKey": "sk-your-omniroute-key" +} +EOF +``` + +**Test:** `claude "say hello"` + +--- + +### OpenAI Codex + +```bash +mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF +model: auto +apiKey: sk-your-omniroute-key +apiBaseUrl: http://localhost:20128/v1 +EOF +``` + +**Test:** `codex "what is 2+2?"` + +--- + +### OpenCode + +```bash +mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF +[provider.openai] +base_url = "http://localhost:20128/v1" +api_key = "sk-your-omniroute-key" +EOF +``` + +**Test:** `opencode` + +--- + +### Cline (CLI or VS Code) + +**CLI mode:** + +```bash +mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF +{ + "apiProvider": "openai", + "openAiBaseUrl": "http://localhost:20128/v1", + "openAiApiKey": "sk-your-omniroute-key" +} +EOF +``` + +**VS Code mode:** +Cline extension settings โ†’ API Provider: `OpenAI Compatible` โ†’ Base URL: `http://localhost:20128/v1` + +Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ Cline โ†’ Apply Config**. + +--- + +### KiloCode (CLI or VS Code) + +**CLI mode:** + +```bash +kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key +``` + +**VS Code settings:** + +```json +{ + "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", + "kilo-code.apiKey": "sk-your-omniroute-key" +} +``` + +Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ KiloCode โ†’ Apply Config**. + +--- + +### Continue (VS Code Extension) + +Edit `~/.continue/config.yaml`: + +```yaml +models: + - name: OmniRoute + provider: openai + model: auto + apiBase: http://localhost:20128/v1 + apiKey: sk-your-omniroute-key + default: true +``` + +Restart VS Code after editing. + +--- + +### Kiro CLI (Amazon) + +```bash +# Login to your AWS/Kiro account: +kiro-cli login + +# The CLI uses its own auth โ€” OmniRoute is not needed as backend for Kiro CLI itself. +# Use kiro-cli alongside OmniRoute for other tools. +kiro-cli status +``` + +--- + +### Cursor (Desktop App) + +> **Note:** Cursor routes requests through its cloud. For OmniRoute integration, +> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL. + +Via GUI: **Settings โ†’ Models โ†’ OpenAI API Key** + +- Base URL: `https://your-domain.com/v1` +- API Key: your OmniRoute key + +--- + +## Dashboard Auto-Configuration + +The OmniRoute dashboard automates configuration for most tools: + +1. Go to `http://localhost:20128/dashboard/cli-tools` +2. Expand any tool card +3. Select your API key from the dropdown +4. Click **Apply Config** (if tool is detected as installed) +5. Or copy the generated config snippet manually + +--- + +## Built-in Agents: Droid & OpenClaw + +**Droid** and **OpenClaw** are AI agents built directly into OmniRoute โ€” no installation needed. +They run as internal routes and use OmniRoute's model routing automatically. + +- Access: `http://localhost:20128/dashboard/agents` +- Configure: same combos and providers as all other tools +- No API key or CLI install required + +--- + +## Available API Endpoints + +| Endpoint | Description | Use For | +| -------------------------- | ----------------------------- | --------------------------- | +| `/v1/chat/completions` | Standard chat (all providers) | All modern tools | +| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows | +| `/v1/completions` | Legacy text completions | Older tools using `prompt:` | +| `/v1/embeddings` | Text embeddings | RAG, search | +| `/v1/images/generations` | Image generation | DALL-E, Flux, etc. | +| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS | +| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI | + +--- + +## ะฃัั‚ั€ะฐะฝะตะฝะธะต ะฝะตะฟะพะปะฐะดะพะบ + +| Error | Cause | Fix | +| ------------------------- | ----------------------- | ------------------------------------------ | +| `Connection refused` | OmniRoute not running | `pm2 start omniroute` | +| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` | +| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` | +| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` | +| CLI shows "not installed" | Binary not in PATH | Check `which ` | +| `kiro-cli: not found` | Not in PATH | `export PATH="$HOME/.local/bin:$PATH"` | + +--- + +## Quick Setup Script (One Command) + +```bash +# Install all CLIs and configure for OmniRoute (replace with your key and server URL) +OMNIROUTE_URL="http://localhost:20128/v1" +OMNIROUTE_KEY="sk-your-omniroute-key" + +npm install -g @anthropic-ai/claude-code @openai/codex opencode-ai cline kilocode + +# Kiro CLI +apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash + +# Write configs +mkdir -p ~/.claude ~/.codex ~/.config/opencode ~/.continue + +cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" +cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" +cat >> ~/.bashrc << EOF +export OPENAI_BASE_URL="$OMNIROUTE_URL" +export OPENAI_API_KEY="$OMNIROUTE_KEY" +export ANTHROPIC_BASE_URL="$OMNIROUTE_URL" +export ANTHROPIC_API_KEY="$OMNIROUTE_KEY" +EOF + +source ~/.bashrc +echo "โœ… All CLIs installed and configured for OmniRoute" +``` diff --git a/docs/i18n/ru/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/ru/docs/CODEBASE_DOCUMENTATION.md new file mode 100644 index 0000000000..816d798ac0 --- /dev/null +++ b/docs/i18n/ru/docs/CODEBASE_DOCUMENTATION.md @@ -0,0 +1,591 @@ +# omniroute โ€” Codebase Documentation (ะ ัƒััะบะธะน) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CODEBASE_DOCUMENTATION.md) + +--- + +> 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
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, Qoder, 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. + +#### ะั€ั…ะธั‚ะตะบั‚ัƒั€ะฐ + +```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 | +| Qoder | 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"] +``` diff --git a/docs/i18n/ru/docs/COVERAGE_PLAN.md b/docs/i18n/ru/docs/COVERAGE_PLAN.md new file mode 100644 index 0000000000..9a114f6868 --- /dev/null +++ b/docs/i18n/ru/docs/COVERAGE_PLAN.md @@ -0,0 +1,170 @@ +# Test Coverage Plan (ะ ัƒััะบะธะน) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/COVERAGE_PLAN.md) + +--- + +Last updated: 2026-03-28 + +## Baseline + +There are multiple coverage numbers depending on how the report is computed. For planning, only one of them is useful. + +| Metric | Scope | Statements / Lines | Branches | Functions | Notes | +| -------------------- | ----------------------------------------------------- | -----------------: | -------: | --------: | --------------------------------------------------- | +| Legacy | Old `npm run test:coverage` | 79.42% | 75.15% | 67.94% | Inflated: counts test files and excludes `open-sse` | +| Diagnostic | Source-only, excluding tests and excluding `open-sse` | 68.16% | 63.55% | 64.06% | Useful only to isolate `src/**` | +| Recommended baseline | Source-only, excluding tests and including `open-sse` | 56.95% | 66.05% | 57.80% | This is the project-wide baseline to improve | + +The recommended baseline is the number to optimize against. + +## Rules + +- Coverage targets apply to source files, not to `tests/**`. +- `open-sse/**` is part of the product and must remain in scope. +- New code should not reduce coverage in touched areas. +- Prefer testing behavior and branch outcomes over implementation details. +- Prefer temp SQLite databases and small fixtures over broad mocks for `src/lib/db/**`. + +## Current command set + +- `npm run test:coverage` + - Main source coverage gate for the unit test suite + - Generates `text-summary`, `html`, `json-summary`, and `lcov` +- `npm run coverage:report` + - Detailed file-by-file report from the latest run +- `npm run test:coverage:legacy` + - Historical comparison only + +## Milestones + +| Phase | Target | Focus | +| ------- | ---------------------: | ------------------------------------------------- | +| Phase 1 | 60% statements / lines | Quick wins and low-risk utility coverage | +| Phase 2 | 65% statements / lines | DB and route foundations | +| Phase 3 | 70% statements / lines | Provider validation and usage analytics | +| Phase 4 | 75% statements / lines | `open-sse` translators and helpers | +| Phase 5 | 80% statements / lines | `open-sse` handlers and executor branches | +| Phase 6 | 85% statements / lines | Harder edge cases, branch debt, regression suites | +| Phase 7 | 90% statements / lines | Final sweep, gap closure, strict ratchet | + +Branches and functions should ratchet upward with each phase, but the primary hard target is statements / lines. + +## Priority hotspots + +These files or areas offer the best return for the next phases: + +1. `open-sse/handlers` + - `chatCore.ts` at 7.57% + - Overall directory at 29.07% +2. `open-sse/translator/request` + - Overall directory at 36.39% + - Many translators are still near single-digit coverage +3. `open-sse/translator/response` + - Overall directory at 8.07% +4. `open-sse/executors` + - Overall directory at 36.62% +5. `src/lib/db` + - `models.ts` at 20.66% + - `registeredKeys.ts` at 34.46% + - `modelComboMappings.ts` at 36.25% + - `settings.ts` at 46.40% + - `webhooks.ts` at 33.33% +6. `src/lib/usage` + - `usageHistory.ts` at 21.12% + - `usageStats.ts` at 9.56% + - `costCalculator.ts` at 30.00% +7. `src/lib/providers` + - `validation.ts` at 41.16% +8. Low-risk utility and API files for early gains + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/api/errorResponse.ts` + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +## Execution checklist + +### Phase 1: 56.95% -> 60% + +- [x] Fix coverage metric so it reflects source code instead of test files +- [x] Keep a legacy coverage script for comparison +- [x] Record the baseline and hotspots in-repo +- [ ] Add focused tests for low-risk utilities: + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/fetchTimeout.ts` + - `src/lib/api/errorResponse.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/display/names.ts` +- [ ] Add route tests for: + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +### Phase 2: 60% -> 65% + +- [ ] Add DB-backed tests for: + - `src/lib/db/modelComboMappings.ts` + - `src/lib/db/settings.ts` + - `src/lib/db/registeredKeys.ts` +- [ ] Cover branch behavior in: + - `src/lib/providers/validation.ts` + - `src/app/api/v1/embeddings/route.ts` + - `src/app/api/v1/moderations/route.ts` + +### Phase 3: 65% -> 70% + +- [ ] Add usage analytics tests for: + - `src/lib/usage/usageHistory.ts` + - `src/lib/usage/usageStats.ts` + - `src/lib/usage/costCalculator.ts` +- [ ] Expand route coverage for proxy management and settings branches + +### Phase 4: 70% -> 75% + +- [ ] Cover translator helpers and central translation paths: + - `open-sse/translator/index.ts` + - `open-sse/translator/helpers/*` + - `open-sse/translator/request/*` + - `open-sse/translator/response/*` + +### Phase 5: 75% -> 80% + +- [ ] Add handler-level tests for: + - `open-sse/handlers/chatCore.ts` + - `open-sse/handlers/responsesHandler.js` + - `open-sse/handlers/imageGeneration.js` + - `open-sse/handlers/embeddings.js` +- [ ] Add executor branch coverage for provider-specific auth, retries, and endpoint overrides + +### Phase 6: 80% -> 85% + +- [ ] Merge more edge-case suites into the main coverage path +- [ ] Increase function coverage for DB modules with weak constructor/helper coverage +- [ ] Close branch gaps in `settings.ts`, `registeredKeys.ts`, `validation.ts`, and translator helpers + +### Phase 7: 85% -> 90% + +- [ ] Treat the remaining low-coverage files as blockers +- [ ] Add regression tests for every uncovered production bug fixed during the push to 90% +- [ ] Raise the coverage gate in CI only after the local baseline is stable for at least two consecutive runs + +## Ratchet policy + +Update `npm run test:coverage` thresholds only after the project actually exceeds the next milestone with a comfortable buffer. + +Recommended ratchet sequence: + +1. 55/60/55 +2. 60/62/58 +3. 65/64/62 +4. 70/66/66 +5. 75/70/72 +6. 80/75/78 +7. 85/80/84 +8. 90/85/88 + +Order is `statements-lines / branches / functions`. + +## Known gap + +The current coverage command measures the main Node unit suite and includes source reached from it, including `open-sse`. It does not yet merge Vitest coverage into a single unified report. That merge is worth doing later, but it is not a blocker for starting the 60% -> 80% climb. diff --git a/docs/i18n/ru/docs/FEATURES.md b/docs/i18n/ru/docs/FEATURES.md index 14ecc8375d..975e15cdd2 100644 --- a/docs/i18n/ru/docs/FEATURES.md +++ b/docs/i18n/ru/docs/FEATURES.md @@ -1,6 +1,6 @@ # OmniRoute โ€” Dashboard Features Gallery (ะ ัƒััะบะธะน) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/FEATURES.md) --- @@ -10,7 +10,7 @@ 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). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. ![Providers Dashboard](screenshots/01-providers.png) diff --git a/docs/i18n/ru/docs/MCP-SERVER.md b/docs/i18n/ru/docs/MCP-SERVER.md new file mode 100644 index 0000000000..6818b353fd --- /dev/null +++ b/docs/i18n/ru/docs/MCP-SERVER.md @@ -0,0 +1,87 @@ +# OmniRoute MCP Server Documentation (ะ ัƒััะบะธะน) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/MCP-SERVER.md) + +--- + +> Model Context Protocol server with 16 intelligent tools + +## ะฃัั‚ะฐะฝะพะฒะธั‚ัŒ + +OmniRoute MCP is built-in. Start it with: + +```bash +omniroute --mcp +``` + +Or via the open-sse transport: + +```bash +# HTTP streamable transport (port 20130) +omniroute --dev # MCP auto-starts on /mcp endpoint +``` + +## IDE Configuration + +See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup. + +--- + +## Essential Tools (8) + +| Tool | Description | +| :------------------------------ | :--------------------------------------- | +| `omniroute_get_health` | Gateway health, circuit breakers, uptime | +| `omniroute_list_combos` | All configured combos with models | +| `omniroute_get_combo_metrics` | Performance metrics for a specific combo | +| `omniroute_switch_combo` | Switch active combo by ID/name | +| `omniroute_check_quota` | Quota status per provider or all | +| `omniroute_route_request` | Send a chat completion through OmniRoute | +| `omniroute_cost_report` | Cost analytics for a time period | +| `omniroute_list_models_catalog` | Full model catalog with capabilities | + +## Advanced Tools (8) + +| Tool | Description | +| :--------------------------------- | :---------------------------------------------------------- | +| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | +| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | +| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | +| `omniroute_test_combo` | Live-test all models in a combo via a real upstream request | +| `omniroute_get_provider_metrics` | Detailed metrics for one provider | +| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | +| `omniroute_explain_route` | Explain a past routing decision | +| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | + +## Authentication + +MCP tools are authenticated via API key scopes. Each tool requires specific scopes: + +| Scope | Tools | +| :------------- | :----------------------------------------------- | +| `read:health` | get_health, get_provider_metrics | +| `read:combos` | list_combos, get_combo_metrics | +| `write:combos` | switch_combo | +| `read:quota` | check_quota | +| `write:route` | route_request, simulate_route, test_combo | +| `read:usage` | cost_report, get_session_snapshot, explain_route | +| `write:config` | set_budget_guard, set_resilience_profile | +| `read:models` | list_models_catalog, best_combo_for_task | + +## Audit Logging + +Every tool call is logged to `mcp_tool_audit` with: + +- Tool name, arguments, result +- Duration (ms), success/failure +- API key hash, timestamp + +## Files + +| File | Purpose | +| :------------------------------------------- | :------------------------------------------ | +| `open-sse/mcp-server/server.ts` | MCP server creation + 16 tool registrations | +| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport | +| `open-sse/mcp-server/auth.ts` | API key + scope validation | +| `open-sse/mcp-server/audit.ts` | Tool call audit logging | +| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers | diff --git a/docs/i18n/ru/docs/RELEASE_CHECKLIST.md b/docs/i18n/ru/docs/RELEASE_CHECKLIST.md new file mode 100644 index 0000000000..3c2427ab82 --- /dev/null +++ b/docs/i18n/ru/docs/RELEASE_CHECKLIST.md @@ -0,0 +1,37 @@ +# Release Checklist (ะ ัƒััะบะธะน) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/RELEASE_CHECKLIST.md) + +--- + +Use this checklist before tagging or publishing a new OmniRoute release. + +## Version and Changelog + +1. Bump `package.json` version (`x.y.z`) in the release branch. +2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: + - `## [x.y.z] โ€” YYYY-MM-DD` +3. Keep `## [Unreleased]` as the first changelog section for upcoming work. +4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. + +## API Docs + +1. Update `docs/openapi.yaml`: + - `info.version` must equal `package.json` version. +2. Validate endpoint examples if API contracts changed. + +## Runtime Docs + +1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. +2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. +3. Update localized docs if source docs changed significantly. + +## Automated Check + +Run the sync guard locally before opening PR: + +```bash +npm run check:docs-sync +``` + +CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/ru/docs/TROUBLESHOOTING.md b/docs/i18n/ru/docs/TROUBLESHOOTING.md new file mode 100644 index 0000000000..898014abe6 --- /dev/null +++ b/docs/i18n/ru/docs/TROUBLESHOOTING.md @@ -0,0 +1,256 @@ +# Troubleshooting (ะ ัƒััะบะธะน) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/TROUBLESHOOTING.md) + +--- + +Common problems and solutions for OmniRoute. + +--- + +## Quick Fixes + +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | + +--- + +## Provider Issues + +### "Language model did not provide messages" + +**Cause:** Provider quota exhausted. + +**Fix:** + +1. 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, Qoder) 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}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) + +--- + +## Circuit Breaker Issues + +### Provider stuck in OPEN state + +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. + +**Fix:** + +1. 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 +- **SDK returns raw string instead of object** โ€” Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** โ€” Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** โ€” Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** โ€” Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` + +--- + +## Resilience Settings + +### Auto rate-limit not triggering + +- 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. + +--- + +## Optional RAG / LLM failure taxonomy (16 problems) + +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` โ€ฆ `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard โ†’ Health** for real-time system status +- **Translator**: Use **Dashboard โ†’ Translator** to debug format issues diff --git a/docs/i18n/ru/USER_GUIDE.md b/docs/i18n/ru/docs/USER_GUIDE.md similarity index 82% rename from docs/i18n/ru/USER_GUIDE.md rename to docs/i18n/ru/docs/USER_GUIDE.md index e12471476f..3e38ffc5d6 100644 --- a/docs/i18n/ru/USER_GUIDE.md +++ b/docs/i18n/ru/docs/USER_GUIDE.md @@ -1,8 +1,6 @@ # User Guide (ะ ัƒััะบะธะน) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/USER_GUIDE.md) - -> ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/USER_GUIDE.md) --- @@ -320,7 +318,7 @@ Model: cc/claude-opus-4-6 --- -## ๐Ÿš€ Deployment +## ะ ะฐะทะฒั‘ั€ั‚ั‹ะฒะฐะฝะธะต ### Global npm install (Recommended) @@ -511,23 +509,26 @@ post_install() { ### Environment Variables -| Variable | Default | Description | -| ------------------------- | ------------------------------------ | ------------------------------------------------------- | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | -| `INITIAL_PASSWORD` | `123456` | First login password | -| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | -| `PORT` | framework default | Service port (`20128` in examples) | -| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | -| `NODE_ENV` | runtime default | Set `production` for deploy | -| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | -| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | -| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | -| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | -| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | -| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | -| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | -| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | +| 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/*` | +| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand | +| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | For the full environment variable reference, see the [README](../README.md). @@ -598,6 +599,11 @@ curl -X POST http://localhost:20128/api/provider-models \ Or use Dashboard: **Providers โ†’ [Provider] โ†’ Custom Models**. +Notes: + +- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers. +- The **Custom Models** section is intended for providers that do not expose managed available-model imports. + ### Dedicated Provider Routes Route requests directly to a specific provider with model validation: @@ -642,6 +648,14 @@ Returns models grouped by provider with types (`chat`, `embedding`, `image`). - Automatic background sync with timeout + fail-fast - Prefer server-side `BASE_URL`/`CLOUD_URL` in production +### Cloudflare Quick Tunnel + +- Available in **Dashboard โ†’ Endpoints** for Docker and other self-hosted deployments +- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint +- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary +- Tunnel URLs are ephemeral and change every time you stop/start the tunnel +- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download + ### LLM Gateway Intelligence (Phase 9) - **Semantic Cache** โ€” Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) @@ -757,11 +771,11 @@ OmniRoute implements provider-level resilience with four components: 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 | +| 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 unless `DISABLE_SQLITE_AUTO_BACKUP=true` | ```bash # API: Export database @@ -787,10 +801,11 @@ curl -X POST http://localhost:20128/api/db-backups/import \ ### Settings Dashboard -The settings page is organized into 5 tabs for easy navigation: +The settings page is organized into 6 tabs for easy navigation: | Tab | Contents | | -------------- | ---------------------------------------------------------------------------------------------- | +| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility | | **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | | **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | | **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | diff --git a/docs/i18n/ru/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/ru/docs/VM_DEPLOYMENT_GUIDE.md new file mode 100644 index 0000000000..038308350e --- /dev/null +++ b/docs/i18n/ru/docs/VM_DEPLOYMENT_GUIDE.md @@ -0,0 +1,403 @@ +# OmniRoute โ€” Deployment Guide on VM with Cloudflare (ะ ัƒััะบะธะน) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/VM_DEPLOYMENT_GUIDE.md) + +--- + +Complete guide to install and configure OmniRoute on a VM (VPS) with domain managed via Cloudflare. + +--- + +## Prerequisites + +| Item | Minimum | Recommended | +| ---------- | ------------------------ | ---------------- | +| **CPU** | 1 vCPU | 2 vCPU | +| **RAM** | 1 GB | 2 GB | +| **Disk** | 10 GB SSD | 25 GB SSD | +| **OS** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS | +| **Domain** | Registered on Cloudflare | โ€” | +| **Docker** | Docker Engine 24+ | Docker 27+ | + +**Tested providers**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. + +--- + +## 1. Configure the VM + +### 1.1 Create the instance + +On your preferred VPS provider: + +- Choose Ubuntu 24.04 LTS +- Select the minimum plan (1 vCPU / 1 GB RAM) +- Set a strong root password or configure SSH key +- Note the **public IP** (e.g., `203.0.113.10`) + +### 1.2 Connect via SSH + +```bash +ssh root@203.0.113.10 +``` + +### 1.3 Update the system + +```bash +apt update && apt upgrade -y +``` + +### 1.4 Install Docker + +```bash +# Install dependencies +apt install -y ca-certificates curl gnupg + +# Add official Docker repository +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 Install nginx + +```bash +apt install -y nginx +``` + +### 1.6 Configure 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 +``` + +> **Tip**: For maximum security, restrict ports 80 and 443 to Cloudflare IPs only. See the [Advanced Security](#advanced-security) section. + +--- + +## 2. Install OmniRoute + +### 2.1 Create configuration directory + +```bash +mkdir -p /opt/omniroute +``` + +### 2.2 Create environment variables file + +```bash +cat > /opt/omniroute/.env << โ€˜EOFโ€™ +# === Security === +JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY +INITIAL_PASSWORD=YourSecurePassword123! +API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY +STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY +STORAGE_ENCRYPTION_KEY_VERSION=v1 +MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT + +# === 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 (change to your domain) === +BASE_URL=https://llms.seudominio.com +NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com + +# === Cloud Sync (optional) === +# CLOUD_URL=https://cloud.omniroute.online +# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online +EOF +``` + +> โš ๏ธ **IMPORTANT**: Generate unique secret keys! Use `openssl rand -hex 32` for each key. + +### 2.3 Start the 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 Verify that it is running + +```bash +docker ps | grep omniroute +docker logs omniroute --tail 20 +``` + +It should display: `[DB] SQLite database ready` and `listening on port 20128`. + +--- + +## 3. Configure nginx (Reverse Proxy) + +### 3.1 Generate SSL certificate (Cloudflare Origin) + +In the Cloudflare dashboard: + +1. Go to **SSL/TLS โ†’ Origin Server** +2. Click **Create Certificate** +3. Keep the defaults (15 years, \*.yourdomain.com) +4. Copy the **Origin Certificate** and the **Private Key** + +```bash +mkdir -p /etc/nginx/ssl + +# Paste the certificate +nano /etc/nginx/ssl/origin.crt + +# Paste the private key +nano /etc/nginx/ssl/origin.key + +chmod 600 /etc/nginx/ssl/origin.key +``` + +### 3.2 Nginx Configuration + +```bash +cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ +# Default server โ€” blocks direct access via 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.yourdomain.com; # Change to your domain + + 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.yourdomain.com; + return 301 https://$server_name$request_uri; +} +NGINX +``` + +### 3.3 Enable and Test + +```bash +# Remove default configuration +rm -f /etc/nginx/sites-enabled/default + +# Enable OmniRoute +ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute + +# Test and reload +nginx -t && systemctl reload nginx +``` + +--- + +## 4. Configure Cloudflare DNS + +### 4.1 Add DNS record + +In the Cloudflare dashboard โ†’ DNS: + +| Type | Name | Content | Proxy | +| ---- | ------ | ---------------------- | ---------- | +| A | `llms` | `203.0.113.10` (VM IP) | โœ… Proxied | + +### 4.2 Configure SSL + +Under **SSL/TLS โ†’ Overview**: + +- Mode: **Full (Strict)** + +Under **SSL/TLS โ†’ Edge Certificates**: + +- Always Use HTTPS: โœ… On +- Minimum TLS Version: TLS 1.2 +- Automatic HTTPS Rewrites: โœ… On + +### 4.3 Testing + +```bash +curl -sI https://llms.seudominio.com/health +# Should return HTTP/2 200 +``` + +--- + +## 5. Operations and Maintenance + +### Upgrade to a new version + +```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 +``` + +### View logs + +```bash +docker logs -f omniroute # Real-time stream +docker logs omniroute --tail 50 # Last 50 lines +``` + +### Manual database backup + +```bash +# Copy data from the volume to the host +docker cp omniroute:/app/data ./backup-$(date +%F) + +# Or compress the entire volume +docker run --rm -v omniroute-data:/data -v $(pwd):/backup \ + alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data +``` + +### Restore from 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. Advanced Security + +### Restrict nginx to Cloudflare IPs + +```bash +cat > /etc/nginx/cloudflare-ips.conf << โ€˜CFโ€™ +# Cloudflare IPv4 ranges โ€” update periodically +# 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 +``` + +Add the following to `nginx.conf` inside the `http {}` block: + +```nginx +include /etc/nginx/cloudflare-ips.conf; +``` + +### Install fail2ban + +```bash +apt install -y fail2ban +systemctl enable fail2ban +systemctl start fail2ban + +# Check status +fail2ban-client status sshd +``` + +### Block direct access to the Docker port + +```bash +# Prevent direct external access to port 20128 +iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP +iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT + +# Persist the rules +apt install -y iptables-persistent +netfilter-persistent save +``` + +--- + +## 7. Deploy to Cloudflare Workers (Optional) + +For remote access via Cloudflare Workers (without exposing the VM directly): + +```bash +# In the local repository +cd omnirouteCloud +npm install +npx wrangler login +npx wrangler deploy +``` + +See the full documentation at [omnirouteCloud/README.md](../omnirouteCloud/README.md). + +--- + +## Port Summary + +| Port | Service | Access | +| ----- | ----------- | -------------------------- | +| 22 | SSH | Public (with fail2ban) | +| 80 | nginx HTTP | Redirect โ†’ HTTPS | +| 443 | nginx HTTPS | Via Cloudflare Proxy | +| 20128 | OmniRoute | Localhost only (via nginx) | diff --git a/docs/i18n/ru/src/lib/a2a/README.md b/docs/i18n/ru/src/lib/a2a/README.md new file mode 100644 index 0000000000..f7eb36f34b --- /dev/null +++ b/docs/i18n/ru/src/lib/a2a/README.md @@ -0,0 +1,752 @@ +# OmniRoute A2A Server (ะ ัƒััะบะธะน) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../../../src/lib/a2a/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../../../es/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../../../fr/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../../../de/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../../../it/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../../../ru/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../../../zh-CN/src/lib/a2a/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../../../ja/src/lib/a2a/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../../../ko/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../../../ar/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../../../in/src/lib/a2a/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../../../th/src/lib/a2a/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../../../vi/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../../../id/src/lib/a2a/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../../../ms/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../../../nl/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../../../pl/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../../../sv/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../../../no/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../../../da/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../../../fi/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../../../pt/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../../../ro/src/lib/a2a/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../../../hu/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../../../bg/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../../../sk/src/lib/a2a/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../../../uk-UA/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../../../he/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../../../phi/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../../../pt-BR/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../../../cs/src/lib/a2a/README.md) + +--- + +> **Agent-to-Agent Protocol v0.3** โ€” Enables any AI agent to use OmniRoute as an intelligent routing agent via JSON-RPC 2.0. + +The A2A Server exposes OmniRoute as a **first-class agent** that other agents can discover, delegate tasks to, and collaborate with using the [A2A Protocol](https://google.github.io/A2A/). + +--- + +## ะั€ั…ะธั‚ะตะบั‚ัƒั€ะฐ + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Orchestrator Agent โ”‚ +โ”‚ (LangChain, CrewAI, AutoGen, Custom Agent) โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ 1. GET /.well-known/agent.json (discover) + โ”‚ 2. POST /a2a (JSON-RPC 2.0) + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ OmniRoute A2A Server โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Task Manager โ”‚ โ”‚ Skill Engine โ”‚ โ”‚ SSE Streaming โ”‚ โ”‚ +โ”‚ โ”‚ (lifecycle) โ”‚โ”€โ”€โ”‚ (registry) โ”‚โ”€โ”€โ”‚ (real-time) โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ +โ”‚ Skills: โ”‚ โ”‚ +โ”‚ โ”œโ”€ smart-routing โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ””โ”€ quota-management โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ Routing Decision Logger โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ OmniRoute Gateway (internal) + /v1/chat/completions, /api/combos, /api/usage/quota +``` + +--- + +## ะ‘ั‹ัั‚ั€ั‹ะน ัั‚ะฐั€ั‚ + +### Agent Discovery + +Every A2A-compatible agent exposes an **Agent Card** at `/.well-known/agent.json`: + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +**Response:** + +```json +{ + "name": "OmniRoute", + "description": "Intelligent AI gateway with auto-routing across 50+ providers", + "url": "http://localhost:20128/a2a", + "version": "1.8.1", + "capabilities": { + "streaming": true, + "pushNotifications": false + }, + "skills": [ + { + "id": "smart-routing", + "name": "Smart Routing", + "description": "Routes prompts through OmniRoute intelligent pipeline", + "tags": ["routing", "llm", "multi-provider", "cost-optimization"], + "examples": [ + "Write a hello world in Python", + "Explain quantum computing using the cheapest provider" + ] + }, + { + "id": "quota-management", + "name": "Quota Management", + "description": "Natural-language queries about provider quotas", + "tags": ["quota", "analytics", "cost"], + "examples": [ + "Which provider has the most quota remaining?", + "Suggest a free combo for coding" + ] + } + ], + "authentication": { + "schemes": ["bearer"], + "apiKeyHeader": "Authorization" + } +} +``` + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Send a message to a skill and receive the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python hello world"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "a1b2c3d4-...", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "print('Hello, World!')" }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.0030)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "2026-03-04T..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"Quantum computing..."}}} + +: heartbeat 2026-03-04T21:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Running Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Skills Reference + +### `smart-routing` + +Routes prompts through OmniRoute's intelligent pipeline with full observability. + +**Parameters (in `metadata`):** + +| Parameter | Type | Default | Description | +| --------- | -------- | ------------ | ---------------------------------------------------------------------------------------- | +| `model` | `string` | `"auto"` | Target model (e.g., `claude-sonnet-4`, `gpt-4o`, `auto`) | +| `combo` | `string` | active combo | Specific combo to route through | +| `budget` | `number` | none | Maximum cost in USD for this request | +| `role` | `string` | none | Task role hint: `coding`, `review`, `planning`, `analysis`, `debugging`, `documentation` | + +**Returns:** + +| Field | Description | +| ------------------------------ | --------------------------------------------------------- | +| `artifacts[].content` | The LLM response text | +| `metadata.routing_explanation` | Human-readable explanation of routing decision | +| `metadata.cost_envelope` | Estimated vs actual cost with currency | +| `metadata.resilience_trace` | Array of events (primary_selected, fallback_needed, etc.) | +| `metadata.policy_verdict` | Whether the request was allowed and why | + +### `quota-management` + +Answers natural-language queries about provider quotas. + +**Query types (inferred from message content):** + +| Query Pattern | Response Type | +| ---------------------------------------------- | -------------------------------------------------------- | +| Contains `"ranking"`, `"most quota"`, `"best"` | Providers ranked by remaining quota | +| Contains `"free"`, `"suggest"` | Lists free combos or suggests free-tier providers | +| Default | Full quota summary with warnings for low-quota providers | + +--- + +## Task Lifecycle + +``` +submitted โ”€โ”€โ†’ working โ”€โ”€โ†’ completed + โ”€โ”€โ†’ failed + โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ†’ cancelled +``` + +| State | Description | +| ----------- | ----------------------------------------------------- | +| `submitted` | Task created, queued for execution | +| `working` | Skill handler is executing | +| `completed` | Execution succeeded, artifacts available | +| `failed` | Execution failed or task expired (TTL: 5 min default) | +| `cancelled` | Cancelled by client via `tasks/cancel` | + +- Terminal states: `completed`, `failed`, `cancelled` (no further transitions) +- Expired tasks in `submitted` or `working` are auto-marked as `failed` +- Tasks are garbage-collected after 2ร— TTL + +--- + +## Client Examples + +### Python โ€” Orchestrator Agent + +```python +""" +A2A Client โ€” Python example. +Discovers OmniRoute agent, sends a task, and processes the result. +""" +import requests +import json + +BASE_URL = "http://localhost:20128" +API_KEY = "your-api-key" +HEADERS = { + "Content-Type": "application/json", + "Authorization": f"Bearer {API_KEY}", +} + +# 1. Discover agent capabilities +agent_card = requests.get(f"{BASE_URL}/.well-known/agent.json").json() +print(f"Agent: {agent_card['name']} v{agent_card['version']}") +print(f"Skills: {[s['id'] for s in agent_card['skills']]}") + +# 2. Send a smart-routing task +response = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python quicksort implementation"}], + "metadata": { + "model": "auto", + "combo": "fast-coding", + "budget": 0.10, + } + } +}) +result = response.json()["result"] +print(f"\n๐Ÿ“ Response: {result['artifacts'][0]['content'][:200]}...") +print(f"๐Ÿ”€ Routing: {result['metadata']['routing_explanation']}") +print(f"๐Ÿ’ฐ Cost: ${result['metadata']['cost_envelope']['actual']}") +print(f"๐Ÿ›ก๏ธ Policy: {result['metadata']['policy_verdict']['reason']}") + +# 3. Query quota status +quota_resp = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-2", + "method": "message/send", + "params": { + "skill": "quota-management", + "messages": [{"role": "user", "content": "Which provider has the most quota remaining?"}], + } +}) +quota_result = quota_resp.json()["result"] +print(f"\n๐Ÿ“Š Quota: {quota_result['artifacts'][0]['content']}") +``` + +### TypeScript โ€” Multi-Agent Orchestrator + +```typescript +/** + * A2A Client โ€” TypeScript example. + * Shows agent discovery, task delegation, and streaming. + */ + +const BASE_URL = "http://localhost:20128"; +const API_KEY = "your-api-key"; + +interface JsonRpcResponse { + jsonrpc: "2.0"; + id: string | number; + result?: T; + error?: { code: number; message: string }; +} + +async function a2aCall(method: string, params: Record): Promise { + const resp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: `${method}-${Date.now()}`, + method, + params, + }), + }); + const json: JsonRpcResponse = await resp.json(); + if (json.error) throw new Error(`[${json.error.code}] ${json.error.message}`); + return json.result!; +} + +// โ”€โ”€ Agent Discovery โ”€โ”€ +const agentCard = await fetch(`${BASE_URL}/.well-known/agent.json`).then((r) => r.json()); +console.log(`Connected to: ${agentCard.name} (${agentCard.skills.length} skills)`); + +// โ”€โ”€ Smart Routing: Send a coding task โ”€โ”€ +const routingResult = await a2aCall("message/send", { + skill: "smart-routing", + messages: [{ role: "user", content: "Implement a Redis cache wrapper in TypeScript" }], + metadata: { model: "claude-sonnet-4", role: "coding" }, +}); +console.log("Response:", routingResult.artifacts[0].content); +console.log("Provider:", routingResult.metadata.routing_explanation); + +// โ”€โ”€ Quota Management: Find free alternatives โ”€โ”€ +const quotaResult = await a2aCall("message/send", { + skill: "quota-management", + messages: [{ role: "user", content: "Suggest free combos for documentation" }], +}); +console.log("Free combos:", quotaResult.artifacts[0].content); + +// โ”€โ”€ Streaming: Real-time response โ”€โ”€ +const streamResp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "stream-1", + method: "message/stream", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Explain microservices architecture" }], + }, + }), +}); + +const reader = streamResp.body!.getReader(); +const decoder = new TextDecoder(); +while (true) { + const { done, value } = await reader.read(); + if (done) break; + const chunk = decoder.decode(value); + for (const line of chunk.split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + if (event.params.chunk) { + process.stdout.write(event.params.chunk.content); + } + if (event.params.task.state === "completed") { + console.log("\nโœ… Stream completed"); + } + } + } +} +``` + +### Python โ€” LangChain A2A Integration + +```python +""" +LangChain integration โ€” Use OmniRoute A2A as a custom LLM. +""" +from langchain.llms.base import BaseLLM +from langchain.schema import LLMResult, Generation +import requests +from typing import List, Optional + +class OmniRouteA2A(BaseLLM): + base_url: str = "http://localhost:20128" + api_key: str = "" + model: str = "auto" + combo: Optional[str] = None + + @property + def _llm_type(self) -> str: + return "omniroute-a2a" + + def _call(self, prompt: str, stop: Optional[List[str]] = None, **kwargs) -> str: + response = requests.post( + f"{self.base_url}/a2a", + headers={ + "Content-Type": "application/json", + "Authorization": f"Bearer {self.api_key}", + }, + json={ + "jsonrpc": "2.0", + "id": "langchain-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": prompt}], + "metadata": { + "model": self.model, + **({"combo": self.combo} if self.combo else {}), + }, + }, + }, + ) + result = response.json()["result"] + return result["artifacts"][0]["content"] + + def _generate(self, prompts: List[str], stop=None, **kwargs) -> LLMResult: + return LLMResult( + generations=[[Generation(text=self._call(p, stop))] for p in prompts] + ) + +# Usage +llm = OmniRouteA2A( + base_url="http://localhost:20128", + api_key="your-key", + model="auto", + combo="fast-coding", +) +result = llm("Write a Python function to merge two sorted lists") +print(result) +``` + +### Go โ€” A2A Client + +```go +package main + +import ( + "bytes" + "encoding/json" + "fmt" + "io" + "net/http" +) + +const baseURL = "http://localhost:20128" +const apiKey = "your-api-key" + +type JsonRpcRequest struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Method string `json:"method"` + Params interface{} `json:"params"` +} + +type JsonRpcResponse struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Result interface{} `json:"result"` + Error *struct { + Code int `json:"code"` + Message string `json:"message"` + } `json:"error"` +} + +func a2aCall(method string, params interface{}) (*JsonRpcResponse, error) { + body, _ := json.Marshal(JsonRpcRequest{ + Jsonrpc: "2.0", + ID: "go-1", + Method: method, + Params: params, + }) + + req, _ := http.NewRequest("POST", baseURL+"/a2a", bytes.NewReader(body)) + req.Header.Set("Content-Type", "application/json") + req.Header.Set("Authorization", "Bearer "+apiKey) + + resp, err := http.DefaultClient.Do(req) + if err != nil { + return nil, err + } + defer resp.Body.Close() + data, _ := io.ReadAll(resp.Body) + + var result JsonRpcResponse + json.Unmarshal(data, &result) + return &result, nil +} + +func main() { + // Discover agent + resp, _ := http.Get(baseURL + "/.well-known/agent.json") + defer resp.Body.Close() + body, _ := io.ReadAll(resp.Body) + fmt.Println("Agent Card:", string(body)) + + // Send smart-routing task + result, _ := a2aCall("message/send", map[string]interface{}{ + "skill": "smart-routing", + "messages": []map[string]string{{"role": "user", "content": "Hello from Go!"}}, + "metadata": map[string]interface{}{"model": "auto"}, + }) + out, _ := json.MarshalIndent(result.Result, "", " ") + fmt.Println("Result:", string(out)) +} +``` + +--- + +## Use Cases + +### ๐Ÿค– Use Case 1: Multi-Agent Coding Pipeline + +An orchestrator agent delegates code generation to OmniRoute, then passes the output to a review agent. + +```python +def coding_pipeline(task: str): + # Step 1: Generate code via OmniRoute A2A + code_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Write production-quality code: {task}"} + ], metadata={"model": "auto", "role": "coding"}) + code = code_result["artifacts"][0]["content"] + + # Step 2: Review the code via OmniRoute A2A (different model) + review_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Review this code for bugs and improvements:\n\n{code}"} + ], metadata={"model": "auto", "role": "review"}) + review = review_result["artifacts"][0]["content"] + + # Step 3: Check costs + print(f"Code cost: ${code_result['metadata']['cost_envelope']['actual']}") + print(f"Review cost: ${review_result['metadata']['cost_envelope']['actual']}") + + return {"code": code, "review": review} +``` + +### ๐Ÿ’ก Use Case 2: Quota-Aware Agent Swarm + +Multiple agents share quota through OmniRoute, using the quota skill to coordinate. + +```python +async def quota_aware_agent(agent_name: str, task: str): + # Check quota before starting + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Which provider has the most quota remaining?"} + ]) + print(f"[{agent_name}] {quota['artifacts'][0]['content']}") + + # Send request with budget constraint + result = a2a_send("smart-routing", [ + {"role": "user", "content": task} + ], metadata={"budget": 0.05}) + + policy = result["metadata"]["policy_verdict"] + if not policy["allowed"]: + print(f"[{agent_name}] โš ๏ธ Budget exceeded: {policy['reason']}") + # Fall back to free combo + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Suggest free combos"} + ]) + print(f"[{agent_name}] Free alternatives: {quota['artifacts'][0]['content']}") + + return result +``` + +### ๐Ÿ“Š Use Case 3: Real-Time Streaming Dashboard + +A monitoring agent streams responses and displays progress in real-time. + +```typescript +async function streamingDashboard(prompt: string) { + const response = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { "Content-Type": "application/json", Authorization: `Bearer ${API_KEY}` }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "dash-1", + method: "message/stream", + params: { skill: "smart-routing", messages: [{ role: "user", content: prompt }] }, + }), + }); + + let totalChunks = 0; + const reader = response.body!.getReader(); + const decoder = new TextDecoder(); + + while (true) { + const { done, value } = await reader.read(); + if (done) break; + + for (const line of decoder.decode(value).split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + const state = event.params.task.state; + + if (state === "working" && event.params.chunk) { + totalChunks++; + process.stdout.write( + `\r[Chunk ${totalChunks}] ${event.params.chunk.content.slice(0, 50)}...` + ); + } + if (state === "completed") { + const meta = event.params.metadata; + console.log( + `\nโœ… Done | Cost: $${meta?.cost_envelope?.actual || 0} | Route: ${meta?.routing_explanation || "N/A"}` + ); + } + if (state === "failed") { + console.error(`\nโŒ Failed: ${event.params.metadata?.error}`); + } + } + } + } +} +``` + +### ๐Ÿ” Use Case 4: Task Polling Pattern + +For long-running tasks, poll the task status instead of waiting synchronously. + +```python +import time + +def poll_task(task_id: str, timeout: int = 60): + """Poll task status until completion or timeout.""" + start = time.time() + while time.time() - start < timeout: + result = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "poll-1", + "method": "tasks/get", + "params": {"taskId": task_id}, + }).json() + + task = result["result"]["task"] + state = task["state"] + print(f" Task {task_id[:8]}... state={state}") + + if state in ("completed", "failed", "cancelled"): + return task + time.sleep(2) + + # Timeout โ€” cancel the task + requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "cancel-1", + "method": "tasks/cancel", + "params": {"taskId": task_id}, + }) + raise TimeoutError(f"Task {task_id} timed out after {timeout}s") +``` + +--- + +## Error Codes + +| Code | Constant | Meaning | +| ------ | ------------------------ | ---------------------------------------- | +| -32700 | โ€” | Parse error (invalid JSON) | +| -32600 | `INVALID_REQUEST` | Invalid JSON-RPC request or unauthorized | +| -32601 | `METHOD_NOT_FOUND` | Unknown method or skill | +| -32602 | `INVALID_PARAMS` | Missing or invalid parameters | +| -32603 | `INTERNAL_ERROR` | Skill execution failed | +| -32001 | `TASK_NOT_FOUND` | Task ID not found | +| -32002 | `TASK_ALREADY_COMPLETED` | Cannot modify a completed task | +| -32003 | `UNAUTHORIZED` | Invalid or missing API key | +| -32004 | `BUDGET_EXCEEDED` | Request exceeds configured budget | +| -32005 | `PROVIDER_UNAVAILABLE` | No available providers | + +--- + +## Authentication + +All `/a2a` requests require a Bearer token via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server (`OMNIROUTE_API_KEY` is empty), authentication is bypassed. + +--- + +## File Structure + +``` +src/lib/a2a/ +โ”œโ”€โ”€ taskManager.ts # Task lifecycle (create/update/cancel/list), TTL, cleanup +โ”œโ”€โ”€ taskExecution.ts # Generic task executor with state management +โ”œโ”€โ”€ streaming.ts # SSE stream formatting, heartbeat, chunk/completion events +โ”œโ”€โ”€ routingLogger.ts # Routing decision logger (stats, history, retention) +โ””โ”€โ”€ skills/ + โ”œโ”€โ”€ smartRouting.ts # Smart routing skill (routes via /v1/chat/completions) + โ””โ”€โ”€ quotaManagement.ts # Quota management skill (natural-language quota queries) + +src/app/a2a/ +โ””โ”€โ”€ route.ts # Next.js API route handler (JSON-RPC 2.0 dispatch) + +open-sse/mcp-server/ +โ””โ”€โ”€ schemas/a2a.ts # Zod schemas (AgentCard, Task, JSON-RPC, SSE events) +``` + +--- + +## Comparison: MCP vs A2A + +| Feature | MCP Server | A2A Server | +| ----------------- | ---------------------------- | ------------------------------------------------- | +| **Protocol** | Model Context Protocol | Agent-to-Agent Protocol v0.3 | +| **Transport** | stdio / HTTP | HTTP (JSON-RPC 2.0) | +| **Discovery** | Tool listing via MCP | `/.well-known/agent.json` | +| **Granularity** | 16 individual tools | 2 high-level skills | +| **Best for** | IDE agents (Cursor, VS Code) | Multi-agent systems (LangChain, CrewAI) | +| **Streaming** | Not supported | SSE via `message/stream` | +| **Task tracking** | No | Full lifecycle (submitted โ†’ completed) | +| **Observability** | Audit log per tool call | Cost envelope + resilience trace + policy verdict | + +--- + +## ะ›ะธั†ะตะฝะทะธั + +Part of [OmniRoute](https://github.com/diegosouzapw/OmniRoute) โ€” MIT License. diff --git a/docs/i18n/sk/A2A-SERVER.md b/docs/i18n/sk/A2A-SERVER.md deleted file mode 100644 index 01531ff482..0000000000 --- a/docs/i18n/sk/A2A-SERVER.md +++ /dev/null @@ -1,200 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/A2A-SERVER.md) - ---- - -# OmniRoute A2A Server Documentation - -> Agent-to-Agent Protocol v0.3 โ€” OmniRoute as an intelligent routing agent - -## Agent Discovery - -```bash -curl http://localhost:20128/.well-known/agent.json -``` - -Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements. - ---- - -## Authentication - -All `/a2a` requests require an API key via the `Authorization` header: - -``` -Authorization: Bearer YOUR_OMNIROUTE_API_KEY -``` - -If no API key is configured on the server, authentication is bypassed. - ---- - -## JSON-RPC 2.0 Methods - -### `message/send` โ€” Synchronous Execution - -Sends a message to a skill and waits for the complete response. - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{ - "jsonrpc": "2.0", - "id": "1", - "method": "message/send", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Write a hello world in Python"}], - "metadata": {"model": "auto", "combo": "fast-coding"} - } - }' -``` - -**Response:** - -```json -{ - "jsonrpc": "2.0", - "id": "1", - "result": { - "task": { "id": "uuid", "state": "completed" }, - "artifacts": [{ "type": "text", "content": "..." }], - "metadata": { - "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)", - "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, - "resilience_trace": [ - { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." } - ], - "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } - } - } -} -``` - -### `message/stream` โ€” SSE Streaming - -Same as `message/send` but returns Server-Sent Events for real-time streaming. - -```bash -curl -N -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{ - "jsonrpc": "2.0", - "id": "1", - "method": "message/stream", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Explain quantum computing"}] - } - }' -``` - -**SSE Events:** - -``` -data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}} - -: heartbeat 2026-03-03T17:00:00Z - -data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} -``` - -### `tasks/get` โ€” Query Task Status - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' -``` - -### `tasks/cancel` โ€” Cancel a Task - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' -``` - ---- - -## Available Skills - -| Skill | Description | -| :----------------- | :------------------------------------------------------------------------------------------------------------------------------ | -| `smart-routing` | Routes prompts through OmniRoute's intelligent pipeline. Returns response with routing explanation, cost, and resilience trace. | -| `quota-management` | Answers natural-language queries about provider quotas, suggests free combos, and provides quota rankings. | - ---- - -## Task Lifecycle - -``` -submitted โ†’ working โ†’ completed - โ†’ failed - โ†’ cancelled -``` - -- Tasks expire after 5 minutes (configurable) -- Terminal states: `completed`, `failed`, `cancelled` -- Event log tracks every state transition - ---- - -## Error Codes - -| Code | Meaning | -| :----- | :----------------------------- | -| -32700 | Parse error (invalid JSON) | -| -32600 | Invalid request / Unauthorized | -| -32601 | Method or skill not found | -| -32602 | Invalid params | -| -32603 | Internal error | - ---- - -## Integration Examples - -### Python (requests) - -```python -import requests - -resp = requests.post("http://localhost:20128/a2a", json={ - "jsonrpc": "2.0", "id": "1", - "method": "message/send", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Hello"}] - } -}, headers={"Authorization": "Bearer YOUR_KEY"}) - -result = resp.json()["result"] -print(result["artifacts"][0]["content"]) -print(result["metadata"]["routing_explanation"]) -``` - -### TypeScript (fetch) - -```typescript -const resp = await fetch("http://localhost:20128/a2a", { - method: "POST", - headers: { - "Content-Type": "application/json", - Authorization: "Bearer YOUR_KEY", - }, - body: JSON.stringify({ - jsonrpc: "2.0", - id: "1", - method: "message/send", - params: { - skill: "smart-routing", - messages: [{ role: "user", content: "Hello" }], - }, - }), -}); -const { result } = await resp.json(); -console.log(result.metadata.routing_explanation); -``` diff --git a/docs/i18n/sk/API_REFERENCE.md b/docs/i18n/sk/API_REFERENCE.md deleted file mode 100644 index b878605221..0000000000 --- a/docs/i18n/sk/API_REFERENCE.md +++ /dev/null @@ -1,455 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/API_REFERENCE.md) - ---- - -# API Reference - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/API_REFERENCE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/API_REFERENCE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/API_REFERENCE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/API_REFERENCE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/API_REFERENCE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/API_REFERENCE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/API_REFERENCE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/API_REFERENCE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/API_REFERENCE.md) - -Complete reference for all OmniRoute API endpoints. - ---- - -## Table of Contents - -- [Chat Completions](#chat-completions) -- [Embeddings](#embeddings) -- [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`. - -### ACP Agents - -| Endpoint | Method | Description | -| ----------------- | ------ | -------------------------------------------------------- | -| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | -| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | -| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | - -GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). - -### Resilience & Rate Limits - -| Endpoint | Method | Description | -| ----------------------- | ------- | ------------------------------- | -| `/api/resilience` | 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` diff --git a/docs/i18n/sk/ARCHITECTURE.md b/docs/i18n/sk/ARCHITECTURE.md deleted file mode 100644 index 4ea06a29f2..0000000000 --- a/docs/i18n/sk/ARCHITECTURE.md +++ /dev/null @@ -1,787 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/ARCHITECTURE.md) - ---- - -# OmniRoute Architecture - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/ARCHITECTURE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/ARCHITECTURE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/ARCHITECTURE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/ARCHITECTURE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/ARCHITECTURE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/ARCHITECTURE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/ARCHITECTURE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/ARCHITECTURE.md) - -_Last updated: 2026-03-04_ - -## 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 (`...`) for reasoning models -- Response sanitization for strict OpenAI SDK compatibility -- Role normalization (developerโ†’system, systemโ†’user) for cross-provider compatibility -- Structured output conversion (json_schema โ†’ Gemini responseSchema) -- Local persistence for providers, keys, aliases, combos, settings, pricing -- Usage/cost tracking and request logging -- Optional cloud sync for multi-device/state sync -- IP allowlist/blocklist for API access control -- Thinking budget management (passthrough/auto/custom/adaptive) -- Global system prompt injection -- Session tracking and fingerprinting -- Per-account enhanced rate limiting with provider-specific profiles -- Circuit breaker pattern for provider resilience -- Anti-thundering herd protection with mutex locking -- Signature-based request deduplication cache -- Domain layer: model availability, cost rules, fallback policy, lockout policy -- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) -- Policy engine for centralized request evaluation (lockout โ†’ budget โ†’ fallback) -- Request telemetry with p50/p95/p99 latency aggregation -- Correlation ID (X-Request-Id) for end-to-end tracing -- Compliance audit logging with opt-out per API key -- Eval framework for LLM quality assurance -- Resilience UI dashboard with real-time circuit breaker status -- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) - -Primary runtime model: - -- Next.js 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[(storage.sqlite)] - UDB[(usage tables + log artifacts)] - end - - subgraph Upstreams[Upstream Providers] - P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/Qoder/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/route.ts` (GET) -- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) -- OAuth: `src/app/api/oauth/*` -- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` -- Usage: `src/app/api/usage/*` -- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` -- CLI tooling helpers: `src/app/api/cli-tools/*` -- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) -- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) -- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) -- Sessions: `src/app/api/sessions` (GET) -- Rate limits: `src/app/api/rate-limits` (GET) -- Resilience: `src/app/api/resilience` (GET/PATCH) โ€” provider profiles, circuit breaker, rate limit state -- Resilience reset: `src/app/api/resilience/reset` (POST) โ€” reset breakers + cooldowns -- Cache stats: `src/app/api/cache/stats` (GET/DELETE) -- Model availability: `src/app/api/models/availability` (GET/POST) -- Telemetry: `src/app/api/telemetry/summary` (GET) -- Budget: `src/app/api/usage/budget` (GET/POST) -- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) -- Compliance audit: `src/app/api/compliance/audit-log` (GET) -- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) -- Policies: `src/app/api/policies` (GET/POST) - -## 2) SSE + 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` -- Response sanitization: `open-sse/handlers/responseSanitizer.ts` -- Role normalization: `open-sse/services/roleNormalizer.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`, `qoder.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 (SQLite): - -- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) -- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) -- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) -- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** - -Usage persistence: - -- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) -- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` -- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) -- legacy JSON files are migrated to SQLite by startup migrations when present - -Domain State DB (SQLite): - -- `src/lib/db/domainState.ts` โ€” CRUD operations 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: - -- primary runtime DB: `${DATA_DIR}/storage.sqlite` -- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) -- structured call payload archives: `${DATA_DIR}/call_logs/` -- optional translator/request debug sessions: `/logs/...` - -## Deployment Topology - -```mermaid -flowchart LR - 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[(storage.sqlite)] - UsageDB[(usage tables + log artifacts)] - end - - subgraph External[External Services] - Providers[AI Providers] - SyncCloud[Cloud Sync Service] - end - - CLI --> Next - Browser --> Next - Next --> Core - Next --> MainDB - Core --> MainDB - Core --> UsageDB - Core --> Providers - Next --> SyncCloud -``` - -## Module Mapping (Decision-Critical) - -### Route and API Modules - -- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs -- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) -- `src/app/api/providers*`: provider CRUD, validation, testing -- `src/app/api/provider-nodes*`: custom compatible node management -- `src/app/api/provider-models`: custom model management (CRUD) -- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) -- `src/app/api/oauth/*`: OAuth/device-code flows -- `src/app/api/keys*`: local API key lifecycle -- `src/app/api/models/alias`: alias management -- `src/app/api/combos*`: fallback combo management -- `src/app/api/pricing`: pricing overrides for cost calculation -- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) -- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) -- `src/app/api/usage/*`: usage and logs APIs -- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers -- `src/app/api/cli-tools/*`: local CLI config writers/checkers -- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) -- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) -- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) -- `src/app/api/sessions`: active session listing (GET) -- `src/app/api/rate-limits`: per-account rate limit status (GET) - -### Routing and Execution Core - -- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop -- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup -- `open-sse/executors/*`: provider-specific network and format behavior - -### Translation Registry and Format Converters - -- `open-sse/translator/index.ts`: translator registry and orchestration -- Request translators: `open-sse/translator/request/*` -- Response translators: `open-sse/translator/response/*` -- Format constants: `open-sse/translator/formats.ts` - -### Persistence - -- `src/lib/db/*`: persistent config/state and domain persistence on SQLite -- `src/lib/localDb.ts`: compatibility re-export for DB modules -- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables - -## Provider Executor Coverage (Strategy Pattern) - -Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. - -| Executor | Provider(s) | Special Handling | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | -| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, Qoder, 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 | -| Qoder | openai | OAuth (Basic) | โœ… | โœ… | โœ… | โš ๏ธ Per request | -| OpenRouter | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| GLM/Kimi/MiniMax | claude | API Key | โœ… | โœ… | โŒ | โŒ | -| DeepSeek | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Groq | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| xAI (Grok) | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Mistral | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Perplexity | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Together AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Fireworks AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Cerebras | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Cohere | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| NVIDIA NIM | openai | API Key | โœ… | โœ… | โŒ | โŒ | - -## Format Translation Coverage - -Detected source formats include: - -- `openai` -- `openai-responses` -- `claude` -- `gemini` - -Target formats include: - -- OpenAI chat/Responses -- Claude -- Gemini/Gemini-CLI/Antigravity envelope -- Kiro -- Cursor - -Translations use **OpenAI as the hub format** โ€” all conversions go through OpenAI as intermediate: - -``` -Source Format โ†’ OpenAI (hub) โ†’ Target Format -``` - -Translations are selected dynamically based on source payload shape and provider target format. - -Additional processing layers in the translation pipeline: - -- **Response sanitization** โ€” Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance -- **Role normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI targets; merges `system` โ†’ `user` for models that reject the system role (GLM, ERNIE) -- **Think tag extraction** โ€” Parses `...` blocks from content into `reasoning_content` field -- **Structured output** โ€” Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` - -## Supported API Endpoints - -| 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 `/logs//` 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 - -- SQLite schema migrations and auto-upgrade hooks at startup -- legacy JSON โ†’ SQLite migration compatibility path - -## Observability and Operational Signals - -Runtime visibility sources: - -- console logs from `src/sse/utils/logger.ts` -- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) -- textual request status log in `log.txt` (optional/compat) -- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` -- dashboard usage endpoints (`/api/usage/*`) for UI consumption - -## Security-Sensitive Boundaries - -- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing -- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning -- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format -- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level -- Cloud sync endpoints rely on API key auth + machine id semantics - -## Environment and Runtime Matrix - -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` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. -2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. -3. Request logger writes full headers/body when enabled; treat log directory as sensitive. -4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. -5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. -6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). -7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). -8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). - -## Operational Verification Checklist - -- Build from source: `npm run build` -- Build Docker image: `docker build -t omniroute .` -- Start service and verify: -- `GET /api/settings` -- `GET /api/v1/models` -- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/sk/AUTO-COMBO.md b/docs/i18n/sk/AUTO-COMBO.md deleted file mode 100644 index 2166e41dff..0000000000 --- a/docs/i18n/sk/AUTO-COMBO.md +++ /dev/null @@ -1,67 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/AUTO-COMBO.md) - ---- - -# OmniRoute Auto-Combo Engine - -> Self-managing model chains with adaptive scoring - -## How It Works - -The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**: - -| Factor | Weight | Description | -| :--------- | :----- | :---------------------------------------------- | -| Quota | 0.20 | Remaining capacity [0..1] | -| Health | 0.25 | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 | -| CostInv | 0.20 | Inverse cost (cheaper = higher score) | -| LatencyInv | 0.15 | Inverse p95 latency (faster = higher) | -| TaskFit | 0.10 | Model ร— task type fitness score | -| Stability | 0.10 | Low variance in latency/errors | - -## Mode Packs - -| Pack | Focus | Key Weight | -| :---------------------- | :----------- | :--------------- | -| ๐Ÿš€ **Ship Fast** | Speed | latencyInv: 0.35 | -| ๐Ÿ’ฐ **Cost Saver** | Economy | costInv: 0.40 | -| ๐ŸŽฏ **Quality First** | Best model | taskFit: 0.40 | -| ๐Ÿ“ก **Offline Friendly** | Availability | quota: 0.40 | - -## Self-Healing - -- **Temporary exclusion**: Score < 0.2 โ†’ excluded for 5 min (progressive backoff, max 30 min) -- **Circuit breaker awareness**: OPEN โ†’ auto-excluded; HALF_OPEN โ†’ probe requests -- **Incident mode**: >50% OPEN โ†’ disable exploration, maximize stability -- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout - -## Bandit Exploration - -5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode. - -## API - -```bash -# Create auto-combo -curl -X POST http://localhost:20128/api/combos/auto \ - -H "Content-Type: application/json" \ - -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}' - -# List auto-combos -curl http://localhost:20128/api/combos/auto -``` - -## Task Fitness - -30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` โ†’ high coding score). - -## Files - -| File | Purpose | -| :------------------------------------------- | :------------------------------------ | -| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization | -| `open-sse/services/autoCombo/taskFitness.ts` | Model ร— task fitness lookup | -| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap | -| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode | -| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles | -| `src/app/api/combos/auto/route.ts` | REST API | diff --git a/docs/i18n/sk/CHANGELOG.md b/docs/i18n/sk/CHANGELOG.md index ef261fe4e1..432788c60d 100644 --- a/docs/i18n/sk/CHANGELOG.md +++ b/docs/i18n/sk/CHANGELOG.md @@ -1,12 +1,92 @@ # Changelog (Slovenฤina) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CHANGELOG.md) --- - ## [Unreleased] +### ๐Ÿ› ๏ธ Maintenance + +- **AGENTS.md rewrite:** Condensed from 297โ†’153 lines. Added build/lint/test commands (including single-test execution), code style guidelines (Prettier, TypeScript, ESLint, naming, imports, error handling, security), and trimmed verbose architecture tables for AI agent consumption. + +## [3.4.2] - 2026-04-01 + +### ๐Ÿ› Bug Fixes + +- **CI Stabilization:** Fixed failing analytics/settings Playwright selectors and request assertions so GitHub Actions E2E runs pass reliably across localized UIs and switch-based controls. +- **Deterministic Tests:** Removed date-sensitive quota fixtures from Copilot usage tests and aligned idempotency/model catalog tests with the merged runtime behavior. +- **MCP Type Hardening:** Removed zero-budget explicit `any` regressions from the MCP server tool registration path, restoring the `check:any-budget:t11` workflow gate. + +### ๐Ÿ› ๏ธ Maintenance + +- **Release Branch Integration:** Consolidated the active feature branches into `release/v3.4.2` on top of current `main` and validated the branch with lint, unit, coverage, build, and CI-mode E2E runs. + +## [3.4.1] - 2026-03-31 + +> [!WARNING] +> **BREAKING CHANGE: request logging, retention, and logging environment variables have been redesigned.** +> On the first startup after upgrading, OmniRoute archives legacy request logs from `DATA_DIR/logs/`, legacy `DATA_DIR/call_logs/`, and `DATA_DIR/log.txt` into `DATA_DIR/log_archives/*.zip`, then removes the deprecated layout and switches to the new unified artifact format under `DATA_DIR/call_logs/`. + +### โœจ New Features + +- **.ENV Migration Utility:** Included `scripts/migrate-env.mjs` to seamlessly migrate ` Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` - ---- - -## Step 2 โ€” Install CLI Tools - -All npm-based tools require Node.js 18+: - -```bash -# Claude Code (Anthropic) -npm install -g @anthropic-ai/claude-code - -# OpenAI Codex -npm install -g @openai/codex - -# Gemini CLI (Google) -npm install -g @google/gemini-cli - -# OpenCode -npm install -g opencode-ai - -# Cline -npm install -g cline - -# KiloCode -npm install -g kilecode - -# Kiro CLI (Amazon โ€” requires curl + unzip) -apt-get install -y unzip # on Debian/Ubuntu -curl -fsSL https://cli.kiro.dev/install | bash -export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc -``` - -**Verify:** - -```bash -claude --version # 2.x.x -codex --version # 0.x.x -gemini --version # 0.x.x -opencode --version # x.x.x -cline --version # 2.x.x -kilocode --version # x.x.x (or: kilo --version) -kiro-cli --version # 1.x.x -``` - ---- - -## Step 3 โ€” Set Global Environment Variables - -Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`: - -```bash -# OmniRoute Universal Endpoint -export OPENAI_BASE_URL="http://localhost:20128/v1" -export OPENAI_API_KEY="sk-your-omniroute-key" -export ANTHROPIC_BASE_URL="http://localhost:20128/v1" -export ANTHROPIC_API_KEY="sk-your-omniroute-key" -export GEMINI_BASE_URL="http://localhost:20128/v1" -export GEMINI_API_KEY="sk-your-omniroute-key" -``` - -> For a **remote server** replace `localhost:20128` with the server IP or domain, -> e.g. `http://192.168.0.15:20128`. - ---- - -## Step 4 โ€” Configure Each Tool - -### Claude Code - -```bash -# Via CLI: -claude config set --global api-base-url http://localhost:20128/v1 - -# Or create ~/.claude/settings.json: -mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF -{ - "apiBaseUrl": "http://localhost:20128/v1", - "apiKey": "sk-your-omniroute-key" -} -EOF -``` - -**Test:** `claude "say hello"` - ---- - -### OpenAI Codex - -```bash -mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF -model: auto -apiKey: sk-your-omniroute-key -apiBaseUrl: http://localhost:20128/v1 -EOF -``` - -**Test:** `codex "what is 2+2?"` - ---- - -### Gemini CLI - -```bash -mkdir -p ~/.gemini && cat > ~/.gemini/settings.json << EOF -{ - "apiKey": "sk-your-omniroute-key", - "baseUrl": "http://localhost:20128/v1" -} -EOF -``` - -**Test:** `gemini "hello"` - ---- - -### OpenCode - -```bash -mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF -[provider.openai] -base_url = "http://localhost:20128/v1" -api_key = "sk-your-omniroute-key" -EOF -``` - -**Test:** `opencode` - ---- - -### Cline (CLI or VS Code) - -**CLI mode:** - -```bash -mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF -{ - "apiProvider": "openai", - "openAiBaseUrl": "http://localhost:20128/v1", - "openAiApiKey": "sk-your-omniroute-key" -} -EOF -``` - -**VS Code mode:** -Cline extension settings โ†’ API Provider: `OpenAI Compatible` โ†’ Base URL: `http://localhost:20128/v1` - -Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ Cline โ†’ Apply Config**. - ---- - -### KiloCode (CLI or VS Code) - -**CLI mode:** - -```bash -kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key -``` - -**VS Code settings:** - -```json -{ - "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", - "kilo-code.apiKey": "sk-your-omniroute-key" -} -``` - -Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ KiloCode โ†’ Apply Config**. - ---- - -### Continue (VS Code Extension) - -Edit `~/.continue/config.yaml`: - -```yaml -models: - - name: OmniRoute - provider: openai - model: auto - apiBase: http://localhost:20128/v1 - apiKey: sk-your-omniroute-key - default: true -``` - -Restart VS Code after editing. - ---- - -### Kiro CLI (Amazon) - -```bash -# Login to your AWS/Kiro account: -kiro-cli login - -# The CLI uses its own auth โ€” OmniRoute is not needed as backend for Kiro CLI itself. -# Use kiro-cli alongside OmniRoute for other tools. -kiro-cli status -``` - ---- - -### Cursor (Desktop App) - -> **Note:** Cursor routes requests through its cloud. For OmniRoute integration, -> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL. - -Via GUI: **Settings โ†’ Models โ†’ OpenAI API Key** - -- Base URL: `https://your-domain.com/v1` -- API Key: your OmniRoute key - ---- - -## Dashboard Auto-Configuration - -The OmniRoute dashboard automates configuration for most tools: - -1. Go to `http://localhost:20128/dashboard/cli-tools` -2. Expand any tool card -3. Select your API key from the dropdown -4. Click **Apply Config** (if tool is detected as installed) -5. Or copy the generated config snippet manually - ---- - -## Built-in Agents: Droid & OpenClaw - -**Droid** and **OpenClaw** are AI agents built directly into OmniRoute โ€” no installation needed. -They run as internal routes and use OmniRoute's model routing automatically. - -- Access: `http://localhost:20128/dashboard/agents` -- Configure: same combos and providers as all other tools -- No API key or CLI install required - ---- - -## Available API Endpoints - -| Endpoint | Description | Use For | -| -------------------------- | ----------------------------- | --------------------------- | -| `/v1/chat/completions` | Standard chat (all providers) | All modern tools | -| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows | -| `/v1/completions` | Legacy text completions | Older tools using `prompt:` | -| `/v1/embeddings` | Text embeddings | RAG, search | -| `/v1/images/generations` | Image generation | DALL-E, Flux, etc. | -| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS | -| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI | - ---- - -## Troubleshooting - -| Error | Cause | Fix | -| ------------------------- | ----------------------- | ------------------------------------------ | -| `Connection refused` | OmniRoute not running | `pm2 start omniroute` | -| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` | -| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` | -| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` | -| CLI shows "not installed" | Binary not in PATH | Check `which ` | -| `kiro-cli: not found` | Not in PATH | `export PATH="$HOME/.local/bin:$PATH"` | - ---- - -## Quick Setup Script (One Command) - -```bash -# Install all CLIs and configure for OmniRoute (replace with your key and server URL) -OMNIROUTE_URL="http://localhost:20128/v1" -OMNIROUTE_KEY="sk-your-omniroute-key" - -npm install -g @anthropic-ai/claude-code @openai/codex @google/gemini-cli opencode-ai cline kilecode - -# Kiro CLI -apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash - -# Write configs -mkdir -p ~/.claude ~/.codex ~/.gemini ~/.config/opencode ~/.continue - -cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" -cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" -cat > ~/.gemini/settings.json <<< "{\"apiKey\":\"$OMNIROUTE_KEY\",\"baseUrl\":\"$OMNIROUTE_URL\"}" -cat >> ~/.bashrc << EOF -export OPENAI_BASE_URL="$OMNIROUTE_URL" -export OPENAI_API_KEY="$OMNIROUTE_KEY" -export ANTHROPIC_BASE_URL="$OMNIROUTE_URL" -export ANTHROPIC_API_KEY="$OMNIROUTE_KEY" -EOF - -source ~/.bashrc -echo "โœ… All CLIs installed and configured for OmniRoute" -``` diff --git a/docs/i18n/sk/CODEBASE_DOCUMENTATION.md b/docs/i18n/sk/CODEBASE_DOCUMENTATION.md deleted file mode 100644 index e2d7950052..0000000000 --- a/docs/i18n/sk/CODEBASE_DOCUMENTATION.md +++ /dev/null @@ -1,593 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CODEBASE_DOCUMENTATION.md) - ---- - -# omniroute โ€” Codebase Documentation - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) - -> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. - ---- - -## 1. 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
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, Qoder, 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 | -| Qoder | 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"] -``` diff --git a/docs/i18n/sk/CONTRIBUTING.md b/docs/i18n/sk/CONTRIBUTING.md new file mode 100644 index 0000000000..857dc87287 --- /dev/null +++ b/docs/i18n/sk/CONTRIBUTING.md @@ -0,0 +1,299 @@ +# Contributing to OmniRoute (Slovenฤina) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CONTRIBUTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CONTRIBUTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CONTRIBUTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CONTRIBUTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CONTRIBUTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CONTRIBUTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CONTRIBUTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CONTRIBUTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CONTRIBUTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CONTRIBUTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CONTRIBUTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CONTRIBUTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CONTRIBUTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CONTRIBUTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CONTRIBUTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CONTRIBUTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CONTRIBUTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CONTRIBUTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CONTRIBUTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CONTRIBUTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CONTRIBUTING.md) + +--- + +Thank you for your interest in contributing! This guide covers everything you need to get started. + +--- + +## Development Setup + +### Prerequisites + +- **Node.js** >= 18 < 24 (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` | `20128` | Server port | +| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | Base URL for frontend | +| `JWT_SECRET` | (generate above) | JWT signing secret | +| `INITIAL_PASSWORD` | `CHANGEME` | First login password | +| `APP_LOG_LEVEL` | `info` | Log verbosity level | + +### Dashboard Settings + +The dashboard provides UI toggles for features that can also be configured via environment variables: + +| Setting Location | Toggle | Description | +| ------------------- | ------------------ | ------------------------------ | +| Settings โ†’ Advanced | Debug Mode | Enable debug request logs (UI) | +| Settings โ†’ General | Sidebar Visibility | Show/hide sidebar sections | + +These settings are stored in the database and persist across restarts, overriding env var defaults when set. + +### 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:20128/dashboard` +- **API**: `http://localhost:20128/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`, `mcp`, `a2a`, `memory`, `skills`. + +--- + +## Running Tests + +```bash +# All tests (unit + vitest + ecosystem + e2e) +npm run test:all + +# Single test file (Node.js native test runner โ€” most tests use this) +node --import tsx/esm --test tests/unit/your-file.test.mjs + +# Vitest (MCP server, autoCombo, cache) +npm run test:vitest + +# E2E tests (requires Playwright) +npm run test:e2e + +# Protocol clients E2E (MCP transports, A2A) +npm run test:protocols:e2e + +# Ecosystem compatibility tests +npm run test:ecosystem + +# Coverage (55% min statements/lines/functions; 60% branches) +npm run test:coverage +npm run coverage:report + +# Lint + format check +npm run lint +npm run check +``` + +Coverage notes: + +- `npm run test:coverage` measures source coverage for the main unit test suite, excludes `tests/**`, and includes `open-sse/**` +- `npm run coverage:report` prints the detailed file-by-file report from the latest coverage run +- `npm run test:coverage:legacy` preserves the older metric for historical comparison +- See `docs/COVERAGE_PLAN.md` for the phased coverage improvement roadmap + +Current test status: **122 unit test files** covering: + +- Provider translators and format conversion +- Rate limiting, circuit breaker, and resilience +- Semantic cache, idempotency, progress tracking +- Database operations and schema (21 DB modules) +- OAuth flows and authentication +- API endpoint validation (Zod v4) +- MCP server tools and scope enforcement +- Memory and Skills systems + +--- + +## Code Style + +- **ESLint** โ€” Run `npm run lint` before committing +- **Prettier** โ€” Auto-formatted via `lint-staged` on commit (2 spaces, semicolons, double quotes, 100 char width, es5 trailing commas) +- **TypeScript** โ€” All `src/` code uses `.ts`/`.tsx`; `open-sse/` uses `.ts`/`.js`; document with TSDoc (`@param`, `@returns`, `@throws`) +- **No `eval()`** โ€” ESLint enforces `no-eval`, `no-implied-eval`, `no-new-func` +- **Zod validation** โ€” Use Zod v4 schemas for all API input validation +- **Naming**: Files = camelCase/kebab-case, components = PascalCase, constants = UPPER_SNAKE + +--- + +## Project Structure + +``` +src/ # TypeScript (.ts / .tsx) +โ”œโ”€โ”€ app/ # Next.js 16 App Router +โ”‚ โ”œโ”€โ”€ (dashboard)/ # Dashboard pages (23 sections) +โ”‚ โ”œโ”€โ”€ api/ # API routes (51 directories) +โ”‚ โ””โ”€โ”€ login/ # Auth pages (.tsx) +โ”œโ”€โ”€ domain/ # Policy engine (policyEngine, comboResolver, costRules, etc.) +โ”œโ”€โ”€ lib/ # Core business logic (.ts) +โ”‚ โ”œโ”€โ”€ a2a/ # Agent-to-Agent v0.3 protocol server +โ”‚ โ”œโ”€โ”€ acp/ # Agent Communication Protocol registry +โ”‚ โ”œโ”€โ”€ compliance/ # Compliance policy engine +โ”‚ โ”œโ”€โ”€ db/ # SQLite database layer (21 modules + 16 migrations) +โ”‚ โ”œโ”€โ”€ memory/ # Persistent conversational memory +โ”‚ โ”œโ”€โ”€ oauth/ # OAuth providers, services, and utilities +โ”‚ โ”œโ”€โ”€ skills/ # Extensible skill framework +โ”‚ โ”œโ”€โ”€ usage/ # Usage tracking and cost calculation +โ”‚ โ””โ”€โ”€ localDb.ts # Re-export layer only โ€” never add logic here +โ”œโ”€โ”€ middleware/ # Request middleware (promptInjectionGuard) +โ”œโ”€โ”€ mitm/ # MITM proxy (cert, DNS, target routing) +โ”œโ”€โ”€ shared/ +โ”‚ โ”œโ”€โ”€ components/ # React components (.tsx) +โ”‚ โ”œโ”€โ”€ constants/ # Provider definitions (60+), MCP scopes, routing strategies +โ”‚ โ”œโ”€โ”€ utils/ # Circuit breaker, sanitizer, auth helpers +โ”‚ โ””โ”€โ”€ validation/ # Zod v4 schemas +โ””โ”€โ”€ sse/ # SSE proxy pipeline + +open-sse/ # @omniroute/open-sse workspace +โ”œโ”€โ”€ executors/ # 14 provider-specific request executors +โ”œโ”€โ”€ handlers/ # 11 request handlers (chat, responses, embeddings, images, etc.) +โ”œโ”€โ”€ mcp-server/ # MCP server (25 tools, 3 transports, 10 scopes) +โ”œโ”€โ”€ services/ # 36+ services (combo, autoCombo, rateLimitManager, etc.) +โ”œโ”€โ”€ translator/ # Format translators (OpenAI โ†” Claude โ†” Gemini โ†” Responses โ†” Ollama) +โ”œโ”€โ”€ transformer/ # Responses API transformer +โ””โ”€โ”€ utils/ # 22 utility modules (stream, TLS, proxy, logging) + +electron/ # Electron desktop app (cross-platform) + +tests/ +โ”œโ”€โ”€ unit/ # Node.js test runner (122 test files) +โ”œโ”€โ”€ integration/ # Integration tests +โ”œโ”€โ”€ e2e/ # Playwright tests +โ”œโ”€โ”€ security/ # Security tests +โ”œโ”€โ”€ translator/ # Translator-specific tests +โ””โ”€โ”€ load/ # Load tests + +docs/ # Documentation +โ”œโ”€โ”€ ARCHITECTURE.md # System architecture +โ”œโ”€โ”€ API_REFERENCE.md # All endpoints +โ”œโ”€โ”€ USER_GUIDE.md # Provider setup, CLI integration +โ”œโ”€โ”€ TROUBLESHOOTING.md # Common issues +โ”œโ”€โ”€ MCP-SERVER.md # MCP server (25 tools) +โ”œโ”€โ”€ A2A-SERVER.md # A2A agent protocol +โ”œโ”€โ”€ AUTO-COMBO.md # Auto-combo engine +โ”œโ”€โ”€ CLI-TOOLS.md # CLI tools integration +โ”œโ”€โ”€ COVERAGE_PLAN.md # Test coverage improvement plan +โ”œโ”€โ”€ openapi.yaml # OpenAPI specification +โ””โ”€โ”€ adr/ # Architecture Decision Records +``` + +--- + +## Adding a New Provider + +### Step 1: Register Provider Constants + +Add to `src/shared/constants/providers.ts` โ€” Zod-validated at module load. + +### Step 2: Add Executor (if custom logic needed) + +Create executor in `open-sse/executors/your-provider.ts` extending the base executor. + +### Step 3: Add Translator (if non-OpenAI format) + +Create request/response translators in `open-sse/translator/`. + +### Step 4: Add OAuth Config (if OAuth-based) + +Add OAuth credentials in `src/lib/oauth/constants/oauth.ts` and service in `src/lib/oauth/services/`. + +### Step 5: Register Models + +Add model definitions in `open-sse/config/providerRegistry.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 +- [ ] All inputs validated with Zod schemas +- [ ] CHANGELOG updated (if user-facing change) +- [ ] Documentation updated (if applicable) + +--- + +## Releasing + +Releases are managed via the `/generate-release` workflow. When a new GitHub Release is created, the package is **automatically published to npm** via GitHub Actions. + +--- + +## Getting Help + +- **Architecture**: See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) +- **API Reference**: See [`docs/API_REFERENCE.md`](docs/API_REFERENCE.md) +- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **ADRs**: See `docs/adr/` for architectural decision records diff --git a/docs/i18n/sk/FEATURES.md b/docs/i18n/sk/FEATURES.md deleted file mode 100644 index be6153b8fb..0000000000 --- a/docs/i18n/sk/FEATURES.md +++ /dev/null @@ -1,147 +0,0 @@ -# OmniRoute โ€” Dashboard Features Gallery (Slovenฤina) - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) - -> ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../docs/FEATURES.md) - ---- - -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 (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. - -![Providers Dashboard](screenshots/01-providers.png) - ---- - -## ๐ŸŽจ Combos - -Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. - -![Combos Dashboard](screenshots/02-combos.png) - ---- - -## ๐Ÿ“Š Analytics - -Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. - -![Analytics Dashboard](screenshots/03-analytics.png) - ---- - -## ๐Ÿฅ System Health - -Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. - -![Health Dashboard](screenshots/04-health.png) - ---- - -## ๐Ÿ”ง Translator Playground - -Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). - -![Translator Playground](screenshots/05-translator.png) - ---- - -## ๐ŸŽฎ Model Playground _(v2.0.9+)_ - -Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. - ---- - -## ๐ŸŽจ Themes _(v2.0.5+)_ - -Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. - ---- - -## โš™๏ธ Settings - -Comprehensive settings panel with tabs: - -- **General** โ€” System storage, backup management (export/import database) -- **Appearance** โ€” Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls -- **Security** โ€” API endpoint protection, custom provider blocking, IP filtering, session info -- **Routing** โ€” Model aliases, background task degradation -- **Resilience** โ€” Rate limit persistence, circuit breaker tuning -- **Advanced** โ€” Configuration overrides - -![Settings Dashboard](screenshots/06-settings.png) - ---- - -## ๐Ÿ”ง CLI Tools - -One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. - -![CLI Tools Dashboard](screenshots/07-cli-tools.png) - ---- - -## ๐Ÿค– CLI Agents _(v2.0.11+)_ - -Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: - -- **Installation status** โ€” Installed / Not Found with version detection -- **Protocol badges** โ€” stdio, HTTP, etc. -- **Custom agents** โ€” Register any CLI tool via form (name, binary, version command, spawn args) -- **CLI Fingerprint Matching** โ€” Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP - ---- - -## ๐Ÿ–ผ๏ธ Media _(v2.0.3+)_ - -Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. - ---- - -## ๐Ÿ“ Request Logs - -Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. - -![Usage Logs](screenshots/08-usage.png) - ---- - -## ๐ŸŒ API Endpoint - -Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. - -![Endpoint Dashboard](screenshots/09-endpoint.png) - ---- - -## ๐Ÿ”‘ API Key Management - -Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. - ---- - -## ๐Ÿ“‹ Audit Log - -Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. - ---- - -## ๐Ÿ–ฅ๏ธ Desktop Application - -Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. - -Key features: - -- Server readiness polling (no blank screen on cold start) -- System tray with port management -- Content Security Policy -- Single-instance lock -- Auto-update on restart -- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) -- Hardened Electron build packaging โ€” symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+) - -๐Ÿ“– See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/sk/MCP-SERVER.md b/docs/i18n/sk/MCP-SERVER.md deleted file mode 100644 index 829acd30b1..0000000000 --- a/docs/i18n/sk/MCP-SERVER.md +++ /dev/null @@ -1,87 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/MCP-SERVER.md) - ---- - -# OmniRoute MCP Server Documentation - -> Model Context Protocol server with 16 intelligent tools - -## Installation - -OmniRoute MCP is built-in. Start it with: - -```bash -omniroute --mcp -``` - -Or via the open-sse transport: - -```bash -# HTTP streamable transport (port 20130) -omniroute --dev # MCP auto-starts on /mcp endpoint -``` - -## IDE Configuration - -See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup. - ---- - -## Essential Tools (8) - -| Tool | Description | -| :------------------------------ | :--------------------------------------- | -| `omniroute_get_health` | Gateway health, circuit breakers, uptime | -| `omniroute_list_combos` | All configured combos with models | -| `omniroute_get_combo_metrics` | Performance metrics for a specific combo | -| `omniroute_switch_combo` | Switch active combo by ID/name | -| `omniroute_check_quota` | Quota status per provider or all | -| `omniroute_route_request` | Send a chat completion through OmniRoute | -| `omniroute_cost_report` | Cost analytics for a time period | -| `omniroute_list_models_catalog` | Full model catalog with capabilities | - -## Advanced Tools (8) - -| Tool | Description | -| :--------------------------------- | :---------------------------------------------- | -| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | -| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | -| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | -| `omniroute_test_combo` | Live-test all models in a combo | -| `omniroute_get_provider_metrics` | Detailed metrics for one provider | -| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | -| `omniroute_explain_route` | Explain a past routing decision | -| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | - -## Authentication - -MCP tools are authenticated via API key scopes. Each tool requires specific scopes: - -| Scope | Tools | -| :------------- | :----------------------------------------------- | -| `read:health` | get_health, get_provider_metrics | -| `read:combos` | list_combos, get_combo_metrics | -| `write:combos` | switch_combo | -| `read:quota` | check_quota | -| `write:route` | route_request, simulate_route, test_combo | -| `read:usage` | cost_report, get_session_snapshot, explain_route | -| `write:config` | set_budget_guard, set_resilience_profile | -| `read:models` | list_models_catalog, best_combo_for_task | - -## Audit Logging - -Every tool call is logged to `mcp_tool_audit` with: - -- Tool name, arguments, result -- Duration (ms), success/failure -- API key hash, timestamp - -## Files - -| File | Purpose | -| :------------------------------------------- | :------------------------------------------ | -| `open-sse/mcp-server/server.ts` | MCP server creation + 16 tool registrations | -| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport | -| `open-sse/mcp-server/auth.ts` | API key + scope validation | -| `open-sse/mcp-server/audit.ts` | Tool call audit logging | -| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers | diff --git a/docs/i18n/sk/README.md b/docs/i18n/sk/README.md index 3719e992ec..145e2acc48 100644 --- a/docs/i18n/sk/README.md +++ b/docs/i18n/sk/README.md @@ -1,12 +1,12 @@ # ๐Ÿš€ OmniRoute โ€” The Free AI Gateway (Slovenฤina) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/README.md) --- ### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback. -_Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._ +_Your universal API proxy โ€” one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._ **Chat Completions โ€ข Embeddings โ€ข Image Generation โ€ข Video โ€ข Music โ€ข Audio โ€ข Reranking โ€ข **Web Search** โ€ข MCP Server โ€ข A2A Protocol โ€ข 100% TypeScript** @@ -46,15 +46,17 @@ _Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now wi > - `APP_LOG_FILE_PATH` > - `APP_LOG_MAX_FILE_SIZE` > - `APP_LOG_RETENTION_DAYS` +> - `APP_LOG_MAX_FILES` > - `APP_LOG_LEVEL` > - `APP_LOG_FORMAT` > - `CALL_LOG_RETENTION_DAYS` +> - `CALL_LOG_MAX_ENTRIES` > > For release details and upgrade notes, see the [CHANGELOG](CHANGELOG.md). --- -## ๐Ÿ†• What's New in v3.0.0 +## ๐Ÿ†• What's New > **Upgrading from v2.9.5?** โ€” See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes. @@ -274,7 +276,7 @@ Developers pay $20โ€“200/month for Claude Pro, Codex Pro, or GitHub Copilot. Eve - **Smart 4-Tier Fallback** โ€” If subscription quota runs out, automatically redirects to API Key โ†’ Cheap โ†’ Free with zero manual intervention - **Real-Time Quota Tracking** โ€” Shows token consumption in real-time with reset countdown (5h, daily, weekly) - **Multi-Account Support** โ€” Multiple accounts per provider with auto round-robin โ€” when one runs out, switches to the next -- **Custom Combos** โ€” Customizable fallback chains with 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Custom Combos** โ€” Customizable fallback chains with 9 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random) - **Codex Business Quotas** โ€” Business/Team workspace quota monitoring directly in the dashboard @@ -286,7 +288,7 @@ OpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If **How OmniRoute solves it:** -- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 67+ providers +- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 60+ providers - **Format Translation** โ€” Automatic and transparent: OpenAI โ†” Claude โ†” Gemini โ†” Responses API - **Response Sanitization** โ€” Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+ - **Role Normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI providers; `system` โ†’ `user` for GLM/ERNIE @@ -372,7 +374,7 @@ Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code.. - **CLI Tools Dashboard** โ€” Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline - **GitHub Copilot Config Generator** โ€” Generates `chatLanguageModels.json` for VS Code with bulk model selection - **Onboarding Wizard** โ€” Guided 4-step setup for first-time users -- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 67+ providers +- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 60+ providers @@ -419,7 +421,7 @@ When a call fails, the dev doesn't know if it was a rate limit, expired token, w - **SQLite Proxy Logs** โ€” Persistent logs that survive server restarts - **Translator Playground** โ€” 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time) - **Request Telemetry** โ€” p50/p95/p99 latency + X-Request-Id tracing -- **File-Based Logging with Rotation** โ€” Console interceptor captures everything to JSON log with size-based rotation +- **File-Based Logging with Rotation** โ€” App logs rotate by size, retention days, and archive count; call log artifacts rotate by retention days and file count - **System Info Report** โ€” `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage. @@ -514,7 +516,7 @@ Developers who want all responses in a specific language, with a specific tone, - **System Prompt Injection** โ€” Global prompt applied to all requests - **Thinking Budget Validation** โ€” Reasoning token allocation control per request (passthrough, auto, custom, adaptive) -- **6 Routing Strategies** โ€” Global strategies that determine how requests are distributed +- **9 Routing Strategies** โ€” Global strategies that determine how requests are distributed - **Wildcard Router** โ€” `provider/*` patterns route dynamically to any provider - **Combo Enable/Disable Toggle** โ€” Toggle combos directly from the dashboard - **Provider Toggle** โ€” Enable/disable all connections for a provider with one click @@ -581,7 +583,7 @@ Different clients should have least-privilege access to tool categories. **How OmniRoute solves it:** -- 9 granular MCP scopes for controlled tool access +- 10 granular MCP scopes for controlled tool access - Scope enforcement and visibility in MCP management UI - Safe default posture for operational tooling @@ -1325,19 +1327,19 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. ### ๐Ÿค– Agent & Protocol Operations (v2.0) -| Feature | What It Does | -| ------------------------------------- | -------------------------------------------------------------------------------------------------- | -| ๐Ÿ”ง **MCP Server (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) | -| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | -| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | -| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | -| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | -| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | -| ๐Ÿ” **MCP Scope Enforcement** | 9 granular scope permissions for controlled tool access | -| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | -| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | -| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | -| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | +| Feature | What It Does | +| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| ๐Ÿ”ง **MCP Server (25 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools | +| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | +| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | +| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | +| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | +| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | +| ๐Ÿ” **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access | +| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | +| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | +| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | +| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | ### ๐Ÿง  Routing & Intelligence @@ -1348,7 +1350,7 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. | ๐Ÿ”„ **Format Translation** | OpenAI โ†” Claude โ†” Gemini โ†” Responses with schema-safe conversions | | ๐Ÿ‘ฅ **Multi-Account Support** | Multiple accounts per provider with intelligent selection | | ๐Ÿ”„ **Auto Token Refresh** | OAuth tokens refresh automatically with retry | -| ๐ŸŽจ **Custom Combos** | 6 balancing strategies + fallback chain control | +| ๐ŸŽจ **Custom Combos** | 9 balancing strategies + fallback chain control | | ๐ŸŒ **Wildcard Router** | `provider/*` dynamic routing | | ๐Ÿง  **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits | | ๐Ÿ”€ **Model Aliases** | Built-in + custom model aliasing and migration safety | @@ -1949,6 +1951,7 @@ opencode - Request artifacts are written to `DATA_DIR/call_logs/` as one JSON file per request - Enable pipeline capture from Dashboard โ†’ Logs โ†’ Request Logs if you need detailed per-stage payloads - Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log` +- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed **Connection test shows "Invalid" for OpenAI-compatible providers** diff --git a/docs/i18n/sk/RELEASE_CHECKLIST.md b/docs/i18n/sk/RELEASE_CHECKLIST.md deleted file mode 100644 index 903e812c3f..0000000000 --- a/docs/i18n/sk/RELEASE_CHECKLIST.md +++ /dev/null @@ -1,37 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/RELEASE_CHECKLIST.md) - ---- - -# Release Checklist - -Use this checklist before tagging or publishing a new OmniRoute release. - -## Version and Changelog - -1. Bump `package.json` version (`x.y.z`) in the release branch. -2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: - - `## [x.y.z] โ€” YYYY-MM-DD` -3. Keep `## [Unreleased]` as the first changelog section for upcoming work. -4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. - -## API Docs - -1. Update `docs/openapi.yaml`: - - `info.version` must equal `package.json` version. -2. Validate endpoint examples if API contracts changed. - -## Runtime Docs - -1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. -2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. -3. Update localized docs if source docs changed significantly. - -## Automated Check - -Run the sync guard locally before opening PR: - -```bash -npm run check:docs-sync -``` - -CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/sk/SECURITY.md b/docs/i18n/sk/SECURITY.md new file mode 100644 index 0000000000..96a65372c8 --- /dev/null +++ b/docs/i18n/sk/SECURITY.md @@ -0,0 +1,179 @@ +# Security Policy (Slovenฤina) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../SECURITY.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/SECURITY.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/SECURITY.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/SECURITY.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/SECURITY.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/SECURITY.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/SECURITY.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/SECURITY.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/SECURITY.md) + +--- + +## 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 | +| ------- | -------------- | +| 3.4.x | โœ… Active | +| 3.0.x | โœ… Security | +| < 3.0.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 | +| **MCP Scopes** | 10 granular scopes for MCP tool access control | + +### ๐Ÿ›ก๏ธ 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:::` +- 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** | Allowlist/blocklist IP ranges in dashboard | +| **Rate Limiting** | Per-provider rate limits with automatic backoff | +| **Anti-Thundering Herd** | Mutex + per-connection locking prevents cascading 502s | +| **TLS Fingerprint** | Browser-like TLS fingerprint spoofing to reduce bot detection | +| **CLI Fingerprint** | Per-provider header/body ordering to match native CLI signatures | + +### ๐Ÿ”Œ Resilience & Availability + +| 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 `CALL_LOG_RETENTION_DAYS` | +| **No-Log Opt-out** | Per API key `noLog` flag disables request logging | +| **Audit Log** | Administrative actions tracked in `audit_log` table | +| **MCP Audit** | SQLite-backed audit logging for all MCP tool calls | +| **Zod Validation** | All API inputs validated with Zod v4 schemas at module load | + +--- + +## 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 +- Provider constants validated at module load via Zod (`src/shared/validation/providerSchema.ts`) diff --git a/docs/i18n/sk/TROUBLESHOOTING.md b/docs/i18n/sk/TROUBLESHOOTING.md deleted file mode 100644 index 63c148000a..0000000000 --- a/docs/i18n/sk/TROUBLESHOOTING.md +++ /dev/null @@ -1,258 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/TROUBLESHOOTING.md) - ---- - -# Troubleshooting - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/TROUBLESHOOTING.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/TROUBLESHOOTING.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/TROUBLESHOOTING.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/TROUBLESHOOTING.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/TROUBLESHOOTING.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/TROUBLESHOOTING.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/TROUBLESHOOTING.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/TROUBLESHOOTING.md) - -Common problems and solutions for OmniRoute. - ---- - -## Quick Fixes - -| Problem | Solution | -| ----------------------------- | ------------------------------------------------------------------ | -| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | -| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | -| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | -| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | -| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | - ---- - -## Provider Issues - -### "Language model did not provide messages" - -**Cause:** Provider quota exhausted. - -**Fix:** - -1. 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, Qoder) 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}/storage.sqlite` (providers, combos, aliases, keys, settings) -- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` -- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) - ---- - -## Circuit Breaker Issues - -### Provider stuck in OPEN state - -When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. - -**Fix:** - -1. 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 -- **SDK returns raw string instead of object** โ€” Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures -- **GLM/ERNIE rejects `system` role** โ€” Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models -- **`developer` role not recognized** โ€” Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers -- **`json_schema` not working with Gemini** โ€” Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` - ---- - -## Resilience Settings - -### Auto rate-limit not triggering - -- 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. - ---- - -## Optional RAG / LLM failure taxonomy (16 problems) - -Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. - -In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. - -If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: - -- retrieval drift and broken context boundaries -- empty or stale indexes and vector stores -- embedding versus semantic mismatch -- prompt assembly and context window issues -- logic collapse and overconfident answers -- long chain and agent coordination failures -- multi agent memory and role drift -- deployment and bootstrap ordering problems - -The idea is simple: - -1. When you investigate a bad response, capture: - - user task and request - - route or provider combo in OmniRoute - - any RAG context used downstream (retrieved documents, tool calls, etc) -2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` โ€ฆ `No.16`). -3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. -4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. - -Full text and concrete recipes live here (MIT license, text only): - -[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) - -You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. - ---- - -## Still Stuck? - -- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details -- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints -- **Health Dashboard**: Check **Dashboard โ†’ Health** for real-time system status -- **Translator**: Use **Dashboard โ†’ Translator** to debug format issues diff --git a/docs/i18n/sk/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/sk/VM_DEPLOYMENT_GUIDE.md deleted file mode 100644 index fd2f380f12..0000000000 --- a/docs/i18n/sk/VM_DEPLOYMENT_GUIDE.md +++ /dev/null @@ -1,401 +0,0 @@ -# OmniRoute โ€” Sprievodca nasadenรญm na VM s Cloudflare - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](../pt-BR/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](../es/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](../fr/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](../it/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](../ru/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](../zh-CN/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](../de/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](../in/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](../th/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](../uk-UA/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](../ar/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](../ja/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](../vi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](../bg/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](../da/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](../fi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](../he/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](../hu/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](../id/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](../ko/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](../ms/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](../nl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](../no/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](../pt/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](../ro/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](../pl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](../sk/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](../sv/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](../phi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](../cs/VM_DEPLOYMENT_GUIDE.md) - -Kompletnรฝ sprievodca inลกtalรกciou a konfigurรกciou OmniRoute na VM (VPS) s domรฉnou spravovanou cez Cloudflare. - ---- - -## Predpoklady - -| Poloลพka | Minimรกlne | Odporรบฤanรฉ | -| ---------- | -------------------------- | ---------------- | -| **CPU** | 1 vCPU | 2 vCPU | -| **RAM** | 1 GB | 2 GB | -| **Disk** | 10 GB SSD | 25 GB SSD | -| **OS** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS | -| **Domรฉna** | Registrovanรฝ na Cloudflare | โ€” | -| **Docker** | Docker Engine 24+ | Docker 27+ | - -**Testovanรญ poskytovatelia**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. - ---- - -## 1. Nakonfigurujte VM - -### 1.1 Vytvorte inลกtanciu - -U preferovanรฉho poskytovateฤพa VPS: - -- Vyberte Ubuntu 24.04 LTS -- Vyberte minimรกlny plรกn (1 vCPU / 1 GB RAM) -- Nastavte silnรฉ heslo root alebo nakonfigurujte kฤพรบฤ SSH - โ€“ Vลกimnite si **verejnรบ IP** (napr. `203.0.113.10`) - -### 1.2 Pripojenie cez SSH - -```bash -ssh root@203.0.113.10 -``` - -### 1.3 Aktualizujte systรฉm - -```bash -apt update && apt upgrade -y -``` - -### 1.4 Nainลกtalujte Docker - -```bash -# Install dependencies -apt install -y ca-certificates curl gnupg - -# Add official Docker repository -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 Nainลกtalujte nginx - -```bash -apt install -y nginx -``` - -### 1.6 Konfigurรกcia brรกny 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 -``` - -> **Tip**: Pre maximรกlnu bezpeฤnosลฅ obmedzte porty 80 a 443 iba na IP adresy Cloudflare. Pozrite si ฤasลฅ [Advanced Security](#advanced-security). - ---- - -## 2. Nainลกtalujte OmniRoute - -### 2.1 Vytvorte konfiguraฤnรฝ adresรกr - -```bash -mkdir -p /opt/omniroute -``` - -### 2.2 Vytvorenie sรบboru premennรฝch prostredia - -```bash -cat > /opt/omniroute/.env << โ€˜EOFโ€™ -# === Security === -JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY -INITIAL_PASSWORD=YourSecurePassword123! -API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY -STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY -STORAGE_ENCRYPTION_KEY_VERSION=v1 -MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT - -# === 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 (change to your domain) === -BASE_URL=https://llms.seudominio.com -NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com - -# === Cloud Sync (optional) === -# CLOUD_URL=https://cloud.omniroute.online -# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online -EOF -``` - -> โš ๏ธ **Dร”LEลฝITร‰**: Vytvorte jedineฤnรฉ tajnรฉ kฤพรบฤe! Pre kaลพdรฝ kฤพรบฤ pouลพite `openssl rand -hex 32`. - -### 2.3 Spustite kontajner - -```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 Overte, ฤi beลพรญ - -```bash -docker ps | grep omniroute -docker logs omniroute --tail 20 -``` - -Malo by sa zobraziลฅ: `[DB] SQLite database ready` a `listening on port 20128`. - ---- - -## 3. Konfigurรกcia nginx (reverznรฝ proxy) - -### 3.1 Generovanie SSL certifikรกtu (Cloudflare Origin) - -Na hlavnom paneli Cloudflare: - -1. Prejdite na **SSL/TLS โ†’ Pรดvodnรฝ server** -2. Kliknite na **Vytvoriลฅ certifikรกt** -3. Ponechajte predvolenรฉ hodnoty (15 rokov, \*.yourdomain.com) -4. Skopรญrujte **Certifikรกt o pรดvode** a **Sรบkromnรฝ kฤพรบฤ** - -```bash -mkdir -p /etc/nginx/ssl - -# Paste the certificate -nano /etc/nginx/ssl/origin.crt - -# Paste the private key -nano /etc/nginx/ssl/origin.key - -chmod 600 /etc/nginx/ssl/origin.key -``` - -### 3.2 Konfigurรกcia Nginx - -```bash -cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ -# Default server โ€” blocks direct access via 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.yourdomain.com; # Change to your domain - - 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.yourdomain.com; - return 301 https://$server_name$request_uri; -} -NGINX -``` - -### 3.3 Povoliลฅ a otestovaลฅ - -```bash -# Remove default configuration -rm -f /etc/nginx/sites-enabled/default - -# Enable OmniRoute -ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute - -# Test and reload -nginx -t && systemctl reload nginx -``` - ---- - -## 4. Nakonfigurujte Cloudflare DNS - -### 4.1 Pridaลฅ DNS zรกznam - -Na hlavnom paneli Cloudflare โ†’ DNS: - -| Typ | Meno | Obsah | Proxy | -| --- | ------ | ---------------------- | ------------------ | -| A | `llms` | `203.0.113.10` (IP VM) | โœ… Sprostredkovanรฝ | - -### 4.2 Konfigurรกcia SSL - -V ฤasti **SSL/TLS โ†’ Prehฤพad**: - -- Reลพim: **Plnรฝ (prรญsny)** - -V ฤasti **SSL/TLS โ†’ Edge Certificates**: - -- Vลพdy pouลพรญvaลฅ HTTPS: โœ… Zap -- Minimรกlna verzia TLS: TLS 1.2 -- Automatickรฉ prepisy HTTPS: โœ… Zap - -### 4.3 Testovanie - -```bash -curl -sI https://llms.seudominio.com/health -# Should return HTTP/2 200 -``` - ---- - -## 5. Prevรกdzka a รบdrลพba - -### Inovujte na novรบ verziu - -```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 -``` - -### Zobraziลฅ dennรญky - -```bash -docker logs -f omniroute # Real-time stream -docker logs omniroute --tail 50 # Last 50 lines -``` - -### Manuรกlne zรกlohovanie databรกzy - -```bash -# Copy data from the volume to the host -docker cp omniroute:/app/data ./backup-$(date +%F) - -# Or compress the entire volume -docker run --rm -v omniroute-data:/data -v $(pwd):/backup \ - alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data -``` - -### Obnoviลฅ zo zรกlohy - -```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. Pokroฤilรฉ zabezpeฤenie - -### Obmedzte nginx na IP adresy Cloudflare - -```bash -cat > /etc/nginx/cloudflare-ips.conf << โ€˜CFโ€™ -# Cloudflare IPv4 ranges โ€” update periodically -# 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 -``` - -Pridajte nasledujรบce do `nginx.conf` v rรกmci bloku `http {}`: - -```nginx -include /etc/nginx/cloudflare-ips.conf; -``` - -### Nainลกtalujte fail2ban - -```bash -apt install -y fail2ban -systemctl enable fail2ban -systemctl start fail2ban - -# Check status -fail2ban-client status sshd -``` - -### Blokovaลฅ priamy prรญstup k portu Docker - -```bash -# Prevent direct external access to port 20128 -iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP -iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT - -# Persist the rules -apt install -y iptables-persistent -netfilter-persistent save -``` - ---- - -## 7. Nasadenie pre pracovnรญkov Cloudflare (voliteฤพnรฉ) - -Pre vzdialenรฝ prรญstup cez Cloudflare Workers (bez priameho odhalenia VM): - -```bash -# In the local repository -cd omnirouteCloud -npm install -npx wrangler login -npx wrangler deploy -``` - -รšplnรบ dokumentรกciu nรกjdete na strรกnke [omnirouteCloud/README.md](../omnirouteCloud/README.md). - ---- - -## Sรบhrn portov - -| Prรญstav | Sluลพba | Prรญstup | -| ------- | ----------- | ------------------------- | -| 22 | SSH | Verejnรฉ (s fail2ban) | -| 80 | nginx HTTP | Presmerovanie โ†’ HTTPS | -| 443 | nginx HTTPS | Cez Cloudflare Proxy | -| 20128 | OmniRoute | Iba Localhost (cez nginx) | diff --git a/docs/i18n/sk/docs/A2A-SERVER.md b/docs/i18n/sk/docs/A2A-SERVER.md new file mode 100644 index 0000000000..5e14cc79fc --- /dev/null +++ b/docs/i18n/sk/docs/A2A-SERVER.md @@ -0,0 +1,200 @@ +# OmniRoute A2A Server Documentation (Slovenฤina) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/A2A-SERVER.md) + +--- + +> Agent-to-Agent Protocol v0.3 โ€” OmniRoute as an intelligent routing agent + +## Agent Discovery + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements. + +--- + +## Authentication + +All `/a2a` requests require an API key via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server, authentication is bypassed. + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Sends a message to a skill and waits for the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a hello world in Python"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "uuid", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "..." }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}} + +: heartbeat 2026-03-03T17:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Available Skills + +| Skill | Description | +| :----------------- | :------------------------------------------------------------------------------------------------------------------------------ | +| `smart-routing` | Routes prompts through OmniRoute's intelligent pipeline. Returns response with routing explanation, cost, and resilience trace. | +| `quota-management` | Answers natural-language queries about provider quotas, suggests free combos, and provides quota rankings. | + +--- + +## Task Lifecycle + +``` +submitted โ†’ working โ†’ completed + โ†’ failed + โ†’ cancelled +``` + +- Tasks expire after 5 minutes (configurable) +- Terminal states: `completed`, `failed`, `cancelled` +- Event log tracks every state transition + +--- + +## Error Codes + +| Code | Meaning | +| :----- | :----------------------------- | +| -32700 | Parse error (invalid JSON) | +| -32600 | Invalid request / Unauthorized | +| -32601 | Method or skill not found | +| -32602 | Invalid params | +| -32603 | Internal error | + +--- + +## Integration Examples + +### Python (requests) + +```python +import requests + +resp = requests.post("http://localhost:20128/a2a", json={ + "jsonrpc": "2.0", "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Hello"}] + } +}, headers={"Authorization": "Bearer YOUR_KEY"}) + +result = resp.json()["result"] +print(result["artifacts"][0]["content"]) +print(result["metadata"]["routing_explanation"]) +``` + +### TypeScript (fetch) + +```typescript +const resp = await fetch("http://localhost:20128/a2a", { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: "Bearer YOUR_KEY", + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "1", + method: "message/send", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Hello" }], + }, + }), +}); +const { result } = await resp.json(); +console.log(result.metadata.routing_explanation); +``` diff --git a/docs/i18n/sk/docs/API_REFERENCE.md b/docs/i18n/sk/docs/API_REFERENCE.md new file mode 100644 index 0000000000..436b61979f --- /dev/null +++ b/docs/i18n/sk/docs/API_REFERENCE.md @@ -0,0 +1,465 @@ +# API Reference (Slovenฤina) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/API_REFERENCE.md) + +--- + +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 | +| `X-Session-Id` | Request | Sticky session key for external session affinity | +| `x_session_id` | Request | Underscore variant also accepted (direct HTTP) | +| `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 | +| `X-OmniRoute-Session-Id` | Response | Effective session ID used by OmniRoute | + +> Nginx note: if you rely on underscore headers (for example `x_session_id`), enable `underscores_in_headers 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/stats + +# Clear all caches +DELETE /api/cache/stats +``` + +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/PATCH | 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 + provider summary (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`) | +| `/api/cache/stats` | 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 | + +### Tunnels + +| Endpoint | Method | Description | +| -------------------------- | ------ | ----------------------------------------------------------------------- | +| `/api/tunnels/cloudflared` | GET | Read Cloudflare Quick Tunnel install/runtime status for the dashboard | +| `/api/tunnels/cloudflared` | POST | Enable or disable the Cloudflare Quick Tunnel (`action=enable/disable`) | + +### 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`. + +### ACP Agents + +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | + +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). + +### Resilience & Rate Limits + +| Endpoint | Method | Description | +| ----------------------- | --------- | ------------------------------- | +| `/api/resilience` | GET/PATCH | 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` diff --git a/docs/i18n/sk/docs/ARCHITECTURE.md b/docs/i18n/sk/docs/ARCHITECTURE.md new file mode 100644 index 0000000000..42ccb53d8e --- /dev/null +++ b/docs/i18n/sk/docs/ARCHITECTURE.md @@ -0,0 +1,814 @@ +# OmniRoute Architecture (Slovenฤina) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/ARCHITECTURE.md) + +--- + +_Last updated: 2026-03-28_ + +## 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 (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developerโ†’system, systemโ†’user) for cross-provider compatibility +- Structured output conversion (json_schema โ†’ Gemini responseSchema) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) +- Global system prompt injection +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout โ†’ budget โ†’ fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) + +Primary runtime model: + +- Next.js 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.) + +## Dashboard Surface (Current) + +Main pages under `src/app/(dashboard)/dashboard/`: + +- `/dashboard` โ€” quick start + provider overview +- `/dashboard/endpoint` โ€” endpoint proxy + MCP + A2A + API endpoint tabs +- `/dashboard/providers` โ€” provider connections and credentials +- `/dashboard/combos` โ€” combo strategies, templates, model routing rules +- `/dashboard/costs` โ€” cost aggregation and pricing visibility +- `/dashboard/analytics` โ€” usage analytics and evaluations +- `/dashboard/limits` โ€” quota/rate controls +- `/dashboard/cli-tools` โ€” CLI onboarding, runtime detection, config generation +- `/dashboard/agents` โ€” detected ACP agents + custom agent registration +- `/dashboard/media` โ€” image/video/music playground +- `/dashboard/search-tools` โ€” search provider testing and history +- `/dashboard/health` โ€” uptime, circuit breakers, rate limits +- `/dashboard/logs` โ€” request/proxy/audit/console logs +- `/dashboard/settings` โ€” system settings tabs (general, routing, combo defaults, etc.) +- `/dashboard/api-manager` โ€” API key lifecycle and model permissions + +## 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[(storage.sqlite)] + UDB[(usage tables + log artifacts)] + end + + subgraph Upstreams[Upstream Providers] + P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/Qoder/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/route.ts` (GET) +- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- OAuth: `src/app/api/oauth/*` +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` +- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI tooling helpers: `src/app/api/cli-tools/*` +- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) +- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) โ€” provider profiles, circuit breaker, rate limit state +- Resilience reset: `src/app/api/resilience/reset` (POST) โ€” reset breakers + cooldowns +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) +- Telemetry: `src/app/api/telemetry/summary` (GET) +- Budget: `src/app/api/usage/budget` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Policies: `src/app/api/policies` (GET/POST) + +## 2) SSE + 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` +- Response sanitization: `open-sse/handlers/responseSanitizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.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`, `qoder.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 (SQLite): + +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** + +Usage persistence: + +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present + +Domain State DB (SQLite): + +- `src/lib/db/domainState.ts` โ€” CRUD operations 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`, `src/shared/services/modelSyncScheduler.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Periodic task: `src/shared/services/modelSyncScheduler.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. Combo routing adds one extra guard: provider-scoped 400s such as upstream content-block and role-validation failures are treated as model-local failures so later combo targets can still run. + +## 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: + +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` + +## Deployment Topology + +```mermaid +flowchart LR + 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[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] + end + + subgraph External[External Services] + Providers[AI Providers] + SyncCloud[Cloud Sync Service] + end + + CLI --> Next + Browser --> Next + Next --> Core + Next --> MainDB + Core --> MainDB + Core --> UsageDB + Core --> Providers + Next --> SyncCloud +``` + +## Module Mapping (Decision-Critical) + +### Route and API Modules + +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle +- `src/app/api/models/alias`: alias management +- `src/app/api/combos*`: fallback combo management +- `src/app/api/pricing`: pricing overrides for cost calculation +- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers +- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) +- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) +- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) +- `src/app/api/sessions`: active session listing (GET) +- `src/app/api/rate-limits`: per-account rate limit status (GET) + +### Routing and Execution Core + +- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior + +### Translation Registry and Format Converters + +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` +- Format constants: `open-sse/translator/formats.ts` + +### Persistence + +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables + +## Provider Executor Coverage (Strategy Pattern) + +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. + +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, Qoder, 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 | +| Qoder | openai | OAuth (Basic) | โœ… | โœ… | โœ… | โš ๏ธ Per request | +| OpenRouter | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| GLM/Kimi/MiniMax | claude | API Key | โœ… | โœ… | โŒ | โŒ | +| DeepSeek | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Groq | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| xAI (Grok) | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Mistral | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Perplexity | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Together AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Fireworks AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Cerebras | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Cohere | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| NVIDIA NIM | openai | API Key | โœ… | โœ… | โŒ | โŒ | + +## Format Translation Coverage + +Detected source formats include: + +- `openai` +- `openai-responses` +- `claude` +- `gemini` + +Target formats include: + +- OpenAI chat/Responses +- Claude +- Gemini/Gemini-CLI/Antigravity envelope +- Kiro +- Cursor + +Translations use **OpenAI as the hub format** โ€” all conversions go through OpenAI as intermediate: + +``` +Source Format โ†’ OpenAI (hub) โ†’ Target Format +``` + +Translations are selected dynamically based on source payload shape and provider target format. + +Additional processing layers in the translation pipeline: + +- **Response sanitization** โ€” Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI targets; merges `system` โ†’ `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** โ€” Parses `...` blocks from content into `reasoning_content` field +- **Structured output** โ€” Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` + +## Supported API Endpoints + +| 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` | Provider Models | Provider model metadata backing custom and managed available models | + +## 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 `/logs//` 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 + +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON โ†’ SQLite migration compatibility path + +## Observability and Operational Signals + +Runtime visibility sources: + +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- four-stage detailed payload captures in SQLite (`request_detail_logs`) when `settings.detailed_logs_enabled=true` +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption + +Detailed request payload capture stores up to four JSON payload stages per routed call: + +- raw request received from the client +- translated request actually sent upstream +- provider response reconstructed as JSON; streamed responses are compacted to the final summary plus stream metadata +- final client response returned by OmniRoute; streamed responses are stored in the same compact summary form + +## Security-Sensitive Boundaries + +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics + +## Environment and Runtime Matrix + +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` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). + +## Operational Verification Checklist + +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: +- `GET /api/settings` +- `GET /api/v1/models` +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/sk/docs/AUTO-COMBO.md b/docs/i18n/sk/docs/AUTO-COMBO.md new file mode 100644 index 0000000000..cd714695b8 --- /dev/null +++ b/docs/i18n/sk/docs/AUTO-COMBO.md @@ -0,0 +1,67 @@ +# OmniRoute Auto-Combo Engine (Slovenฤina) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/AUTO-COMBO.md) + +--- + +> Self-managing model chains with adaptive scoring + +## How It Works + +The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**: + +| Factor | Weight | Description | +| :--------- | :----- | :---------------------------------------------- | +| Quota | 0.20 | Remaining capacity [0..1] | +| Health | 0.25 | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 | +| CostInv | 0.20 | Inverse cost (cheaper = higher score) | +| LatencyInv | 0.15 | Inverse p95 latency (faster = higher) | +| TaskFit | 0.10 | Model ร— task type fitness score | +| Stability | 0.10 | Low variance in latency/errors | + +## Mode Packs + +| Pack | Focus | Key Weight | +| :---------------------- | :----------- | :--------------- | +| ๐Ÿš€ **Ship Fast** | Speed | latencyInv: 0.35 | +| ๐Ÿ’ฐ **Cost Saver** | Economy | costInv: 0.40 | +| ๐ŸŽฏ **Quality First** | Best model | taskFit: 0.40 | +| ๐Ÿ“ก **Offline Friendly** | Availability | quota: 0.40 | + +## Self-Healing + +- **Temporary exclusion**: Score < 0.2 โ†’ excluded for 5 min (progressive backoff, max 30 min) +- **Circuit breaker awareness**: OPEN โ†’ auto-excluded; HALF_OPEN โ†’ probe requests +- **Incident mode**: >50% OPEN โ†’ disable exploration, maximize stability +- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout + +## Bandit Exploration + +5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode. + +## API + +```bash +# Create auto-combo +curl -X POST http://localhost:20128/api/combos/auto \ + -H "Content-Type: application/json" \ + -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}' + +# List auto-combos +curl http://localhost:20128/api/combos/auto +``` + +## Task Fitness + +30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` โ†’ high coding score). + +## Files + +| File | Purpose | +| :------------------------------------------- | :------------------------------------ | +| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization | +| `open-sse/services/autoCombo/taskFitness.ts` | Model ร— task fitness lookup | +| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap | +| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode | +| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles | +| `src/app/api/combos/auto/route.ts` | REST API | diff --git a/docs/i18n/sk/docs/CLI-TOOLS.md b/docs/i18n/sk/docs/CLI-TOOLS.md new file mode 100644 index 0000000000..6d1a617aa5 --- /dev/null +++ b/docs/i18n/sk/docs/CLI-TOOLS.md @@ -0,0 +1,348 @@ +# CLI Tools Setup Guide โ€” OmniRoute (Slovenฤina) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CLI-TOOLS.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CLI-TOOLS.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CLI-TOOLS.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CLI-TOOLS.md) + +--- + +This guide explains how to install and configure all supported AI coding CLI tools +to use **OmniRoute** as the unified backend, giving you centralized key management, +cost tracking, model switching, and request logging across every tool. + +--- + +## How It Works + +``` +Claude / Codex / OpenCode / Cline / KiloCode / Continue / Kiro / Cursor / Copilot + โ”‚ + โ–ผ (all point to OmniRoute) + http://YOUR_SERVER:20128/v1 + โ”‚ + โ–ผ (OmniRoute routes to the right provider) + Anthropic / OpenAI / Gemini / DeepSeek / Groq / Mistral / ... +``` + +**Benefits:** + +- One API key to manage all tools +- Cost tracking across all CLIs in the dashboard +- Model switching without reconfiguring every tool +- Works locally and on remote servers (VPS) + +--- + +## Supported Tools (Dashboard Source of Truth) + +The dashboard cards in `/dashboard/cli-tools` are generated from `src/shared/constants/cliTools.ts`. +Current list (v3.0.0-rc.16): + +| Tool | ID | Command | Setup Mode | Install Method | +| ------------------ | ------------- | ---------- | ---------- | -------------- | +| **Claude Code** | `claude` | `claude` | env | npm | +| **OpenAI Codex** | `codex` | `codex` | custom | npm | +| **Factory Droid** | `droid` | `droid` | custom | bundled/CLI | +| **OpenClaw** | `openclaw` | `openclaw` | custom | bundled/CLI | +| **Cursor** | `cursor` | app | guide | desktop app | +| **Cline** | `cline` | `cline` | custom | npm | +| **Kilo Code** | `kilo` | `kilocode` | custom | npm | +| **Continue** | `continue` | extension | guide | VS Code | +| **Antigravity** | `antigravity` | internal | mitm | OmniRoute | +| **GitHub Copilot** | `copilot` | extension | custom | VS Code | +| **OpenCode** | `opencode` | `opencode` | guide | npm | +| **Kiro AI** | `kiro` | app/cli | mitm | desktop/CLI | + +### CLI fingerprint sync (Agents + Settings) + +`/dashboard/agents` and `Settings > CLI Fingerprint` use `src/shared/constants/cliCompatProviders.ts`. +This keeps provider IDs aligned with CLI cards and legacy IDs. + +| CLI ID | Fingerprint Provider ID | +| ---------------------------------------------------------------------------------------------------- | ----------------------- | +| `kilo` | `kilocode` | +| `copilot` | `github` | +| `claude` / `codex` / `antigravity` / `kiro` / `cursor` / `cline` / `opencode` / `droid` / `openclaw` | same ID | + +Legacy IDs still accepted for compatibility: `copilot`, `kimi-coding`, `qwen`. + +--- + +## Step 1 โ€” Get an OmniRoute API Key + +1. Open the OmniRoute dashboard โ†’ **API Manager** (`/dashboard/api-manager`) +2. Click **Create API Key** +3. Give it a name (e.g. `cli-tools`) and select all permissions +4. Copy the key โ€” you'll need it for every CLI below + +> Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` + +--- + +## Step 2 โ€” Install CLI Tools + +All npm-based tools require Node.js 18+: + +```bash +# Claude Code (Anthropic) +npm install -g @anthropic-ai/claude-code + +# OpenAI Codex +npm install -g @openai/codex + +# OpenCode +npm install -g opencode-ai + +# Cline +npm install -g cline + +# KiloCode +npm install -g kilocode + +# Kiro CLI (Amazon โ€” requires curl + unzip) +apt-get install -y unzip # on Debian/Ubuntu +curl -fsSL https://cli.kiro.dev/install | bash +export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc +``` + +**Verify:** + +```bash +claude --version # 2.x.x +codex --version # 0.x.x +opencode --version # x.x.x +cline --version # 2.x.x +kilocode --version # x.x.x (or: kilo --version) +kiro-cli --version # 1.x.x +``` + +--- + +## Step 3 โ€” Set Global Environment Variables + +Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`: + +```bash +# OmniRoute Universal Endpoint +export OPENAI_BASE_URL="http://localhost:20128/v1" +export OPENAI_API_KEY="sk-your-omniroute-key" +export ANTHROPIC_BASE_URL="http://localhost:20128/v1" +export ANTHROPIC_API_KEY="sk-your-omniroute-key" +export GEMINI_BASE_URL="http://localhost:20128/v1" +export GEMINI_API_KEY="sk-your-omniroute-key" +``` + +> For a **remote server** replace `localhost:20128` with the server IP or domain, +> e.g. `http://192.168.0.15:20128`. + +--- + +## Step 4 โ€” Configure Each Tool + +### Claude Code + +```bash +# Via CLI: +claude config set --global api-base-url http://localhost:20128/v1 + +# Or create ~/.claude/settings.json: +mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF +{ + "apiBaseUrl": "http://localhost:20128/v1", + "apiKey": "sk-your-omniroute-key" +} +EOF +``` + +**Test:** `claude "say hello"` + +--- + +### OpenAI Codex + +```bash +mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF +model: auto +apiKey: sk-your-omniroute-key +apiBaseUrl: http://localhost:20128/v1 +EOF +``` + +**Test:** `codex "what is 2+2?"` + +--- + +### OpenCode + +```bash +mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF +[provider.openai] +base_url = "http://localhost:20128/v1" +api_key = "sk-your-omniroute-key" +EOF +``` + +**Test:** `opencode` + +--- + +### Cline (CLI or VS Code) + +**CLI mode:** + +```bash +mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF +{ + "apiProvider": "openai", + "openAiBaseUrl": "http://localhost:20128/v1", + "openAiApiKey": "sk-your-omniroute-key" +} +EOF +``` + +**VS Code mode:** +Cline extension settings โ†’ API Provider: `OpenAI Compatible` โ†’ Base URL: `http://localhost:20128/v1` + +Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ Cline โ†’ Apply Config**. + +--- + +### KiloCode (CLI or VS Code) + +**CLI mode:** + +```bash +kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key +``` + +**VS Code settings:** + +```json +{ + "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", + "kilo-code.apiKey": "sk-your-omniroute-key" +} +``` + +Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ KiloCode โ†’ Apply Config**. + +--- + +### Continue (VS Code Extension) + +Edit `~/.continue/config.yaml`: + +```yaml +models: + - name: OmniRoute + provider: openai + model: auto + apiBase: http://localhost:20128/v1 + apiKey: sk-your-omniroute-key + default: true +``` + +Restart VS Code after editing. + +--- + +### Kiro CLI (Amazon) + +```bash +# Login to your AWS/Kiro account: +kiro-cli login + +# The CLI uses its own auth โ€” OmniRoute is not needed as backend for Kiro CLI itself. +# Use kiro-cli alongside OmniRoute for other tools. +kiro-cli status +``` + +--- + +### Cursor (Desktop App) + +> **Note:** Cursor routes requests through its cloud. For OmniRoute integration, +> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL. + +Via GUI: **Settings โ†’ Models โ†’ OpenAI API Key** + +- Base URL: `https://your-domain.com/v1` +- API Key: your OmniRoute key + +--- + +## Dashboard Auto-Configuration + +The OmniRoute dashboard automates configuration for most tools: + +1. Go to `http://localhost:20128/dashboard/cli-tools` +2. Expand any tool card +3. Select your API key from the dropdown +4. Click **Apply Config** (if tool is detected as installed) +5. Or copy the generated config snippet manually + +--- + +## Built-in Agents: Droid & OpenClaw + +**Droid** and **OpenClaw** are AI agents built directly into OmniRoute โ€” no installation needed. +They run as internal routes and use OmniRoute's model routing automatically. + +- Access: `http://localhost:20128/dashboard/agents` +- Configure: same combos and providers as all other tools +- No API key or CLI install required + +--- + +## Available API Endpoints + +| Endpoint | Description | Use For | +| -------------------------- | ----------------------------- | --------------------------- | +| `/v1/chat/completions` | Standard chat (all providers) | All modern tools | +| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows | +| `/v1/completions` | Legacy text completions | Older tools using `prompt:` | +| `/v1/embeddings` | Text embeddings | RAG, search | +| `/v1/images/generations` | Image generation | DALL-E, Flux, etc. | +| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS | +| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI | + +--- + +## Rieลกenie problรฉmov + +| Error | Cause | Fix | +| ------------------------- | ----------------------- | ------------------------------------------ | +| `Connection refused` | OmniRoute not running | `pm2 start omniroute` | +| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` | +| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` | +| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` | +| CLI shows "not installed" | Binary not in PATH | Check `which ` | +| `kiro-cli: not found` | Not in PATH | `export PATH="$HOME/.local/bin:$PATH"` | + +--- + +## Quick Setup Script (One Command) + +```bash +# Install all CLIs and configure for OmniRoute (replace with your key and server URL) +OMNIROUTE_URL="http://localhost:20128/v1" +OMNIROUTE_KEY="sk-your-omniroute-key" + +npm install -g @anthropic-ai/claude-code @openai/codex opencode-ai cline kilocode + +# Kiro CLI +apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash + +# Write configs +mkdir -p ~/.claude ~/.codex ~/.config/opencode ~/.continue + +cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" +cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" +cat >> ~/.bashrc << EOF +export OPENAI_BASE_URL="$OMNIROUTE_URL" +export OPENAI_API_KEY="$OMNIROUTE_KEY" +export ANTHROPIC_BASE_URL="$OMNIROUTE_URL" +export ANTHROPIC_API_KEY="$OMNIROUTE_KEY" +EOF + +source ~/.bashrc +echo "โœ… All CLIs installed and configured for OmniRoute" +``` diff --git a/docs/i18n/sk/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/sk/docs/CODEBASE_DOCUMENTATION.md new file mode 100644 index 0000000000..0940377da6 --- /dev/null +++ b/docs/i18n/sk/docs/CODEBASE_DOCUMENTATION.md @@ -0,0 +1,591 @@ +# omniroute โ€” Codebase Documentation (Slovenฤina) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CODEBASE_DOCUMENTATION.md) + +--- + +> 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
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, Qoder, 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. + +#### Architektรบra + +```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 | +| Qoder | 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"] +``` diff --git a/docs/i18n/sk/docs/COVERAGE_PLAN.md b/docs/i18n/sk/docs/COVERAGE_PLAN.md new file mode 100644 index 0000000000..a1ffd47711 --- /dev/null +++ b/docs/i18n/sk/docs/COVERAGE_PLAN.md @@ -0,0 +1,170 @@ +# Test Coverage Plan (Slovenฤina) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/COVERAGE_PLAN.md) + +--- + +Last updated: 2026-03-28 + +## Baseline + +There are multiple coverage numbers depending on how the report is computed. For planning, only one of them is useful. + +| Metric | Scope | Statements / Lines | Branches | Functions | Notes | +| -------------------- | ----------------------------------------------------- | -----------------: | -------: | --------: | --------------------------------------------------- | +| Legacy | Old `npm run test:coverage` | 79.42% | 75.15% | 67.94% | Inflated: counts test files and excludes `open-sse` | +| Diagnostic | Source-only, excluding tests and excluding `open-sse` | 68.16% | 63.55% | 64.06% | Useful only to isolate `src/**` | +| Recommended baseline | Source-only, excluding tests and including `open-sse` | 56.95% | 66.05% | 57.80% | This is the project-wide baseline to improve | + +The recommended baseline is the number to optimize against. + +## Rules + +- Coverage targets apply to source files, not to `tests/**`. +- `open-sse/**` is part of the product and must remain in scope. +- New code should not reduce coverage in touched areas. +- Prefer testing behavior and branch outcomes over implementation details. +- Prefer temp SQLite databases and small fixtures over broad mocks for `src/lib/db/**`. + +## Current command set + +- `npm run test:coverage` + - Main source coverage gate for the unit test suite + - Generates `text-summary`, `html`, `json-summary`, and `lcov` +- `npm run coverage:report` + - Detailed file-by-file report from the latest run +- `npm run test:coverage:legacy` + - Historical comparison only + +## Milestones + +| Phase | Target | Focus | +| ------- | ---------------------: | ------------------------------------------------- | +| Phase 1 | 60% statements / lines | Quick wins and low-risk utility coverage | +| Phase 2 | 65% statements / lines | DB and route foundations | +| Phase 3 | 70% statements / lines | Provider validation and usage analytics | +| Phase 4 | 75% statements / lines | `open-sse` translators and helpers | +| Phase 5 | 80% statements / lines | `open-sse` handlers and executor branches | +| Phase 6 | 85% statements / lines | Harder edge cases, branch debt, regression suites | +| Phase 7 | 90% statements / lines | Final sweep, gap closure, strict ratchet | + +Branches and functions should ratchet upward with each phase, but the primary hard target is statements / lines. + +## Priority hotspots + +These files or areas offer the best return for the next phases: + +1. `open-sse/handlers` + - `chatCore.ts` at 7.57% + - Overall directory at 29.07% +2. `open-sse/translator/request` + - Overall directory at 36.39% + - Many translators are still near single-digit coverage +3. `open-sse/translator/response` + - Overall directory at 8.07% +4. `open-sse/executors` + - Overall directory at 36.62% +5. `src/lib/db` + - `models.ts` at 20.66% + - `registeredKeys.ts` at 34.46% + - `modelComboMappings.ts` at 36.25% + - `settings.ts` at 46.40% + - `webhooks.ts` at 33.33% +6. `src/lib/usage` + - `usageHistory.ts` at 21.12% + - `usageStats.ts` at 9.56% + - `costCalculator.ts` at 30.00% +7. `src/lib/providers` + - `validation.ts` at 41.16% +8. Low-risk utility and API files for early gains + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/api/errorResponse.ts` + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +## Execution checklist + +### Phase 1: 56.95% -> 60% + +- [x] Fix coverage metric so it reflects source code instead of test files +- [x] Keep a legacy coverage script for comparison +- [x] Record the baseline and hotspots in-repo +- [ ] Add focused tests for low-risk utilities: + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/fetchTimeout.ts` + - `src/lib/api/errorResponse.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/display/names.ts` +- [ ] Add route tests for: + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +### Phase 2: 60% -> 65% + +- [ ] Add DB-backed tests for: + - `src/lib/db/modelComboMappings.ts` + - `src/lib/db/settings.ts` + - `src/lib/db/registeredKeys.ts` +- [ ] Cover branch behavior in: + - `src/lib/providers/validation.ts` + - `src/app/api/v1/embeddings/route.ts` + - `src/app/api/v1/moderations/route.ts` + +### Phase 3: 65% -> 70% + +- [ ] Add usage analytics tests for: + - `src/lib/usage/usageHistory.ts` + - `src/lib/usage/usageStats.ts` + - `src/lib/usage/costCalculator.ts` +- [ ] Expand route coverage for proxy management and settings branches + +### Phase 4: 70% -> 75% + +- [ ] Cover translator helpers and central translation paths: + - `open-sse/translator/index.ts` + - `open-sse/translator/helpers/*` + - `open-sse/translator/request/*` + - `open-sse/translator/response/*` + +### Phase 5: 75% -> 80% + +- [ ] Add handler-level tests for: + - `open-sse/handlers/chatCore.ts` + - `open-sse/handlers/responsesHandler.js` + - `open-sse/handlers/imageGeneration.js` + - `open-sse/handlers/embeddings.js` +- [ ] Add executor branch coverage for provider-specific auth, retries, and endpoint overrides + +### Phase 6: 80% -> 85% + +- [ ] Merge more edge-case suites into the main coverage path +- [ ] Increase function coverage for DB modules with weak constructor/helper coverage +- [ ] Close branch gaps in `settings.ts`, `registeredKeys.ts`, `validation.ts`, and translator helpers + +### Phase 7: 85% -> 90% + +- [ ] Treat the remaining low-coverage files as blockers +- [ ] Add regression tests for every uncovered production bug fixed during the push to 90% +- [ ] Raise the coverage gate in CI only after the local baseline is stable for at least two consecutive runs + +## Ratchet policy + +Update `npm run test:coverage` thresholds only after the project actually exceeds the next milestone with a comfortable buffer. + +Recommended ratchet sequence: + +1. 55/60/55 +2. 60/62/58 +3. 65/64/62 +4. 70/66/66 +5. 75/70/72 +6. 80/75/78 +7. 85/80/84 +8. 90/85/88 + +Order is `statements-lines / branches / functions`. + +## Known gap + +The current coverage command measures the main Node unit suite and includes source reached from it, including `open-sse`. It does not yet merge Vitest coverage into a single unified report. That merge is worth doing later, but it is not a blocker for starting the 60% -> 80% climb. diff --git a/docs/i18n/sk/docs/FEATURES.md b/docs/i18n/sk/docs/FEATURES.md index 2123f296c7..990cfd5492 100644 --- a/docs/i18n/sk/docs/FEATURES.md +++ b/docs/i18n/sk/docs/FEATURES.md @@ -1,6 +1,6 @@ # OmniRoute โ€” Dashboard Features Gallery (Slovenฤina) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/FEATURES.md) --- @@ -10,7 +10,7 @@ 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). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. ![Providers Dashboard](screenshots/01-providers.png) diff --git a/docs/i18n/sk/docs/MCP-SERVER.md b/docs/i18n/sk/docs/MCP-SERVER.md new file mode 100644 index 0000000000..5d9f50f712 --- /dev/null +++ b/docs/i18n/sk/docs/MCP-SERVER.md @@ -0,0 +1,87 @@ +# OmniRoute MCP Server Documentation (Slovenฤina) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/MCP-SERVER.md) + +--- + +> Model Context Protocol server with 16 intelligent tools + +## Inลกtalรกcia + +OmniRoute MCP is built-in. Start it with: + +```bash +omniroute --mcp +``` + +Or via the open-sse transport: + +```bash +# HTTP streamable transport (port 20130) +omniroute --dev # MCP auto-starts on /mcp endpoint +``` + +## IDE Configuration + +See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup. + +--- + +## Essential Tools (8) + +| Tool | Description | +| :------------------------------ | :--------------------------------------- | +| `omniroute_get_health` | Gateway health, circuit breakers, uptime | +| `omniroute_list_combos` | All configured combos with models | +| `omniroute_get_combo_metrics` | Performance metrics for a specific combo | +| `omniroute_switch_combo` | Switch active combo by ID/name | +| `omniroute_check_quota` | Quota status per provider or all | +| `omniroute_route_request` | Send a chat completion through OmniRoute | +| `omniroute_cost_report` | Cost analytics for a time period | +| `omniroute_list_models_catalog` | Full model catalog with capabilities | + +## Advanced Tools (8) + +| Tool | Description | +| :--------------------------------- | :---------------------------------------------------------- | +| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | +| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | +| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | +| `omniroute_test_combo` | Live-test all models in a combo via a real upstream request | +| `omniroute_get_provider_metrics` | Detailed metrics for one provider | +| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | +| `omniroute_explain_route` | Explain a past routing decision | +| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | + +## Authentication + +MCP tools are authenticated via API key scopes. Each tool requires specific scopes: + +| Scope | Tools | +| :------------- | :----------------------------------------------- | +| `read:health` | get_health, get_provider_metrics | +| `read:combos` | list_combos, get_combo_metrics | +| `write:combos` | switch_combo | +| `read:quota` | check_quota | +| `write:route` | route_request, simulate_route, test_combo | +| `read:usage` | cost_report, get_session_snapshot, explain_route | +| `write:config` | set_budget_guard, set_resilience_profile | +| `read:models` | list_models_catalog, best_combo_for_task | + +## Audit Logging + +Every tool call is logged to `mcp_tool_audit` with: + +- Tool name, arguments, result +- Duration (ms), success/failure +- API key hash, timestamp + +## Files + +| File | Purpose | +| :------------------------------------------- | :------------------------------------------ | +| `open-sse/mcp-server/server.ts` | MCP server creation + 16 tool registrations | +| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport | +| `open-sse/mcp-server/auth.ts` | API key + scope validation | +| `open-sse/mcp-server/audit.ts` | Tool call audit logging | +| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers | diff --git a/docs/i18n/sk/docs/RELEASE_CHECKLIST.md b/docs/i18n/sk/docs/RELEASE_CHECKLIST.md new file mode 100644 index 0000000000..7cd194b327 --- /dev/null +++ b/docs/i18n/sk/docs/RELEASE_CHECKLIST.md @@ -0,0 +1,37 @@ +# Release Checklist (Slovenฤina) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/RELEASE_CHECKLIST.md) + +--- + +Use this checklist before tagging or publishing a new OmniRoute release. + +## Version and Changelog + +1. Bump `package.json` version (`x.y.z`) in the release branch. +2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: + - `## [x.y.z] โ€” YYYY-MM-DD` +3. Keep `## [Unreleased]` as the first changelog section for upcoming work. +4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. + +## API Docs + +1. Update `docs/openapi.yaml`: + - `info.version` must equal `package.json` version. +2. Validate endpoint examples if API contracts changed. + +## Runtime Docs + +1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. +2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. +3. Update localized docs if source docs changed significantly. + +## Automated Check + +Run the sync guard locally before opening PR: + +```bash +npm run check:docs-sync +``` + +CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/sk/docs/TROUBLESHOOTING.md b/docs/i18n/sk/docs/TROUBLESHOOTING.md new file mode 100644 index 0000000000..e5bce2adb6 --- /dev/null +++ b/docs/i18n/sk/docs/TROUBLESHOOTING.md @@ -0,0 +1,256 @@ +# Troubleshooting (Slovenฤina) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/TROUBLESHOOTING.md) + +--- + +Common problems and solutions for OmniRoute. + +--- + +## Quick Fixes + +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | + +--- + +## Provider Issues + +### "Language model did not provide messages" + +**Cause:** Provider quota exhausted. + +**Fix:** + +1. 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, Qoder) 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}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) + +--- + +## Circuit Breaker Issues + +### Provider stuck in OPEN state + +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. + +**Fix:** + +1. 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 +- **SDK returns raw string instead of object** โ€” Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** โ€” Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** โ€” Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** โ€” Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` + +--- + +## Resilience Settings + +### Auto rate-limit not triggering + +- 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. + +--- + +## Optional RAG / LLM failure taxonomy (16 problems) + +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` โ€ฆ `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard โ†’ Health** for real-time system status +- **Translator**: Use **Dashboard โ†’ Translator** to debug format issues diff --git a/docs/i18n/sk/USER_GUIDE.md b/docs/i18n/sk/docs/USER_GUIDE.md similarity index 82% rename from docs/i18n/sk/USER_GUIDE.md rename to docs/i18n/sk/docs/USER_GUIDE.md index 876e698fed..e5cce0a5f7 100644 --- a/docs/i18n/sk/USER_GUIDE.md +++ b/docs/i18n/sk/docs/USER_GUIDE.md @@ -1,8 +1,6 @@ # User Guide (Slovenฤina) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/USER_GUIDE.md) - -> ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/USER_GUIDE.md) --- @@ -320,7 +318,7 @@ Model: cc/claude-opus-4-6 --- -## ๐Ÿš€ Deployment +## Nasadenie ### Global npm install (Recommended) @@ -511,23 +509,26 @@ post_install() { ### Environment Variables -| Variable | Default | Description | -| ------------------------- | ------------------------------------ | ------------------------------------------------------- | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | -| `INITIAL_PASSWORD` | `123456` | First login password | -| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | -| `PORT` | framework default | Service port (`20128` in examples) | -| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | -| `NODE_ENV` | runtime default | Set `production` for deploy | -| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | -| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | -| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | -| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | -| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | -| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | -| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | -| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | +| 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/*` | +| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand | +| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | For the full environment variable reference, see the [README](../README.md). @@ -598,6 +599,11 @@ curl -X POST http://localhost:20128/api/provider-models \ Or use Dashboard: **Providers โ†’ [Provider] โ†’ Custom Models**. +Notes: + +- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers. +- The **Custom Models** section is intended for providers that do not expose managed available-model imports. + ### Dedicated Provider Routes Route requests directly to a specific provider with model validation: @@ -642,6 +648,14 @@ Returns models grouped by provider with types (`chat`, `embedding`, `image`). - Automatic background sync with timeout + fail-fast - Prefer server-side `BASE_URL`/`CLOUD_URL` in production +### Cloudflare Quick Tunnel + +- Available in **Dashboard โ†’ Endpoints** for Docker and other self-hosted deployments +- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint +- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary +- Tunnel URLs are ephemeral and change every time you stop/start the tunnel +- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download + ### LLM Gateway Intelligence (Phase 9) - **Semantic Cache** โ€” Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) @@ -757,11 +771,11 @@ OmniRoute implements provider-level resilience with four components: 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 | +| 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 unless `DISABLE_SQLITE_AUTO_BACKUP=true` | ```bash # API: Export database @@ -787,10 +801,11 @@ curl -X POST http://localhost:20128/api/db-backups/import \ ### Settings Dashboard -The settings page is organized into 5 tabs for easy navigation: +The settings page is organized into 6 tabs for easy navigation: | Tab | Contents | | -------------- | ---------------------------------------------------------------------------------------------- | +| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility | | **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | | **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | | **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | diff --git a/docs/i18n/sk/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/sk/docs/VM_DEPLOYMENT_GUIDE.md new file mode 100644 index 0000000000..15b0463cb5 --- /dev/null +++ b/docs/i18n/sk/docs/VM_DEPLOYMENT_GUIDE.md @@ -0,0 +1,403 @@ +# OmniRoute โ€” Deployment Guide on VM with Cloudflare (Slovenฤina) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/VM_DEPLOYMENT_GUIDE.md) + +--- + +Complete guide to install and configure OmniRoute on a VM (VPS) with domain managed via Cloudflare. + +--- + +## Prerequisites + +| Item | Minimum | Recommended | +| ---------- | ------------------------ | ---------------- | +| **CPU** | 1 vCPU | 2 vCPU | +| **RAM** | 1 GB | 2 GB | +| **Disk** | 10 GB SSD | 25 GB SSD | +| **OS** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS | +| **Domain** | Registered on Cloudflare | โ€” | +| **Docker** | Docker Engine 24+ | Docker 27+ | + +**Tested providers**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. + +--- + +## 1. Configure the VM + +### 1.1 Create the instance + +On your preferred VPS provider: + +- Choose Ubuntu 24.04 LTS +- Select the minimum plan (1 vCPU / 1 GB RAM) +- Set a strong root password or configure SSH key +- Note the **public IP** (e.g., `203.0.113.10`) + +### 1.2 Connect via SSH + +```bash +ssh root@203.0.113.10 +``` + +### 1.3 Update the system + +```bash +apt update && apt upgrade -y +``` + +### 1.4 Install Docker + +```bash +# Install dependencies +apt install -y ca-certificates curl gnupg + +# Add official Docker repository +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 Install nginx + +```bash +apt install -y nginx +``` + +### 1.6 Configure 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 +``` + +> **Tip**: For maximum security, restrict ports 80 and 443 to Cloudflare IPs only. See the [Advanced Security](#advanced-security) section. + +--- + +## 2. Install OmniRoute + +### 2.1 Create configuration directory + +```bash +mkdir -p /opt/omniroute +``` + +### 2.2 Create environment variables file + +```bash +cat > /opt/omniroute/.env << โ€˜EOFโ€™ +# === Security === +JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY +INITIAL_PASSWORD=YourSecurePassword123! +API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY +STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY +STORAGE_ENCRYPTION_KEY_VERSION=v1 +MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT + +# === 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 (change to your domain) === +BASE_URL=https://llms.seudominio.com +NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com + +# === Cloud Sync (optional) === +# CLOUD_URL=https://cloud.omniroute.online +# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online +EOF +``` + +> โš ๏ธ **IMPORTANT**: Generate unique secret keys! Use `openssl rand -hex 32` for each key. + +### 2.3 Start the 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 Verify that it is running + +```bash +docker ps | grep omniroute +docker logs omniroute --tail 20 +``` + +It should display: `[DB] SQLite database ready` and `listening on port 20128`. + +--- + +## 3. Configure nginx (Reverse Proxy) + +### 3.1 Generate SSL certificate (Cloudflare Origin) + +In the Cloudflare dashboard: + +1. Go to **SSL/TLS โ†’ Origin Server** +2. Click **Create Certificate** +3. Keep the defaults (15 years, \*.yourdomain.com) +4. Copy the **Origin Certificate** and the **Private Key** + +```bash +mkdir -p /etc/nginx/ssl + +# Paste the certificate +nano /etc/nginx/ssl/origin.crt + +# Paste the private key +nano /etc/nginx/ssl/origin.key + +chmod 600 /etc/nginx/ssl/origin.key +``` + +### 3.2 Nginx Configuration + +```bash +cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ +# Default server โ€” blocks direct access via 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.yourdomain.com; # Change to your domain + + 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.yourdomain.com; + return 301 https://$server_name$request_uri; +} +NGINX +``` + +### 3.3 Enable and Test + +```bash +# Remove default configuration +rm -f /etc/nginx/sites-enabled/default + +# Enable OmniRoute +ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute + +# Test and reload +nginx -t && systemctl reload nginx +``` + +--- + +## 4. Configure Cloudflare DNS + +### 4.1 Add DNS record + +In the Cloudflare dashboard โ†’ DNS: + +| Type | Name | Content | Proxy | +| ---- | ------ | ---------------------- | ---------- | +| A | `llms` | `203.0.113.10` (VM IP) | โœ… Proxied | + +### 4.2 Configure SSL + +Under **SSL/TLS โ†’ Overview**: + +- Mode: **Full (Strict)** + +Under **SSL/TLS โ†’ Edge Certificates**: + +- Always Use HTTPS: โœ… On +- Minimum TLS Version: TLS 1.2 +- Automatic HTTPS Rewrites: โœ… On + +### 4.3 Testing + +```bash +curl -sI https://llms.seudominio.com/health +# Should return HTTP/2 200 +``` + +--- + +## 5. Operations and Maintenance + +### Upgrade to a new version + +```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 +``` + +### View logs + +```bash +docker logs -f omniroute # Real-time stream +docker logs omniroute --tail 50 # Last 50 lines +``` + +### Manual database backup + +```bash +# Copy data from the volume to the host +docker cp omniroute:/app/data ./backup-$(date +%F) + +# Or compress the entire volume +docker run --rm -v omniroute-data:/data -v $(pwd):/backup \ + alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data +``` + +### Restore from 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. Advanced Security + +### Restrict nginx to Cloudflare IPs + +```bash +cat > /etc/nginx/cloudflare-ips.conf << โ€˜CFโ€™ +# Cloudflare IPv4 ranges โ€” update periodically +# 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 +``` + +Add the following to `nginx.conf` inside the `http {}` block: + +```nginx +include /etc/nginx/cloudflare-ips.conf; +``` + +### Install fail2ban + +```bash +apt install -y fail2ban +systemctl enable fail2ban +systemctl start fail2ban + +# Check status +fail2ban-client status sshd +``` + +### Block direct access to the Docker port + +```bash +# Prevent direct external access to port 20128 +iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP +iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT + +# Persist the rules +apt install -y iptables-persistent +netfilter-persistent save +``` + +--- + +## 7. Deploy to Cloudflare Workers (Optional) + +For remote access via Cloudflare Workers (without exposing the VM directly): + +```bash +# In the local repository +cd omnirouteCloud +npm install +npx wrangler login +npx wrangler deploy +``` + +See the full documentation at [omnirouteCloud/README.md](../omnirouteCloud/README.md). + +--- + +## Port Summary + +| Port | Service | Access | +| ----- | ----------- | -------------------------- | +| 22 | SSH | Public (with fail2ban) | +| 80 | nginx HTTP | Redirect โ†’ HTTPS | +| 443 | nginx HTTPS | Via Cloudflare Proxy | +| 20128 | OmniRoute | Localhost only (via nginx) | diff --git a/docs/i18n/sk/src/lib/a2a/README.md b/docs/i18n/sk/src/lib/a2a/README.md new file mode 100644 index 0000000000..69e1d86b47 --- /dev/null +++ b/docs/i18n/sk/src/lib/a2a/README.md @@ -0,0 +1,752 @@ +# OmniRoute A2A Server (Slovenฤina) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../../../src/lib/a2a/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../../../es/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../../../fr/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../../../de/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../../../it/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../../../ru/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../../../zh-CN/src/lib/a2a/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../../../ja/src/lib/a2a/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../../../ko/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../../../ar/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../../../in/src/lib/a2a/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../../../th/src/lib/a2a/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../../../vi/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../../../id/src/lib/a2a/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../../../ms/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../../../nl/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../../../pl/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../../../sv/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../../../no/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../../../da/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../../../fi/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../../../pt/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../../../ro/src/lib/a2a/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../../../hu/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../../../bg/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../../../sk/src/lib/a2a/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../../../uk-UA/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../../../he/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../../../phi/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../../../pt-BR/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../../../cs/src/lib/a2a/README.md) + +--- + +> **Agent-to-Agent Protocol v0.3** โ€” Enables any AI agent to use OmniRoute as an intelligent routing agent via JSON-RPC 2.0. + +The A2A Server exposes OmniRoute as a **first-class agent** that other agents can discover, delegate tasks to, and collaborate with using the [A2A Protocol](https://google.github.io/A2A/). + +--- + +## Architektรบra + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Orchestrator Agent โ”‚ +โ”‚ (LangChain, CrewAI, AutoGen, Custom Agent) โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ 1. GET /.well-known/agent.json (discover) + โ”‚ 2. POST /a2a (JSON-RPC 2.0) + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ OmniRoute A2A Server โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Task Manager โ”‚ โ”‚ Skill Engine โ”‚ โ”‚ SSE Streaming โ”‚ โ”‚ +โ”‚ โ”‚ (lifecycle) โ”‚โ”€โ”€โ”‚ (registry) โ”‚โ”€โ”€โ”‚ (real-time) โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ +โ”‚ Skills: โ”‚ โ”‚ +โ”‚ โ”œโ”€ smart-routing โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ””โ”€ quota-management โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ Routing Decision Logger โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ OmniRoute Gateway (internal) + /v1/chat/completions, /api/combos, /api/usage/quota +``` + +--- + +## Rรฝchly ลกtart + +### Agent Discovery + +Every A2A-compatible agent exposes an **Agent Card** at `/.well-known/agent.json`: + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +**Response:** + +```json +{ + "name": "OmniRoute", + "description": "Intelligent AI gateway with auto-routing across 50+ providers", + "url": "http://localhost:20128/a2a", + "version": "1.8.1", + "capabilities": { + "streaming": true, + "pushNotifications": false + }, + "skills": [ + { + "id": "smart-routing", + "name": "Smart Routing", + "description": "Routes prompts through OmniRoute intelligent pipeline", + "tags": ["routing", "llm", "multi-provider", "cost-optimization"], + "examples": [ + "Write a hello world in Python", + "Explain quantum computing using the cheapest provider" + ] + }, + { + "id": "quota-management", + "name": "Quota Management", + "description": "Natural-language queries about provider quotas", + "tags": ["quota", "analytics", "cost"], + "examples": [ + "Which provider has the most quota remaining?", + "Suggest a free combo for coding" + ] + } + ], + "authentication": { + "schemes": ["bearer"], + "apiKeyHeader": "Authorization" + } +} +``` + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Send a message to a skill and receive the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python hello world"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "a1b2c3d4-...", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "print('Hello, World!')" }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.0030)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "2026-03-04T..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"Quantum computing..."}}} + +: heartbeat 2026-03-04T21:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Running Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Skills Reference + +### `smart-routing` + +Routes prompts through OmniRoute's intelligent pipeline with full observability. + +**Parameters (in `metadata`):** + +| Parameter | Type | Default | Description | +| --------- | -------- | ------------ | ---------------------------------------------------------------------------------------- | +| `model` | `string` | `"auto"` | Target model (e.g., `claude-sonnet-4`, `gpt-4o`, `auto`) | +| `combo` | `string` | active combo | Specific combo to route through | +| `budget` | `number` | none | Maximum cost in USD for this request | +| `role` | `string` | none | Task role hint: `coding`, `review`, `planning`, `analysis`, `debugging`, `documentation` | + +**Returns:** + +| Field | Description | +| ------------------------------ | --------------------------------------------------------- | +| `artifacts[].content` | The LLM response text | +| `metadata.routing_explanation` | Human-readable explanation of routing decision | +| `metadata.cost_envelope` | Estimated vs actual cost with currency | +| `metadata.resilience_trace` | Array of events (primary_selected, fallback_needed, etc.) | +| `metadata.policy_verdict` | Whether the request was allowed and why | + +### `quota-management` + +Answers natural-language queries about provider quotas. + +**Query types (inferred from message content):** + +| Query Pattern | Response Type | +| ---------------------------------------------- | -------------------------------------------------------- | +| Contains `"ranking"`, `"most quota"`, `"best"` | Providers ranked by remaining quota | +| Contains `"free"`, `"suggest"` | Lists free combos or suggests free-tier providers | +| Default | Full quota summary with warnings for low-quota providers | + +--- + +## Task Lifecycle + +``` +submitted โ”€โ”€โ†’ working โ”€โ”€โ†’ completed + โ”€โ”€โ†’ failed + โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ†’ cancelled +``` + +| State | Description | +| ----------- | ----------------------------------------------------- | +| `submitted` | Task created, queued for execution | +| `working` | Skill handler is executing | +| `completed` | Execution succeeded, artifacts available | +| `failed` | Execution failed or task expired (TTL: 5 min default) | +| `cancelled` | Cancelled by client via `tasks/cancel` | + +- Terminal states: `completed`, `failed`, `cancelled` (no further transitions) +- Expired tasks in `submitted` or `working` are auto-marked as `failed` +- Tasks are garbage-collected after 2ร— TTL + +--- + +## Client Examples + +### Python โ€” Orchestrator Agent + +```python +""" +A2A Client โ€” Python example. +Discovers OmniRoute agent, sends a task, and processes the result. +""" +import requests +import json + +BASE_URL = "http://localhost:20128" +API_KEY = "your-api-key" +HEADERS = { + "Content-Type": "application/json", + "Authorization": f"Bearer {API_KEY}", +} + +# 1. Discover agent capabilities +agent_card = requests.get(f"{BASE_URL}/.well-known/agent.json").json() +print(f"Agent: {agent_card['name']} v{agent_card['version']}") +print(f"Skills: {[s['id'] for s in agent_card['skills']]}") + +# 2. Send a smart-routing task +response = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python quicksort implementation"}], + "metadata": { + "model": "auto", + "combo": "fast-coding", + "budget": 0.10, + } + } +}) +result = response.json()["result"] +print(f"\n๐Ÿ“ Response: {result['artifacts'][0]['content'][:200]}...") +print(f"๐Ÿ”€ Routing: {result['metadata']['routing_explanation']}") +print(f"๐Ÿ’ฐ Cost: ${result['metadata']['cost_envelope']['actual']}") +print(f"๐Ÿ›ก๏ธ Policy: {result['metadata']['policy_verdict']['reason']}") + +# 3. Query quota status +quota_resp = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-2", + "method": "message/send", + "params": { + "skill": "quota-management", + "messages": [{"role": "user", "content": "Which provider has the most quota remaining?"}], + } +}) +quota_result = quota_resp.json()["result"] +print(f"\n๐Ÿ“Š Quota: {quota_result['artifacts'][0]['content']}") +``` + +### TypeScript โ€” Multi-Agent Orchestrator + +```typescript +/** + * A2A Client โ€” TypeScript example. + * Shows agent discovery, task delegation, and streaming. + */ + +const BASE_URL = "http://localhost:20128"; +const API_KEY = "your-api-key"; + +interface JsonRpcResponse { + jsonrpc: "2.0"; + id: string | number; + result?: T; + error?: { code: number; message: string }; +} + +async function a2aCall(method: string, params: Record): Promise { + const resp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: `${method}-${Date.now()}`, + method, + params, + }), + }); + const json: JsonRpcResponse = await resp.json(); + if (json.error) throw new Error(`[${json.error.code}] ${json.error.message}`); + return json.result!; +} + +// โ”€โ”€ Agent Discovery โ”€โ”€ +const agentCard = await fetch(`${BASE_URL}/.well-known/agent.json`).then((r) => r.json()); +console.log(`Connected to: ${agentCard.name} (${agentCard.skills.length} skills)`); + +// โ”€โ”€ Smart Routing: Send a coding task โ”€โ”€ +const routingResult = await a2aCall("message/send", { + skill: "smart-routing", + messages: [{ role: "user", content: "Implement a Redis cache wrapper in TypeScript" }], + metadata: { model: "claude-sonnet-4", role: "coding" }, +}); +console.log("Response:", routingResult.artifacts[0].content); +console.log("Provider:", routingResult.metadata.routing_explanation); + +// โ”€โ”€ Quota Management: Find free alternatives โ”€โ”€ +const quotaResult = await a2aCall("message/send", { + skill: "quota-management", + messages: [{ role: "user", content: "Suggest free combos for documentation" }], +}); +console.log("Free combos:", quotaResult.artifacts[0].content); + +// โ”€โ”€ Streaming: Real-time response โ”€โ”€ +const streamResp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "stream-1", + method: "message/stream", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Explain microservices architecture" }], + }, + }), +}); + +const reader = streamResp.body!.getReader(); +const decoder = new TextDecoder(); +while (true) { + const { done, value } = await reader.read(); + if (done) break; + const chunk = decoder.decode(value); + for (const line of chunk.split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + if (event.params.chunk) { + process.stdout.write(event.params.chunk.content); + } + if (event.params.task.state === "completed") { + console.log("\nโœ… Stream completed"); + } + } + } +} +``` + +### Python โ€” LangChain A2A Integration + +```python +""" +LangChain integration โ€” Use OmniRoute A2A as a custom LLM. +""" +from langchain.llms.base import BaseLLM +from langchain.schema import LLMResult, Generation +import requests +from typing import List, Optional + +class OmniRouteA2A(BaseLLM): + base_url: str = "http://localhost:20128" + api_key: str = "" + model: str = "auto" + combo: Optional[str] = None + + @property + def _llm_type(self) -> str: + return "omniroute-a2a" + + def _call(self, prompt: str, stop: Optional[List[str]] = None, **kwargs) -> str: + response = requests.post( + f"{self.base_url}/a2a", + headers={ + "Content-Type": "application/json", + "Authorization": f"Bearer {self.api_key}", + }, + json={ + "jsonrpc": "2.0", + "id": "langchain-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": prompt}], + "metadata": { + "model": self.model, + **({"combo": self.combo} if self.combo else {}), + }, + }, + }, + ) + result = response.json()["result"] + return result["artifacts"][0]["content"] + + def _generate(self, prompts: List[str], stop=None, **kwargs) -> LLMResult: + return LLMResult( + generations=[[Generation(text=self._call(p, stop))] for p in prompts] + ) + +# Usage +llm = OmniRouteA2A( + base_url="http://localhost:20128", + api_key="your-key", + model="auto", + combo="fast-coding", +) +result = llm("Write a Python function to merge two sorted lists") +print(result) +``` + +### Go โ€” A2A Client + +```go +package main + +import ( + "bytes" + "encoding/json" + "fmt" + "io" + "net/http" +) + +const baseURL = "http://localhost:20128" +const apiKey = "your-api-key" + +type JsonRpcRequest struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Method string `json:"method"` + Params interface{} `json:"params"` +} + +type JsonRpcResponse struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Result interface{} `json:"result"` + Error *struct { + Code int `json:"code"` + Message string `json:"message"` + } `json:"error"` +} + +func a2aCall(method string, params interface{}) (*JsonRpcResponse, error) { + body, _ := json.Marshal(JsonRpcRequest{ + Jsonrpc: "2.0", + ID: "go-1", + Method: method, + Params: params, + }) + + req, _ := http.NewRequest("POST", baseURL+"/a2a", bytes.NewReader(body)) + req.Header.Set("Content-Type", "application/json") + req.Header.Set("Authorization", "Bearer "+apiKey) + + resp, err := http.DefaultClient.Do(req) + if err != nil { + return nil, err + } + defer resp.Body.Close() + data, _ := io.ReadAll(resp.Body) + + var result JsonRpcResponse + json.Unmarshal(data, &result) + return &result, nil +} + +func main() { + // Discover agent + resp, _ := http.Get(baseURL + "/.well-known/agent.json") + defer resp.Body.Close() + body, _ := io.ReadAll(resp.Body) + fmt.Println("Agent Card:", string(body)) + + // Send smart-routing task + result, _ := a2aCall("message/send", map[string]interface{}{ + "skill": "smart-routing", + "messages": []map[string]string{{"role": "user", "content": "Hello from Go!"}}, + "metadata": map[string]interface{}{"model": "auto"}, + }) + out, _ := json.MarshalIndent(result.Result, "", " ") + fmt.Println("Result:", string(out)) +} +``` + +--- + +## Use Cases + +### ๐Ÿค– Use Case 1: Multi-Agent Coding Pipeline + +An orchestrator agent delegates code generation to OmniRoute, then passes the output to a review agent. + +```python +def coding_pipeline(task: str): + # Step 1: Generate code via OmniRoute A2A + code_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Write production-quality code: {task}"} + ], metadata={"model": "auto", "role": "coding"}) + code = code_result["artifacts"][0]["content"] + + # Step 2: Review the code via OmniRoute A2A (different model) + review_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Review this code for bugs and improvements:\n\n{code}"} + ], metadata={"model": "auto", "role": "review"}) + review = review_result["artifacts"][0]["content"] + + # Step 3: Check costs + print(f"Code cost: ${code_result['metadata']['cost_envelope']['actual']}") + print(f"Review cost: ${review_result['metadata']['cost_envelope']['actual']}") + + return {"code": code, "review": review} +``` + +### ๐Ÿ’ก Use Case 2: Quota-Aware Agent Swarm + +Multiple agents share quota through OmniRoute, using the quota skill to coordinate. + +```python +async def quota_aware_agent(agent_name: str, task: str): + # Check quota before starting + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Which provider has the most quota remaining?"} + ]) + print(f"[{agent_name}] {quota['artifacts'][0]['content']}") + + # Send request with budget constraint + result = a2a_send("smart-routing", [ + {"role": "user", "content": task} + ], metadata={"budget": 0.05}) + + policy = result["metadata"]["policy_verdict"] + if not policy["allowed"]: + print(f"[{agent_name}] โš ๏ธ Budget exceeded: {policy['reason']}") + # Fall back to free combo + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Suggest free combos"} + ]) + print(f"[{agent_name}] Free alternatives: {quota['artifacts'][0]['content']}") + + return result +``` + +### ๐Ÿ“Š Use Case 3: Real-Time Streaming Dashboard + +A monitoring agent streams responses and displays progress in real-time. + +```typescript +async function streamingDashboard(prompt: string) { + const response = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { "Content-Type": "application/json", Authorization: `Bearer ${API_KEY}` }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "dash-1", + method: "message/stream", + params: { skill: "smart-routing", messages: [{ role: "user", content: prompt }] }, + }), + }); + + let totalChunks = 0; + const reader = response.body!.getReader(); + const decoder = new TextDecoder(); + + while (true) { + const { done, value } = await reader.read(); + if (done) break; + + for (const line of decoder.decode(value).split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + const state = event.params.task.state; + + if (state === "working" && event.params.chunk) { + totalChunks++; + process.stdout.write( + `\r[Chunk ${totalChunks}] ${event.params.chunk.content.slice(0, 50)}...` + ); + } + if (state === "completed") { + const meta = event.params.metadata; + console.log( + `\nโœ… Done | Cost: $${meta?.cost_envelope?.actual || 0} | Route: ${meta?.routing_explanation || "N/A"}` + ); + } + if (state === "failed") { + console.error(`\nโŒ Failed: ${event.params.metadata?.error}`); + } + } + } + } +} +``` + +### ๐Ÿ” Use Case 4: Task Polling Pattern + +For long-running tasks, poll the task status instead of waiting synchronously. + +```python +import time + +def poll_task(task_id: str, timeout: int = 60): + """Poll task status until completion or timeout.""" + start = time.time() + while time.time() - start < timeout: + result = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "poll-1", + "method": "tasks/get", + "params": {"taskId": task_id}, + }).json() + + task = result["result"]["task"] + state = task["state"] + print(f" Task {task_id[:8]}... state={state}") + + if state in ("completed", "failed", "cancelled"): + return task + time.sleep(2) + + # Timeout โ€” cancel the task + requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "cancel-1", + "method": "tasks/cancel", + "params": {"taskId": task_id}, + }) + raise TimeoutError(f"Task {task_id} timed out after {timeout}s") +``` + +--- + +## Error Codes + +| Code | Constant | Meaning | +| ------ | ------------------------ | ---------------------------------------- | +| -32700 | โ€” | Parse error (invalid JSON) | +| -32600 | `INVALID_REQUEST` | Invalid JSON-RPC request or unauthorized | +| -32601 | `METHOD_NOT_FOUND` | Unknown method or skill | +| -32602 | `INVALID_PARAMS` | Missing or invalid parameters | +| -32603 | `INTERNAL_ERROR` | Skill execution failed | +| -32001 | `TASK_NOT_FOUND` | Task ID not found | +| -32002 | `TASK_ALREADY_COMPLETED` | Cannot modify a completed task | +| -32003 | `UNAUTHORIZED` | Invalid or missing API key | +| -32004 | `BUDGET_EXCEEDED` | Request exceeds configured budget | +| -32005 | `PROVIDER_UNAVAILABLE` | No available providers | + +--- + +## Authentication + +All `/a2a` requests require a Bearer token via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server (`OMNIROUTE_API_KEY` is empty), authentication is bypassed. + +--- + +## File Structure + +``` +src/lib/a2a/ +โ”œโ”€โ”€ taskManager.ts # Task lifecycle (create/update/cancel/list), TTL, cleanup +โ”œโ”€โ”€ taskExecution.ts # Generic task executor with state management +โ”œโ”€โ”€ streaming.ts # SSE stream formatting, heartbeat, chunk/completion events +โ”œโ”€โ”€ routingLogger.ts # Routing decision logger (stats, history, retention) +โ””โ”€โ”€ skills/ + โ”œโ”€โ”€ smartRouting.ts # Smart routing skill (routes via /v1/chat/completions) + โ””โ”€โ”€ quotaManagement.ts # Quota management skill (natural-language quota queries) + +src/app/a2a/ +โ””โ”€โ”€ route.ts # Next.js API route handler (JSON-RPC 2.0 dispatch) + +open-sse/mcp-server/ +โ””โ”€โ”€ schemas/a2a.ts # Zod schemas (AgentCard, Task, JSON-RPC, SSE events) +``` + +--- + +## Comparison: MCP vs A2A + +| Feature | MCP Server | A2A Server | +| ----------------- | ---------------------------- | ------------------------------------------------- | +| **Protocol** | Model Context Protocol | Agent-to-Agent Protocol v0.3 | +| **Transport** | stdio / HTTP | HTTP (JSON-RPC 2.0) | +| **Discovery** | Tool listing via MCP | `/.well-known/agent.json` | +| **Granularity** | 16 individual tools | 2 high-level skills | +| **Best for** | IDE agents (Cursor, VS Code) | Multi-agent systems (LangChain, CrewAI) | +| **Streaming** | Not supported | SSE via `message/stream` | +| **Task tracking** | No | Full lifecycle (submitted โ†’ completed) | +| **Observability** | Audit log per tool call | Cost envelope + resilience trace + policy verdict | + +--- + +## Licencia + +Part of [OmniRoute](https://github.com/diegosouzapw/OmniRoute) โ€” MIT License. diff --git a/docs/i18n/sv/A2A-SERVER.md b/docs/i18n/sv/A2A-SERVER.md deleted file mode 100644 index 01531ff482..0000000000 --- a/docs/i18n/sv/A2A-SERVER.md +++ /dev/null @@ -1,200 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/A2A-SERVER.md) - ---- - -# OmniRoute A2A Server Documentation - -> Agent-to-Agent Protocol v0.3 โ€” OmniRoute as an intelligent routing agent - -## Agent Discovery - -```bash -curl http://localhost:20128/.well-known/agent.json -``` - -Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements. - ---- - -## Authentication - -All `/a2a` requests require an API key via the `Authorization` header: - -``` -Authorization: Bearer YOUR_OMNIROUTE_API_KEY -``` - -If no API key is configured on the server, authentication is bypassed. - ---- - -## JSON-RPC 2.0 Methods - -### `message/send` โ€” Synchronous Execution - -Sends a message to a skill and waits for the complete response. - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{ - "jsonrpc": "2.0", - "id": "1", - "method": "message/send", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Write a hello world in Python"}], - "metadata": {"model": "auto", "combo": "fast-coding"} - } - }' -``` - -**Response:** - -```json -{ - "jsonrpc": "2.0", - "id": "1", - "result": { - "task": { "id": "uuid", "state": "completed" }, - "artifacts": [{ "type": "text", "content": "..." }], - "metadata": { - "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)", - "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, - "resilience_trace": [ - { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." } - ], - "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } - } - } -} -``` - -### `message/stream` โ€” SSE Streaming - -Same as `message/send` but returns Server-Sent Events for real-time streaming. - -```bash -curl -N -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{ - "jsonrpc": "2.0", - "id": "1", - "method": "message/stream", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Explain quantum computing"}] - } - }' -``` - -**SSE Events:** - -``` -data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}} - -: heartbeat 2026-03-03T17:00:00Z - -data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} -``` - -### `tasks/get` โ€” Query Task Status - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' -``` - -### `tasks/cancel` โ€” Cancel a Task - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' -``` - ---- - -## Available Skills - -| Skill | Description | -| :----------------- | :------------------------------------------------------------------------------------------------------------------------------ | -| `smart-routing` | Routes prompts through OmniRoute's intelligent pipeline. Returns response with routing explanation, cost, and resilience trace. | -| `quota-management` | Answers natural-language queries about provider quotas, suggests free combos, and provides quota rankings. | - ---- - -## Task Lifecycle - -``` -submitted โ†’ working โ†’ completed - โ†’ failed - โ†’ cancelled -``` - -- Tasks expire after 5 minutes (configurable) -- Terminal states: `completed`, `failed`, `cancelled` -- Event log tracks every state transition - ---- - -## Error Codes - -| Code | Meaning | -| :----- | :----------------------------- | -| -32700 | Parse error (invalid JSON) | -| -32600 | Invalid request / Unauthorized | -| -32601 | Method or skill not found | -| -32602 | Invalid params | -| -32603 | Internal error | - ---- - -## Integration Examples - -### Python (requests) - -```python -import requests - -resp = requests.post("http://localhost:20128/a2a", json={ - "jsonrpc": "2.0", "id": "1", - "method": "message/send", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Hello"}] - } -}, headers={"Authorization": "Bearer YOUR_KEY"}) - -result = resp.json()["result"] -print(result["artifacts"][0]["content"]) -print(result["metadata"]["routing_explanation"]) -``` - -### TypeScript (fetch) - -```typescript -const resp = await fetch("http://localhost:20128/a2a", { - method: "POST", - headers: { - "Content-Type": "application/json", - Authorization: "Bearer YOUR_KEY", - }, - body: JSON.stringify({ - jsonrpc: "2.0", - id: "1", - method: "message/send", - params: { - skill: "smart-routing", - messages: [{ role: "user", content: "Hello" }], - }, - }), -}); -const { result } = await resp.json(); -console.log(result.metadata.routing_explanation); -``` diff --git a/docs/i18n/sv/API_REFERENCE.md b/docs/i18n/sv/API_REFERENCE.md deleted file mode 100644 index b878605221..0000000000 --- a/docs/i18n/sv/API_REFERENCE.md +++ /dev/null @@ -1,455 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/API_REFERENCE.md) - ---- - -# API Reference - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/API_REFERENCE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/API_REFERENCE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/API_REFERENCE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/API_REFERENCE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/API_REFERENCE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/API_REFERENCE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/API_REFERENCE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/API_REFERENCE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/API_REFERENCE.md) - -Complete reference for all OmniRoute API endpoints. - ---- - -## Table of Contents - -- [Chat Completions](#chat-completions) -- [Embeddings](#embeddings) -- [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`. - -### ACP Agents - -| Endpoint | Method | Description | -| ----------------- | ------ | -------------------------------------------------------- | -| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | -| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | -| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | - -GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). - -### Resilience & Rate Limits - -| Endpoint | Method | Description | -| ----------------------- | ------- | ------------------------------- | -| `/api/resilience` | 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` diff --git a/docs/i18n/sv/ARCHITECTURE.md b/docs/i18n/sv/ARCHITECTURE.md deleted file mode 100644 index 4ea06a29f2..0000000000 --- a/docs/i18n/sv/ARCHITECTURE.md +++ /dev/null @@ -1,787 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/ARCHITECTURE.md) - ---- - -# OmniRoute Architecture - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/ARCHITECTURE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/ARCHITECTURE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/ARCHITECTURE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/ARCHITECTURE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/ARCHITECTURE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/ARCHITECTURE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/ARCHITECTURE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/ARCHITECTURE.md) - -_Last updated: 2026-03-04_ - -## 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 (`...`) for reasoning models -- Response sanitization for strict OpenAI SDK compatibility -- Role normalization (developerโ†’system, systemโ†’user) for cross-provider compatibility -- Structured output conversion (json_schema โ†’ Gemini responseSchema) -- Local persistence for providers, keys, aliases, combos, settings, pricing -- Usage/cost tracking and request logging -- Optional cloud sync for multi-device/state sync -- IP allowlist/blocklist for API access control -- Thinking budget management (passthrough/auto/custom/adaptive) -- Global system prompt injection -- Session tracking and fingerprinting -- Per-account enhanced rate limiting with provider-specific profiles -- Circuit breaker pattern for provider resilience -- Anti-thundering herd protection with mutex locking -- Signature-based request deduplication cache -- Domain layer: model availability, cost rules, fallback policy, lockout policy -- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) -- Policy engine for centralized request evaluation (lockout โ†’ budget โ†’ fallback) -- Request telemetry with p50/p95/p99 latency aggregation -- Correlation ID (X-Request-Id) for end-to-end tracing -- Compliance audit logging with opt-out per API key -- Eval framework for LLM quality assurance -- Resilience UI dashboard with real-time circuit breaker status -- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) - -Primary runtime model: - -- Next.js 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[(storage.sqlite)] - UDB[(usage tables + log artifacts)] - end - - subgraph Upstreams[Upstream Providers] - P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/Qoder/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/route.ts` (GET) -- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) -- OAuth: `src/app/api/oauth/*` -- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` -- Usage: `src/app/api/usage/*` -- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` -- CLI tooling helpers: `src/app/api/cli-tools/*` -- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) -- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) -- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) -- Sessions: `src/app/api/sessions` (GET) -- Rate limits: `src/app/api/rate-limits` (GET) -- Resilience: `src/app/api/resilience` (GET/PATCH) โ€” provider profiles, circuit breaker, rate limit state -- Resilience reset: `src/app/api/resilience/reset` (POST) โ€” reset breakers + cooldowns -- Cache stats: `src/app/api/cache/stats` (GET/DELETE) -- Model availability: `src/app/api/models/availability` (GET/POST) -- Telemetry: `src/app/api/telemetry/summary` (GET) -- Budget: `src/app/api/usage/budget` (GET/POST) -- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) -- Compliance audit: `src/app/api/compliance/audit-log` (GET) -- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) -- Policies: `src/app/api/policies` (GET/POST) - -## 2) SSE + 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` -- Response sanitization: `open-sse/handlers/responseSanitizer.ts` -- Role normalization: `open-sse/services/roleNormalizer.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`, `qoder.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 (SQLite): - -- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) -- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) -- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) -- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** - -Usage persistence: - -- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) -- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` -- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) -- legacy JSON files are migrated to SQLite by startup migrations when present - -Domain State DB (SQLite): - -- `src/lib/db/domainState.ts` โ€” CRUD operations 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: - -- primary runtime DB: `${DATA_DIR}/storage.sqlite` -- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) -- structured call payload archives: `${DATA_DIR}/call_logs/` -- optional translator/request debug sessions: `/logs/...` - -## Deployment Topology - -```mermaid -flowchart LR - 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[(storage.sqlite)] - UsageDB[(usage tables + log artifacts)] - end - - subgraph External[External Services] - Providers[AI Providers] - SyncCloud[Cloud Sync Service] - end - - CLI --> Next - Browser --> Next - Next --> Core - Next --> MainDB - Core --> MainDB - Core --> UsageDB - Core --> Providers - Next --> SyncCloud -``` - -## Module Mapping (Decision-Critical) - -### Route and API Modules - -- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs -- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) -- `src/app/api/providers*`: provider CRUD, validation, testing -- `src/app/api/provider-nodes*`: custom compatible node management -- `src/app/api/provider-models`: custom model management (CRUD) -- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) -- `src/app/api/oauth/*`: OAuth/device-code flows -- `src/app/api/keys*`: local API key lifecycle -- `src/app/api/models/alias`: alias management -- `src/app/api/combos*`: fallback combo management -- `src/app/api/pricing`: pricing overrides for cost calculation -- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) -- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) -- `src/app/api/usage/*`: usage and logs APIs -- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers -- `src/app/api/cli-tools/*`: local CLI config writers/checkers -- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) -- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) -- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) -- `src/app/api/sessions`: active session listing (GET) -- `src/app/api/rate-limits`: per-account rate limit status (GET) - -### Routing and Execution Core - -- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop -- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup -- `open-sse/executors/*`: provider-specific network and format behavior - -### Translation Registry and Format Converters - -- `open-sse/translator/index.ts`: translator registry and orchestration -- Request translators: `open-sse/translator/request/*` -- Response translators: `open-sse/translator/response/*` -- Format constants: `open-sse/translator/formats.ts` - -### Persistence - -- `src/lib/db/*`: persistent config/state and domain persistence on SQLite -- `src/lib/localDb.ts`: compatibility re-export for DB modules -- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables - -## Provider Executor Coverage (Strategy Pattern) - -Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. - -| Executor | Provider(s) | Special Handling | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | -| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, Qoder, 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 | -| Qoder | openai | OAuth (Basic) | โœ… | โœ… | โœ… | โš ๏ธ Per request | -| OpenRouter | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| GLM/Kimi/MiniMax | claude | API Key | โœ… | โœ… | โŒ | โŒ | -| DeepSeek | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Groq | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| xAI (Grok) | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Mistral | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Perplexity | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Together AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Fireworks AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Cerebras | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Cohere | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| NVIDIA NIM | openai | API Key | โœ… | โœ… | โŒ | โŒ | - -## Format Translation Coverage - -Detected source formats include: - -- `openai` -- `openai-responses` -- `claude` -- `gemini` - -Target formats include: - -- OpenAI chat/Responses -- Claude -- Gemini/Gemini-CLI/Antigravity envelope -- Kiro -- Cursor - -Translations use **OpenAI as the hub format** โ€” all conversions go through OpenAI as intermediate: - -``` -Source Format โ†’ OpenAI (hub) โ†’ Target Format -``` - -Translations are selected dynamically based on source payload shape and provider target format. - -Additional processing layers in the translation pipeline: - -- **Response sanitization** โ€” Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance -- **Role normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI targets; merges `system` โ†’ `user` for models that reject the system role (GLM, ERNIE) -- **Think tag extraction** โ€” Parses `...` blocks from content into `reasoning_content` field -- **Structured output** โ€” Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` - -## Supported API Endpoints - -| 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 `/logs//` 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 - -- SQLite schema migrations and auto-upgrade hooks at startup -- legacy JSON โ†’ SQLite migration compatibility path - -## Observability and Operational Signals - -Runtime visibility sources: - -- console logs from `src/sse/utils/logger.ts` -- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) -- textual request status log in `log.txt` (optional/compat) -- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` -- dashboard usage endpoints (`/api/usage/*`) for UI consumption - -## Security-Sensitive Boundaries - -- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing -- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning -- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format -- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level -- Cloud sync endpoints rely on API key auth + machine id semantics - -## Environment and Runtime Matrix - -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` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. -2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. -3. Request logger writes full headers/body when enabled; treat log directory as sensitive. -4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. -5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. -6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). -7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). -8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). - -## Operational Verification Checklist - -- Build from source: `npm run build` -- Build Docker image: `docker build -t omniroute .` -- Start service and verify: -- `GET /api/settings` -- `GET /api/v1/models` -- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/sv/AUTO-COMBO.md b/docs/i18n/sv/AUTO-COMBO.md deleted file mode 100644 index 2166e41dff..0000000000 --- a/docs/i18n/sv/AUTO-COMBO.md +++ /dev/null @@ -1,67 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/AUTO-COMBO.md) - ---- - -# OmniRoute Auto-Combo Engine - -> Self-managing model chains with adaptive scoring - -## How It Works - -The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**: - -| Factor | Weight | Description | -| :--------- | :----- | :---------------------------------------------- | -| Quota | 0.20 | Remaining capacity [0..1] | -| Health | 0.25 | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 | -| CostInv | 0.20 | Inverse cost (cheaper = higher score) | -| LatencyInv | 0.15 | Inverse p95 latency (faster = higher) | -| TaskFit | 0.10 | Model ร— task type fitness score | -| Stability | 0.10 | Low variance in latency/errors | - -## Mode Packs - -| Pack | Focus | Key Weight | -| :---------------------- | :----------- | :--------------- | -| ๐Ÿš€ **Ship Fast** | Speed | latencyInv: 0.35 | -| ๐Ÿ’ฐ **Cost Saver** | Economy | costInv: 0.40 | -| ๐ŸŽฏ **Quality First** | Best model | taskFit: 0.40 | -| ๐Ÿ“ก **Offline Friendly** | Availability | quota: 0.40 | - -## Self-Healing - -- **Temporary exclusion**: Score < 0.2 โ†’ excluded for 5 min (progressive backoff, max 30 min) -- **Circuit breaker awareness**: OPEN โ†’ auto-excluded; HALF_OPEN โ†’ probe requests -- **Incident mode**: >50% OPEN โ†’ disable exploration, maximize stability -- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout - -## Bandit Exploration - -5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode. - -## API - -```bash -# Create auto-combo -curl -X POST http://localhost:20128/api/combos/auto \ - -H "Content-Type: application/json" \ - -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}' - -# List auto-combos -curl http://localhost:20128/api/combos/auto -``` - -## Task Fitness - -30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` โ†’ high coding score). - -## Files - -| File | Purpose | -| :------------------------------------------- | :------------------------------------ | -| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization | -| `open-sse/services/autoCombo/taskFitness.ts` | Model ร— task fitness lookup | -| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap | -| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode | -| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles | -| `src/app/api/combos/auto/route.ts` | REST API | diff --git a/docs/i18n/sv/CHANGELOG.md b/docs/i18n/sv/CHANGELOG.md index 877bbdcac8..67fcb2e9ad 100644 --- a/docs/i18n/sv/CHANGELOG.md +++ b/docs/i18n/sv/CHANGELOG.md @@ -1,12 +1,92 @@ # Changelog (Svenska) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CHANGELOG.md) --- - ## [Unreleased] +### ๐Ÿ› ๏ธ Maintenance + +- **AGENTS.md rewrite:** Condensed from 297โ†’153 lines. Added build/lint/test commands (including single-test execution), code style guidelines (Prettier, TypeScript, ESLint, naming, imports, error handling, security), and trimmed verbose architecture tables for AI agent consumption. + +## [3.4.2] - 2026-04-01 + +### ๐Ÿ› Bug Fixes + +- **CI Stabilization:** Fixed failing analytics/settings Playwright selectors and request assertions so GitHub Actions E2E runs pass reliably across localized UIs and switch-based controls. +- **Deterministic Tests:** Removed date-sensitive quota fixtures from Copilot usage tests and aligned idempotency/model catalog tests with the merged runtime behavior. +- **MCP Type Hardening:** Removed zero-budget explicit `any` regressions from the MCP server tool registration path, restoring the `check:any-budget:t11` workflow gate. + +### ๐Ÿ› ๏ธ Maintenance + +- **Release Branch Integration:** Consolidated the active feature branches into `release/v3.4.2` on top of current `main` and validated the branch with lint, unit, coverage, build, and CI-mode E2E runs. + +## [3.4.1] - 2026-03-31 + +> [!WARNING] +> **BREAKING CHANGE: request logging, retention, and logging environment variables have been redesigned.** +> On the first startup after upgrading, OmniRoute archives legacy request logs from `DATA_DIR/logs/`, legacy `DATA_DIR/call_logs/`, and `DATA_DIR/log.txt` into `DATA_DIR/log_archives/*.zip`, then removes the deprecated layout and switches to the new unified artifact format under `DATA_DIR/call_logs/`. + +### โœจ New Features + +- **.ENV Migration Utility:** Included `scripts/migrate-env.mjs` to seamlessly migrate ` Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` - ---- - -## Step 2 โ€” Install CLI Tools - -All npm-based tools require Node.js 18+: - -```bash -# Claude Code (Anthropic) -npm install -g @anthropic-ai/claude-code - -# OpenAI Codex -npm install -g @openai/codex - -# Gemini CLI (Google) -npm install -g @google/gemini-cli - -# OpenCode -npm install -g opencode-ai - -# Cline -npm install -g cline - -# KiloCode -npm install -g kilecode - -# Kiro CLI (Amazon โ€” requires curl + unzip) -apt-get install -y unzip # on Debian/Ubuntu -curl -fsSL https://cli.kiro.dev/install | bash -export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc -``` - -**Verify:** - -```bash -claude --version # 2.x.x -codex --version # 0.x.x -gemini --version # 0.x.x -opencode --version # x.x.x -cline --version # 2.x.x -kilocode --version # x.x.x (or: kilo --version) -kiro-cli --version # 1.x.x -``` - ---- - -## Step 3 โ€” Set Global Environment Variables - -Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`: - -```bash -# OmniRoute Universal Endpoint -export OPENAI_BASE_URL="http://localhost:20128/v1" -export OPENAI_API_KEY="sk-your-omniroute-key" -export ANTHROPIC_BASE_URL="http://localhost:20128/v1" -export ANTHROPIC_API_KEY="sk-your-omniroute-key" -export GEMINI_BASE_URL="http://localhost:20128/v1" -export GEMINI_API_KEY="sk-your-omniroute-key" -``` - -> For a **remote server** replace `localhost:20128` with the server IP or domain, -> e.g. `http://192.168.0.15:20128`. - ---- - -## Step 4 โ€” Configure Each Tool - -### Claude Code - -```bash -# Via CLI: -claude config set --global api-base-url http://localhost:20128/v1 - -# Or create ~/.claude/settings.json: -mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF -{ - "apiBaseUrl": "http://localhost:20128/v1", - "apiKey": "sk-your-omniroute-key" -} -EOF -``` - -**Test:** `claude "say hello"` - ---- - -### OpenAI Codex - -```bash -mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF -model: auto -apiKey: sk-your-omniroute-key -apiBaseUrl: http://localhost:20128/v1 -EOF -``` - -**Test:** `codex "what is 2+2?"` - ---- - -### Gemini CLI - -```bash -mkdir -p ~/.gemini && cat > ~/.gemini/settings.json << EOF -{ - "apiKey": "sk-your-omniroute-key", - "baseUrl": "http://localhost:20128/v1" -} -EOF -``` - -**Test:** `gemini "hello"` - ---- - -### OpenCode - -```bash -mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF -[provider.openai] -base_url = "http://localhost:20128/v1" -api_key = "sk-your-omniroute-key" -EOF -``` - -**Test:** `opencode` - ---- - -### Cline (CLI or VS Code) - -**CLI mode:** - -```bash -mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF -{ - "apiProvider": "openai", - "openAiBaseUrl": "http://localhost:20128/v1", - "openAiApiKey": "sk-your-omniroute-key" -} -EOF -``` - -**VS Code mode:** -Cline extension settings โ†’ API Provider: `OpenAI Compatible` โ†’ Base URL: `http://localhost:20128/v1` - -Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ Cline โ†’ Apply Config**. - ---- - -### KiloCode (CLI or VS Code) - -**CLI mode:** - -```bash -kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key -``` - -**VS Code settings:** - -```json -{ - "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", - "kilo-code.apiKey": "sk-your-omniroute-key" -} -``` - -Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ KiloCode โ†’ Apply Config**. - ---- - -### Continue (VS Code Extension) - -Edit `~/.continue/config.yaml`: - -```yaml -models: - - name: OmniRoute - provider: openai - model: auto - apiBase: http://localhost:20128/v1 - apiKey: sk-your-omniroute-key - default: true -``` - -Restart VS Code after editing. - ---- - -### Kiro CLI (Amazon) - -```bash -# Login to your AWS/Kiro account: -kiro-cli login - -# The CLI uses its own auth โ€” OmniRoute is not needed as backend for Kiro CLI itself. -# Use kiro-cli alongside OmniRoute for other tools. -kiro-cli status -``` - ---- - -### Cursor (Desktop App) - -> **Note:** Cursor routes requests through its cloud. For OmniRoute integration, -> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL. - -Via GUI: **Settings โ†’ Models โ†’ OpenAI API Key** - -- Base URL: `https://your-domain.com/v1` -- API Key: your OmniRoute key - ---- - -## Dashboard Auto-Configuration - -The OmniRoute dashboard automates configuration for most tools: - -1. Go to `http://localhost:20128/dashboard/cli-tools` -2. Expand any tool card -3. Select your API key from the dropdown -4. Click **Apply Config** (if tool is detected as installed) -5. Or copy the generated config snippet manually - ---- - -## Built-in Agents: Droid & OpenClaw - -**Droid** and **OpenClaw** are AI agents built directly into OmniRoute โ€” no installation needed. -They run as internal routes and use OmniRoute's model routing automatically. - -- Access: `http://localhost:20128/dashboard/agents` -- Configure: same combos and providers as all other tools -- No API key or CLI install required - ---- - -## Available API Endpoints - -| Endpoint | Description | Use For | -| -------------------------- | ----------------------------- | --------------------------- | -| `/v1/chat/completions` | Standard chat (all providers) | All modern tools | -| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows | -| `/v1/completions` | Legacy text completions | Older tools using `prompt:` | -| `/v1/embeddings` | Text embeddings | RAG, search | -| `/v1/images/generations` | Image generation | DALL-E, Flux, etc. | -| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS | -| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI | - ---- - -## Troubleshooting - -| Error | Cause | Fix | -| ------------------------- | ----------------------- | ------------------------------------------ | -| `Connection refused` | OmniRoute not running | `pm2 start omniroute` | -| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` | -| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` | -| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` | -| CLI shows "not installed" | Binary not in PATH | Check `which ` | -| `kiro-cli: not found` | Not in PATH | `export PATH="$HOME/.local/bin:$PATH"` | - ---- - -## Quick Setup Script (One Command) - -```bash -# Install all CLIs and configure for OmniRoute (replace with your key and server URL) -OMNIROUTE_URL="http://localhost:20128/v1" -OMNIROUTE_KEY="sk-your-omniroute-key" - -npm install -g @anthropic-ai/claude-code @openai/codex @google/gemini-cli opencode-ai cline kilecode - -# Kiro CLI -apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash - -# Write configs -mkdir -p ~/.claude ~/.codex ~/.gemini ~/.config/opencode ~/.continue - -cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" -cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" -cat > ~/.gemini/settings.json <<< "{\"apiKey\":\"$OMNIROUTE_KEY\",\"baseUrl\":\"$OMNIROUTE_URL\"}" -cat >> ~/.bashrc << EOF -export OPENAI_BASE_URL="$OMNIROUTE_URL" -export OPENAI_API_KEY="$OMNIROUTE_KEY" -export ANTHROPIC_BASE_URL="$OMNIROUTE_URL" -export ANTHROPIC_API_KEY="$OMNIROUTE_KEY" -EOF - -source ~/.bashrc -echo "โœ… All CLIs installed and configured for OmniRoute" -``` diff --git a/docs/i18n/sv/CODEBASE_DOCUMENTATION.md b/docs/i18n/sv/CODEBASE_DOCUMENTATION.md deleted file mode 100644 index e2d7950052..0000000000 --- a/docs/i18n/sv/CODEBASE_DOCUMENTATION.md +++ /dev/null @@ -1,593 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CODEBASE_DOCUMENTATION.md) - ---- - -# omniroute โ€” Codebase Documentation - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) - -> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. - ---- - -## 1. 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
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, Qoder, 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 | -| Qoder | 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"] -``` diff --git a/docs/i18n/sv/CONTRIBUTING.md b/docs/i18n/sv/CONTRIBUTING.md new file mode 100644 index 0000000000..5eec17b927 --- /dev/null +++ b/docs/i18n/sv/CONTRIBUTING.md @@ -0,0 +1,299 @@ +# Contributing to OmniRoute (Svenska) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CONTRIBUTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CONTRIBUTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CONTRIBUTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CONTRIBUTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CONTRIBUTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CONTRIBUTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CONTRIBUTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CONTRIBUTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CONTRIBUTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CONTRIBUTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CONTRIBUTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CONTRIBUTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CONTRIBUTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CONTRIBUTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CONTRIBUTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CONTRIBUTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CONTRIBUTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CONTRIBUTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CONTRIBUTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CONTRIBUTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CONTRIBUTING.md) + +--- + +Thank you for your interest in contributing! This guide covers everything you need to get started. + +--- + +## Development Setup + +### Prerequisites + +- **Node.js** >= 18 < 24 (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` | `20128` | Server port | +| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | Base URL for frontend | +| `JWT_SECRET` | (generate above) | JWT signing secret | +| `INITIAL_PASSWORD` | `CHANGEME` | First login password | +| `APP_LOG_LEVEL` | `info` | Log verbosity level | + +### Dashboard Settings + +The dashboard provides UI toggles for features that can also be configured via environment variables: + +| Setting Location | Toggle | Description | +| ------------------- | ------------------ | ------------------------------ | +| Settings โ†’ Advanced | Debug Mode | Enable debug request logs (UI) | +| Settings โ†’ General | Sidebar Visibility | Show/hide sidebar sections | + +These settings are stored in the database and persist across restarts, overriding env var defaults when set. + +### 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:20128/dashboard` +- **API**: `http://localhost:20128/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`, `mcp`, `a2a`, `memory`, `skills`. + +--- + +## Running Tests + +```bash +# All tests (unit + vitest + ecosystem + e2e) +npm run test:all + +# Single test file (Node.js native test runner โ€” most tests use this) +node --import tsx/esm --test tests/unit/your-file.test.mjs + +# Vitest (MCP server, autoCombo, cache) +npm run test:vitest + +# E2E tests (requires Playwright) +npm run test:e2e + +# Protocol clients E2E (MCP transports, A2A) +npm run test:protocols:e2e + +# Ecosystem compatibility tests +npm run test:ecosystem + +# Coverage (55% min statements/lines/functions; 60% branches) +npm run test:coverage +npm run coverage:report + +# Lint + format check +npm run lint +npm run check +``` + +Coverage notes: + +- `npm run test:coverage` measures source coverage for the main unit test suite, excludes `tests/**`, and includes `open-sse/**` +- `npm run coverage:report` prints the detailed file-by-file report from the latest coverage run +- `npm run test:coverage:legacy` preserves the older metric for historical comparison +- See `docs/COVERAGE_PLAN.md` for the phased coverage improvement roadmap + +Current test status: **122 unit test files** covering: + +- Provider translators and format conversion +- Rate limiting, circuit breaker, and resilience +- Semantic cache, idempotency, progress tracking +- Database operations and schema (21 DB modules) +- OAuth flows and authentication +- API endpoint validation (Zod v4) +- MCP server tools and scope enforcement +- Memory and Skills systems + +--- + +## Code Style + +- **ESLint** โ€” Run `npm run lint` before committing +- **Prettier** โ€” Auto-formatted via `lint-staged` on commit (2 spaces, semicolons, double quotes, 100 char width, es5 trailing commas) +- **TypeScript** โ€” All `src/` code uses `.ts`/`.tsx`; `open-sse/` uses `.ts`/`.js`; document with TSDoc (`@param`, `@returns`, `@throws`) +- **No `eval()`** โ€” ESLint enforces `no-eval`, `no-implied-eval`, `no-new-func` +- **Zod validation** โ€” Use Zod v4 schemas for all API input validation +- **Naming**: Files = camelCase/kebab-case, components = PascalCase, constants = UPPER_SNAKE + +--- + +## Project Structure + +``` +src/ # TypeScript (.ts / .tsx) +โ”œโ”€โ”€ app/ # Next.js 16 App Router +โ”‚ โ”œโ”€โ”€ (dashboard)/ # Dashboard pages (23 sections) +โ”‚ โ”œโ”€โ”€ api/ # API routes (51 directories) +โ”‚ โ””โ”€โ”€ login/ # Auth pages (.tsx) +โ”œโ”€โ”€ domain/ # Policy engine (policyEngine, comboResolver, costRules, etc.) +โ”œโ”€โ”€ lib/ # Core business logic (.ts) +โ”‚ โ”œโ”€โ”€ a2a/ # Agent-to-Agent v0.3 protocol server +โ”‚ โ”œโ”€โ”€ acp/ # Agent Communication Protocol registry +โ”‚ โ”œโ”€โ”€ compliance/ # Compliance policy engine +โ”‚ โ”œโ”€โ”€ db/ # SQLite database layer (21 modules + 16 migrations) +โ”‚ โ”œโ”€โ”€ memory/ # Persistent conversational memory +โ”‚ โ”œโ”€โ”€ oauth/ # OAuth providers, services, and utilities +โ”‚ โ”œโ”€โ”€ skills/ # Extensible skill framework +โ”‚ โ”œโ”€โ”€ usage/ # Usage tracking and cost calculation +โ”‚ โ””โ”€โ”€ localDb.ts # Re-export layer only โ€” never add logic here +โ”œโ”€โ”€ middleware/ # Request middleware (promptInjectionGuard) +โ”œโ”€โ”€ mitm/ # MITM proxy (cert, DNS, target routing) +โ”œโ”€โ”€ shared/ +โ”‚ โ”œโ”€โ”€ components/ # React components (.tsx) +โ”‚ โ”œโ”€โ”€ constants/ # Provider definitions (60+), MCP scopes, routing strategies +โ”‚ โ”œโ”€โ”€ utils/ # Circuit breaker, sanitizer, auth helpers +โ”‚ โ””โ”€โ”€ validation/ # Zod v4 schemas +โ””โ”€โ”€ sse/ # SSE proxy pipeline + +open-sse/ # @omniroute/open-sse workspace +โ”œโ”€โ”€ executors/ # 14 provider-specific request executors +โ”œโ”€โ”€ handlers/ # 11 request handlers (chat, responses, embeddings, images, etc.) +โ”œโ”€โ”€ mcp-server/ # MCP server (25 tools, 3 transports, 10 scopes) +โ”œโ”€โ”€ services/ # 36+ services (combo, autoCombo, rateLimitManager, etc.) +โ”œโ”€โ”€ translator/ # Format translators (OpenAI โ†” Claude โ†” Gemini โ†” Responses โ†” Ollama) +โ”œโ”€โ”€ transformer/ # Responses API transformer +โ””โ”€โ”€ utils/ # 22 utility modules (stream, TLS, proxy, logging) + +electron/ # Electron desktop app (cross-platform) + +tests/ +โ”œโ”€โ”€ unit/ # Node.js test runner (122 test files) +โ”œโ”€โ”€ integration/ # Integration tests +โ”œโ”€โ”€ e2e/ # Playwright tests +โ”œโ”€โ”€ security/ # Security tests +โ”œโ”€โ”€ translator/ # Translator-specific tests +โ””โ”€โ”€ load/ # Load tests + +docs/ # Documentation +โ”œโ”€โ”€ ARCHITECTURE.md # System architecture +โ”œโ”€โ”€ API_REFERENCE.md # All endpoints +โ”œโ”€โ”€ USER_GUIDE.md # Provider setup, CLI integration +โ”œโ”€โ”€ TROUBLESHOOTING.md # Common issues +โ”œโ”€โ”€ MCP-SERVER.md # MCP server (25 tools) +โ”œโ”€โ”€ A2A-SERVER.md # A2A agent protocol +โ”œโ”€โ”€ AUTO-COMBO.md # Auto-combo engine +โ”œโ”€โ”€ CLI-TOOLS.md # CLI tools integration +โ”œโ”€โ”€ COVERAGE_PLAN.md # Test coverage improvement plan +โ”œโ”€โ”€ openapi.yaml # OpenAPI specification +โ””โ”€โ”€ adr/ # Architecture Decision Records +``` + +--- + +## Adding a New Provider + +### Step 1: Register Provider Constants + +Add to `src/shared/constants/providers.ts` โ€” Zod-validated at module load. + +### Step 2: Add Executor (if custom logic needed) + +Create executor in `open-sse/executors/your-provider.ts` extending the base executor. + +### Step 3: Add Translator (if non-OpenAI format) + +Create request/response translators in `open-sse/translator/`. + +### Step 4: Add OAuth Config (if OAuth-based) + +Add OAuth credentials in `src/lib/oauth/constants/oauth.ts` and service in `src/lib/oauth/services/`. + +### Step 5: Register Models + +Add model definitions in `open-sse/config/providerRegistry.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 +- [ ] All inputs validated with Zod schemas +- [ ] CHANGELOG updated (if user-facing change) +- [ ] Documentation updated (if applicable) + +--- + +## Releasing + +Releases are managed via the `/generate-release` workflow. When a new GitHub Release is created, the package is **automatically published to npm** via GitHub Actions. + +--- + +## Getting Help + +- **Architecture**: See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) +- **API Reference**: See [`docs/API_REFERENCE.md`](docs/API_REFERENCE.md) +- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **ADRs**: See `docs/adr/` for architectural decision records diff --git a/docs/i18n/sv/FEATURES.md b/docs/i18n/sv/FEATURES.md deleted file mode 100644 index 7ace6cbdb5..0000000000 --- a/docs/i18n/sv/FEATURES.md +++ /dev/null @@ -1,147 +0,0 @@ -# OmniRoute โ€” Dashboard Features Gallery (Svenska) - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) - -> ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../docs/FEATURES.md) - ---- - -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 (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. - -![Providers Dashboard](screenshots/01-providers.png) - ---- - -## ๐ŸŽจ Combos - -Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. - -![Combos Dashboard](screenshots/02-combos.png) - ---- - -## ๐Ÿ“Š Analytics - -Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. - -![Analytics Dashboard](screenshots/03-analytics.png) - ---- - -## ๐Ÿฅ System Health - -Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. - -![Health Dashboard](screenshots/04-health.png) - ---- - -## ๐Ÿ”ง Translator Playground - -Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). - -![Translator Playground](screenshots/05-translator.png) - ---- - -## ๐ŸŽฎ Model Playground _(v2.0.9+)_ - -Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. - ---- - -## ๐ŸŽจ Themes _(v2.0.5+)_ - -Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. - ---- - -## โš™๏ธ Settings - -Comprehensive settings panel with tabs: - -- **General** โ€” System storage, backup management (export/import database) -- **Appearance** โ€” Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls -- **Security** โ€” API endpoint protection, custom provider blocking, IP filtering, session info -- **Routing** โ€” Model aliases, background task degradation -- **Resilience** โ€” Rate limit persistence, circuit breaker tuning -- **Advanced** โ€” Configuration overrides - -![Settings Dashboard](screenshots/06-settings.png) - ---- - -## ๐Ÿ”ง CLI Tools - -One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. - -![CLI Tools Dashboard](screenshots/07-cli-tools.png) - ---- - -## ๐Ÿค– CLI Agents _(v2.0.11+)_ - -Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: - -- **Installation status** โ€” Installed / Not Found with version detection -- **Protocol badges** โ€” stdio, HTTP, etc. -- **Custom agents** โ€” Register any CLI tool via form (name, binary, version command, spawn args) -- **CLI Fingerprint Matching** โ€” Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP - ---- - -## ๐Ÿ–ผ๏ธ Media _(v2.0.3+)_ - -Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. - ---- - -## ๐Ÿ“ Request Logs - -Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. - -![Usage Logs](screenshots/08-usage.png) - ---- - -## ๐ŸŒ API Endpoint - -Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. - -![Endpoint Dashboard](screenshots/09-endpoint.png) - ---- - -## ๐Ÿ”‘ API Key Management - -Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. - ---- - -## ๐Ÿ“‹ Audit Log - -Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. - ---- - -## ๐Ÿ–ฅ๏ธ Desktop Application - -Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. - -Key features: - -- Server readiness polling (no blank screen on cold start) -- System tray with port management -- Content Security Policy -- Single-instance lock -- Auto-update on restart -- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) -- Hardened Electron build packaging โ€” symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+) - -๐Ÿ“– See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/sv/MCP-SERVER.md b/docs/i18n/sv/MCP-SERVER.md deleted file mode 100644 index 829acd30b1..0000000000 --- a/docs/i18n/sv/MCP-SERVER.md +++ /dev/null @@ -1,87 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/MCP-SERVER.md) - ---- - -# OmniRoute MCP Server Documentation - -> Model Context Protocol server with 16 intelligent tools - -## Installation - -OmniRoute MCP is built-in. Start it with: - -```bash -omniroute --mcp -``` - -Or via the open-sse transport: - -```bash -# HTTP streamable transport (port 20130) -omniroute --dev # MCP auto-starts on /mcp endpoint -``` - -## IDE Configuration - -See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup. - ---- - -## Essential Tools (8) - -| Tool | Description | -| :------------------------------ | :--------------------------------------- | -| `omniroute_get_health` | Gateway health, circuit breakers, uptime | -| `omniroute_list_combos` | All configured combos with models | -| `omniroute_get_combo_metrics` | Performance metrics for a specific combo | -| `omniroute_switch_combo` | Switch active combo by ID/name | -| `omniroute_check_quota` | Quota status per provider or all | -| `omniroute_route_request` | Send a chat completion through OmniRoute | -| `omniroute_cost_report` | Cost analytics for a time period | -| `omniroute_list_models_catalog` | Full model catalog with capabilities | - -## Advanced Tools (8) - -| Tool | Description | -| :--------------------------------- | :---------------------------------------------- | -| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | -| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | -| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | -| `omniroute_test_combo` | Live-test all models in a combo | -| `omniroute_get_provider_metrics` | Detailed metrics for one provider | -| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | -| `omniroute_explain_route` | Explain a past routing decision | -| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | - -## Authentication - -MCP tools are authenticated via API key scopes. Each tool requires specific scopes: - -| Scope | Tools | -| :------------- | :----------------------------------------------- | -| `read:health` | get_health, get_provider_metrics | -| `read:combos` | list_combos, get_combo_metrics | -| `write:combos` | switch_combo | -| `read:quota` | check_quota | -| `write:route` | route_request, simulate_route, test_combo | -| `read:usage` | cost_report, get_session_snapshot, explain_route | -| `write:config` | set_budget_guard, set_resilience_profile | -| `read:models` | list_models_catalog, best_combo_for_task | - -## Audit Logging - -Every tool call is logged to `mcp_tool_audit` with: - -- Tool name, arguments, result -- Duration (ms), success/failure -- API key hash, timestamp - -## Files - -| File | Purpose | -| :------------------------------------------- | :------------------------------------------ | -| `open-sse/mcp-server/server.ts` | MCP server creation + 16 tool registrations | -| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport | -| `open-sse/mcp-server/auth.ts` | API key + scope validation | -| `open-sse/mcp-server/audit.ts` | Tool call audit logging | -| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers | diff --git a/docs/i18n/sv/README.md b/docs/i18n/sv/README.md index 8cabca67cc..b181d60255 100644 --- a/docs/i18n/sv/README.md +++ b/docs/i18n/sv/README.md @@ -1,12 +1,12 @@ # ๐Ÿš€ OmniRoute โ€” The Free AI Gateway (Svenska) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/README.md) --- ### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback. -_Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._ +_Your universal API proxy โ€” one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._ **Chat Completions โ€ข Embeddings โ€ข Image Generation โ€ข Video โ€ข Music โ€ข Audio โ€ข Reranking โ€ข **Web Search** โ€ข MCP Server โ€ข A2A Protocol โ€ข 100% TypeScript** @@ -46,15 +46,17 @@ _Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now wi > - `APP_LOG_FILE_PATH` > - `APP_LOG_MAX_FILE_SIZE` > - `APP_LOG_RETENTION_DAYS` +> - `APP_LOG_MAX_FILES` > - `APP_LOG_LEVEL` > - `APP_LOG_FORMAT` > - `CALL_LOG_RETENTION_DAYS` +> - `CALL_LOG_MAX_ENTRIES` > > For release details and upgrade notes, see the [CHANGELOG](CHANGELOG.md). --- -## ๐Ÿ†• What's New in v3.0.0 +## ๐Ÿ†• What's New > **Upgrading from v2.9.5?** โ€” See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes. @@ -274,7 +276,7 @@ Developers pay $20โ€“200/month for Claude Pro, Codex Pro, or GitHub Copilot. Eve - **Smart 4-Tier Fallback** โ€” If subscription quota runs out, automatically redirects to API Key โ†’ Cheap โ†’ Free with zero manual intervention - **Real-Time Quota Tracking** โ€” Shows token consumption in real-time with reset countdown (5h, daily, weekly) - **Multi-Account Support** โ€” Multiple accounts per provider with auto round-robin โ€” when one runs out, switches to the next -- **Custom Combos** โ€” Customizable fallback chains with 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Custom Combos** โ€” Customizable fallback chains with 9 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random) - **Codex Business Quotas** โ€” Business/Team workspace quota monitoring directly in the dashboard @@ -286,7 +288,7 @@ OpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If **How OmniRoute solves it:** -- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 67+ providers +- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 60+ providers - **Format Translation** โ€” Automatic and transparent: OpenAI โ†” Claude โ†” Gemini โ†” Responses API - **Response Sanitization** โ€” Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+ - **Role Normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI providers; `system` โ†’ `user` for GLM/ERNIE @@ -372,7 +374,7 @@ Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code.. - **CLI Tools Dashboard** โ€” Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline - **GitHub Copilot Config Generator** โ€” Generates `chatLanguageModels.json` for VS Code with bulk model selection - **Onboarding Wizard** โ€” Guided 4-step setup for first-time users -- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 67+ providers +- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 60+ providers @@ -419,7 +421,7 @@ When a call fails, the dev doesn't know if it was a rate limit, expired token, w - **SQLite Proxy Logs** โ€” Persistent logs that survive server restarts - **Translator Playground** โ€” 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time) - **Request Telemetry** โ€” p50/p95/p99 latency + X-Request-Id tracing -- **File-Based Logging with Rotation** โ€” Console interceptor captures everything to JSON log with size-based rotation +- **File-Based Logging with Rotation** โ€” App logs rotate by size, retention days, and archive count; call log artifacts rotate by retention days and file count - **System Info Report** โ€” `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage. @@ -514,7 +516,7 @@ Developers who want all responses in a specific language, with a specific tone, - **System Prompt Injection** โ€” Global prompt applied to all requests - **Thinking Budget Validation** โ€” Reasoning token allocation control per request (passthrough, auto, custom, adaptive) -- **6 Routing Strategies** โ€” Global strategies that determine how requests are distributed +- **9 Routing Strategies** โ€” Global strategies that determine how requests are distributed - **Wildcard Router** โ€” `provider/*` patterns route dynamically to any provider - **Combo Enable/Disable Toggle** โ€” Toggle combos directly from the dashboard - **Provider Toggle** โ€” Enable/disable all connections for a provider with one click @@ -581,7 +583,7 @@ Different clients should have least-privilege access to tool categories. **How OmniRoute solves it:** -- 9 granular MCP scopes for controlled tool access +- 10 granular MCP scopes for controlled tool access - Scope enforcement and visibility in MCP management UI - Safe default posture for operational tooling @@ -1325,19 +1327,19 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. ### ๐Ÿค– Agent & Protocol Operations (v2.0) -| Feature | What It Does | -| ------------------------------------- | -------------------------------------------------------------------------------------------------- | -| ๐Ÿ”ง **MCP Server (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) | -| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | -| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | -| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | -| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | -| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | -| ๐Ÿ” **MCP Scope Enforcement** | 9 granular scope permissions for controlled tool access | -| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | -| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | -| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | -| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | +| Feature | What It Does | +| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| ๐Ÿ”ง **MCP Server (25 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools | +| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | +| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | +| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | +| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | +| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | +| ๐Ÿ” **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access | +| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | +| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | +| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | +| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | ### ๐Ÿง  Routing & Intelligence @@ -1348,7 +1350,7 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. | ๐Ÿ”„ **Format Translation** | OpenAI โ†” Claude โ†” Gemini โ†” Responses with schema-safe conversions | | ๐Ÿ‘ฅ **Multi-Account Support** | Multiple accounts per provider with intelligent selection | | ๐Ÿ”„ **Auto Token Refresh** | OAuth tokens refresh automatically with retry | -| ๐ŸŽจ **Custom Combos** | 6 balancing strategies + fallback chain control | +| ๐ŸŽจ **Custom Combos** | 9 balancing strategies + fallback chain control | | ๐ŸŒ **Wildcard Router** | `provider/*` dynamic routing | | ๐Ÿง  **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits | | ๐Ÿ”€ **Model Aliases** | Built-in + custom model aliasing and migration safety | @@ -1949,6 +1951,7 @@ opencode - Request artifacts are written to `DATA_DIR/call_logs/` as one JSON file per request - Enable pipeline capture from Dashboard โ†’ Logs โ†’ Request Logs if you need detailed per-stage payloads - Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log` +- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed **Connection test shows "Invalid" for OpenAI-compatible providers** diff --git a/docs/i18n/sv/RELEASE_CHECKLIST.md b/docs/i18n/sv/RELEASE_CHECKLIST.md deleted file mode 100644 index 903e812c3f..0000000000 --- a/docs/i18n/sv/RELEASE_CHECKLIST.md +++ /dev/null @@ -1,37 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/RELEASE_CHECKLIST.md) - ---- - -# Release Checklist - -Use this checklist before tagging or publishing a new OmniRoute release. - -## Version and Changelog - -1. Bump `package.json` version (`x.y.z`) in the release branch. -2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: - - `## [x.y.z] โ€” YYYY-MM-DD` -3. Keep `## [Unreleased]` as the first changelog section for upcoming work. -4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. - -## API Docs - -1. Update `docs/openapi.yaml`: - - `info.version` must equal `package.json` version. -2. Validate endpoint examples if API contracts changed. - -## Runtime Docs - -1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. -2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. -3. Update localized docs if source docs changed significantly. - -## Automated Check - -Run the sync guard locally before opening PR: - -```bash -npm run check:docs-sync -``` - -CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/sv/SECURITY.md b/docs/i18n/sv/SECURITY.md new file mode 100644 index 0000000000..a4f2fa255f --- /dev/null +++ b/docs/i18n/sv/SECURITY.md @@ -0,0 +1,179 @@ +# Security Policy (Svenska) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../SECURITY.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/SECURITY.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/SECURITY.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/SECURITY.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/SECURITY.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/SECURITY.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/SECURITY.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/SECURITY.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/SECURITY.md) + +--- + +## 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 | +| ------- | -------------- | +| 3.4.x | โœ… Active | +| 3.0.x | โœ… Security | +| < 3.0.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 | +| **MCP Scopes** | 10 granular scopes for MCP tool access control | + +### ๐Ÿ›ก๏ธ 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:::` +- 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** | Allowlist/blocklist IP ranges in dashboard | +| **Rate Limiting** | Per-provider rate limits with automatic backoff | +| **Anti-Thundering Herd** | Mutex + per-connection locking prevents cascading 502s | +| **TLS Fingerprint** | Browser-like TLS fingerprint spoofing to reduce bot detection | +| **CLI Fingerprint** | Per-provider header/body ordering to match native CLI signatures | + +### ๐Ÿ”Œ Resilience & Availability + +| 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 `CALL_LOG_RETENTION_DAYS` | +| **No-Log Opt-out** | Per API key `noLog` flag disables request logging | +| **Audit Log** | Administrative actions tracked in `audit_log` table | +| **MCP Audit** | SQLite-backed audit logging for all MCP tool calls | +| **Zod Validation** | All API inputs validated with Zod v4 schemas at module load | + +--- + +## 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 +- Provider constants validated at module load via Zod (`src/shared/validation/providerSchema.ts`) diff --git a/docs/i18n/sv/TROUBLESHOOTING.md b/docs/i18n/sv/TROUBLESHOOTING.md deleted file mode 100644 index 63c148000a..0000000000 --- a/docs/i18n/sv/TROUBLESHOOTING.md +++ /dev/null @@ -1,258 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/TROUBLESHOOTING.md) - ---- - -# Troubleshooting - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/TROUBLESHOOTING.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/TROUBLESHOOTING.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/TROUBLESHOOTING.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/TROUBLESHOOTING.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/TROUBLESHOOTING.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/TROUBLESHOOTING.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/TROUBLESHOOTING.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/TROUBLESHOOTING.md) - -Common problems and solutions for OmniRoute. - ---- - -## Quick Fixes - -| Problem | Solution | -| ----------------------------- | ------------------------------------------------------------------ | -| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | -| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | -| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | -| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | -| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | - ---- - -## Provider Issues - -### "Language model did not provide messages" - -**Cause:** Provider quota exhausted. - -**Fix:** - -1. 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, Qoder) 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}/storage.sqlite` (providers, combos, aliases, keys, settings) -- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` -- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) - ---- - -## Circuit Breaker Issues - -### Provider stuck in OPEN state - -When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. - -**Fix:** - -1. 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 -- **SDK returns raw string instead of object** โ€” Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures -- **GLM/ERNIE rejects `system` role** โ€” Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models -- **`developer` role not recognized** โ€” Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers -- **`json_schema` not working with Gemini** โ€” Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` - ---- - -## Resilience Settings - -### Auto rate-limit not triggering - -- 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. - ---- - -## Optional RAG / LLM failure taxonomy (16 problems) - -Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. - -In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. - -If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: - -- retrieval drift and broken context boundaries -- empty or stale indexes and vector stores -- embedding versus semantic mismatch -- prompt assembly and context window issues -- logic collapse and overconfident answers -- long chain and agent coordination failures -- multi agent memory and role drift -- deployment and bootstrap ordering problems - -The idea is simple: - -1. When you investigate a bad response, capture: - - user task and request - - route or provider combo in OmniRoute - - any RAG context used downstream (retrieved documents, tool calls, etc) -2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` โ€ฆ `No.16`). -3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. -4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. - -Full text and concrete recipes live here (MIT license, text only): - -[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) - -You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. - ---- - -## Still Stuck? - -- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details -- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints -- **Health Dashboard**: Check **Dashboard โ†’ Health** for real-time system status -- **Translator**: Use **Dashboard โ†’ Translator** to debug format issues diff --git a/docs/i18n/sv/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/sv/VM_DEPLOYMENT_GUIDE.md deleted file mode 100644 index b78859696b..0000000000 --- a/docs/i18n/sv/VM_DEPLOYMENT_GUIDE.md +++ /dev/null @@ -1,401 +0,0 @@ -# OmniRoute โ€” Implementeringsguide pรฅ virtuell dator med Cloudflare - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](../pt-BR/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](../es/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](../fr/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](../it/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](../ru/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](../zh-CN/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](../de/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](../in/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](../th/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](../uk-UA/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](../ar/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](../ja/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](../vi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](../bg/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](../da/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](../fi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](../he/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](../hu/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](../id/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](../ko/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](../ms/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](../nl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](../no/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](../pt/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](../ro/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](../pl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](../sk/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](../sv/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](../phi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](../cs/VM_DEPLOYMENT_GUIDE.md) - -Komplett guide fรถr att installera och konfigurera OmniRoute pรฅ en virtuell dator (VPS) med domรคn som hanteras via Cloudflare. - ---- - -## Fรถrutsรคttningar - -| Objekt | Minsta | Rekommenderas | -| ---------- | ------------------------- | ---------------- | -| **CPU** | 1 vCPU | 2 vCPU | -| **RAM** | 1 GB | 2 GB | -| **Disk** | 10 GB SSD | 25 GB SSD | -| **OS** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS | -| **Domรคn** | Registrerad pรฅ Cloudflare | โ€” | -| **Docker** | Docker Engine 24+ | Docker 27+ | - -**Testade leverantรถrer**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. - ---- - -## 1. Konfigurera den virtuella datorn - -### 1.1 Skapa instansen - -Pรฅ din fรถredragna VPS-leverantรถr: - -- Vรคlj Ubuntu 24.04 LTS -- Vรคlj minimiplan (1 vCPU / 1 GB RAM) -- Stรคll in ett starkt root-lรถsenord eller konfigurera SSH-nyckel -- Notera den **offentliga IP-adressen** (t.ex. `203.0.113.10`) - -### 1.2 Anslut via SSH - -```bash -ssh root@203.0.113.10 -``` - -### 1.3 Uppdatera systemet - -```bash -apt update && apt upgrade -y -``` - -### 1.4 Installera Docker - -```bash -# Install dependencies -apt install -y ca-certificates curl gnupg - -# Add official Docker repository -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 Installera nginx - -```bash -apt install -y nginx -``` - -### 1.6 Konfigurera brandvรคgg (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 -``` - -> **Tips**: Fรถr maximal sรคkerhet, begrรคnsa portarna 80 och 443 till endast Cloudflare IP-adresser. Se avsnittet [Advanced Security](#advanced-security). - ---- - -## 2. Installera OmniRoute - -### 2.1 Skapa konfigurationskatalog - -```bash -mkdir -p /opt/omniroute -``` - -### 2.2 Skapa fil med miljรถvariabler - -```bash -cat > /opt/omniroute/.env << โ€˜EOFโ€™ -# === Security === -JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY -INITIAL_PASSWORD=YourSecurePassword123! -API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY -STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY -STORAGE_ENCRYPTION_KEY_VERSION=v1 -MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT - -# === 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 (change to your domain) === -BASE_URL=https://llms.seudominio.com -NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com - -# === Cloud Sync (optional) === -# CLOUD_URL=https://cloud.omniroute.online -# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online -EOF -``` - -> โš ๏ธ **VIKTIGT**: Skapa unika hemliga nycklar! Anvรคnd `openssl rand -hex 32` fรถr varje nyckel. - -### 2.3 Starta behรฅllaren - -```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 Kontrollera att den kรถrs - -```bash -docker ps | grep omniroute -docker logs omniroute --tail 20 -``` - -Den ska visa: `[DB] SQLite database ready` och `listening on port 20128`. - ---- - -## 3. Konfigurera nginx (omvรคnd proxy) - -### 3.1 Generera SSL-certifikat (Cloudflare Origin) - -I Cloudflares instrumentpanel: - -1. Gรฅ till **SSL/TLS โ†’ Origin Server** -2. Klicka pรฅ **Skapa certifikat** -3. Behรฅll standardinstรคllningarna (15 รฅr, \*.dindomรคn.com) -4. Kopiera **ursprungscertifikatet** och **privat nyckel** - -```bash -mkdir -p /etc/nginx/ssl - -# Paste the certificate -nano /etc/nginx/ssl/origin.crt - -# Paste the private key -nano /etc/nginx/ssl/origin.key - -chmod 600 /etc/nginx/ssl/origin.key -``` - -### 3.2 Nginx-konfiguration - -```bash -cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ -# Default server โ€” blocks direct access via 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.yourdomain.com; # Change to your domain - - 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.yourdomain.com; - return 301 https://$server_name$request_uri; -} -NGINX -``` - -### 3.3 Aktivera och testa - -```bash -# Remove default configuration -rm -f /etc/nginx/sites-enabled/default - -# Enable OmniRoute -ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute - -# Test and reload -nginx -t && systemctl reload nginx -``` - ---- - -## 4. Konfigurera Cloudflare DNS - -### 4.1 Lรคgg till DNS-post - -I Cloudflares instrumentpanel โ†’ DNS: - -| Skriv | Namn | Innehรฅll | Proxy | -| ----- | ------ | ---------------------- | ----------- | -| A | `llms` | `203.0.113.10` (VM IP) | โœ… Fullmakt | - -### 4.2 Konfigurera SSL - -Under **SSL/TLS โ†’ ร–versikt**: - -- Lรคge: **Fullstรคndig (Strikt)** - -Under **SSL/TLS โ†’ Edge-certifikat**: - -- Anvรคnd alltid HTTPS: โœ… Pรฅ -- Minsta TLS-version: TLS 1.2 -- Automatiska HTTPS-omskrivningar: โœ… Pรฅ - -### 4.3 Testning - -```bash -curl -sI https://llms.seudominio.com/health -# Should return HTTP/2 200 -``` - ---- - -## 5. Drift och underhรฅll - -### Uppgradera till en ny version - -```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 -``` - -### Visa loggar - -```bash -docker logs -f omniroute # Real-time stream -docker logs omniroute --tail 50 # Last 50 lines -``` - -### Manuell sรคkerhetskopiering av databas - -```bash -# Copy data from the volume to the host -docker cp omniroute:/app/data ./backup-$(date +%F) - -# Or compress the entire volume -docker run --rm -v omniroute-data:/data -v $(pwd):/backup \ - alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data -``` - -### ร…terstรคll frรฅn sรคkerhetskopia - -```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. Avancerad sรคkerhet - -### Begrรคnsa nginx till Cloudflare IP-adresser - -```bash -cat > /etc/nginx/cloudflare-ips.conf << โ€˜CFโ€™ -# Cloudflare IPv4 ranges โ€” update periodically -# 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 -``` - -Lรคgg till fรถljande till `nginx.conf` inuti `http {}`-blocket: - -```nginx -include /etc/nginx/cloudflare-ips.conf; -``` - -### Installera fail2ban - -```bash -apt install -y fail2ban -systemctl enable fail2ban -systemctl start fail2ban - -# Check status -fail2ban-client status sshd -``` - -### Blockera direktรฅtkomst till Docker-porten - -```bash -# Prevent direct external access to port 20128 -iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP -iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT - -# Persist the rules -apt install -y iptables-persistent -netfilter-persistent save -``` - ---- - -## 7. Distribuera till Cloudflare-arbetare (valfritt) - -Fรถr fjรคrrรฅtkomst via Cloudflare Workers (utan att exponera den virtuella datorn direkt): - -```bash -# In the local repository -cd omnirouteCloud -npm install -npx wrangler login -npx wrangler deploy -``` - -Se hela dokumentationen pรฅ [omnirouteCloud/README.md](../omnirouteCloud/README.md). - ---- - -## Portsammanfattning - -| Hamn | Service | Tillgรฅng | -| ----- | ----------- | ---------------------------- | -| 22 | SSH | Public (med fail2ban) | -| 80 | nginx HTTP | Omdirigera โ†’ HTTPS | -| 443 | nginx HTTPS | Via Cloudflare Proxy | -| 20128 | OmniRoute | Endast Localhost (via nginx) | diff --git a/docs/i18n/sv/docs/A2A-SERVER.md b/docs/i18n/sv/docs/A2A-SERVER.md new file mode 100644 index 0000000000..524791a9ad --- /dev/null +++ b/docs/i18n/sv/docs/A2A-SERVER.md @@ -0,0 +1,200 @@ +# OmniRoute A2A Server Documentation (Svenska) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/A2A-SERVER.md) + +--- + +> Agent-to-Agent Protocol v0.3 โ€” OmniRoute as an intelligent routing agent + +## Agent Discovery + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements. + +--- + +## Authentication + +All `/a2a` requests require an API key via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server, authentication is bypassed. + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Sends a message to a skill and waits for the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a hello world in Python"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "uuid", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "..." }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}} + +: heartbeat 2026-03-03T17:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Available Skills + +| Skill | Description | +| :----------------- | :------------------------------------------------------------------------------------------------------------------------------ | +| `smart-routing` | Routes prompts through OmniRoute's intelligent pipeline. Returns response with routing explanation, cost, and resilience trace. | +| `quota-management` | Answers natural-language queries about provider quotas, suggests free combos, and provides quota rankings. | + +--- + +## Task Lifecycle + +``` +submitted โ†’ working โ†’ completed + โ†’ failed + โ†’ cancelled +``` + +- Tasks expire after 5 minutes (configurable) +- Terminal states: `completed`, `failed`, `cancelled` +- Event log tracks every state transition + +--- + +## Error Codes + +| Code | Meaning | +| :----- | :----------------------------- | +| -32700 | Parse error (invalid JSON) | +| -32600 | Invalid request / Unauthorized | +| -32601 | Method or skill not found | +| -32602 | Invalid params | +| -32603 | Internal error | + +--- + +## Integration Examples + +### Python (requests) + +```python +import requests + +resp = requests.post("http://localhost:20128/a2a", json={ + "jsonrpc": "2.0", "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Hello"}] + } +}, headers={"Authorization": "Bearer YOUR_KEY"}) + +result = resp.json()["result"] +print(result["artifacts"][0]["content"]) +print(result["metadata"]["routing_explanation"]) +``` + +### TypeScript (fetch) + +```typescript +const resp = await fetch("http://localhost:20128/a2a", { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: "Bearer YOUR_KEY", + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "1", + method: "message/send", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Hello" }], + }, + }), +}); +const { result } = await resp.json(); +console.log(result.metadata.routing_explanation); +``` diff --git a/docs/i18n/sv/docs/API_REFERENCE.md b/docs/i18n/sv/docs/API_REFERENCE.md new file mode 100644 index 0000000000..744c1a26a2 --- /dev/null +++ b/docs/i18n/sv/docs/API_REFERENCE.md @@ -0,0 +1,465 @@ +# API Reference (Svenska) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/API_REFERENCE.md) + +--- + +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 | +| `X-Session-Id` | Request | Sticky session key for external session affinity | +| `x_session_id` | Request | Underscore variant also accepted (direct HTTP) | +| `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 | +| `X-OmniRoute-Session-Id` | Response | Effective session ID used by OmniRoute | + +> Nginx note: if you rely on underscore headers (for example `x_session_id`), enable `underscores_in_headers 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/stats + +# Clear all caches +DELETE /api/cache/stats +``` + +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/PATCH | 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 + provider summary (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`) | +| `/api/cache/stats` | 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 | + +### Tunnels + +| Endpoint | Method | Description | +| -------------------------- | ------ | ----------------------------------------------------------------------- | +| `/api/tunnels/cloudflared` | GET | Read Cloudflare Quick Tunnel install/runtime status for the dashboard | +| `/api/tunnels/cloudflared` | POST | Enable or disable the Cloudflare Quick Tunnel (`action=enable/disable`) | + +### 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`. + +### ACP Agents + +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | + +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). + +### Resilience & Rate Limits + +| Endpoint | Method | Description | +| ----------------------- | --------- | ------------------------------- | +| `/api/resilience` | GET/PATCH | 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` diff --git a/docs/i18n/sv/docs/ARCHITECTURE.md b/docs/i18n/sv/docs/ARCHITECTURE.md new file mode 100644 index 0000000000..0cb6ba8cb0 --- /dev/null +++ b/docs/i18n/sv/docs/ARCHITECTURE.md @@ -0,0 +1,814 @@ +# OmniRoute Architecture (Svenska) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/ARCHITECTURE.md) + +--- + +_Last updated: 2026-03-28_ + +## 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 (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developerโ†’system, systemโ†’user) for cross-provider compatibility +- Structured output conversion (json_schema โ†’ Gemini responseSchema) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) +- Global system prompt injection +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout โ†’ budget โ†’ fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) + +Primary runtime model: + +- Next.js 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.) + +## Dashboard Surface (Current) + +Main pages under `src/app/(dashboard)/dashboard/`: + +- `/dashboard` โ€” quick start + provider overview +- `/dashboard/endpoint` โ€” endpoint proxy + MCP + A2A + API endpoint tabs +- `/dashboard/providers` โ€” provider connections and credentials +- `/dashboard/combos` โ€” combo strategies, templates, model routing rules +- `/dashboard/costs` โ€” cost aggregation and pricing visibility +- `/dashboard/analytics` โ€” usage analytics and evaluations +- `/dashboard/limits` โ€” quota/rate controls +- `/dashboard/cli-tools` โ€” CLI onboarding, runtime detection, config generation +- `/dashboard/agents` โ€” detected ACP agents + custom agent registration +- `/dashboard/media` โ€” image/video/music playground +- `/dashboard/search-tools` โ€” search provider testing and history +- `/dashboard/health` โ€” uptime, circuit breakers, rate limits +- `/dashboard/logs` โ€” request/proxy/audit/console logs +- `/dashboard/settings` โ€” system settings tabs (general, routing, combo defaults, etc.) +- `/dashboard/api-manager` โ€” API key lifecycle and model permissions + +## 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[(storage.sqlite)] + UDB[(usage tables + log artifacts)] + end + + subgraph Upstreams[Upstream Providers] + P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/Qoder/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/route.ts` (GET) +- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- OAuth: `src/app/api/oauth/*` +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` +- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI tooling helpers: `src/app/api/cli-tools/*` +- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) +- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) โ€” provider profiles, circuit breaker, rate limit state +- Resilience reset: `src/app/api/resilience/reset` (POST) โ€” reset breakers + cooldowns +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) +- Telemetry: `src/app/api/telemetry/summary` (GET) +- Budget: `src/app/api/usage/budget` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Policies: `src/app/api/policies` (GET/POST) + +## 2) SSE + 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` +- Response sanitization: `open-sse/handlers/responseSanitizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.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`, `qoder.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 (SQLite): + +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** + +Usage persistence: + +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present + +Domain State DB (SQLite): + +- `src/lib/db/domainState.ts` โ€” CRUD operations 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`, `src/shared/services/modelSyncScheduler.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Periodic task: `src/shared/services/modelSyncScheduler.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. Combo routing adds one extra guard: provider-scoped 400s such as upstream content-block and role-validation failures are treated as model-local failures so later combo targets can still run. + +## 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: + +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` + +## Deployment Topology + +```mermaid +flowchart LR + 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[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] + end + + subgraph External[External Services] + Providers[AI Providers] + SyncCloud[Cloud Sync Service] + end + + CLI --> Next + Browser --> Next + Next --> Core + Next --> MainDB + Core --> MainDB + Core --> UsageDB + Core --> Providers + Next --> SyncCloud +``` + +## Module Mapping (Decision-Critical) + +### Route and API Modules + +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle +- `src/app/api/models/alias`: alias management +- `src/app/api/combos*`: fallback combo management +- `src/app/api/pricing`: pricing overrides for cost calculation +- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers +- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) +- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) +- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) +- `src/app/api/sessions`: active session listing (GET) +- `src/app/api/rate-limits`: per-account rate limit status (GET) + +### Routing and Execution Core + +- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior + +### Translation Registry and Format Converters + +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` +- Format constants: `open-sse/translator/formats.ts` + +### Persistence + +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables + +## Provider Executor Coverage (Strategy Pattern) + +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. + +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, Qoder, 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 | +| Qoder | openai | OAuth (Basic) | โœ… | โœ… | โœ… | โš ๏ธ Per request | +| OpenRouter | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| GLM/Kimi/MiniMax | claude | API Key | โœ… | โœ… | โŒ | โŒ | +| DeepSeek | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Groq | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| xAI (Grok) | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Mistral | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Perplexity | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Together AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Fireworks AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Cerebras | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Cohere | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| NVIDIA NIM | openai | API Key | โœ… | โœ… | โŒ | โŒ | + +## Format Translation Coverage + +Detected source formats include: + +- `openai` +- `openai-responses` +- `claude` +- `gemini` + +Target formats include: + +- OpenAI chat/Responses +- Claude +- Gemini/Gemini-CLI/Antigravity envelope +- Kiro +- Cursor + +Translations use **OpenAI as the hub format** โ€” all conversions go through OpenAI as intermediate: + +``` +Source Format โ†’ OpenAI (hub) โ†’ Target Format +``` + +Translations are selected dynamically based on source payload shape and provider target format. + +Additional processing layers in the translation pipeline: + +- **Response sanitization** โ€” Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI targets; merges `system` โ†’ `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** โ€” Parses `...` blocks from content into `reasoning_content` field +- **Structured output** โ€” Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` + +## Supported API Endpoints + +| 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` | Provider Models | Provider model metadata backing custom and managed available models | + +## 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 `/logs//` 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 + +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON โ†’ SQLite migration compatibility path + +## Observability and Operational Signals + +Runtime visibility sources: + +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- four-stage detailed payload captures in SQLite (`request_detail_logs`) when `settings.detailed_logs_enabled=true` +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption + +Detailed request payload capture stores up to four JSON payload stages per routed call: + +- raw request received from the client +- translated request actually sent upstream +- provider response reconstructed as JSON; streamed responses are compacted to the final summary plus stream metadata +- final client response returned by OmniRoute; streamed responses are stored in the same compact summary form + +## Security-Sensitive Boundaries + +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics + +## Environment and Runtime Matrix + +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` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). + +## Operational Verification Checklist + +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: +- `GET /api/settings` +- `GET /api/v1/models` +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/sv/docs/AUTO-COMBO.md b/docs/i18n/sv/docs/AUTO-COMBO.md new file mode 100644 index 0000000000..c07be7b67a --- /dev/null +++ b/docs/i18n/sv/docs/AUTO-COMBO.md @@ -0,0 +1,67 @@ +# OmniRoute Auto-Combo Engine (Svenska) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/AUTO-COMBO.md) + +--- + +> Self-managing model chains with adaptive scoring + +## How It Works + +The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**: + +| Factor | Weight | Description | +| :--------- | :----- | :---------------------------------------------- | +| Quota | 0.20 | Remaining capacity [0..1] | +| Health | 0.25 | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 | +| CostInv | 0.20 | Inverse cost (cheaper = higher score) | +| LatencyInv | 0.15 | Inverse p95 latency (faster = higher) | +| TaskFit | 0.10 | Model ร— task type fitness score | +| Stability | 0.10 | Low variance in latency/errors | + +## Mode Packs + +| Pack | Focus | Key Weight | +| :---------------------- | :----------- | :--------------- | +| ๐Ÿš€ **Ship Fast** | Speed | latencyInv: 0.35 | +| ๐Ÿ’ฐ **Cost Saver** | Economy | costInv: 0.40 | +| ๐ŸŽฏ **Quality First** | Best model | taskFit: 0.40 | +| ๐Ÿ“ก **Offline Friendly** | Availability | quota: 0.40 | + +## Self-Healing + +- **Temporary exclusion**: Score < 0.2 โ†’ excluded for 5 min (progressive backoff, max 30 min) +- **Circuit breaker awareness**: OPEN โ†’ auto-excluded; HALF_OPEN โ†’ probe requests +- **Incident mode**: >50% OPEN โ†’ disable exploration, maximize stability +- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout + +## Bandit Exploration + +5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode. + +## API + +```bash +# Create auto-combo +curl -X POST http://localhost:20128/api/combos/auto \ + -H "Content-Type: application/json" \ + -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}' + +# List auto-combos +curl http://localhost:20128/api/combos/auto +``` + +## Task Fitness + +30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` โ†’ high coding score). + +## Files + +| File | Purpose | +| :------------------------------------------- | :------------------------------------ | +| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization | +| `open-sse/services/autoCombo/taskFitness.ts` | Model ร— task fitness lookup | +| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap | +| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode | +| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles | +| `src/app/api/combos/auto/route.ts` | REST API | diff --git a/docs/i18n/da/CLI-TOOLS.md b/docs/i18n/sv/docs/CLI-TOOLS.md similarity index 66% rename from docs/i18n/da/CLI-TOOLS.md rename to docs/i18n/sv/docs/CLI-TOOLS.md index 2c1c108057..3f23563997 100644 --- a/docs/i18n/da/CLI-TOOLS.md +++ b/docs/i18n/sv/docs/CLI-TOOLS.md @@ -1,8 +1,8 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CLI-TOOLS.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CLI-TOOLS.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CLI-TOOLS.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CLI-TOOLS.md) +# CLI Tools Setup Guide โ€” OmniRoute (Svenska) -# CLI-vรฆrktรธjer Opsรฆtningsvejledning โ€” OmniRoute +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CLI-TOOLS.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CLI-TOOLS.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CLI-TOOLS.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CLI-TOOLS.md) -Denne vejledning forklarer, hvordan du installerer og konfigurerer alle understรธttede AI CLI-vรฆrktรธjer til at bruge **OmniRoute** som et samlet backend. +--- This guide explains how to install and configure all supported AI coding CLI tools to use **OmniRoute** as the unified backend, giving you centralized key management, @@ -13,7 +13,7 @@ cost tracking, model switching, and request logging across every tool. ## How It Works ``` -Claude / Codex / Gemini CLI / OpenCode / Cline / KiloCode / Continue / Kiro CLI +Claude / Codex / OpenCode / Cline / KiloCode / Continue / Kiro / Cursor / Copilot โ”‚ โ–ผ (all point to OmniRoute) http://YOUR_SERVER:20128/v1 @@ -31,21 +31,38 @@ Claude / Codex / Gemini CLI / OpenCode / Cline / KiloCode / Continue / Kiro CLI --- -## Supported Tools +## Supported Tools (Dashboard Source of Truth) -| Tool | Command | Type | Install Method | -| ---------------- | ------------------- | ----------------- | -------------- | -| **Claude Code** | `claude` | CLI | npm | -| **OpenAI Codex** | `codex` | CLI | npm | -| **Gemini CLI** | `gemini` | CLI | npm | -| **OpenCode** | `opencode` | CLI | npm | -| **Cline** | `cline` | CLI + VS Code ext | npm | -| **KiloCode** | `kilocode` / `kilo` | CLI + VS Code ext | npm | -| **Continue** | guide-based | VS Code ext | VS Code | -| **Kiro CLI** | `kiro-cli` | CLI | curl installer | -| **Cursor** | `cursor` | Desktop app | Download | -| **Droid** | web-based | Built-in agent | OmniRoute | -| **OpenClaw** | web-based | Built-in agent | OmniRoute | +The dashboard cards in `/dashboard/cli-tools` are generated from `src/shared/constants/cliTools.ts`. +Current list (v3.0.0-rc.16): + +| Tool | ID | Command | Setup Mode | Install Method | +| ------------------ | ------------- | ---------- | ---------- | -------------- | +| **Claude Code** | `claude` | `claude` | env | npm | +| **OpenAI Codex** | `codex` | `codex` | custom | npm | +| **Factory Droid** | `droid` | `droid` | custom | bundled/CLI | +| **OpenClaw** | `openclaw` | `openclaw` | custom | bundled/CLI | +| **Cursor** | `cursor` | app | guide | desktop app | +| **Cline** | `cline` | `cline` | custom | npm | +| **Kilo Code** | `kilo` | `kilocode` | custom | npm | +| **Continue** | `continue` | extension | guide | VS Code | +| **Antigravity** | `antigravity` | internal | mitm | OmniRoute | +| **GitHub Copilot** | `copilot` | extension | custom | VS Code | +| **OpenCode** | `opencode` | `opencode` | guide | npm | +| **Kiro AI** | `kiro` | app/cli | mitm | desktop/CLI | + +### CLI fingerprint sync (Agents + Settings) + +`/dashboard/agents` and `Settings > CLI Fingerprint` use `src/shared/constants/cliCompatProviders.ts`. +This keeps provider IDs aligned with CLI cards and legacy IDs. + +| CLI ID | Fingerprint Provider ID | +| ---------------------------------------------------------------------------------------------------- | ----------------------- | +| `kilo` | `kilocode` | +| `copilot` | `github` | +| `claude` / `codex` / `antigravity` / `kiro` / `cursor` / `cline` / `opencode` / `droid` / `openclaw` | same ID | + +Legacy IDs still accepted for compatibility: `copilot`, `kimi-coding`, `qwen`. --- @@ -71,9 +88,6 @@ npm install -g @anthropic-ai/claude-code # OpenAI Codex npm install -g @openai/codex -# Gemini CLI (Google) -npm install -g @google/gemini-cli - # OpenCode npm install -g opencode-ai @@ -81,7 +95,7 @@ npm install -g opencode-ai npm install -g cline # KiloCode -npm install -g kilecode +npm install -g kilocode # Kiro CLI (Amazon โ€” requires curl + unzip) apt-get install -y unzip # on Debian/Ubuntu @@ -94,7 +108,6 @@ export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc ```bash claude --version # 2.x.x codex --version # 0.x.x -gemini --version # 0.x.x opencode --version # x.x.x cline --version # 2.x.x kilocode --version # x.x.x (or: kilo --version) @@ -157,21 +170,6 @@ EOF --- -### Gemini CLI - -```bash -mkdir -p ~/.gemini && cat > ~/.gemini/settings.json << EOF -{ - "apiKey": "sk-your-omniroute-key", - "baseUrl": "http://localhost:20128/v1" -} -EOF -``` - -**Test:** `gemini "hello"` - ---- - ### OpenCode ```bash @@ -308,7 +306,7 @@ They run as internal routes and use OmniRoute's model routing automatically. --- -## Troubleshooting +## Felsรถkning | Error | Cause | Fix | | ------------------------- | ----------------------- | ------------------------------------------ | @@ -328,17 +326,16 @@ They run as internal routes and use OmniRoute's model routing automatically. OMNIROUTE_URL="http://localhost:20128/v1" OMNIROUTE_KEY="sk-your-omniroute-key" -npm install -g @anthropic-ai/claude-code @openai/codex @google/gemini-cli opencode-ai cline kilecode +npm install -g @anthropic-ai/claude-code @openai/codex opencode-ai cline kilocode # Kiro CLI apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash # Write configs -mkdir -p ~/.claude ~/.codex ~/.gemini ~/.config/opencode ~/.continue +mkdir -p ~/.claude ~/.codex ~/.config/opencode ~/.continue cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" -cat > ~/.gemini/settings.json <<< "{\"apiKey\":\"$OMNIROUTE_KEY\",\"baseUrl\":\"$OMNIROUTE_URL\"}" cat >> ~/.bashrc << EOF export OPENAI_BASE_URL="$OMNIROUTE_URL" export OPENAI_API_KEY="$OMNIROUTE_KEY" diff --git a/docs/i18n/sv/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/sv/docs/CODEBASE_DOCUMENTATION.md new file mode 100644 index 0000000000..c4cb59f725 --- /dev/null +++ b/docs/i18n/sv/docs/CODEBASE_DOCUMENTATION.md @@ -0,0 +1,591 @@ +# omniroute โ€” Codebase Documentation (Svenska) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CODEBASE_DOCUMENTATION.md) + +--- + +> 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
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, Qoder, 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. + +#### Arkitektur + +```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 | +| Qoder | 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"] +``` diff --git a/docs/i18n/sv/docs/COVERAGE_PLAN.md b/docs/i18n/sv/docs/COVERAGE_PLAN.md new file mode 100644 index 0000000000..f701d7f777 --- /dev/null +++ b/docs/i18n/sv/docs/COVERAGE_PLAN.md @@ -0,0 +1,170 @@ +# Test Coverage Plan (Svenska) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/COVERAGE_PLAN.md) + +--- + +Last updated: 2026-03-28 + +## Baseline + +There are multiple coverage numbers depending on how the report is computed. For planning, only one of them is useful. + +| Metric | Scope | Statements / Lines | Branches | Functions | Notes | +| -------------------- | ----------------------------------------------------- | -----------------: | -------: | --------: | --------------------------------------------------- | +| Legacy | Old `npm run test:coverage` | 79.42% | 75.15% | 67.94% | Inflated: counts test files and excludes `open-sse` | +| Diagnostic | Source-only, excluding tests and excluding `open-sse` | 68.16% | 63.55% | 64.06% | Useful only to isolate `src/**` | +| Recommended baseline | Source-only, excluding tests and including `open-sse` | 56.95% | 66.05% | 57.80% | This is the project-wide baseline to improve | + +The recommended baseline is the number to optimize against. + +## Rules + +- Coverage targets apply to source files, not to `tests/**`. +- `open-sse/**` is part of the product and must remain in scope. +- New code should not reduce coverage in touched areas. +- Prefer testing behavior and branch outcomes over implementation details. +- Prefer temp SQLite databases and small fixtures over broad mocks for `src/lib/db/**`. + +## Current command set + +- `npm run test:coverage` + - Main source coverage gate for the unit test suite + - Generates `text-summary`, `html`, `json-summary`, and `lcov` +- `npm run coverage:report` + - Detailed file-by-file report from the latest run +- `npm run test:coverage:legacy` + - Historical comparison only + +## Milestones + +| Phase | Target | Focus | +| ------- | ---------------------: | ------------------------------------------------- | +| Phase 1 | 60% statements / lines | Quick wins and low-risk utility coverage | +| Phase 2 | 65% statements / lines | DB and route foundations | +| Phase 3 | 70% statements / lines | Provider validation and usage analytics | +| Phase 4 | 75% statements / lines | `open-sse` translators and helpers | +| Phase 5 | 80% statements / lines | `open-sse` handlers and executor branches | +| Phase 6 | 85% statements / lines | Harder edge cases, branch debt, regression suites | +| Phase 7 | 90% statements / lines | Final sweep, gap closure, strict ratchet | + +Branches and functions should ratchet upward with each phase, but the primary hard target is statements / lines. + +## Priority hotspots + +These files or areas offer the best return for the next phases: + +1. `open-sse/handlers` + - `chatCore.ts` at 7.57% + - Overall directory at 29.07% +2. `open-sse/translator/request` + - Overall directory at 36.39% + - Many translators are still near single-digit coverage +3. `open-sse/translator/response` + - Overall directory at 8.07% +4. `open-sse/executors` + - Overall directory at 36.62% +5. `src/lib/db` + - `models.ts` at 20.66% + - `registeredKeys.ts` at 34.46% + - `modelComboMappings.ts` at 36.25% + - `settings.ts` at 46.40% + - `webhooks.ts` at 33.33% +6. `src/lib/usage` + - `usageHistory.ts` at 21.12% + - `usageStats.ts` at 9.56% + - `costCalculator.ts` at 30.00% +7. `src/lib/providers` + - `validation.ts` at 41.16% +8. Low-risk utility and API files for early gains + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/api/errorResponse.ts` + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +## Execution checklist + +### Phase 1: 56.95% -> 60% + +- [x] Fix coverage metric so it reflects source code instead of test files +- [x] Keep a legacy coverage script for comparison +- [x] Record the baseline and hotspots in-repo +- [ ] Add focused tests for low-risk utilities: + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/fetchTimeout.ts` + - `src/lib/api/errorResponse.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/display/names.ts` +- [ ] Add route tests for: + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +### Phase 2: 60% -> 65% + +- [ ] Add DB-backed tests for: + - `src/lib/db/modelComboMappings.ts` + - `src/lib/db/settings.ts` + - `src/lib/db/registeredKeys.ts` +- [ ] Cover branch behavior in: + - `src/lib/providers/validation.ts` + - `src/app/api/v1/embeddings/route.ts` + - `src/app/api/v1/moderations/route.ts` + +### Phase 3: 65% -> 70% + +- [ ] Add usage analytics tests for: + - `src/lib/usage/usageHistory.ts` + - `src/lib/usage/usageStats.ts` + - `src/lib/usage/costCalculator.ts` +- [ ] Expand route coverage for proxy management and settings branches + +### Phase 4: 70% -> 75% + +- [ ] Cover translator helpers and central translation paths: + - `open-sse/translator/index.ts` + - `open-sse/translator/helpers/*` + - `open-sse/translator/request/*` + - `open-sse/translator/response/*` + +### Phase 5: 75% -> 80% + +- [ ] Add handler-level tests for: + - `open-sse/handlers/chatCore.ts` + - `open-sse/handlers/responsesHandler.js` + - `open-sse/handlers/imageGeneration.js` + - `open-sse/handlers/embeddings.js` +- [ ] Add executor branch coverage for provider-specific auth, retries, and endpoint overrides + +### Phase 6: 80% -> 85% + +- [ ] Merge more edge-case suites into the main coverage path +- [ ] Increase function coverage for DB modules with weak constructor/helper coverage +- [ ] Close branch gaps in `settings.ts`, `registeredKeys.ts`, `validation.ts`, and translator helpers + +### Phase 7: 85% -> 90% + +- [ ] Treat the remaining low-coverage files as blockers +- [ ] Add regression tests for every uncovered production bug fixed during the push to 90% +- [ ] Raise the coverage gate in CI only after the local baseline is stable for at least two consecutive runs + +## Ratchet policy + +Update `npm run test:coverage` thresholds only after the project actually exceeds the next milestone with a comfortable buffer. + +Recommended ratchet sequence: + +1. 55/60/55 +2. 60/62/58 +3. 65/64/62 +4. 70/66/66 +5. 75/70/72 +6. 80/75/78 +7. 85/80/84 +8. 90/85/88 + +Order is `statements-lines / branches / functions`. + +## Known gap + +The current coverage command measures the main Node unit suite and includes source reached from it, including `open-sse`. It does not yet merge Vitest coverage into a single unified report. That merge is worth doing later, but it is not a blocker for starting the 60% -> 80% climb. diff --git a/docs/i18n/sv/docs/FEATURES.md b/docs/i18n/sv/docs/FEATURES.md index a03d5c5bec..2006c2e706 100644 --- a/docs/i18n/sv/docs/FEATURES.md +++ b/docs/i18n/sv/docs/FEATURES.md @@ -1,6 +1,6 @@ # OmniRoute โ€” Dashboard Features Gallery (Svenska) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/FEATURES.md) --- @@ -10,7 +10,7 @@ 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). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. ![Providers Dashboard](screenshots/01-providers.png) diff --git a/docs/i18n/sv/docs/MCP-SERVER.md b/docs/i18n/sv/docs/MCP-SERVER.md new file mode 100644 index 0000000000..b8844d4c7d --- /dev/null +++ b/docs/i18n/sv/docs/MCP-SERVER.md @@ -0,0 +1,87 @@ +# OmniRoute MCP Server Documentation (Svenska) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/MCP-SERVER.md) + +--- + +> Model Context Protocol server with 16 intelligent tools + +## Installera + +OmniRoute MCP is built-in. Start it with: + +```bash +omniroute --mcp +``` + +Or via the open-sse transport: + +```bash +# HTTP streamable transport (port 20130) +omniroute --dev # MCP auto-starts on /mcp endpoint +``` + +## IDE Configuration + +See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup. + +--- + +## Essential Tools (8) + +| Tool | Description | +| :------------------------------ | :--------------------------------------- | +| `omniroute_get_health` | Gateway health, circuit breakers, uptime | +| `omniroute_list_combos` | All configured combos with models | +| `omniroute_get_combo_metrics` | Performance metrics for a specific combo | +| `omniroute_switch_combo` | Switch active combo by ID/name | +| `omniroute_check_quota` | Quota status per provider or all | +| `omniroute_route_request` | Send a chat completion through OmniRoute | +| `omniroute_cost_report` | Cost analytics for a time period | +| `omniroute_list_models_catalog` | Full model catalog with capabilities | + +## Advanced Tools (8) + +| Tool | Description | +| :--------------------------------- | :---------------------------------------------------------- | +| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | +| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | +| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | +| `omniroute_test_combo` | Live-test all models in a combo via a real upstream request | +| `omniroute_get_provider_metrics` | Detailed metrics for one provider | +| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | +| `omniroute_explain_route` | Explain a past routing decision | +| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | + +## Authentication + +MCP tools are authenticated via API key scopes. Each tool requires specific scopes: + +| Scope | Tools | +| :------------- | :----------------------------------------------- | +| `read:health` | get_health, get_provider_metrics | +| `read:combos` | list_combos, get_combo_metrics | +| `write:combos` | switch_combo | +| `read:quota` | check_quota | +| `write:route` | route_request, simulate_route, test_combo | +| `read:usage` | cost_report, get_session_snapshot, explain_route | +| `write:config` | set_budget_guard, set_resilience_profile | +| `read:models` | list_models_catalog, best_combo_for_task | + +## Audit Logging + +Every tool call is logged to `mcp_tool_audit` with: + +- Tool name, arguments, result +- Duration (ms), success/failure +- API key hash, timestamp + +## Files + +| File | Purpose | +| :------------------------------------------- | :------------------------------------------ | +| `open-sse/mcp-server/server.ts` | MCP server creation + 16 tool registrations | +| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport | +| `open-sse/mcp-server/auth.ts` | API key + scope validation | +| `open-sse/mcp-server/audit.ts` | Tool call audit logging | +| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers | diff --git a/docs/i18n/sv/docs/RELEASE_CHECKLIST.md b/docs/i18n/sv/docs/RELEASE_CHECKLIST.md new file mode 100644 index 0000000000..8e69654f79 --- /dev/null +++ b/docs/i18n/sv/docs/RELEASE_CHECKLIST.md @@ -0,0 +1,37 @@ +# Release Checklist (Svenska) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/RELEASE_CHECKLIST.md) + +--- + +Use this checklist before tagging or publishing a new OmniRoute release. + +## Version and Changelog + +1. Bump `package.json` version (`x.y.z`) in the release branch. +2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: + - `## [x.y.z] โ€” YYYY-MM-DD` +3. Keep `## [Unreleased]` as the first changelog section for upcoming work. +4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. + +## API Docs + +1. Update `docs/openapi.yaml`: + - `info.version` must equal `package.json` version. +2. Validate endpoint examples if API contracts changed. + +## Runtime Docs + +1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. +2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. +3. Update localized docs if source docs changed significantly. + +## Automated Check + +Run the sync guard locally before opening PR: + +```bash +npm run check:docs-sync +``` + +CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/sv/docs/TROUBLESHOOTING.md b/docs/i18n/sv/docs/TROUBLESHOOTING.md new file mode 100644 index 0000000000..d6de6a1153 --- /dev/null +++ b/docs/i18n/sv/docs/TROUBLESHOOTING.md @@ -0,0 +1,256 @@ +# Troubleshooting (Svenska) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/TROUBLESHOOTING.md) + +--- + +Common problems and solutions for OmniRoute. + +--- + +## Quick Fixes + +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | + +--- + +## Provider Issues + +### "Language model did not provide messages" + +**Cause:** Provider quota exhausted. + +**Fix:** + +1. 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, Qoder) 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}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) + +--- + +## Circuit Breaker Issues + +### Provider stuck in OPEN state + +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. + +**Fix:** + +1. 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 +- **SDK returns raw string instead of object** โ€” Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** โ€” Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** โ€” Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** โ€” Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` + +--- + +## Resilience Settings + +### Auto rate-limit not triggering + +- 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. + +--- + +## Optional RAG / LLM failure taxonomy (16 problems) + +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` โ€ฆ `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard โ†’ Health** for real-time system status +- **Translator**: Use **Dashboard โ†’ Translator** to debug format issues diff --git a/docs/i18n/sv/USER_GUIDE.md b/docs/i18n/sv/docs/USER_GUIDE.md similarity index 82% rename from docs/i18n/sv/USER_GUIDE.md rename to docs/i18n/sv/docs/USER_GUIDE.md index d0a0e6b082..fa77a0ca99 100644 --- a/docs/i18n/sv/USER_GUIDE.md +++ b/docs/i18n/sv/docs/USER_GUIDE.md @@ -1,8 +1,6 @@ # User Guide (Svenska) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/USER_GUIDE.md) - -> ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/USER_GUIDE.md) --- @@ -320,7 +318,7 @@ Model: cc/claude-opus-4-6 --- -## ๐Ÿš€ Deployment +## Distribution ### Global npm install (Recommended) @@ -511,23 +509,26 @@ post_install() { ### Environment Variables -| Variable | Default | Description | -| ------------------------- | ------------------------------------ | ------------------------------------------------------- | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | -| `INITIAL_PASSWORD` | `123456` | First login password | -| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | -| `PORT` | framework default | Service port (`20128` in examples) | -| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | -| `NODE_ENV` | runtime default | Set `production` for deploy | -| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | -| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | -| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | -| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | -| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | -| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | -| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | -| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | +| 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/*` | +| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand | +| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | For the full environment variable reference, see the [README](../README.md). @@ -598,6 +599,11 @@ curl -X POST http://localhost:20128/api/provider-models \ Or use Dashboard: **Providers โ†’ [Provider] โ†’ Custom Models**. +Notes: + +- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers. +- The **Custom Models** section is intended for providers that do not expose managed available-model imports. + ### Dedicated Provider Routes Route requests directly to a specific provider with model validation: @@ -642,6 +648,14 @@ Returns models grouped by provider with types (`chat`, `embedding`, `image`). - Automatic background sync with timeout + fail-fast - Prefer server-side `BASE_URL`/`CLOUD_URL` in production +### Cloudflare Quick Tunnel + +- Available in **Dashboard โ†’ Endpoints** for Docker and other self-hosted deployments +- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint +- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary +- Tunnel URLs are ephemeral and change every time you stop/start the tunnel +- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download + ### LLM Gateway Intelligence (Phase 9) - **Semantic Cache** โ€” Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) @@ -757,11 +771,11 @@ OmniRoute implements provider-level resilience with four components: 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 | +| 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 unless `DISABLE_SQLITE_AUTO_BACKUP=true` | ```bash # API: Export database @@ -787,10 +801,11 @@ curl -X POST http://localhost:20128/api/db-backups/import \ ### Settings Dashboard -The settings page is organized into 5 tabs for easy navigation: +The settings page is organized into 6 tabs for easy navigation: | Tab | Contents | | -------------- | ---------------------------------------------------------------------------------------------- | +| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility | | **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | | **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | | **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | diff --git a/docs/i18n/sv/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/sv/docs/VM_DEPLOYMENT_GUIDE.md new file mode 100644 index 0000000000..0ae1f81f2a --- /dev/null +++ b/docs/i18n/sv/docs/VM_DEPLOYMENT_GUIDE.md @@ -0,0 +1,403 @@ +# OmniRoute โ€” Deployment Guide on VM with Cloudflare (Svenska) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/VM_DEPLOYMENT_GUIDE.md) + +--- + +Complete guide to install and configure OmniRoute on a VM (VPS) with domain managed via Cloudflare. + +--- + +## Prerequisites + +| Item | Minimum | Recommended | +| ---------- | ------------------------ | ---------------- | +| **CPU** | 1 vCPU | 2 vCPU | +| **RAM** | 1 GB | 2 GB | +| **Disk** | 10 GB SSD | 25 GB SSD | +| **OS** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS | +| **Domain** | Registered on Cloudflare | โ€” | +| **Docker** | Docker Engine 24+ | Docker 27+ | + +**Tested providers**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. + +--- + +## 1. Configure the VM + +### 1.1 Create the instance + +On your preferred VPS provider: + +- Choose Ubuntu 24.04 LTS +- Select the minimum plan (1 vCPU / 1 GB RAM) +- Set a strong root password or configure SSH key +- Note the **public IP** (e.g., `203.0.113.10`) + +### 1.2 Connect via SSH + +```bash +ssh root@203.0.113.10 +``` + +### 1.3 Update the system + +```bash +apt update && apt upgrade -y +``` + +### 1.4 Install Docker + +```bash +# Install dependencies +apt install -y ca-certificates curl gnupg + +# Add official Docker repository +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 Install nginx + +```bash +apt install -y nginx +``` + +### 1.6 Configure 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 +``` + +> **Tip**: For maximum security, restrict ports 80 and 443 to Cloudflare IPs only. See the [Advanced Security](#advanced-security) section. + +--- + +## 2. Install OmniRoute + +### 2.1 Create configuration directory + +```bash +mkdir -p /opt/omniroute +``` + +### 2.2 Create environment variables file + +```bash +cat > /opt/omniroute/.env << โ€˜EOFโ€™ +# === Security === +JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY +INITIAL_PASSWORD=YourSecurePassword123! +API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY +STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY +STORAGE_ENCRYPTION_KEY_VERSION=v1 +MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT + +# === 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 (change to your domain) === +BASE_URL=https://llms.seudominio.com +NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com + +# === Cloud Sync (optional) === +# CLOUD_URL=https://cloud.omniroute.online +# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online +EOF +``` + +> โš ๏ธ **IMPORTANT**: Generate unique secret keys! Use `openssl rand -hex 32` for each key. + +### 2.3 Start the 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 Verify that it is running + +```bash +docker ps | grep omniroute +docker logs omniroute --tail 20 +``` + +It should display: `[DB] SQLite database ready` and `listening on port 20128`. + +--- + +## 3. Configure nginx (Reverse Proxy) + +### 3.1 Generate SSL certificate (Cloudflare Origin) + +In the Cloudflare dashboard: + +1. Go to **SSL/TLS โ†’ Origin Server** +2. Click **Create Certificate** +3. Keep the defaults (15 years, \*.yourdomain.com) +4. Copy the **Origin Certificate** and the **Private Key** + +```bash +mkdir -p /etc/nginx/ssl + +# Paste the certificate +nano /etc/nginx/ssl/origin.crt + +# Paste the private key +nano /etc/nginx/ssl/origin.key + +chmod 600 /etc/nginx/ssl/origin.key +``` + +### 3.2 Nginx Configuration + +```bash +cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ +# Default server โ€” blocks direct access via 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.yourdomain.com; # Change to your domain + + 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.yourdomain.com; + return 301 https://$server_name$request_uri; +} +NGINX +``` + +### 3.3 Enable and Test + +```bash +# Remove default configuration +rm -f /etc/nginx/sites-enabled/default + +# Enable OmniRoute +ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute + +# Test and reload +nginx -t && systemctl reload nginx +``` + +--- + +## 4. Configure Cloudflare DNS + +### 4.1 Add DNS record + +In the Cloudflare dashboard โ†’ DNS: + +| Type | Name | Content | Proxy | +| ---- | ------ | ---------------------- | ---------- | +| A | `llms` | `203.0.113.10` (VM IP) | โœ… Proxied | + +### 4.2 Configure SSL + +Under **SSL/TLS โ†’ Overview**: + +- Mode: **Full (Strict)** + +Under **SSL/TLS โ†’ Edge Certificates**: + +- Always Use HTTPS: โœ… On +- Minimum TLS Version: TLS 1.2 +- Automatic HTTPS Rewrites: โœ… On + +### 4.3 Testing + +```bash +curl -sI https://llms.seudominio.com/health +# Should return HTTP/2 200 +``` + +--- + +## 5. Operations and Maintenance + +### Upgrade to a new version + +```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 +``` + +### View logs + +```bash +docker logs -f omniroute # Real-time stream +docker logs omniroute --tail 50 # Last 50 lines +``` + +### Manual database backup + +```bash +# Copy data from the volume to the host +docker cp omniroute:/app/data ./backup-$(date +%F) + +# Or compress the entire volume +docker run --rm -v omniroute-data:/data -v $(pwd):/backup \ + alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data +``` + +### Restore from 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. Advanced Security + +### Restrict nginx to Cloudflare IPs + +```bash +cat > /etc/nginx/cloudflare-ips.conf << โ€˜CFโ€™ +# Cloudflare IPv4 ranges โ€” update periodically +# 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 +``` + +Add the following to `nginx.conf` inside the `http {}` block: + +```nginx +include /etc/nginx/cloudflare-ips.conf; +``` + +### Install fail2ban + +```bash +apt install -y fail2ban +systemctl enable fail2ban +systemctl start fail2ban + +# Check status +fail2ban-client status sshd +``` + +### Block direct access to the Docker port + +```bash +# Prevent direct external access to port 20128 +iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP +iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT + +# Persist the rules +apt install -y iptables-persistent +netfilter-persistent save +``` + +--- + +## 7. Deploy to Cloudflare Workers (Optional) + +For remote access via Cloudflare Workers (without exposing the VM directly): + +```bash +# In the local repository +cd omnirouteCloud +npm install +npx wrangler login +npx wrangler deploy +``` + +See the full documentation at [omnirouteCloud/README.md](../omnirouteCloud/README.md). + +--- + +## Port Summary + +| Port | Service | Access | +| ----- | ----------- | -------------------------- | +| 22 | SSH | Public (with fail2ban) | +| 80 | nginx HTTP | Redirect โ†’ HTTPS | +| 443 | nginx HTTPS | Via Cloudflare Proxy | +| 20128 | OmniRoute | Localhost only (via nginx) | diff --git a/docs/i18n/sv/src/lib/a2a/README.md b/docs/i18n/sv/src/lib/a2a/README.md new file mode 100644 index 0000000000..ce4b070088 --- /dev/null +++ b/docs/i18n/sv/src/lib/a2a/README.md @@ -0,0 +1,752 @@ +# OmniRoute A2A Server (Svenska) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../../../src/lib/a2a/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../../../es/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../../../fr/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../../../de/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../../../it/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../../../ru/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../../../zh-CN/src/lib/a2a/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../../../ja/src/lib/a2a/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../../../ko/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../../../ar/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../../../in/src/lib/a2a/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../../../th/src/lib/a2a/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../../../vi/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../../../id/src/lib/a2a/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../../../ms/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../../../nl/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../../../pl/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../../../sv/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../../../no/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../../../da/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../../../fi/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../../../pt/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../../../ro/src/lib/a2a/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../../../hu/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../../../bg/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../../../sk/src/lib/a2a/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../../../uk-UA/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../../../he/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../../../phi/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../../../pt-BR/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../../../cs/src/lib/a2a/README.md) + +--- + +> **Agent-to-Agent Protocol v0.3** โ€” Enables any AI agent to use OmniRoute as an intelligent routing agent via JSON-RPC 2.0. + +The A2A Server exposes OmniRoute as a **first-class agent** that other agents can discover, delegate tasks to, and collaborate with using the [A2A Protocol](https://google.github.io/A2A/). + +--- + +## Arkitektur + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Orchestrator Agent โ”‚ +โ”‚ (LangChain, CrewAI, AutoGen, Custom Agent) โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ 1. GET /.well-known/agent.json (discover) + โ”‚ 2. POST /a2a (JSON-RPC 2.0) + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ OmniRoute A2A Server โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Task Manager โ”‚ โ”‚ Skill Engine โ”‚ โ”‚ SSE Streaming โ”‚ โ”‚ +โ”‚ โ”‚ (lifecycle) โ”‚โ”€โ”€โ”‚ (registry) โ”‚โ”€โ”€โ”‚ (real-time) โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ +โ”‚ Skills: โ”‚ โ”‚ +โ”‚ โ”œโ”€ smart-routing โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ””โ”€ quota-management โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ Routing Decision Logger โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ OmniRoute Gateway (internal) + /v1/chat/completions, /api/combos, /api/usage/quota +``` + +--- + +## Snabbstart + +### Agent Discovery + +Every A2A-compatible agent exposes an **Agent Card** at `/.well-known/agent.json`: + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +**Response:** + +```json +{ + "name": "OmniRoute", + "description": "Intelligent AI gateway with auto-routing across 50+ providers", + "url": "http://localhost:20128/a2a", + "version": "1.8.1", + "capabilities": { + "streaming": true, + "pushNotifications": false + }, + "skills": [ + { + "id": "smart-routing", + "name": "Smart Routing", + "description": "Routes prompts through OmniRoute intelligent pipeline", + "tags": ["routing", "llm", "multi-provider", "cost-optimization"], + "examples": [ + "Write a hello world in Python", + "Explain quantum computing using the cheapest provider" + ] + }, + { + "id": "quota-management", + "name": "Quota Management", + "description": "Natural-language queries about provider quotas", + "tags": ["quota", "analytics", "cost"], + "examples": [ + "Which provider has the most quota remaining?", + "Suggest a free combo for coding" + ] + } + ], + "authentication": { + "schemes": ["bearer"], + "apiKeyHeader": "Authorization" + } +} +``` + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Send a message to a skill and receive the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python hello world"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "a1b2c3d4-...", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "print('Hello, World!')" }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.0030)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "2026-03-04T..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"Quantum computing..."}}} + +: heartbeat 2026-03-04T21:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Running Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Skills Reference + +### `smart-routing` + +Routes prompts through OmniRoute's intelligent pipeline with full observability. + +**Parameters (in `metadata`):** + +| Parameter | Type | Default | Description | +| --------- | -------- | ------------ | ---------------------------------------------------------------------------------------- | +| `model` | `string` | `"auto"` | Target model (e.g., `claude-sonnet-4`, `gpt-4o`, `auto`) | +| `combo` | `string` | active combo | Specific combo to route through | +| `budget` | `number` | none | Maximum cost in USD for this request | +| `role` | `string` | none | Task role hint: `coding`, `review`, `planning`, `analysis`, `debugging`, `documentation` | + +**Returns:** + +| Field | Description | +| ------------------------------ | --------------------------------------------------------- | +| `artifacts[].content` | The LLM response text | +| `metadata.routing_explanation` | Human-readable explanation of routing decision | +| `metadata.cost_envelope` | Estimated vs actual cost with currency | +| `metadata.resilience_trace` | Array of events (primary_selected, fallback_needed, etc.) | +| `metadata.policy_verdict` | Whether the request was allowed and why | + +### `quota-management` + +Answers natural-language queries about provider quotas. + +**Query types (inferred from message content):** + +| Query Pattern | Response Type | +| ---------------------------------------------- | -------------------------------------------------------- | +| Contains `"ranking"`, `"most quota"`, `"best"` | Providers ranked by remaining quota | +| Contains `"free"`, `"suggest"` | Lists free combos or suggests free-tier providers | +| Default | Full quota summary with warnings for low-quota providers | + +--- + +## Task Lifecycle + +``` +submitted โ”€โ”€โ†’ working โ”€โ”€โ†’ completed + โ”€โ”€โ†’ failed + โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ†’ cancelled +``` + +| State | Description | +| ----------- | ----------------------------------------------------- | +| `submitted` | Task created, queued for execution | +| `working` | Skill handler is executing | +| `completed` | Execution succeeded, artifacts available | +| `failed` | Execution failed or task expired (TTL: 5 min default) | +| `cancelled` | Cancelled by client via `tasks/cancel` | + +- Terminal states: `completed`, `failed`, `cancelled` (no further transitions) +- Expired tasks in `submitted` or `working` are auto-marked as `failed` +- Tasks are garbage-collected after 2ร— TTL + +--- + +## Client Examples + +### Python โ€” Orchestrator Agent + +```python +""" +A2A Client โ€” Python example. +Discovers OmniRoute agent, sends a task, and processes the result. +""" +import requests +import json + +BASE_URL = "http://localhost:20128" +API_KEY = "your-api-key" +HEADERS = { + "Content-Type": "application/json", + "Authorization": f"Bearer {API_KEY}", +} + +# 1. Discover agent capabilities +agent_card = requests.get(f"{BASE_URL}/.well-known/agent.json").json() +print(f"Agent: {agent_card['name']} v{agent_card['version']}") +print(f"Skills: {[s['id'] for s in agent_card['skills']]}") + +# 2. Send a smart-routing task +response = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python quicksort implementation"}], + "metadata": { + "model": "auto", + "combo": "fast-coding", + "budget": 0.10, + } + } +}) +result = response.json()["result"] +print(f"\n๐Ÿ“ Response: {result['artifacts'][0]['content'][:200]}...") +print(f"๐Ÿ”€ Routing: {result['metadata']['routing_explanation']}") +print(f"๐Ÿ’ฐ Cost: ${result['metadata']['cost_envelope']['actual']}") +print(f"๐Ÿ›ก๏ธ Policy: {result['metadata']['policy_verdict']['reason']}") + +# 3. Query quota status +quota_resp = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-2", + "method": "message/send", + "params": { + "skill": "quota-management", + "messages": [{"role": "user", "content": "Which provider has the most quota remaining?"}], + } +}) +quota_result = quota_resp.json()["result"] +print(f"\n๐Ÿ“Š Quota: {quota_result['artifacts'][0]['content']}") +``` + +### TypeScript โ€” Multi-Agent Orchestrator + +```typescript +/** + * A2A Client โ€” TypeScript example. + * Shows agent discovery, task delegation, and streaming. + */ + +const BASE_URL = "http://localhost:20128"; +const API_KEY = "your-api-key"; + +interface JsonRpcResponse { + jsonrpc: "2.0"; + id: string | number; + result?: T; + error?: { code: number; message: string }; +} + +async function a2aCall(method: string, params: Record): Promise { + const resp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: `${method}-${Date.now()}`, + method, + params, + }), + }); + const json: JsonRpcResponse = await resp.json(); + if (json.error) throw new Error(`[${json.error.code}] ${json.error.message}`); + return json.result!; +} + +// โ”€โ”€ Agent Discovery โ”€โ”€ +const agentCard = await fetch(`${BASE_URL}/.well-known/agent.json`).then((r) => r.json()); +console.log(`Connected to: ${agentCard.name} (${agentCard.skills.length} skills)`); + +// โ”€โ”€ Smart Routing: Send a coding task โ”€โ”€ +const routingResult = await a2aCall("message/send", { + skill: "smart-routing", + messages: [{ role: "user", content: "Implement a Redis cache wrapper in TypeScript" }], + metadata: { model: "claude-sonnet-4", role: "coding" }, +}); +console.log("Response:", routingResult.artifacts[0].content); +console.log("Provider:", routingResult.metadata.routing_explanation); + +// โ”€โ”€ Quota Management: Find free alternatives โ”€โ”€ +const quotaResult = await a2aCall("message/send", { + skill: "quota-management", + messages: [{ role: "user", content: "Suggest free combos for documentation" }], +}); +console.log("Free combos:", quotaResult.artifacts[0].content); + +// โ”€โ”€ Streaming: Real-time response โ”€โ”€ +const streamResp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "stream-1", + method: "message/stream", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Explain microservices architecture" }], + }, + }), +}); + +const reader = streamResp.body!.getReader(); +const decoder = new TextDecoder(); +while (true) { + const { done, value } = await reader.read(); + if (done) break; + const chunk = decoder.decode(value); + for (const line of chunk.split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + if (event.params.chunk) { + process.stdout.write(event.params.chunk.content); + } + if (event.params.task.state === "completed") { + console.log("\nโœ… Stream completed"); + } + } + } +} +``` + +### Python โ€” LangChain A2A Integration + +```python +""" +LangChain integration โ€” Use OmniRoute A2A as a custom LLM. +""" +from langchain.llms.base import BaseLLM +from langchain.schema import LLMResult, Generation +import requests +from typing import List, Optional + +class OmniRouteA2A(BaseLLM): + base_url: str = "http://localhost:20128" + api_key: str = "" + model: str = "auto" + combo: Optional[str] = None + + @property + def _llm_type(self) -> str: + return "omniroute-a2a" + + def _call(self, prompt: str, stop: Optional[List[str]] = None, **kwargs) -> str: + response = requests.post( + f"{self.base_url}/a2a", + headers={ + "Content-Type": "application/json", + "Authorization": f"Bearer {self.api_key}", + }, + json={ + "jsonrpc": "2.0", + "id": "langchain-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": prompt}], + "metadata": { + "model": self.model, + **({"combo": self.combo} if self.combo else {}), + }, + }, + }, + ) + result = response.json()["result"] + return result["artifacts"][0]["content"] + + def _generate(self, prompts: List[str], stop=None, **kwargs) -> LLMResult: + return LLMResult( + generations=[[Generation(text=self._call(p, stop))] for p in prompts] + ) + +# Usage +llm = OmniRouteA2A( + base_url="http://localhost:20128", + api_key="your-key", + model="auto", + combo="fast-coding", +) +result = llm("Write a Python function to merge two sorted lists") +print(result) +``` + +### Go โ€” A2A Client + +```go +package main + +import ( + "bytes" + "encoding/json" + "fmt" + "io" + "net/http" +) + +const baseURL = "http://localhost:20128" +const apiKey = "your-api-key" + +type JsonRpcRequest struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Method string `json:"method"` + Params interface{} `json:"params"` +} + +type JsonRpcResponse struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Result interface{} `json:"result"` + Error *struct { + Code int `json:"code"` + Message string `json:"message"` + } `json:"error"` +} + +func a2aCall(method string, params interface{}) (*JsonRpcResponse, error) { + body, _ := json.Marshal(JsonRpcRequest{ + Jsonrpc: "2.0", + ID: "go-1", + Method: method, + Params: params, + }) + + req, _ := http.NewRequest("POST", baseURL+"/a2a", bytes.NewReader(body)) + req.Header.Set("Content-Type", "application/json") + req.Header.Set("Authorization", "Bearer "+apiKey) + + resp, err := http.DefaultClient.Do(req) + if err != nil { + return nil, err + } + defer resp.Body.Close() + data, _ := io.ReadAll(resp.Body) + + var result JsonRpcResponse + json.Unmarshal(data, &result) + return &result, nil +} + +func main() { + // Discover agent + resp, _ := http.Get(baseURL + "/.well-known/agent.json") + defer resp.Body.Close() + body, _ := io.ReadAll(resp.Body) + fmt.Println("Agent Card:", string(body)) + + // Send smart-routing task + result, _ := a2aCall("message/send", map[string]interface{}{ + "skill": "smart-routing", + "messages": []map[string]string{{"role": "user", "content": "Hello from Go!"}}, + "metadata": map[string]interface{}{"model": "auto"}, + }) + out, _ := json.MarshalIndent(result.Result, "", " ") + fmt.Println("Result:", string(out)) +} +``` + +--- + +## Use Cases + +### ๐Ÿค– Use Case 1: Multi-Agent Coding Pipeline + +An orchestrator agent delegates code generation to OmniRoute, then passes the output to a review agent. + +```python +def coding_pipeline(task: str): + # Step 1: Generate code via OmniRoute A2A + code_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Write production-quality code: {task}"} + ], metadata={"model": "auto", "role": "coding"}) + code = code_result["artifacts"][0]["content"] + + # Step 2: Review the code via OmniRoute A2A (different model) + review_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Review this code for bugs and improvements:\n\n{code}"} + ], metadata={"model": "auto", "role": "review"}) + review = review_result["artifacts"][0]["content"] + + # Step 3: Check costs + print(f"Code cost: ${code_result['metadata']['cost_envelope']['actual']}") + print(f"Review cost: ${review_result['metadata']['cost_envelope']['actual']}") + + return {"code": code, "review": review} +``` + +### ๐Ÿ’ก Use Case 2: Quota-Aware Agent Swarm + +Multiple agents share quota through OmniRoute, using the quota skill to coordinate. + +```python +async def quota_aware_agent(agent_name: str, task: str): + # Check quota before starting + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Which provider has the most quota remaining?"} + ]) + print(f"[{agent_name}] {quota['artifacts'][0]['content']}") + + # Send request with budget constraint + result = a2a_send("smart-routing", [ + {"role": "user", "content": task} + ], metadata={"budget": 0.05}) + + policy = result["metadata"]["policy_verdict"] + if not policy["allowed"]: + print(f"[{agent_name}] โš ๏ธ Budget exceeded: {policy['reason']}") + # Fall back to free combo + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Suggest free combos"} + ]) + print(f"[{agent_name}] Free alternatives: {quota['artifacts'][0]['content']}") + + return result +``` + +### ๐Ÿ“Š Use Case 3: Real-Time Streaming Dashboard + +A monitoring agent streams responses and displays progress in real-time. + +```typescript +async function streamingDashboard(prompt: string) { + const response = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { "Content-Type": "application/json", Authorization: `Bearer ${API_KEY}` }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "dash-1", + method: "message/stream", + params: { skill: "smart-routing", messages: [{ role: "user", content: prompt }] }, + }), + }); + + let totalChunks = 0; + const reader = response.body!.getReader(); + const decoder = new TextDecoder(); + + while (true) { + const { done, value } = await reader.read(); + if (done) break; + + for (const line of decoder.decode(value).split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + const state = event.params.task.state; + + if (state === "working" && event.params.chunk) { + totalChunks++; + process.stdout.write( + `\r[Chunk ${totalChunks}] ${event.params.chunk.content.slice(0, 50)}...` + ); + } + if (state === "completed") { + const meta = event.params.metadata; + console.log( + `\nโœ… Done | Cost: $${meta?.cost_envelope?.actual || 0} | Route: ${meta?.routing_explanation || "N/A"}` + ); + } + if (state === "failed") { + console.error(`\nโŒ Failed: ${event.params.metadata?.error}`); + } + } + } + } +} +``` + +### ๐Ÿ” Use Case 4: Task Polling Pattern + +For long-running tasks, poll the task status instead of waiting synchronously. + +```python +import time + +def poll_task(task_id: str, timeout: int = 60): + """Poll task status until completion or timeout.""" + start = time.time() + while time.time() - start < timeout: + result = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "poll-1", + "method": "tasks/get", + "params": {"taskId": task_id}, + }).json() + + task = result["result"]["task"] + state = task["state"] + print(f" Task {task_id[:8]}... state={state}") + + if state in ("completed", "failed", "cancelled"): + return task + time.sleep(2) + + # Timeout โ€” cancel the task + requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "cancel-1", + "method": "tasks/cancel", + "params": {"taskId": task_id}, + }) + raise TimeoutError(f"Task {task_id} timed out after {timeout}s") +``` + +--- + +## Error Codes + +| Code | Constant | Meaning | +| ------ | ------------------------ | ---------------------------------------- | +| -32700 | โ€” | Parse error (invalid JSON) | +| -32600 | `INVALID_REQUEST` | Invalid JSON-RPC request or unauthorized | +| -32601 | `METHOD_NOT_FOUND` | Unknown method or skill | +| -32602 | `INVALID_PARAMS` | Missing or invalid parameters | +| -32603 | `INTERNAL_ERROR` | Skill execution failed | +| -32001 | `TASK_NOT_FOUND` | Task ID not found | +| -32002 | `TASK_ALREADY_COMPLETED` | Cannot modify a completed task | +| -32003 | `UNAUTHORIZED` | Invalid or missing API key | +| -32004 | `BUDGET_EXCEEDED` | Request exceeds configured budget | +| -32005 | `PROVIDER_UNAVAILABLE` | No available providers | + +--- + +## Authentication + +All `/a2a` requests require a Bearer token via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server (`OMNIROUTE_API_KEY` is empty), authentication is bypassed. + +--- + +## File Structure + +``` +src/lib/a2a/ +โ”œโ”€โ”€ taskManager.ts # Task lifecycle (create/update/cancel/list), TTL, cleanup +โ”œโ”€โ”€ taskExecution.ts # Generic task executor with state management +โ”œโ”€โ”€ streaming.ts # SSE stream formatting, heartbeat, chunk/completion events +โ”œโ”€โ”€ routingLogger.ts # Routing decision logger (stats, history, retention) +โ””โ”€โ”€ skills/ + โ”œโ”€โ”€ smartRouting.ts # Smart routing skill (routes via /v1/chat/completions) + โ””โ”€โ”€ quotaManagement.ts # Quota management skill (natural-language quota queries) + +src/app/a2a/ +โ””โ”€โ”€ route.ts # Next.js API route handler (JSON-RPC 2.0 dispatch) + +open-sse/mcp-server/ +โ””โ”€โ”€ schemas/a2a.ts # Zod schemas (AgentCard, Task, JSON-RPC, SSE events) +``` + +--- + +## Comparison: MCP vs A2A + +| Feature | MCP Server | A2A Server | +| ----------------- | ---------------------------- | ------------------------------------------------- | +| **Protocol** | Model Context Protocol | Agent-to-Agent Protocol v0.3 | +| **Transport** | stdio / HTTP | HTTP (JSON-RPC 2.0) | +| **Discovery** | Tool listing via MCP | `/.well-known/agent.json` | +| **Granularity** | 16 individual tools | 2 high-level skills | +| **Best for** | IDE agents (Cursor, VS Code) | Multi-agent systems (LangChain, CrewAI) | +| **Streaming** | Not supported | SSE via `message/stream` | +| **Task tracking** | No | Full lifecycle (submitted โ†’ completed) | +| **Observability** | Audit log per tool call | Cost envelope + resilience trace + policy verdict | + +--- + +## Licens + +Part of [OmniRoute](https://github.com/diegosouzapw/OmniRoute) โ€” MIT License. diff --git a/docs/i18n/th/A2A-SERVER.md b/docs/i18n/th/A2A-SERVER.md deleted file mode 100644 index 01531ff482..0000000000 --- a/docs/i18n/th/A2A-SERVER.md +++ /dev/null @@ -1,200 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/A2A-SERVER.md) - ---- - -# OmniRoute A2A Server Documentation - -> Agent-to-Agent Protocol v0.3 โ€” OmniRoute as an intelligent routing agent - -## Agent Discovery - -```bash -curl http://localhost:20128/.well-known/agent.json -``` - -Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements. - ---- - -## Authentication - -All `/a2a` requests require an API key via the `Authorization` header: - -``` -Authorization: Bearer YOUR_OMNIROUTE_API_KEY -``` - -If no API key is configured on the server, authentication is bypassed. - ---- - -## JSON-RPC 2.0 Methods - -### `message/send` โ€” Synchronous Execution - -Sends a message to a skill and waits for the complete response. - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{ - "jsonrpc": "2.0", - "id": "1", - "method": "message/send", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Write a hello world in Python"}], - "metadata": {"model": "auto", "combo": "fast-coding"} - } - }' -``` - -**Response:** - -```json -{ - "jsonrpc": "2.0", - "id": "1", - "result": { - "task": { "id": "uuid", "state": "completed" }, - "artifacts": [{ "type": "text", "content": "..." }], - "metadata": { - "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)", - "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, - "resilience_trace": [ - { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." } - ], - "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } - } - } -} -``` - -### `message/stream` โ€” SSE Streaming - -Same as `message/send` but returns Server-Sent Events for real-time streaming. - -```bash -curl -N -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{ - "jsonrpc": "2.0", - "id": "1", - "method": "message/stream", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Explain quantum computing"}] - } - }' -``` - -**SSE Events:** - -``` -data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}} - -: heartbeat 2026-03-03T17:00:00Z - -data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} -``` - -### `tasks/get` โ€” Query Task Status - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' -``` - -### `tasks/cancel` โ€” Cancel a Task - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' -``` - ---- - -## Available Skills - -| Skill | Description | -| :----------------- | :------------------------------------------------------------------------------------------------------------------------------ | -| `smart-routing` | Routes prompts through OmniRoute's intelligent pipeline. Returns response with routing explanation, cost, and resilience trace. | -| `quota-management` | Answers natural-language queries about provider quotas, suggests free combos, and provides quota rankings. | - ---- - -## Task Lifecycle - -``` -submitted โ†’ working โ†’ completed - โ†’ failed - โ†’ cancelled -``` - -- Tasks expire after 5 minutes (configurable) -- Terminal states: `completed`, `failed`, `cancelled` -- Event log tracks every state transition - ---- - -## Error Codes - -| Code | Meaning | -| :----- | :----------------------------- | -| -32700 | Parse error (invalid JSON) | -| -32600 | Invalid request / Unauthorized | -| -32601 | Method or skill not found | -| -32602 | Invalid params | -| -32603 | Internal error | - ---- - -## Integration Examples - -### Python (requests) - -```python -import requests - -resp = requests.post("http://localhost:20128/a2a", json={ - "jsonrpc": "2.0", "id": "1", - "method": "message/send", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Hello"}] - } -}, headers={"Authorization": "Bearer YOUR_KEY"}) - -result = resp.json()["result"] -print(result["artifacts"][0]["content"]) -print(result["metadata"]["routing_explanation"]) -``` - -### TypeScript (fetch) - -```typescript -const resp = await fetch("http://localhost:20128/a2a", { - method: "POST", - headers: { - "Content-Type": "application/json", - Authorization: "Bearer YOUR_KEY", - }, - body: JSON.stringify({ - jsonrpc: "2.0", - id: "1", - method: "message/send", - params: { - skill: "smart-routing", - messages: [{ role: "user", content: "Hello" }], - }, - }), -}); -const { result } = await resp.json(); -console.log(result.metadata.routing_explanation); -``` diff --git a/docs/i18n/th/API_REFERENCE.md b/docs/i18n/th/API_REFERENCE.md deleted file mode 100644 index b878605221..0000000000 --- a/docs/i18n/th/API_REFERENCE.md +++ /dev/null @@ -1,455 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/API_REFERENCE.md) - ---- - -# API Reference - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/API_REFERENCE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/API_REFERENCE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/API_REFERENCE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/API_REFERENCE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/API_REFERENCE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/API_REFERENCE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/API_REFERENCE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/API_REFERENCE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/API_REFERENCE.md) - -Complete reference for all OmniRoute API endpoints. - ---- - -## Table of Contents - -- [Chat Completions](#chat-completions) -- [Embeddings](#embeddings) -- [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`. - -### ACP Agents - -| Endpoint | Method | Description | -| ----------------- | ------ | -------------------------------------------------------- | -| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | -| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | -| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | - -GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). - -### Resilience & Rate Limits - -| Endpoint | Method | Description | -| ----------------------- | ------- | ------------------------------- | -| `/api/resilience` | 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` diff --git a/docs/i18n/th/ARCHITECTURE.md b/docs/i18n/th/ARCHITECTURE.md deleted file mode 100644 index 4ea06a29f2..0000000000 --- a/docs/i18n/th/ARCHITECTURE.md +++ /dev/null @@ -1,787 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/ARCHITECTURE.md) - ---- - -# OmniRoute Architecture - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/ARCHITECTURE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/ARCHITECTURE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/ARCHITECTURE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/ARCHITECTURE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/ARCHITECTURE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/ARCHITECTURE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/ARCHITECTURE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/ARCHITECTURE.md) - -_Last updated: 2026-03-04_ - -## 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 (`...`) for reasoning models -- Response sanitization for strict OpenAI SDK compatibility -- Role normalization (developerโ†’system, systemโ†’user) for cross-provider compatibility -- Structured output conversion (json_schema โ†’ Gemini responseSchema) -- Local persistence for providers, keys, aliases, combos, settings, pricing -- Usage/cost tracking and request logging -- Optional cloud sync for multi-device/state sync -- IP allowlist/blocklist for API access control -- Thinking budget management (passthrough/auto/custom/adaptive) -- Global system prompt injection -- Session tracking and fingerprinting -- Per-account enhanced rate limiting with provider-specific profiles -- Circuit breaker pattern for provider resilience -- Anti-thundering herd protection with mutex locking -- Signature-based request deduplication cache -- Domain layer: model availability, cost rules, fallback policy, lockout policy -- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) -- Policy engine for centralized request evaluation (lockout โ†’ budget โ†’ fallback) -- Request telemetry with p50/p95/p99 latency aggregation -- Correlation ID (X-Request-Id) for end-to-end tracing -- Compliance audit logging with opt-out per API key -- Eval framework for LLM quality assurance -- Resilience UI dashboard with real-time circuit breaker status -- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) - -Primary runtime model: - -- Next.js 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[(storage.sqlite)] - UDB[(usage tables + log artifacts)] - end - - subgraph Upstreams[Upstream Providers] - P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/Qoder/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/route.ts` (GET) -- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) -- OAuth: `src/app/api/oauth/*` -- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` -- Usage: `src/app/api/usage/*` -- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` -- CLI tooling helpers: `src/app/api/cli-tools/*` -- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) -- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) -- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) -- Sessions: `src/app/api/sessions` (GET) -- Rate limits: `src/app/api/rate-limits` (GET) -- Resilience: `src/app/api/resilience` (GET/PATCH) โ€” provider profiles, circuit breaker, rate limit state -- Resilience reset: `src/app/api/resilience/reset` (POST) โ€” reset breakers + cooldowns -- Cache stats: `src/app/api/cache/stats` (GET/DELETE) -- Model availability: `src/app/api/models/availability` (GET/POST) -- Telemetry: `src/app/api/telemetry/summary` (GET) -- Budget: `src/app/api/usage/budget` (GET/POST) -- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) -- Compliance audit: `src/app/api/compliance/audit-log` (GET) -- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) -- Policies: `src/app/api/policies` (GET/POST) - -## 2) SSE + 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` -- Response sanitization: `open-sse/handlers/responseSanitizer.ts` -- Role normalization: `open-sse/services/roleNormalizer.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`, `qoder.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 (SQLite): - -- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) -- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) -- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) -- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** - -Usage persistence: - -- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) -- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` -- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) -- legacy JSON files are migrated to SQLite by startup migrations when present - -Domain State DB (SQLite): - -- `src/lib/db/domainState.ts` โ€” CRUD operations 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: - -- primary runtime DB: `${DATA_DIR}/storage.sqlite` -- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) -- structured call payload archives: `${DATA_DIR}/call_logs/` -- optional translator/request debug sessions: `/logs/...` - -## Deployment Topology - -```mermaid -flowchart LR - 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[(storage.sqlite)] - UsageDB[(usage tables + log artifacts)] - end - - subgraph External[External Services] - Providers[AI Providers] - SyncCloud[Cloud Sync Service] - end - - CLI --> Next - Browser --> Next - Next --> Core - Next --> MainDB - Core --> MainDB - Core --> UsageDB - Core --> Providers - Next --> SyncCloud -``` - -## Module Mapping (Decision-Critical) - -### Route and API Modules - -- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs -- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) -- `src/app/api/providers*`: provider CRUD, validation, testing -- `src/app/api/provider-nodes*`: custom compatible node management -- `src/app/api/provider-models`: custom model management (CRUD) -- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) -- `src/app/api/oauth/*`: OAuth/device-code flows -- `src/app/api/keys*`: local API key lifecycle -- `src/app/api/models/alias`: alias management -- `src/app/api/combos*`: fallback combo management -- `src/app/api/pricing`: pricing overrides for cost calculation -- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) -- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) -- `src/app/api/usage/*`: usage and logs APIs -- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers -- `src/app/api/cli-tools/*`: local CLI config writers/checkers -- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) -- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) -- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) -- `src/app/api/sessions`: active session listing (GET) -- `src/app/api/rate-limits`: per-account rate limit status (GET) - -### Routing and Execution Core - -- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop -- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup -- `open-sse/executors/*`: provider-specific network and format behavior - -### Translation Registry and Format Converters - -- `open-sse/translator/index.ts`: translator registry and orchestration -- Request translators: `open-sse/translator/request/*` -- Response translators: `open-sse/translator/response/*` -- Format constants: `open-sse/translator/formats.ts` - -### Persistence - -- `src/lib/db/*`: persistent config/state and domain persistence on SQLite -- `src/lib/localDb.ts`: compatibility re-export for DB modules -- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables - -## Provider Executor Coverage (Strategy Pattern) - -Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. - -| Executor | Provider(s) | Special Handling | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | -| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, Qoder, 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 | -| Qoder | openai | OAuth (Basic) | โœ… | โœ… | โœ… | โš ๏ธ Per request | -| OpenRouter | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| GLM/Kimi/MiniMax | claude | API Key | โœ… | โœ… | โŒ | โŒ | -| DeepSeek | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Groq | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| xAI (Grok) | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Mistral | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Perplexity | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Together AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Fireworks AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Cerebras | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Cohere | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| NVIDIA NIM | openai | API Key | โœ… | โœ… | โŒ | โŒ | - -## Format Translation Coverage - -Detected source formats include: - -- `openai` -- `openai-responses` -- `claude` -- `gemini` - -Target formats include: - -- OpenAI chat/Responses -- Claude -- Gemini/Gemini-CLI/Antigravity envelope -- Kiro -- Cursor - -Translations use **OpenAI as the hub format** โ€” all conversions go through OpenAI as intermediate: - -``` -Source Format โ†’ OpenAI (hub) โ†’ Target Format -``` - -Translations are selected dynamically based on source payload shape and provider target format. - -Additional processing layers in the translation pipeline: - -- **Response sanitization** โ€” Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance -- **Role normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI targets; merges `system` โ†’ `user` for models that reject the system role (GLM, ERNIE) -- **Think tag extraction** โ€” Parses `...` blocks from content into `reasoning_content` field -- **Structured output** โ€” Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` - -## Supported API Endpoints - -| 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 `/logs//` 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 - -- SQLite schema migrations and auto-upgrade hooks at startup -- legacy JSON โ†’ SQLite migration compatibility path - -## Observability and Operational Signals - -Runtime visibility sources: - -- console logs from `src/sse/utils/logger.ts` -- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) -- textual request status log in `log.txt` (optional/compat) -- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` -- dashboard usage endpoints (`/api/usage/*`) for UI consumption - -## Security-Sensitive Boundaries - -- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing -- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning -- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format -- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level -- Cloud sync endpoints rely on API key auth + machine id semantics - -## Environment and Runtime Matrix - -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` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. -2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. -3. Request logger writes full headers/body when enabled; treat log directory as sensitive. -4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. -5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. -6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). -7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). -8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). - -## Operational Verification Checklist - -- Build from source: `npm run build` -- Build Docker image: `docker build -t omniroute .` -- Start service and verify: -- `GET /api/settings` -- `GET /api/v1/models` -- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/th/AUTO-COMBO.md b/docs/i18n/th/AUTO-COMBO.md deleted file mode 100644 index 2166e41dff..0000000000 --- a/docs/i18n/th/AUTO-COMBO.md +++ /dev/null @@ -1,67 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/AUTO-COMBO.md) - ---- - -# OmniRoute Auto-Combo Engine - -> Self-managing model chains with adaptive scoring - -## How It Works - -The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**: - -| Factor | Weight | Description | -| :--------- | :----- | :---------------------------------------------- | -| Quota | 0.20 | Remaining capacity [0..1] | -| Health | 0.25 | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 | -| CostInv | 0.20 | Inverse cost (cheaper = higher score) | -| LatencyInv | 0.15 | Inverse p95 latency (faster = higher) | -| TaskFit | 0.10 | Model ร— task type fitness score | -| Stability | 0.10 | Low variance in latency/errors | - -## Mode Packs - -| Pack | Focus | Key Weight | -| :---------------------- | :----------- | :--------------- | -| ๐Ÿš€ **Ship Fast** | Speed | latencyInv: 0.35 | -| ๐Ÿ’ฐ **Cost Saver** | Economy | costInv: 0.40 | -| ๐ŸŽฏ **Quality First** | Best model | taskFit: 0.40 | -| ๐Ÿ“ก **Offline Friendly** | Availability | quota: 0.40 | - -## Self-Healing - -- **Temporary exclusion**: Score < 0.2 โ†’ excluded for 5 min (progressive backoff, max 30 min) -- **Circuit breaker awareness**: OPEN โ†’ auto-excluded; HALF_OPEN โ†’ probe requests -- **Incident mode**: >50% OPEN โ†’ disable exploration, maximize stability -- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout - -## Bandit Exploration - -5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode. - -## API - -```bash -# Create auto-combo -curl -X POST http://localhost:20128/api/combos/auto \ - -H "Content-Type: application/json" \ - -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}' - -# List auto-combos -curl http://localhost:20128/api/combos/auto -``` - -## Task Fitness - -30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` โ†’ high coding score). - -## Files - -| File | Purpose | -| :------------------------------------------- | :------------------------------------ | -| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization | -| `open-sse/services/autoCombo/taskFitness.ts` | Model ร— task fitness lookup | -| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap | -| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode | -| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles | -| `src/app/api/combos/auto/route.ts` | REST API | diff --git a/docs/i18n/th/CHANGELOG.md b/docs/i18n/th/CHANGELOG.md index afbdd9c106..11d6f7335b 100644 --- a/docs/i18n/th/CHANGELOG.md +++ b/docs/i18n/th/CHANGELOG.md @@ -1,12 +1,92 @@ # Changelog (เน„เธ—เธข) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CHANGELOG.md) --- - ## [Unreleased] +### ๐Ÿ› ๏ธ Maintenance + +- **AGENTS.md rewrite:** Condensed from 297โ†’153 lines. Added build/lint/test commands (including single-test execution), code style guidelines (Prettier, TypeScript, ESLint, naming, imports, error handling, security), and trimmed verbose architecture tables for AI agent consumption. + +## [3.4.2] - 2026-04-01 + +### ๐Ÿ› Bug Fixes + +- **CI Stabilization:** Fixed failing analytics/settings Playwright selectors and request assertions so GitHub Actions E2E runs pass reliably across localized UIs and switch-based controls. +- **Deterministic Tests:** Removed date-sensitive quota fixtures from Copilot usage tests and aligned idempotency/model catalog tests with the merged runtime behavior. +- **MCP Type Hardening:** Removed zero-budget explicit `any` regressions from the MCP server tool registration path, restoring the `check:any-budget:t11` workflow gate. + +### ๐Ÿ› ๏ธ Maintenance + +- **Release Branch Integration:** Consolidated the active feature branches into `release/v3.4.2` on top of current `main` and validated the branch with lint, unit, coverage, build, and CI-mode E2E runs. + +## [3.4.1] - 2026-03-31 + +> [!WARNING] +> **BREAKING CHANGE: request logging, retention, and logging environment variables have been redesigned.** +> On the first startup after upgrading, OmniRoute archives legacy request logs from `DATA_DIR/logs/`, legacy `DATA_DIR/call_logs/`, and `DATA_DIR/log.txt` into `DATA_DIR/log_archives/*.zip`, then removes the deprecated layout and switches to the new unified artifact format under `DATA_DIR/call_logs/`. + +### โœจ New Features + +- **.ENV Migration Utility:** Included `scripts/migrate-env.mjs` to seamlessly migrate ` Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` - ---- - -## Step 2 โ€” Install CLI Tools - -All npm-based tools require Node.js 18+: - -```bash -# Claude Code (Anthropic) -npm install -g @anthropic-ai/claude-code - -# OpenAI Codex -npm install -g @openai/codex - -# Gemini CLI (Google) -npm install -g @google/gemini-cli - -# OpenCode -npm install -g opencode-ai - -# Cline -npm install -g cline - -# KiloCode -npm install -g kilecode - -# Kiro CLI (Amazon โ€” requires curl + unzip) -apt-get install -y unzip # on Debian/Ubuntu -curl -fsSL https://cli.kiro.dev/install | bash -export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc -``` - -**Verify:** - -```bash -claude --version # 2.x.x -codex --version # 0.x.x -gemini --version # 0.x.x -opencode --version # x.x.x -cline --version # 2.x.x -kilocode --version # x.x.x (or: kilo --version) -kiro-cli --version # 1.x.x -``` - ---- - -## Step 3 โ€” Set Global Environment Variables - -Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`: - -```bash -# OmniRoute Universal Endpoint -export OPENAI_BASE_URL="http://localhost:20128/v1" -export OPENAI_API_KEY="sk-your-omniroute-key" -export ANTHROPIC_BASE_URL="http://localhost:20128/v1" -export ANTHROPIC_API_KEY="sk-your-omniroute-key" -export GEMINI_BASE_URL="http://localhost:20128/v1" -export GEMINI_API_KEY="sk-your-omniroute-key" -``` - -> For a **remote server** replace `localhost:20128` with the server IP or domain, -> e.g. `http://192.168.0.15:20128`. - ---- - -## Step 4 โ€” Configure Each Tool - -### Claude Code - -```bash -# Via CLI: -claude config set --global api-base-url http://localhost:20128/v1 - -# Or create ~/.claude/settings.json: -mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF -{ - "apiBaseUrl": "http://localhost:20128/v1", - "apiKey": "sk-your-omniroute-key" -} -EOF -``` - -**Test:** `claude "say hello"` - ---- - -### OpenAI Codex - -```bash -mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF -model: auto -apiKey: sk-your-omniroute-key -apiBaseUrl: http://localhost:20128/v1 -EOF -``` - -**Test:** `codex "what is 2+2?"` - ---- - -### Gemini CLI - -```bash -mkdir -p ~/.gemini && cat > ~/.gemini/settings.json << EOF -{ - "apiKey": "sk-your-omniroute-key", - "baseUrl": "http://localhost:20128/v1" -} -EOF -``` - -**Test:** `gemini "hello"` - ---- - -### OpenCode - -```bash -mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF -[provider.openai] -base_url = "http://localhost:20128/v1" -api_key = "sk-your-omniroute-key" -EOF -``` - -**Test:** `opencode` - ---- - -### Cline (CLI or VS Code) - -**CLI mode:** - -```bash -mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF -{ - "apiProvider": "openai", - "openAiBaseUrl": "http://localhost:20128/v1", - "openAiApiKey": "sk-your-omniroute-key" -} -EOF -``` - -**VS Code mode:** -Cline extension settings โ†’ API Provider: `OpenAI Compatible` โ†’ Base URL: `http://localhost:20128/v1` - -Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ Cline โ†’ Apply Config**. - ---- - -### KiloCode (CLI or VS Code) - -**CLI mode:** - -```bash -kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key -``` - -**VS Code settings:** - -```json -{ - "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", - "kilo-code.apiKey": "sk-your-omniroute-key" -} -``` - -Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ KiloCode โ†’ Apply Config**. - ---- - -### Continue (VS Code Extension) - -Edit `~/.continue/config.yaml`: - -```yaml -models: - - name: OmniRoute - provider: openai - model: auto - apiBase: http://localhost:20128/v1 - apiKey: sk-your-omniroute-key - default: true -``` - -Restart VS Code after editing. - ---- - -### Kiro CLI (Amazon) - -```bash -# Login to your AWS/Kiro account: -kiro-cli login - -# The CLI uses its own auth โ€” OmniRoute is not needed as backend for Kiro CLI itself. -# Use kiro-cli alongside OmniRoute for other tools. -kiro-cli status -``` - ---- - -### Cursor (Desktop App) - -> **Note:** Cursor routes requests through its cloud. For OmniRoute integration, -> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL. - -Via GUI: **Settings โ†’ Models โ†’ OpenAI API Key** - -- Base URL: `https://your-domain.com/v1` -- API Key: your OmniRoute key - ---- - -## Dashboard Auto-Configuration - -The OmniRoute dashboard automates configuration for most tools: - -1. Go to `http://localhost:20128/dashboard/cli-tools` -2. Expand any tool card -3. Select your API key from the dropdown -4. Click **Apply Config** (if tool is detected as installed) -5. Or copy the generated config snippet manually - ---- - -## Built-in Agents: Droid & OpenClaw - -**Droid** and **OpenClaw** are AI agents built directly into OmniRoute โ€” no installation needed. -They run as internal routes and use OmniRoute's model routing automatically. - -- Access: `http://localhost:20128/dashboard/agents` -- Configure: same combos and providers as all other tools -- No API key or CLI install required - ---- - -## Available API Endpoints - -| Endpoint | Description | Use For | -| -------------------------- | ----------------------------- | --------------------------- | -| `/v1/chat/completions` | Standard chat (all providers) | All modern tools | -| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows | -| `/v1/completions` | Legacy text completions | Older tools using `prompt:` | -| `/v1/embeddings` | Text embeddings | RAG, search | -| `/v1/images/generations` | Image generation | DALL-E, Flux, etc. | -| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS | -| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI | - ---- - -## Troubleshooting - -| Error | Cause | Fix | -| ------------------------- | ----------------------- | ------------------------------------------ | -| `Connection refused` | OmniRoute not running | `pm2 start omniroute` | -| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` | -| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` | -| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` | -| CLI shows "not installed" | Binary not in PATH | Check `which ` | -| `kiro-cli: not found` | Not in PATH | `export PATH="$HOME/.local/bin:$PATH"` | - ---- - -## Quick Setup Script (One Command) - -```bash -# Install all CLIs and configure for OmniRoute (replace with your key and server URL) -OMNIROUTE_URL="http://localhost:20128/v1" -OMNIROUTE_KEY="sk-your-omniroute-key" - -npm install -g @anthropic-ai/claude-code @openai/codex @google/gemini-cli opencode-ai cline kilecode - -# Kiro CLI -apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash - -# Write configs -mkdir -p ~/.claude ~/.codex ~/.gemini ~/.config/opencode ~/.continue - -cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" -cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" -cat > ~/.gemini/settings.json <<< "{\"apiKey\":\"$OMNIROUTE_KEY\",\"baseUrl\":\"$OMNIROUTE_URL\"}" -cat >> ~/.bashrc << EOF -export OPENAI_BASE_URL="$OMNIROUTE_URL" -export OPENAI_API_KEY="$OMNIROUTE_KEY" -export ANTHROPIC_BASE_URL="$OMNIROUTE_URL" -export ANTHROPIC_API_KEY="$OMNIROUTE_KEY" -EOF - -source ~/.bashrc -echo "โœ… All CLIs installed and configured for OmniRoute" -``` diff --git a/docs/i18n/th/CODEBASE_DOCUMENTATION.md b/docs/i18n/th/CODEBASE_DOCUMENTATION.md deleted file mode 100644 index e2d7950052..0000000000 --- a/docs/i18n/th/CODEBASE_DOCUMENTATION.md +++ /dev/null @@ -1,593 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CODEBASE_DOCUMENTATION.md) - ---- - -# omniroute โ€” Codebase Documentation - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) - -> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. - ---- - -## 1. 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
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, Qoder, 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 | -| Qoder | 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"] -``` diff --git a/docs/i18n/th/CONTRIBUTING.md b/docs/i18n/th/CONTRIBUTING.md new file mode 100644 index 0000000000..0d99255c0f --- /dev/null +++ b/docs/i18n/th/CONTRIBUTING.md @@ -0,0 +1,299 @@ +# Contributing to OmniRoute (เน„เธ—เธข) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CONTRIBUTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CONTRIBUTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CONTRIBUTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CONTRIBUTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CONTRIBUTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CONTRIBUTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CONTRIBUTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CONTRIBUTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CONTRIBUTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CONTRIBUTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CONTRIBUTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CONTRIBUTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CONTRIBUTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CONTRIBUTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CONTRIBUTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CONTRIBUTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CONTRIBUTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CONTRIBUTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CONTRIBUTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CONTRIBUTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CONTRIBUTING.md) + +--- + +Thank you for your interest in contributing! This guide covers everything you need to get started. + +--- + +## Development Setup + +### Prerequisites + +- **Node.js** >= 18 < 24 (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` | `20128` | Server port | +| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | Base URL for frontend | +| `JWT_SECRET` | (generate above) | JWT signing secret | +| `INITIAL_PASSWORD` | `CHANGEME` | First login password | +| `APP_LOG_LEVEL` | `info` | Log verbosity level | + +### Dashboard Settings + +The dashboard provides UI toggles for features that can also be configured via environment variables: + +| Setting Location | Toggle | Description | +| ------------------- | ------------------ | ------------------------------ | +| Settings โ†’ Advanced | Debug Mode | Enable debug request logs (UI) | +| Settings โ†’ General | Sidebar Visibility | Show/hide sidebar sections | + +These settings are stored in the database and persist across restarts, overriding env var defaults when set. + +### 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:20128/dashboard` +- **API**: `http://localhost:20128/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`, `mcp`, `a2a`, `memory`, `skills`. + +--- + +## Running Tests + +```bash +# All tests (unit + vitest + ecosystem + e2e) +npm run test:all + +# Single test file (Node.js native test runner โ€” most tests use this) +node --import tsx/esm --test tests/unit/your-file.test.mjs + +# Vitest (MCP server, autoCombo, cache) +npm run test:vitest + +# E2E tests (requires Playwright) +npm run test:e2e + +# Protocol clients E2E (MCP transports, A2A) +npm run test:protocols:e2e + +# Ecosystem compatibility tests +npm run test:ecosystem + +# Coverage (55% min statements/lines/functions; 60% branches) +npm run test:coverage +npm run coverage:report + +# Lint + format check +npm run lint +npm run check +``` + +Coverage notes: + +- `npm run test:coverage` measures source coverage for the main unit test suite, excludes `tests/**`, and includes `open-sse/**` +- `npm run coverage:report` prints the detailed file-by-file report from the latest coverage run +- `npm run test:coverage:legacy` preserves the older metric for historical comparison +- See `docs/COVERAGE_PLAN.md` for the phased coverage improvement roadmap + +Current test status: **122 unit test files** covering: + +- Provider translators and format conversion +- Rate limiting, circuit breaker, and resilience +- Semantic cache, idempotency, progress tracking +- Database operations and schema (21 DB modules) +- OAuth flows and authentication +- API endpoint validation (Zod v4) +- MCP server tools and scope enforcement +- Memory and Skills systems + +--- + +## Code Style + +- **ESLint** โ€” Run `npm run lint` before committing +- **Prettier** โ€” Auto-formatted via `lint-staged` on commit (2 spaces, semicolons, double quotes, 100 char width, es5 trailing commas) +- **TypeScript** โ€” All `src/` code uses `.ts`/`.tsx`; `open-sse/` uses `.ts`/`.js`; document with TSDoc (`@param`, `@returns`, `@throws`) +- **No `eval()`** โ€” ESLint enforces `no-eval`, `no-implied-eval`, `no-new-func` +- **Zod validation** โ€” Use Zod v4 schemas for all API input validation +- **Naming**: Files = camelCase/kebab-case, components = PascalCase, constants = UPPER_SNAKE + +--- + +## Project Structure + +``` +src/ # TypeScript (.ts / .tsx) +โ”œโ”€โ”€ app/ # Next.js 16 App Router +โ”‚ โ”œโ”€โ”€ (dashboard)/ # Dashboard pages (23 sections) +โ”‚ โ”œโ”€โ”€ api/ # API routes (51 directories) +โ”‚ โ””โ”€โ”€ login/ # Auth pages (.tsx) +โ”œโ”€โ”€ domain/ # Policy engine (policyEngine, comboResolver, costRules, etc.) +โ”œโ”€โ”€ lib/ # Core business logic (.ts) +โ”‚ โ”œโ”€โ”€ a2a/ # Agent-to-Agent v0.3 protocol server +โ”‚ โ”œโ”€โ”€ acp/ # Agent Communication Protocol registry +โ”‚ โ”œโ”€โ”€ compliance/ # Compliance policy engine +โ”‚ โ”œโ”€โ”€ db/ # SQLite database layer (21 modules + 16 migrations) +โ”‚ โ”œโ”€โ”€ memory/ # Persistent conversational memory +โ”‚ โ”œโ”€โ”€ oauth/ # OAuth providers, services, and utilities +โ”‚ โ”œโ”€โ”€ skills/ # Extensible skill framework +โ”‚ โ”œโ”€โ”€ usage/ # Usage tracking and cost calculation +โ”‚ โ””โ”€โ”€ localDb.ts # Re-export layer only โ€” never add logic here +โ”œโ”€โ”€ middleware/ # Request middleware (promptInjectionGuard) +โ”œโ”€โ”€ mitm/ # MITM proxy (cert, DNS, target routing) +โ”œโ”€โ”€ shared/ +โ”‚ โ”œโ”€โ”€ components/ # React components (.tsx) +โ”‚ โ”œโ”€โ”€ constants/ # Provider definitions (60+), MCP scopes, routing strategies +โ”‚ โ”œโ”€โ”€ utils/ # Circuit breaker, sanitizer, auth helpers +โ”‚ โ””โ”€โ”€ validation/ # Zod v4 schemas +โ””โ”€โ”€ sse/ # SSE proxy pipeline + +open-sse/ # @omniroute/open-sse workspace +โ”œโ”€โ”€ executors/ # 14 provider-specific request executors +โ”œโ”€โ”€ handlers/ # 11 request handlers (chat, responses, embeddings, images, etc.) +โ”œโ”€โ”€ mcp-server/ # MCP server (25 tools, 3 transports, 10 scopes) +โ”œโ”€โ”€ services/ # 36+ services (combo, autoCombo, rateLimitManager, etc.) +โ”œโ”€โ”€ translator/ # Format translators (OpenAI โ†” Claude โ†” Gemini โ†” Responses โ†” Ollama) +โ”œโ”€โ”€ transformer/ # Responses API transformer +โ””โ”€โ”€ utils/ # 22 utility modules (stream, TLS, proxy, logging) + +electron/ # Electron desktop app (cross-platform) + +tests/ +โ”œโ”€โ”€ unit/ # Node.js test runner (122 test files) +โ”œโ”€โ”€ integration/ # Integration tests +โ”œโ”€โ”€ e2e/ # Playwright tests +โ”œโ”€โ”€ security/ # Security tests +โ”œโ”€โ”€ translator/ # Translator-specific tests +โ””โ”€โ”€ load/ # Load tests + +docs/ # Documentation +โ”œโ”€โ”€ ARCHITECTURE.md # System architecture +โ”œโ”€โ”€ API_REFERENCE.md # All endpoints +โ”œโ”€โ”€ USER_GUIDE.md # Provider setup, CLI integration +โ”œโ”€โ”€ TROUBLESHOOTING.md # Common issues +โ”œโ”€โ”€ MCP-SERVER.md # MCP server (25 tools) +โ”œโ”€โ”€ A2A-SERVER.md # A2A agent protocol +โ”œโ”€โ”€ AUTO-COMBO.md # Auto-combo engine +โ”œโ”€โ”€ CLI-TOOLS.md # CLI tools integration +โ”œโ”€โ”€ COVERAGE_PLAN.md # Test coverage improvement plan +โ”œโ”€โ”€ openapi.yaml # OpenAPI specification +โ””โ”€โ”€ adr/ # Architecture Decision Records +``` + +--- + +## Adding a New Provider + +### Step 1: Register Provider Constants + +Add to `src/shared/constants/providers.ts` โ€” Zod-validated at module load. + +### Step 2: Add Executor (if custom logic needed) + +Create executor in `open-sse/executors/your-provider.ts` extending the base executor. + +### Step 3: Add Translator (if non-OpenAI format) + +Create request/response translators in `open-sse/translator/`. + +### Step 4: Add OAuth Config (if OAuth-based) + +Add OAuth credentials in `src/lib/oauth/constants/oauth.ts` and service in `src/lib/oauth/services/`. + +### Step 5: Register Models + +Add model definitions in `open-sse/config/providerRegistry.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 +- [ ] All inputs validated with Zod schemas +- [ ] CHANGELOG updated (if user-facing change) +- [ ] Documentation updated (if applicable) + +--- + +## Releasing + +Releases are managed via the `/generate-release` workflow. When a new GitHub Release is created, the package is **automatically published to npm** via GitHub Actions. + +--- + +## Getting Help + +- **Architecture**: See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) +- **API Reference**: See [`docs/API_REFERENCE.md`](docs/API_REFERENCE.md) +- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **ADRs**: See `docs/adr/` for architectural decision records diff --git a/docs/i18n/th/FEATURES.md b/docs/i18n/th/FEATURES.md deleted file mode 100644 index 253fd6246f..0000000000 --- a/docs/i18n/th/FEATURES.md +++ /dev/null @@ -1,147 +0,0 @@ -# OmniRoute โ€” Dashboard Features Gallery (เน„เธ—เธข) - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) - -> ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../docs/FEATURES.md) - ---- - -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 (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. - -![Providers Dashboard](screenshots/01-providers.png) - ---- - -## ๐ŸŽจ Combos - -Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. - -![Combos Dashboard](screenshots/02-combos.png) - ---- - -## ๐Ÿ“Š Analytics - -Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. - -![Analytics Dashboard](screenshots/03-analytics.png) - ---- - -## ๐Ÿฅ System Health - -Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. - -![Health Dashboard](screenshots/04-health.png) - ---- - -## ๐Ÿ”ง Translator Playground - -Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). - -![Translator Playground](screenshots/05-translator.png) - ---- - -## ๐ŸŽฎ Model Playground _(v2.0.9+)_ - -Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. - ---- - -## ๐ŸŽจ Themes _(v2.0.5+)_ - -Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. - ---- - -## โš™๏ธ Settings - -Comprehensive settings panel with tabs: - -- **General** โ€” System storage, backup management (export/import database) -- **Appearance** โ€” Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls -- **Security** โ€” API endpoint protection, custom provider blocking, IP filtering, session info -- **Routing** โ€” Model aliases, background task degradation -- **Resilience** โ€” Rate limit persistence, circuit breaker tuning -- **Advanced** โ€” Configuration overrides - -![Settings Dashboard](screenshots/06-settings.png) - ---- - -## ๐Ÿ”ง CLI Tools - -One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. - -![CLI Tools Dashboard](screenshots/07-cli-tools.png) - ---- - -## ๐Ÿค– CLI Agents _(v2.0.11+)_ - -Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: - -- **Installation status** โ€” Installed / Not Found with version detection -- **Protocol badges** โ€” stdio, HTTP, etc. -- **Custom agents** โ€” Register any CLI tool via form (name, binary, version command, spawn args) -- **CLI Fingerprint Matching** โ€” Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP - ---- - -## ๐Ÿ–ผ๏ธ Media _(v2.0.3+)_ - -Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. - ---- - -## ๐Ÿ“ Request Logs - -Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. - -![Usage Logs](screenshots/08-usage.png) - ---- - -## ๐ŸŒ API Endpoint - -Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. - -![Endpoint Dashboard](screenshots/09-endpoint.png) - ---- - -## ๐Ÿ”‘ API Key Management - -Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. - ---- - -## ๐Ÿ“‹ Audit Log - -Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. - ---- - -## ๐Ÿ–ฅ๏ธ Desktop Application - -Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. - -Key features: - -- Server readiness polling (no blank screen on cold start) -- System tray with port management -- Content Security Policy -- Single-instance lock -- Auto-update on restart -- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) -- Hardened Electron build packaging โ€” symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+) - -๐Ÿ“– See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/th/MCP-SERVER.md b/docs/i18n/th/MCP-SERVER.md deleted file mode 100644 index 829acd30b1..0000000000 --- a/docs/i18n/th/MCP-SERVER.md +++ /dev/null @@ -1,87 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/MCP-SERVER.md) - ---- - -# OmniRoute MCP Server Documentation - -> Model Context Protocol server with 16 intelligent tools - -## Installation - -OmniRoute MCP is built-in. Start it with: - -```bash -omniroute --mcp -``` - -Or via the open-sse transport: - -```bash -# HTTP streamable transport (port 20130) -omniroute --dev # MCP auto-starts on /mcp endpoint -``` - -## IDE Configuration - -See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup. - ---- - -## Essential Tools (8) - -| Tool | Description | -| :------------------------------ | :--------------------------------------- | -| `omniroute_get_health` | Gateway health, circuit breakers, uptime | -| `omniroute_list_combos` | All configured combos with models | -| `omniroute_get_combo_metrics` | Performance metrics for a specific combo | -| `omniroute_switch_combo` | Switch active combo by ID/name | -| `omniroute_check_quota` | Quota status per provider or all | -| `omniroute_route_request` | Send a chat completion through OmniRoute | -| `omniroute_cost_report` | Cost analytics for a time period | -| `omniroute_list_models_catalog` | Full model catalog with capabilities | - -## Advanced Tools (8) - -| Tool | Description | -| :--------------------------------- | :---------------------------------------------- | -| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | -| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | -| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | -| `omniroute_test_combo` | Live-test all models in a combo | -| `omniroute_get_provider_metrics` | Detailed metrics for one provider | -| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | -| `omniroute_explain_route` | Explain a past routing decision | -| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | - -## Authentication - -MCP tools are authenticated via API key scopes. Each tool requires specific scopes: - -| Scope | Tools | -| :------------- | :----------------------------------------------- | -| `read:health` | get_health, get_provider_metrics | -| `read:combos` | list_combos, get_combo_metrics | -| `write:combos` | switch_combo | -| `read:quota` | check_quota | -| `write:route` | route_request, simulate_route, test_combo | -| `read:usage` | cost_report, get_session_snapshot, explain_route | -| `write:config` | set_budget_guard, set_resilience_profile | -| `read:models` | list_models_catalog, best_combo_for_task | - -## Audit Logging - -Every tool call is logged to `mcp_tool_audit` with: - -- Tool name, arguments, result -- Duration (ms), success/failure -- API key hash, timestamp - -## Files - -| File | Purpose | -| :------------------------------------------- | :------------------------------------------ | -| `open-sse/mcp-server/server.ts` | MCP server creation + 16 tool registrations | -| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport | -| `open-sse/mcp-server/auth.ts` | API key + scope validation | -| `open-sse/mcp-server/audit.ts` | Tool call audit logging | -| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers | diff --git a/docs/i18n/th/README.md b/docs/i18n/th/README.md index 8186bc62e6..0df531bd07 100644 --- a/docs/i18n/th/README.md +++ b/docs/i18n/th/README.md @@ -1,12 +1,12 @@ # ๐Ÿš€ OmniRoute โ€” The Free AI Gateway (เน„เธ—เธข) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/README.md) --- ### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback. -_Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._ +_Your universal API proxy โ€” one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._ **Chat Completions โ€ข Embeddings โ€ข Image Generation โ€ข Video โ€ข Music โ€ข Audio โ€ข Reranking โ€ข **Web Search** โ€ข MCP Server โ€ข A2A Protocol โ€ข 100% TypeScript** @@ -46,15 +46,17 @@ _Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now wi > - `APP_LOG_FILE_PATH` > - `APP_LOG_MAX_FILE_SIZE` > - `APP_LOG_RETENTION_DAYS` +> - `APP_LOG_MAX_FILES` > - `APP_LOG_LEVEL` > - `APP_LOG_FORMAT` > - `CALL_LOG_RETENTION_DAYS` +> - `CALL_LOG_MAX_ENTRIES` > > For release details and upgrade notes, see the [CHANGELOG](CHANGELOG.md). --- -## ๐Ÿ†• What's New in v3.0.0 +## ๐Ÿ†• What's New > **Upgrading from v2.9.5?** โ€” See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes. @@ -274,7 +276,7 @@ Developers pay $20โ€“200/month for Claude Pro, Codex Pro, or GitHub Copilot. Eve - **Smart 4-Tier Fallback** โ€” If subscription quota runs out, automatically redirects to API Key โ†’ Cheap โ†’ Free with zero manual intervention - **Real-Time Quota Tracking** โ€” Shows token consumption in real-time with reset countdown (5h, daily, weekly) - **Multi-Account Support** โ€” Multiple accounts per provider with auto round-robin โ€” when one runs out, switches to the next -- **Custom Combos** โ€” Customizable fallback chains with 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Custom Combos** โ€” Customizable fallback chains with 9 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random) - **Codex Business Quotas** โ€” Business/Team workspace quota monitoring directly in the dashboard @@ -286,7 +288,7 @@ OpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If **How OmniRoute solves it:** -- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 67+ providers +- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 60+ providers - **Format Translation** โ€” Automatic and transparent: OpenAI โ†” Claude โ†” Gemini โ†” Responses API - **Response Sanitization** โ€” Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+ - **Role Normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI providers; `system` โ†’ `user` for GLM/ERNIE @@ -372,7 +374,7 @@ Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code.. - **CLI Tools Dashboard** โ€” Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline - **GitHub Copilot Config Generator** โ€” Generates `chatLanguageModels.json` for VS Code with bulk model selection - **Onboarding Wizard** โ€” Guided 4-step setup for first-time users -- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 67+ providers +- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 60+ providers @@ -419,7 +421,7 @@ When a call fails, the dev doesn't know if it was a rate limit, expired token, w - **SQLite Proxy Logs** โ€” Persistent logs that survive server restarts - **Translator Playground** โ€” 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time) - **Request Telemetry** โ€” p50/p95/p99 latency + X-Request-Id tracing -- **File-Based Logging with Rotation** โ€” Console interceptor captures everything to JSON log with size-based rotation +- **File-Based Logging with Rotation** โ€” App logs rotate by size, retention days, and archive count; call log artifacts rotate by retention days and file count - **System Info Report** โ€” `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage. @@ -514,7 +516,7 @@ Developers who want all responses in a specific language, with a specific tone, - **System Prompt Injection** โ€” Global prompt applied to all requests - **Thinking Budget Validation** โ€” Reasoning token allocation control per request (passthrough, auto, custom, adaptive) -- **6 Routing Strategies** โ€” Global strategies that determine how requests are distributed +- **9 Routing Strategies** โ€” Global strategies that determine how requests are distributed - **Wildcard Router** โ€” `provider/*` patterns route dynamically to any provider - **Combo Enable/Disable Toggle** โ€” Toggle combos directly from the dashboard - **Provider Toggle** โ€” Enable/disable all connections for a provider with one click @@ -581,7 +583,7 @@ Different clients should have least-privilege access to tool categories. **How OmniRoute solves it:** -- 9 granular MCP scopes for controlled tool access +- 10 granular MCP scopes for controlled tool access - Scope enforcement and visibility in MCP management UI - Safe default posture for operational tooling @@ -1325,19 +1327,19 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. ### ๐Ÿค– Agent & Protocol Operations (v2.0) -| Feature | What It Does | -| ------------------------------------- | -------------------------------------------------------------------------------------------------- | -| ๐Ÿ”ง **MCP Server (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) | -| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | -| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | -| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | -| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | -| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | -| ๐Ÿ” **MCP Scope Enforcement** | 9 granular scope permissions for controlled tool access | -| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | -| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | -| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | -| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | +| Feature | What It Does | +| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| ๐Ÿ”ง **MCP Server (25 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools | +| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | +| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | +| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | +| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | +| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | +| ๐Ÿ” **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access | +| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | +| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | +| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | +| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | ### ๐Ÿง  Routing & Intelligence @@ -1348,7 +1350,7 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. | ๐Ÿ”„ **Format Translation** | OpenAI โ†” Claude โ†” Gemini โ†” Responses with schema-safe conversions | | ๐Ÿ‘ฅ **Multi-Account Support** | Multiple accounts per provider with intelligent selection | | ๐Ÿ”„ **Auto Token Refresh** | OAuth tokens refresh automatically with retry | -| ๐ŸŽจ **Custom Combos** | 6 balancing strategies + fallback chain control | +| ๐ŸŽจ **Custom Combos** | 9 balancing strategies + fallback chain control | | ๐ŸŒ **Wildcard Router** | `provider/*` dynamic routing | | ๐Ÿง  **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits | | ๐Ÿ”€ **Model Aliases** | Built-in + custom model aliasing and migration safety | @@ -1949,6 +1951,7 @@ opencode - Request artifacts are written to `DATA_DIR/call_logs/` as one JSON file per request - Enable pipeline capture from Dashboard โ†’ Logs โ†’ Request Logs if you need detailed per-stage payloads - Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log` +- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed **Connection test shows "Invalid" for OpenAI-compatible providers** diff --git a/docs/i18n/th/RELEASE_CHECKLIST.md b/docs/i18n/th/RELEASE_CHECKLIST.md deleted file mode 100644 index 903e812c3f..0000000000 --- a/docs/i18n/th/RELEASE_CHECKLIST.md +++ /dev/null @@ -1,37 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/RELEASE_CHECKLIST.md) - ---- - -# Release Checklist - -Use this checklist before tagging or publishing a new OmniRoute release. - -## Version and Changelog - -1. Bump `package.json` version (`x.y.z`) in the release branch. -2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: - - `## [x.y.z] โ€” YYYY-MM-DD` -3. Keep `## [Unreleased]` as the first changelog section for upcoming work. -4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. - -## API Docs - -1. Update `docs/openapi.yaml`: - - `info.version` must equal `package.json` version. -2. Validate endpoint examples if API contracts changed. - -## Runtime Docs - -1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. -2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. -3. Update localized docs if source docs changed significantly. - -## Automated Check - -Run the sync guard locally before opening PR: - -```bash -npm run check:docs-sync -``` - -CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/th/SECURITY.md b/docs/i18n/th/SECURITY.md new file mode 100644 index 0000000000..98972877a2 --- /dev/null +++ b/docs/i18n/th/SECURITY.md @@ -0,0 +1,179 @@ +# Security Policy (เน„เธ—เธข) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../SECURITY.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/SECURITY.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/SECURITY.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/SECURITY.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/SECURITY.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/SECURITY.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/SECURITY.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/SECURITY.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/SECURITY.md) + +--- + +## 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 | +| ------- | -------------- | +| 3.4.x | โœ… Active | +| 3.0.x | โœ… Security | +| < 3.0.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 | +| **MCP Scopes** | 10 granular scopes for MCP tool access control | + +### ๐Ÿ›ก๏ธ 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:::` +- 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** | Allowlist/blocklist IP ranges in dashboard | +| **Rate Limiting** | Per-provider rate limits with automatic backoff | +| **Anti-Thundering Herd** | Mutex + per-connection locking prevents cascading 502s | +| **TLS Fingerprint** | Browser-like TLS fingerprint spoofing to reduce bot detection | +| **CLI Fingerprint** | Per-provider header/body ordering to match native CLI signatures | + +### ๐Ÿ”Œ Resilience & Availability + +| 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 `CALL_LOG_RETENTION_DAYS` | +| **No-Log Opt-out** | Per API key `noLog` flag disables request logging | +| **Audit Log** | Administrative actions tracked in `audit_log` table | +| **MCP Audit** | SQLite-backed audit logging for all MCP tool calls | +| **Zod Validation** | All API inputs validated with Zod v4 schemas at module load | + +--- + +## 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 +- Provider constants validated at module load via Zod (`src/shared/validation/providerSchema.ts`) diff --git a/docs/i18n/th/TROUBLESHOOTING.md b/docs/i18n/th/TROUBLESHOOTING.md deleted file mode 100644 index 63c148000a..0000000000 --- a/docs/i18n/th/TROUBLESHOOTING.md +++ /dev/null @@ -1,258 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/TROUBLESHOOTING.md) - ---- - -# Troubleshooting - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/TROUBLESHOOTING.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/TROUBLESHOOTING.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/TROUBLESHOOTING.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/TROUBLESHOOTING.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/TROUBLESHOOTING.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/TROUBLESHOOTING.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/TROUBLESHOOTING.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/TROUBLESHOOTING.md) - -Common problems and solutions for OmniRoute. - ---- - -## Quick Fixes - -| Problem | Solution | -| ----------------------------- | ------------------------------------------------------------------ | -| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | -| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | -| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | -| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | -| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | - ---- - -## Provider Issues - -### "Language model did not provide messages" - -**Cause:** Provider quota exhausted. - -**Fix:** - -1. 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, Qoder) 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}/storage.sqlite` (providers, combos, aliases, keys, settings) -- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` -- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) - ---- - -## Circuit Breaker Issues - -### Provider stuck in OPEN state - -When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. - -**Fix:** - -1. 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 -- **SDK returns raw string instead of object** โ€” Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures -- **GLM/ERNIE rejects `system` role** โ€” Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models -- **`developer` role not recognized** โ€” Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers -- **`json_schema` not working with Gemini** โ€” Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` - ---- - -## Resilience Settings - -### Auto rate-limit not triggering - -- 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. - ---- - -## Optional RAG / LLM failure taxonomy (16 problems) - -Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. - -In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. - -If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: - -- retrieval drift and broken context boundaries -- empty or stale indexes and vector stores -- embedding versus semantic mismatch -- prompt assembly and context window issues -- logic collapse and overconfident answers -- long chain and agent coordination failures -- multi agent memory and role drift -- deployment and bootstrap ordering problems - -The idea is simple: - -1. When you investigate a bad response, capture: - - user task and request - - route or provider combo in OmniRoute - - any RAG context used downstream (retrieved documents, tool calls, etc) -2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` โ€ฆ `No.16`). -3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. -4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. - -Full text and concrete recipes live here (MIT license, text only): - -[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) - -You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. - ---- - -## Still Stuck? - -- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details -- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints -- **Health Dashboard**: Check **Dashboard โ†’ Health** for real-time system status -- **Translator**: Use **Dashboard โ†’ Translator** to debug format issues diff --git a/docs/i18n/th/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/th/VM_DEPLOYMENT_GUIDE.md deleted file mode 100644 index eaca2449c9..0000000000 --- a/docs/i18n/th/VM_DEPLOYMENT_GUIDE.md +++ /dev/null @@ -1,401 +0,0 @@ -# OmniRoute โ€” เธ„เธนเนˆเธกเธทเธญเธเธฒเธฃเธ›เธฃเธฑเธšเนƒเธŠเน‰เธšเธ™ VM เธžเธฃเน‰เธญเธก Cloudflare - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](../pt-BR/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](../es/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](../fr/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](../it/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](../ru/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](../zh-CN/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](../de/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](../in/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](../th/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](../uk-UA/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](../ar/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](../ja/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](../vi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](../bg/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](../da/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](../fi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](../he/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](../hu/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](../id/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](../ko/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](../ms/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](../nl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](../no/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](../pt/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](../ro/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](../pl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](../sk/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](../sv/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](../phi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](../cs/VM_DEPLOYMENT_GUIDE.md) - -เธ„เธณเนเธ™เธฐเธ™เธณเธ‰เธšเธฑเธšเธชเธกเธšเธนเธฃเธ“เนŒเนƒเธ™เธเธฒเธฃเธ•เธดเธ”เธ•เธฑเน‰เธ‡เนเธฅเธฐเธเธณเธซเธ™เธ”เธ„เนˆเธฒ OmniRoute เธšเธ™ VM (VPS) เธ”เน‰เธงเธขเน‚เธ”เน€เธกเธ™เธ—เธตเนˆเธˆเธฑเธ”เธเธฒเธฃเธœเนˆเธฒเธ™ Cloudflare - ---- - -## เธ‚เน‰เธญเธเธณเธซเธ™เธ”เน€เธšเธทเน‰เธญเธ‡เธ•เน‰เธ™ - -| เธฃเธฒเธขเธเธฒเธฃ | เธ‚เธฑเน‰เธ™เธ•เนˆเธณ | เนเธ™เธฐเธ™เธณ | -| ------------------ | -------------------------- | ----------------- | -| **เธ‹เธตเธžเธตเธขเธน** | 1 vCPU | 2 vCPU | -| **เนเธฃเธก** | 1 เธเธดเธเธฐเน„เธšเธ•เนŒ | 2 เธเธดเธเธฐเน„เธšเธ•เนŒ | -| **เธ”เธดเธชเธเนŒ** | SSD 10GB | 25 GB SSD | -| **เธฃเธฐเธšเธšเธ›เธเธดเธšเธฑเธ•เธดเธเธฒเธฃ** | เธญเธนเธšเธธเธ™เธ•เธน 22.04 LTS | เธญเธนเธšเธธเธ™เธ•เธน 24.04 LTS | -| **เน‚เธ”เน€เธกเธ™** | เธฅเธ‡เธ—เธฐเน€เธšเธตเธขเธ™เธšเธ™ Cloudflare | โ€” | -| **เธ™เธฑเธเน€เธ—เธตเธขเธšเธ—เนˆเธฒ** | เธ™เธฑเธเน€เธ—เธตเธขเธšเธ—เนˆเธฒเน€เธ„เธฃเธทเนˆเธญเธ‡เธขเธ™เธ•เนŒ 24+ | เธ™เธฑเธเน€เธ—เธตเธขเธšเธ—เนˆเธฒ 27+ | - -**เธœเธนเน‰เนƒเธซเน‰เธšเธฃเธดเธเธฒเธฃเธ—เธตเนˆเธœเนˆเธฒเธ™เธเธฒเธฃเธ—เธ”เธชเธญเธš**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail - ---- - -## 1. เธเธณเธซเธ™เธ”เธ„เนˆเธฒ VM - -### 1.1 เธชเธฃเน‰เธฒเธ‡เธญเธดเธ™เธชเนเธ•เธ™เธ‹เนŒ - -เธšเธ™เธœเธนเน‰เนƒเธซเน‰เธšเธฃเธดเธเธฒเธฃ VPS เธ—เธตเนˆเธ„เธธเธ“เธ•เน‰เธญเธ‡เธเธฒเธฃ: - -- เน€เธฅเธทเธญเธ Ubuntu 24.04 LTS -- เน€เธฅเธทเธญเธเนเธœเธ™เธ‚เธฑเน‰เธ™เธ•เนˆเธณ (1 vCPU / 1 GB RAM) -- เธ•เธฑเน‰เธ‡เธฃเธซเธฑเธชเธœเนˆเธฒเธ™เธฃเธนเธ—เธ—เธตเนˆเธฃเธฑเธ”เธเธธเธกเธซเธฃเธทเธญเธเธณเธซเธ™เธ”เธ„เนˆเธฒเธ„เธตเธขเนŒ SSH -- เธซเธกเธฒเธขเน€เธซเธ•เธธ **IP เธชเธฒเธ˜เธฒเธฃเธ“เธฐ** (เน€เธŠเนˆเธ™ `203.0.113.10`) - -### 1.2 เน€เธŠเธทเนˆเธญเธกเธ•เนˆเธญเธœเนˆเธฒเธ™ SSH - -```bash -ssh root@203.0.113.10 -``` - -### 1.3 เธญเธฑเธžเน€เธ”เธ•เธฃเธฐเธšเธš - -```bash -apt update && apt upgrade -y -``` - -### 1.4 เธ•เธดเธ”เธ•เธฑเน‰เธ‡เธ™เธฑเธเน€เธ—เธตเธขเธšเธ—เนˆเธฒ - -```bash -# Install dependencies -apt install -y ca-certificates curl gnupg - -# Add official Docker repository -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 เธ•เธดเธ”เธ•เธฑเน‰เธ‡ nginx - -```bash -apt install -y nginx -``` - -### 1.6 เธเธณเธซเธ™เธ”เธ„เนˆเธฒเน„เธŸเธฃเนŒเธงเธญเธฅเธฅเนŒ (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 -``` - -> **เน€เธ„เธฅเน‡เธ”เธฅเธฑเธš**: เน€เธžเธทเนˆเธญเธ„เธงเธฒเธกเธ›เธฅเธญเธ”เธ เธฑเธขเธชเธนเธ‡เธชเธธเธ” เธˆเธณเธเธฑเธ”เธžเธญเธฃเนŒเธ• 80 เนเธฅเธฐ 443 เน„เธงเน‰เน€เธ‰เธžเธฒเธฐ IP เธ‚เธญเธ‡ Cloudflare เน€เธ—เนˆเธฒเธ™เธฑเน‰เธ™ เธ”เธนเธชเนˆเธงเธ™ [Advanced Security](#advanced-security) - ---- - -## 2. เธ•เธดเธ”เธ•เธฑเน‰เธ‡ OmniRoute - -### 2.1 เธชเธฃเน‰เธฒเธ‡เน„เธ”เน€เธฃเน‡เธเธ—เธญเธฃเธตเธเธฒเธฃเธเธณเธซเธ™เธ”เธ„เนˆเธฒ - -```bash -mkdir -p /opt/omniroute -``` - -### 2.2 เธชเธฃเน‰เธฒเธ‡เน„เธŸเธฅเนŒเธ•เธฑเธงเนเธ›เธฃเธชเธ เธฒเธžเนเธงเธ”เธฅเน‰เธญเธก - -```bash -cat > /opt/omniroute/.env << โ€˜EOFโ€™ -# === Security === -JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY -INITIAL_PASSWORD=YourSecurePassword123! -API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY -STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY -STORAGE_ENCRYPTION_KEY_VERSION=v1 -MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT - -# === 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 (change to your domain) === -BASE_URL=https://llms.seudominio.com -NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com - -# === Cloud Sync (optional) === -# CLOUD_URL=https://cloud.omniroute.online -# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online -EOF -``` - -> โš ๏ธ **เธชเธณเธ„เธฑเธ**: เธชเธฃเน‰เธฒเธ‡เธ„เธตเธขเนŒเธฅเธฑเธšเธ—เธตเนˆเน„เธกเนˆเธ‹เน‰เธณเนƒเธ„เธฃ! เนƒเธŠเน‰ `openssl rand -hex 32` เธชเธณเธซเธฃเธฑเธšเนเธ•เนˆเธฅเธฐเธ„เธตเธขเนŒ - -### 2.3 เน€เธฃเธดเนˆเธกเธ„เธญเธ™เน€เธ—เธ™เน€เธ™เธญเธฃเนŒ - -```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 เธ•เธฃเธงเธˆเธชเธญเธšเธงเนˆเธฒเธกเธฑเธ™เธเธณเธฅเธฑเธ‡เธ—เธณเธ‡เธฒเธ™เธญเธขเธนเนˆ - -```bash -docker ps | grep omniroute -docker logs omniroute --tail 20 -``` - -เธ„เธงเธฃเนเธชเธ”เธ‡: `[DB] SQLite database ready` เนเธฅเธฐ `listening on port 20128` - ---- - -## 3. เธเธณเธซเธ™เธ”เธ„เนˆเธฒ nginx (Reverse Proxy) - -### 3.1 เธชเธฃเน‰เธฒเธ‡เนƒเธšเธฃเธฑเธšเธฃเธญเธ‡ SSL (Cloudflare Origin) - -เนƒเธ™เนเธ”เธŠเธšเธญเธฃเนŒเธ” Cloudflare: - -1. เน„เธ›เธ—เธตเนˆ **SSL/TLS โ†’ เน€เธ‹เธดเธฃเนŒเธŸเน€เธงเธญเธฃเนŒเธ•เน‰เธ™เธ—เธฒเธ‡** -2. เธ„เธฅเธดเธ **เธชเธฃเน‰เธฒเธ‡เนƒเธšเธฃเธฑเธšเธฃเธญเธ‡** -3. เธ„เธ‡เธ„เนˆเธฒเน€เธฃเธดเนˆเธกเธ•เน‰เธ™เน„เธงเน‰ (15 เธ›เธต \*.yourdomain.com) -4. เธ„เธฑเธ”เธฅเธญเธ **Origin Certificate** เนเธฅเธฐ **Private Key** - -```bash -mkdir -p /etc/nginx/ssl - -# Paste the certificate -nano /etc/nginx/ssl/origin.crt - -# Paste the private key -nano /etc/nginx/ssl/origin.key - -chmod 600 /etc/nginx/ssl/origin.key -``` - -### 3.2 เธเธฒเธฃเธเธณเธซเธ™เธ”เธ„เนˆเธฒ Nginx - -```bash -cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ -# Default server โ€” blocks direct access via 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.yourdomain.com; # Change to your domain - - 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.yourdomain.com; - return 301 https://$server_name$request_uri; -} -NGINX -``` - -### 3.3 เน€เธ›เธดเธ”เนƒเธŠเน‰เธ‡เธฒเธ™เนเธฅเธฐเธ—เธ”เธชเธญเธš - -```bash -# Remove default configuration -rm -f /etc/nginx/sites-enabled/default - -# Enable OmniRoute -ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute - -# Test and reload -nginx -t && systemctl reload nginx -``` - ---- - -## 4. เธเธณเธซเธ™เธ”เธ„เนˆเธฒ Cloudflare DNS - -### 4.1 เน€เธžเธดเนˆเธกเธšเธฑเธ™เธ—เธถเธ DNS - -เนƒเธ™เนเธ”เธŠเธšเธญเธฃเนŒเธ” Cloudflare โ†’ DNS: - -| เธžเธดเธกเธžเนŒ | เธŠเธทเนˆเธญ | เน€เธ™เธทเน‰เธญเธซเธฒ | เธซเธ™เธฑเธ‡เธชเธทเธญเธกเธญเธšเธ‰เธฑเธ™เธ—เธฐ | -| ----- | ------ | ---------------------- | --------------- | -| เธ | `llms` | `203.0.113.10` (VM IP) | โœ… เธžเธฃเน‡เธญเธเธ‹เธต | - -### 4.2 เธเธณเธซเธ™เธ”เธ„เนˆเธฒ SSL - -เธ เธฒเธขเนƒเธ•เน‰ **SSL/TLS โ†’ เธ เธฒเธžเธฃเธงเธก**: - -- เน‚เธซเธกเธ”: **เน€เธ•เน‡เธก (เน€เธ‚เน‰เธกเธ‡เธงเธ”)** - -เธ เธฒเธขเนƒเธ•เน‰ **SSL/TLS โ†’ Edge Certificates**: - -- เนƒเธŠเน‰ HTTPS เน€เธชเธกเธญ: โœ… เน€เธ›เธดเธ” -- เน€เธงเธญเธฃเนŒเธŠเธฑเธ™ TLS เธ‚เธฑเน‰เธ™เธ•เนˆเธณ: TLS 1.2 -- เธเธฒเธฃเน€เธ‚เธตเธขเธ™ HTTPS เธญเธฑเธ•เน‚เธ™เธกเธฑเธ•เธด: โœ…เน€เธ›เธดเธ” - -### 4.3 เธเธฒเธฃเธ—เธ”เธชเธญเธš - -```bash -curl -sI https://llms.seudominio.com/health -# Should return HTTP/2 200 -``` - ---- - -## 5. เธเธฒเธฃเธ”เธณเน€เธ™เธดเธ™เธ‡เธฒเธ™เนเธฅเธฐเธเธฒเธฃเธšเธณเธฃเธธเธ‡เธฃเธฑเธเธฉเธฒ - -### เธญเธฑเธ›เน€เธเธฃเธ”เน€เธ›เน‡เธ™เน€เธงเธญเธฃเนŒเธŠเธฑเธ™เนƒเธซเธกเนˆ - -```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 -``` - -### เธ”เธนเธšเธฑเธ™เธ—เธถเธ - -```bash -docker logs -f omniroute # Real-time stream -docker logs omniroute --tail 50 # Last 50 lines -``` - -### เธชเธณเธฃเธญเธ‡เธเธฒเธ™เธ‚เน‰เธญเธกเธนเธฅเธ”เน‰เธงเธขเธ•เธ™เน€เธญเธ‡ - -```bash -# Copy data from the volume to the host -docker cp omniroute:/app/data ./backup-$(date +%F) - -# Or compress the entire volume -docker run --rm -v omniroute-data:/data -v $(pwd):/backup \ - alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data -``` - -### เธเธนเน‰เธ„เธทเธ™เธˆเธฒเธเธ‚เน‰เธญเธกเธนเธฅเธชเธณเธฃเธญเธ‡ - -```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. เธเธฒเธฃเธฃเธฑเธเธฉเธฒเธ„เธงเธฒเธกเธ›เธฅเธญเธ”เธ เธฑเธขเธ‚เธฑเน‰เธ™เธชเธนเธ‡ - -### เธˆเธณเธเธฑเธ” nginx เน„เธงเน‰เธ—เธตเนˆ IP เธ‚เธญเธ‡ Cloudflare - -```bash -cat > /etc/nginx/cloudflare-ips.conf << โ€˜CFโ€™ -# Cloudflare IPv4 ranges โ€” update periodically -# 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 -``` - -เน€เธžเธดเนˆเธกเธชเธดเนˆเธ‡เธ•เนˆเธญเน„เธ›เธ™เธตเน‰เนƒเธ™ `nginx.conf` เธ เธฒเธขเนƒเธ™เธšเธฅเน‡เธญเธ `http {}`: - -```nginx -include /etc/nginx/cloudflare-ips.conf; -``` - -### เธ•เธดเธ”เธ•เธฑเน‰เธ‡ Fail2ban - -```bash -apt install -y fail2ban -systemctl enable fail2ban -systemctl start fail2ban - -# Check status -fail2ban-client status sshd -``` - -### เธšเธฅเน‡เธญเธเธเธฒเธฃเน€เธ‚เน‰เธฒเธ–เธถเธ‡เธžเธญเธฃเนŒเธ• Docker เน‚เธ”เธขเธ•เธฃเธ‡ - -```bash -# Prevent direct external access to port 20128 -iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP -iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT - -# Persist the rules -apt install -y iptables-persistent -netfilter-persistent save -``` - ---- - -## 7. เธ›เธฃเธฑเธšเนƒเธŠเน‰เธเธฑเธš Cloudflare Workers (เน„เธกเนˆเธšเธฑเธ‡เธ„เธฑเธš) - -เธชเธณเธซเธฃเธฑเธšเธเธฒเธฃเน€เธ‚เน‰เธฒเธ–เธถเธ‡เธฃเธฐเธขเธฐเน„เธเธฅเธœเนˆเธฒเธ™ Cloudflare Workers (เน‚เธ”เธขเน„เธกเนˆเธ•เน‰เธญเธ‡เน€เธ›เธดเธ”เน€เธœเธข VM เน‚เธ”เธขเธ•เธฃเธ‡): - -```bash -# In the local repository -cd omnirouteCloud -npm install -npx wrangler login -npx wrangler deploy -``` - -เธ”เธนเน€เธญเธเธชเธฒเธฃเธ‰เธšเธฑเธšเน€เธ•เน‡เธกเน„เธ”เน‰เธ—เธตเนˆ [omnirouteCloud/README.md](../omnirouteCloud/README.md) - ---- - -## เธชเธฃเธธเธ›เธžเธญเธฃเนŒเธ• - -| เธžเธญเธฃเนŒเธ• | เธšเธฃเธดเธเธฒเธฃ | เน€เธ‚เน‰เธฒเธ–เธถเธ‡ | -| ----- | ----------- | ------------------------------- | -| 22 | เน€เธญเธชเน€เธญเธชเน€เธญเธŠ | เธชเธฒเธ˜เธฒเธฃเธ“เธฐ (เธžเธฃเน‰เธญเธก Fail2ban) | -| 80 | nginx HTTP | เน€เธ›เธฅเธตเนˆเธขเธ™เน€เธชเน‰เธ™เธ—เธฒเธ‡ โ†’ HTTPS | -| 443 | nginx HTTPS | เธœเนˆเธฒเธ™ Cloudflare Proxy | -| 20128 | OmniRoute | Localhost เน€เธ—เนˆเธฒเธ™เธฑเน‰เธ™ (เธœเนˆเธฒเธ™ nginx) | diff --git a/docs/i18n/th/docs/A2A-SERVER.md b/docs/i18n/th/docs/A2A-SERVER.md new file mode 100644 index 0000000000..93f2fbf137 --- /dev/null +++ b/docs/i18n/th/docs/A2A-SERVER.md @@ -0,0 +1,200 @@ +# OmniRoute A2A Server Documentation (เน„เธ—เธข) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/A2A-SERVER.md) + +--- + +> Agent-to-Agent Protocol v0.3 โ€” OmniRoute as an intelligent routing agent + +## Agent Discovery + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements. + +--- + +## Authentication + +All `/a2a` requests require an API key via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server, authentication is bypassed. + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Sends a message to a skill and waits for the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a hello world in Python"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "uuid", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "..." }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}} + +: heartbeat 2026-03-03T17:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Available Skills + +| Skill | Description | +| :----------------- | :------------------------------------------------------------------------------------------------------------------------------ | +| `smart-routing` | Routes prompts through OmniRoute's intelligent pipeline. Returns response with routing explanation, cost, and resilience trace. | +| `quota-management` | Answers natural-language queries about provider quotas, suggests free combos, and provides quota rankings. | + +--- + +## Task Lifecycle + +``` +submitted โ†’ working โ†’ completed + โ†’ failed + โ†’ cancelled +``` + +- Tasks expire after 5 minutes (configurable) +- Terminal states: `completed`, `failed`, `cancelled` +- Event log tracks every state transition + +--- + +## Error Codes + +| Code | Meaning | +| :----- | :----------------------------- | +| -32700 | Parse error (invalid JSON) | +| -32600 | Invalid request / Unauthorized | +| -32601 | Method or skill not found | +| -32602 | Invalid params | +| -32603 | Internal error | + +--- + +## Integration Examples + +### Python (requests) + +```python +import requests + +resp = requests.post("http://localhost:20128/a2a", json={ + "jsonrpc": "2.0", "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Hello"}] + } +}, headers={"Authorization": "Bearer YOUR_KEY"}) + +result = resp.json()["result"] +print(result["artifacts"][0]["content"]) +print(result["metadata"]["routing_explanation"]) +``` + +### TypeScript (fetch) + +```typescript +const resp = await fetch("http://localhost:20128/a2a", { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: "Bearer YOUR_KEY", + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "1", + method: "message/send", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Hello" }], + }, + }), +}); +const { result } = await resp.json(); +console.log(result.metadata.routing_explanation); +``` diff --git a/docs/i18n/th/docs/API_REFERENCE.md b/docs/i18n/th/docs/API_REFERENCE.md new file mode 100644 index 0000000000..09c02fbd4f --- /dev/null +++ b/docs/i18n/th/docs/API_REFERENCE.md @@ -0,0 +1,465 @@ +# API Reference (เน„เธ—เธข) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/API_REFERENCE.md) + +--- + +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 | +| `X-Session-Id` | Request | Sticky session key for external session affinity | +| `x_session_id` | Request | Underscore variant also accepted (direct HTTP) | +| `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 | +| `X-OmniRoute-Session-Id` | Response | Effective session ID used by OmniRoute | + +> Nginx note: if you rely on underscore headers (for example `x_session_id`), enable `underscores_in_headers 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/stats + +# Clear all caches +DELETE /api/cache/stats +``` + +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/PATCH | 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 + provider summary (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`) | +| `/api/cache/stats` | 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 | + +### Tunnels + +| Endpoint | Method | Description | +| -------------------------- | ------ | ----------------------------------------------------------------------- | +| `/api/tunnels/cloudflared` | GET | Read Cloudflare Quick Tunnel install/runtime status for the dashboard | +| `/api/tunnels/cloudflared` | POST | Enable or disable the Cloudflare Quick Tunnel (`action=enable/disable`) | + +### 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`. + +### ACP Agents + +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | + +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). + +### Resilience & Rate Limits + +| Endpoint | Method | Description | +| ----------------------- | --------- | ------------------------------- | +| `/api/resilience` | GET/PATCH | 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` diff --git a/docs/i18n/th/docs/ARCHITECTURE.md b/docs/i18n/th/docs/ARCHITECTURE.md new file mode 100644 index 0000000000..6406834394 --- /dev/null +++ b/docs/i18n/th/docs/ARCHITECTURE.md @@ -0,0 +1,814 @@ +# OmniRoute Architecture (เน„เธ—เธข) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/ARCHITECTURE.md) + +--- + +_Last updated: 2026-03-28_ + +## 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 (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developerโ†’system, systemโ†’user) for cross-provider compatibility +- Structured output conversion (json_schema โ†’ Gemini responseSchema) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) +- Global system prompt injection +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout โ†’ budget โ†’ fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) + +Primary runtime model: + +- Next.js 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.) + +## Dashboard Surface (Current) + +Main pages under `src/app/(dashboard)/dashboard/`: + +- `/dashboard` โ€” quick start + provider overview +- `/dashboard/endpoint` โ€” endpoint proxy + MCP + A2A + API endpoint tabs +- `/dashboard/providers` โ€” provider connections and credentials +- `/dashboard/combos` โ€” combo strategies, templates, model routing rules +- `/dashboard/costs` โ€” cost aggregation and pricing visibility +- `/dashboard/analytics` โ€” usage analytics and evaluations +- `/dashboard/limits` โ€” quota/rate controls +- `/dashboard/cli-tools` โ€” CLI onboarding, runtime detection, config generation +- `/dashboard/agents` โ€” detected ACP agents + custom agent registration +- `/dashboard/media` โ€” image/video/music playground +- `/dashboard/search-tools` โ€” search provider testing and history +- `/dashboard/health` โ€” uptime, circuit breakers, rate limits +- `/dashboard/logs` โ€” request/proxy/audit/console logs +- `/dashboard/settings` โ€” system settings tabs (general, routing, combo defaults, etc.) +- `/dashboard/api-manager` โ€” API key lifecycle and model permissions + +## 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[(storage.sqlite)] + UDB[(usage tables + log artifacts)] + end + + subgraph Upstreams[Upstream Providers] + P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/Qoder/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/route.ts` (GET) +- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- OAuth: `src/app/api/oauth/*` +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` +- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI tooling helpers: `src/app/api/cli-tools/*` +- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) +- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) โ€” provider profiles, circuit breaker, rate limit state +- Resilience reset: `src/app/api/resilience/reset` (POST) โ€” reset breakers + cooldowns +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) +- Telemetry: `src/app/api/telemetry/summary` (GET) +- Budget: `src/app/api/usage/budget` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Policies: `src/app/api/policies` (GET/POST) + +## 2) SSE + 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` +- Response sanitization: `open-sse/handlers/responseSanitizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.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`, `qoder.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 (SQLite): + +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** + +Usage persistence: + +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present + +Domain State DB (SQLite): + +- `src/lib/db/domainState.ts` โ€” CRUD operations 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`, `src/shared/services/modelSyncScheduler.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Periodic task: `src/shared/services/modelSyncScheduler.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. Combo routing adds one extra guard: provider-scoped 400s such as upstream content-block and role-validation failures are treated as model-local failures so later combo targets can still run. + +## 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: + +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` + +## Deployment Topology + +```mermaid +flowchart LR + 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[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] + end + + subgraph External[External Services] + Providers[AI Providers] + SyncCloud[Cloud Sync Service] + end + + CLI --> Next + Browser --> Next + Next --> Core + Next --> MainDB + Core --> MainDB + Core --> UsageDB + Core --> Providers + Next --> SyncCloud +``` + +## Module Mapping (Decision-Critical) + +### Route and API Modules + +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle +- `src/app/api/models/alias`: alias management +- `src/app/api/combos*`: fallback combo management +- `src/app/api/pricing`: pricing overrides for cost calculation +- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers +- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) +- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) +- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) +- `src/app/api/sessions`: active session listing (GET) +- `src/app/api/rate-limits`: per-account rate limit status (GET) + +### Routing and Execution Core + +- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior + +### Translation Registry and Format Converters + +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` +- Format constants: `open-sse/translator/formats.ts` + +### Persistence + +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables + +## Provider Executor Coverage (Strategy Pattern) + +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. + +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, Qoder, 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 | +| Qoder | openai | OAuth (Basic) | โœ… | โœ… | โœ… | โš ๏ธ Per request | +| OpenRouter | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| GLM/Kimi/MiniMax | claude | API Key | โœ… | โœ… | โŒ | โŒ | +| DeepSeek | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Groq | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| xAI (Grok) | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Mistral | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Perplexity | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Together AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Fireworks AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Cerebras | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Cohere | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| NVIDIA NIM | openai | API Key | โœ… | โœ… | โŒ | โŒ | + +## Format Translation Coverage + +Detected source formats include: + +- `openai` +- `openai-responses` +- `claude` +- `gemini` + +Target formats include: + +- OpenAI chat/Responses +- Claude +- Gemini/Gemini-CLI/Antigravity envelope +- Kiro +- Cursor + +Translations use **OpenAI as the hub format** โ€” all conversions go through OpenAI as intermediate: + +``` +Source Format โ†’ OpenAI (hub) โ†’ Target Format +``` + +Translations are selected dynamically based on source payload shape and provider target format. + +Additional processing layers in the translation pipeline: + +- **Response sanitization** โ€” Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI targets; merges `system` โ†’ `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** โ€” Parses `...` blocks from content into `reasoning_content` field +- **Structured output** โ€” Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` + +## Supported API Endpoints + +| 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` | Provider Models | Provider model metadata backing custom and managed available models | + +## 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 `/logs//` 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 + +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON โ†’ SQLite migration compatibility path + +## Observability and Operational Signals + +Runtime visibility sources: + +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- four-stage detailed payload captures in SQLite (`request_detail_logs`) when `settings.detailed_logs_enabled=true` +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption + +Detailed request payload capture stores up to four JSON payload stages per routed call: + +- raw request received from the client +- translated request actually sent upstream +- provider response reconstructed as JSON; streamed responses are compacted to the final summary plus stream metadata +- final client response returned by OmniRoute; streamed responses are stored in the same compact summary form + +## Security-Sensitive Boundaries + +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics + +## Environment and Runtime Matrix + +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` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). + +## Operational Verification Checklist + +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: +- `GET /api/settings` +- `GET /api/v1/models` +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/th/docs/AUTO-COMBO.md b/docs/i18n/th/docs/AUTO-COMBO.md new file mode 100644 index 0000000000..2deb01039b --- /dev/null +++ b/docs/i18n/th/docs/AUTO-COMBO.md @@ -0,0 +1,67 @@ +# OmniRoute Auto-Combo Engine (เน„เธ—เธข) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/AUTO-COMBO.md) + +--- + +> Self-managing model chains with adaptive scoring + +## How It Works + +The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**: + +| Factor | Weight | Description | +| :--------- | :----- | :---------------------------------------------- | +| Quota | 0.20 | Remaining capacity [0..1] | +| Health | 0.25 | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 | +| CostInv | 0.20 | Inverse cost (cheaper = higher score) | +| LatencyInv | 0.15 | Inverse p95 latency (faster = higher) | +| TaskFit | 0.10 | Model ร— task type fitness score | +| Stability | 0.10 | Low variance in latency/errors | + +## Mode Packs + +| Pack | Focus | Key Weight | +| :---------------------- | :----------- | :--------------- | +| ๐Ÿš€ **Ship Fast** | Speed | latencyInv: 0.35 | +| ๐Ÿ’ฐ **Cost Saver** | Economy | costInv: 0.40 | +| ๐ŸŽฏ **Quality First** | Best model | taskFit: 0.40 | +| ๐Ÿ“ก **Offline Friendly** | Availability | quota: 0.40 | + +## Self-Healing + +- **Temporary exclusion**: Score < 0.2 โ†’ excluded for 5 min (progressive backoff, max 30 min) +- **Circuit breaker awareness**: OPEN โ†’ auto-excluded; HALF_OPEN โ†’ probe requests +- **Incident mode**: >50% OPEN โ†’ disable exploration, maximize stability +- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout + +## Bandit Exploration + +5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode. + +## API + +```bash +# Create auto-combo +curl -X POST http://localhost:20128/api/combos/auto \ + -H "Content-Type: application/json" \ + -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}' + +# List auto-combos +curl http://localhost:20128/api/combos/auto +``` + +## Task Fitness + +30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` โ†’ high coding score). + +## Files + +| File | Purpose | +| :------------------------------------------- | :------------------------------------ | +| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization | +| `open-sse/services/autoCombo/taskFitness.ts` | Model ร— task fitness lookup | +| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap | +| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode | +| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles | +| `src/app/api/combos/auto/route.ts` | REST API | diff --git a/docs/i18n/th/docs/CLI-TOOLS.md b/docs/i18n/th/docs/CLI-TOOLS.md new file mode 100644 index 0000000000..5888070f3c --- /dev/null +++ b/docs/i18n/th/docs/CLI-TOOLS.md @@ -0,0 +1,348 @@ +# CLI Tools Setup Guide โ€” OmniRoute (เน„เธ—เธข) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CLI-TOOLS.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CLI-TOOLS.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CLI-TOOLS.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CLI-TOOLS.md) + +--- + +This guide explains how to install and configure all supported AI coding CLI tools +to use **OmniRoute** as the unified backend, giving you centralized key management, +cost tracking, model switching, and request logging across every tool. + +--- + +## How It Works + +``` +Claude / Codex / OpenCode / Cline / KiloCode / Continue / Kiro / Cursor / Copilot + โ”‚ + โ–ผ (all point to OmniRoute) + http://YOUR_SERVER:20128/v1 + โ”‚ + โ–ผ (OmniRoute routes to the right provider) + Anthropic / OpenAI / Gemini / DeepSeek / Groq / Mistral / ... +``` + +**Benefits:** + +- One API key to manage all tools +- Cost tracking across all CLIs in the dashboard +- Model switching without reconfiguring every tool +- Works locally and on remote servers (VPS) + +--- + +## Supported Tools (Dashboard Source of Truth) + +The dashboard cards in `/dashboard/cli-tools` are generated from `src/shared/constants/cliTools.ts`. +Current list (v3.0.0-rc.16): + +| Tool | ID | Command | Setup Mode | Install Method | +| ------------------ | ------------- | ---------- | ---------- | -------------- | +| **Claude Code** | `claude` | `claude` | env | npm | +| **OpenAI Codex** | `codex` | `codex` | custom | npm | +| **Factory Droid** | `droid` | `droid` | custom | bundled/CLI | +| **OpenClaw** | `openclaw` | `openclaw` | custom | bundled/CLI | +| **Cursor** | `cursor` | app | guide | desktop app | +| **Cline** | `cline` | `cline` | custom | npm | +| **Kilo Code** | `kilo` | `kilocode` | custom | npm | +| **Continue** | `continue` | extension | guide | VS Code | +| **Antigravity** | `antigravity` | internal | mitm | OmniRoute | +| **GitHub Copilot** | `copilot` | extension | custom | VS Code | +| **OpenCode** | `opencode` | `opencode` | guide | npm | +| **Kiro AI** | `kiro` | app/cli | mitm | desktop/CLI | + +### CLI fingerprint sync (Agents + Settings) + +`/dashboard/agents` and `Settings > CLI Fingerprint` use `src/shared/constants/cliCompatProviders.ts`. +This keeps provider IDs aligned with CLI cards and legacy IDs. + +| CLI ID | Fingerprint Provider ID | +| ---------------------------------------------------------------------------------------------------- | ----------------------- | +| `kilo` | `kilocode` | +| `copilot` | `github` | +| `claude` / `codex` / `antigravity` / `kiro` / `cursor` / `cline` / `opencode` / `droid` / `openclaw` | same ID | + +Legacy IDs still accepted for compatibility: `copilot`, `kimi-coding`, `qwen`. + +--- + +## Step 1 โ€” Get an OmniRoute API Key + +1. Open the OmniRoute dashboard โ†’ **API Manager** (`/dashboard/api-manager`) +2. Click **Create API Key** +3. Give it a name (e.g. `cli-tools`) and select all permissions +4. Copy the key โ€” you'll need it for every CLI below + +> Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` + +--- + +## Step 2 โ€” Install CLI Tools + +All npm-based tools require Node.js 18+: + +```bash +# Claude Code (Anthropic) +npm install -g @anthropic-ai/claude-code + +# OpenAI Codex +npm install -g @openai/codex + +# OpenCode +npm install -g opencode-ai + +# Cline +npm install -g cline + +# KiloCode +npm install -g kilocode + +# Kiro CLI (Amazon โ€” requires curl + unzip) +apt-get install -y unzip # on Debian/Ubuntu +curl -fsSL https://cli.kiro.dev/install | bash +export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc +``` + +**Verify:** + +```bash +claude --version # 2.x.x +codex --version # 0.x.x +opencode --version # x.x.x +cline --version # 2.x.x +kilocode --version # x.x.x (or: kilo --version) +kiro-cli --version # 1.x.x +``` + +--- + +## Step 3 โ€” Set Global Environment Variables + +Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`: + +```bash +# OmniRoute Universal Endpoint +export OPENAI_BASE_URL="http://localhost:20128/v1" +export OPENAI_API_KEY="sk-your-omniroute-key" +export ANTHROPIC_BASE_URL="http://localhost:20128/v1" +export ANTHROPIC_API_KEY="sk-your-omniroute-key" +export GEMINI_BASE_URL="http://localhost:20128/v1" +export GEMINI_API_KEY="sk-your-omniroute-key" +``` + +> For a **remote server** replace `localhost:20128` with the server IP or domain, +> e.g. `http://192.168.0.15:20128`. + +--- + +## Step 4 โ€” Configure Each Tool + +### Claude Code + +```bash +# Via CLI: +claude config set --global api-base-url http://localhost:20128/v1 + +# Or create ~/.claude/settings.json: +mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF +{ + "apiBaseUrl": "http://localhost:20128/v1", + "apiKey": "sk-your-omniroute-key" +} +EOF +``` + +**Test:** `claude "say hello"` + +--- + +### OpenAI Codex + +```bash +mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF +model: auto +apiKey: sk-your-omniroute-key +apiBaseUrl: http://localhost:20128/v1 +EOF +``` + +**Test:** `codex "what is 2+2?"` + +--- + +### OpenCode + +```bash +mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF +[provider.openai] +base_url = "http://localhost:20128/v1" +api_key = "sk-your-omniroute-key" +EOF +``` + +**Test:** `opencode` + +--- + +### Cline (CLI or VS Code) + +**CLI mode:** + +```bash +mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF +{ + "apiProvider": "openai", + "openAiBaseUrl": "http://localhost:20128/v1", + "openAiApiKey": "sk-your-omniroute-key" +} +EOF +``` + +**VS Code mode:** +Cline extension settings โ†’ API Provider: `OpenAI Compatible` โ†’ Base URL: `http://localhost:20128/v1` + +Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ Cline โ†’ Apply Config**. + +--- + +### KiloCode (CLI or VS Code) + +**CLI mode:** + +```bash +kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key +``` + +**VS Code settings:** + +```json +{ + "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", + "kilo-code.apiKey": "sk-your-omniroute-key" +} +``` + +Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ KiloCode โ†’ Apply Config**. + +--- + +### Continue (VS Code Extension) + +Edit `~/.continue/config.yaml`: + +```yaml +models: + - name: OmniRoute + provider: openai + model: auto + apiBase: http://localhost:20128/v1 + apiKey: sk-your-omniroute-key + default: true +``` + +Restart VS Code after editing. + +--- + +### Kiro CLI (Amazon) + +```bash +# Login to your AWS/Kiro account: +kiro-cli login + +# The CLI uses its own auth โ€” OmniRoute is not needed as backend for Kiro CLI itself. +# Use kiro-cli alongside OmniRoute for other tools. +kiro-cli status +``` + +--- + +### Cursor (Desktop App) + +> **Note:** Cursor routes requests through its cloud. For OmniRoute integration, +> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL. + +Via GUI: **Settings โ†’ Models โ†’ OpenAI API Key** + +- Base URL: `https://your-domain.com/v1` +- API Key: your OmniRoute key + +--- + +## Dashboard Auto-Configuration + +The OmniRoute dashboard automates configuration for most tools: + +1. Go to `http://localhost:20128/dashboard/cli-tools` +2. Expand any tool card +3. Select your API key from the dropdown +4. Click **Apply Config** (if tool is detected as installed) +5. Or copy the generated config snippet manually + +--- + +## Built-in Agents: Droid & OpenClaw + +**Droid** and **OpenClaw** are AI agents built directly into OmniRoute โ€” no installation needed. +They run as internal routes and use OmniRoute's model routing automatically. + +- Access: `http://localhost:20128/dashboard/agents` +- Configure: same combos and providers as all other tools +- No API key or CLI install required + +--- + +## Available API Endpoints + +| Endpoint | Description | Use For | +| -------------------------- | ----------------------------- | --------------------------- | +| `/v1/chat/completions` | Standard chat (all providers) | All modern tools | +| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows | +| `/v1/completions` | Legacy text completions | Older tools using `prompt:` | +| `/v1/embeddings` | Text embeddings | RAG, search | +| `/v1/images/generations` | Image generation | DALL-E, Flux, etc. | +| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS | +| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI | + +--- + +## เธเธฒเธฃเนเธเน‰เน„เธ‚เธ›เธฑเธเธซเธฒ + +| Error | Cause | Fix | +| ------------------------- | ----------------------- | ------------------------------------------ | +| `Connection refused` | OmniRoute not running | `pm2 start omniroute` | +| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` | +| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` | +| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` | +| CLI shows "not installed" | Binary not in PATH | Check `which ` | +| `kiro-cli: not found` | Not in PATH | `export PATH="$HOME/.local/bin:$PATH"` | + +--- + +## Quick Setup Script (One Command) + +```bash +# Install all CLIs and configure for OmniRoute (replace with your key and server URL) +OMNIROUTE_URL="http://localhost:20128/v1" +OMNIROUTE_KEY="sk-your-omniroute-key" + +npm install -g @anthropic-ai/claude-code @openai/codex opencode-ai cline kilocode + +# Kiro CLI +apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash + +# Write configs +mkdir -p ~/.claude ~/.codex ~/.config/opencode ~/.continue + +cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" +cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" +cat >> ~/.bashrc << EOF +export OPENAI_BASE_URL="$OMNIROUTE_URL" +export OPENAI_API_KEY="$OMNIROUTE_KEY" +export ANTHROPIC_BASE_URL="$OMNIROUTE_URL" +export ANTHROPIC_API_KEY="$OMNIROUTE_KEY" +EOF + +source ~/.bashrc +echo "โœ… All CLIs installed and configured for OmniRoute" +``` diff --git a/docs/i18n/th/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/th/docs/CODEBASE_DOCUMENTATION.md new file mode 100644 index 0000000000..c363707359 --- /dev/null +++ b/docs/i18n/th/docs/CODEBASE_DOCUMENTATION.md @@ -0,0 +1,591 @@ +# omniroute โ€” Codebase Documentation (เน„เธ—เธข) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CODEBASE_DOCUMENTATION.md) + +--- + +> 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
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, Qoder, 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. + +#### เธชเธ–เธฒเธ›เธฑเธ•เธขเธเธฃเธฃเธก + +```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 | +| Qoder | 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"] +``` diff --git a/docs/i18n/th/docs/COVERAGE_PLAN.md b/docs/i18n/th/docs/COVERAGE_PLAN.md new file mode 100644 index 0000000000..88f1a29be7 --- /dev/null +++ b/docs/i18n/th/docs/COVERAGE_PLAN.md @@ -0,0 +1,170 @@ +# Test Coverage Plan (เน„เธ—เธข) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/COVERAGE_PLAN.md) + +--- + +Last updated: 2026-03-28 + +## Baseline + +There are multiple coverage numbers depending on how the report is computed. For planning, only one of them is useful. + +| Metric | Scope | Statements / Lines | Branches | Functions | Notes | +| -------------------- | ----------------------------------------------------- | -----------------: | -------: | --------: | --------------------------------------------------- | +| Legacy | Old `npm run test:coverage` | 79.42% | 75.15% | 67.94% | Inflated: counts test files and excludes `open-sse` | +| Diagnostic | Source-only, excluding tests and excluding `open-sse` | 68.16% | 63.55% | 64.06% | Useful only to isolate `src/**` | +| Recommended baseline | Source-only, excluding tests and including `open-sse` | 56.95% | 66.05% | 57.80% | This is the project-wide baseline to improve | + +The recommended baseline is the number to optimize against. + +## Rules + +- Coverage targets apply to source files, not to `tests/**`. +- `open-sse/**` is part of the product and must remain in scope. +- New code should not reduce coverage in touched areas. +- Prefer testing behavior and branch outcomes over implementation details. +- Prefer temp SQLite databases and small fixtures over broad mocks for `src/lib/db/**`. + +## Current command set + +- `npm run test:coverage` + - Main source coverage gate for the unit test suite + - Generates `text-summary`, `html`, `json-summary`, and `lcov` +- `npm run coverage:report` + - Detailed file-by-file report from the latest run +- `npm run test:coverage:legacy` + - Historical comparison only + +## Milestones + +| Phase | Target | Focus | +| ------- | ---------------------: | ------------------------------------------------- | +| Phase 1 | 60% statements / lines | Quick wins and low-risk utility coverage | +| Phase 2 | 65% statements / lines | DB and route foundations | +| Phase 3 | 70% statements / lines | Provider validation and usage analytics | +| Phase 4 | 75% statements / lines | `open-sse` translators and helpers | +| Phase 5 | 80% statements / lines | `open-sse` handlers and executor branches | +| Phase 6 | 85% statements / lines | Harder edge cases, branch debt, regression suites | +| Phase 7 | 90% statements / lines | Final sweep, gap closure, strict ratchet | + +Branches and functions should ratchet upward with each phase, but the primary hard target is statements / lines. + +## Priority hotspots + +These files or areas offer the best return for the next phases: + +1. `open-sse/handlers` + - `chatCore.ts` at 7.57% + - Overall directory at 29.07% +2. `open-sse/translator/request` + - Overall directory at 36.39% + - Many translators are still near single-digit coverage +3. `open-sse/translator/response` + - Overall directory at 8.07% +4. `open-sse/executors` + - Overall directory at 36.62% +5. `src/lib/db` + - `models.ts` at 20.66% + - `registeredKeys.ts` at 34.46% + - `modelComboMappings.ts` at 36.25% + - `settings.ts` at 46.40% + - `webhooks.ts` at 33.33% +6. `src/lib/usage` + - `usageHistory.ts` at 21.12% + - `usageStats.ts` at 9.56% + - `costCalculator.ts` at 30.00% +7. `src/lib/providers` + - `validation.ts` at 41.16% +8. Low-risk utility and API files for early gains + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/api/errorResponse.ts` + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +## Execution checklist + +### Phase 1: 56.95% -> 60% + +- [x] Fix coverage metric so it reflects source code instead of test files +- [x] Keep a legacy coverage script for comparison +- [x] Record the baseline and hotspots in-repo +- [ ] Add focused tests for low-risk utilities: + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/fetchTimeout.ts` + - `src/lib/api/errorResponse.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/display/names.ts` +- [ ] Add route tests for: + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +### Phase 2: 60% -> 65% + +- [ ] Add DB-backed tests for: + - `src/lib/db/modelComboMappings.ts` + - `src/lib/db/settings.ts` + - `src/lib/db/registeredKeys.ts` +- [ ] Cover branch behavior in: + - `src/lib/providers/validation.ts` + - `src/app/api/v1/embeddings/route.ts` + - `src/app/api/v1/moderations/route.ts` + +### Phase 3: 65% -> 70% + +- [ ] Add usage analytics tests for: + - `src/lib/usage/usageHistory.ts` + - `src/lib/usage/usageStats.ts` + - `src/lib/usage/costCalculator.ts` +- [ ] Expand route coverage for proxy management and settings branches + +### Phase 4: 70% -> 75% + +- [ ] Cover translator helpers and central translation paths: + - `open-sse/translator/index.ts` + - `open-sse/translator/helpers/*` + - `open-sse/translator/request/*` + - `open-sse/translator/response/*` + +### Phase 5: 75% -> 80% + +- [ ] Add handler-level tests for: + - `open-sse/handlers/chatCore.ts` + - `open-sse/handlers/responsesHandler.js` + - `open-sse/handlers/imageGeneration.js` + - `open-sse/handlers/embeddings.js` +- [ ] Add executor branch coverage for provider-specific auth, retries, and endpoint overrides + +### Phase 6: 80% -> 85% + +- [ ] Merge more edge-case suites into the main coverage path +- [ ] Increase function coverage for DB modules with weak constructor/helper coverage +- [ ] Close branch gaps in `settings.ts`, `registeredKeys.ts`, `validation.ts`, and translator helpers + +### Phase 7: 85% -> 90% + +- [ ] Treat the remaining low-coverage files as blockers +- [ ] Add regression tests for every uncovered production bug fixed during the push to 90% +- [ ] Raise the coverage gate in CI only after the local baseline is stable for at least two consecutive runs + +## Ratchet policy + +Update `npm run test:coverage` thresholds only after the project actually exceeds the next milestone with a comfortable buffer. + +Recommended ratchet sequence: + +1. 55/60/55 +2. 60/62/58 +3. 65/64/62 +4. 70/66/66 +5. 75/70/72 +6. 80/75/78 +7. 85/80/84 +8. 90/85/88 + +Order is `statements-lines / branches / functions`. + +## Known gap + +The current coverage command measures the main Node unit suite and includes source reached from it, including `open-sse`. It does not yet merge Vitest coverage into a single unified report. That merge is worth doing later, but it is not a blocker for starting the 60% -> 80% climb. diff --git a/docs/i18n/th/docs/FEATURES.md b/docs/i18n/th/docs/FEATURES.md index fcc7d494ad..228933dac1 100644 --- a/docs/i18n/th/docs/FEATURES.md +++ b/docs/i18n/th/docs/FEATURES.md @@ -1,6 +1,6 @@ # OmniRoute โ€” Dashboard Features Gallery (เน„เธ—เธข) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/FEATURES.md) --- @@ -10,7 +10,7 @@ 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). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. ![Providers Dashboard](screenshots/01-providers.png) diff --git a/docs/i18n/th/docs/MCP-SERVER.md b/docs/i18n/th/docs/MCP-SERVER.md new file mode 100644 index 0000000000..17340fc0b5 --- /dev/null +++ b/docs/i18n/th/docs/MCP-SERVER.md @@ -0,0 +1,87 @@ +# OmniRoute MCP Server Documentation (เน„เธ—เธข) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/MCP-SERVER.md) + +--- + +> Model Context Protocol server with 16 intelligent tools + +## เธ•เธดเธ”เธ•เธฑเน‰เธ‡ + +OmniRoute MCP is built-in. Start it with: + +```bash +omniroute --mcp +``` + +Or via the open-sse transport: + +```bash +# HTTP streamable transport (port 20130) +omniroute --dev # MCP auto-starts on /mcp endpoint +``` + +## IDE Configuration + +See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup. + +--- + +## Essential Tools (8) + +| Tool | Description | +| :------------------------------ | :--------------------------------------- | +| `omniroute_get_health` | Gateway health, circuit breakers, uptime | +| `omniroute_list_combos` | All configured combos with models | +| `omniroute_get_combo_metrics` | Performance metrics for a specific combo | +| `omniroute_switch_combo` | Switch active combo by ID/name | +| `omniroute_check_quota` | Quota status per provider or all | +| `omniroute_route_request` | Send a chat completion through OmniRoute | +| `omniroute_cost_report` | Cost analytics for a time period | +| `omniroute_list_models_catalog` | Full model catalog with capabilities | + +## Advanced Tools (8) + +| Tool | Description | +| :--------------------------------- | :---------------------------------------------------------- | +| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | +| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | +| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | +| `omniroute_test_combo` | Live-test all models in a combo via a real upstream request | +| `omniroute_get_provider_metrics` | Detailed metrics for one provider | +| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | +| `omniroute_explain_route` | Explain a past routing decision | +| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | + +## Authentication + +MCP tools are authenticated via API key scopes. Each tool requires specific scopes: + +| Scope | Tools | +| :------------- | :----------------------------------------------- | +| `read:health` | get_health, get_provider_metrics | +| `read:combos` | list_combos, get_combo_metrics | +| `write:combos` | switch_combo | +| `read:quota` | check_quota | +| `write:route` | route_request, simulate_route, test_combo | +| `read:usage` | cost_report, get_session_snapshot, explain_route | +| `write:config` | set_budget_guard, set_resilience_profile | +| `read:models` | list_models_catalog, best_combo_for_task | + +## Audit Logging + +Every tool call is logged to `mcp_tool_audit` with: + +- Tool name, arguments, result +- Duration (ms), success/failure +- API key hash, timestamp + +## Files + +| File | Purpose | +| :------------------------------------------- | :------------------------------------------ | +| `open-sse/mcp-server/server.ts` | MCP server creation + 16 tool registrations | +| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport | +| `open-sse/mcp-server/auth.ts` | API key + scope validation | +| `open-sse/mcp-server/audit.ts` | Tool call audit logging | +| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers | diff --git a/docs/i18n/th/docs/RELEASE_CHECKLIST.md b/docs/i18n/th/docs/RELEASE_CHECKLIST.md new file mode 100644 index 0000000000..3856923beb --- /dev/null +++ b/docs/i18n/th/docs/RELEASE_CHECKLIST.md @@ -0,0 +1,37 @@ +# Release Checklist (เน„เธ—เธข) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/RELEASE_CHECKLIST.md) + +--- + +Use this checklist before tagging or publishing a new OmniRoute release. + +## Version and Changelog + +1. Bump `package.json` version (`x.y.z`) in the release branch. +2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: + - `## [x.y.z] โ€” YYYY-MM-DD` +3. Keep `## [Unreleased]` as the first changelog section for upcoming work. +4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. + +## API Docs + +1. Update `docs/openapi.yaml`: + - `info.version` must equal `package.json` version. +2. Validate endpoint examples if API contracts changed. + +## Runtime Docs + +1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. +2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. +3. Update localized docs if source docs changed significantly. + +## Automated Check + +Run the sync guard locally before opening PR: + +```bash +npm run check:docs-sync +``` + +CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/th/docs/TROUBLESHOOTING.md b/docs/i18n/th/docs/TROUBLESHOOTING.md new file mode 100644 index 0000000000..6e0b098681 --- /dev/null +++ b/docs/i18n/th/docs/TROUBLESHOOTING.md @@ -0,0 +1,256 @@ +# Troubleshooting (เน„เธ—เธข) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/TROUBLESHOOTING.md) + +--- + +Common problems and solutions for OmniRoute. + +--- + +## Quick Fixes + +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | + +--- + +## Provider Issues + +### "Language model did not provide messages" + +**Cause:** Provider quota exhausted. + +**Fix:** + +1. 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, Qoder) 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}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) + +--- + +## Circuit Breaker Issues + +### Provider stuck in OPEN state + +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. + +**Fix:** + +1. 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 +- **SDK returns raw string instead of object** โ€” Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** โ€” Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** โ€” Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** โ€” Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` + +--- + +## Resilience Settings + +### Auto rate-limit not triggering + +- 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. + +--- + +## Optional RAG / LLM failure taxonomy (16 problems) + +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` โ€ฆ `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard โ†’ Health** for real-time system status +- **Translator**: Use **Dashboard โ†’ Translator** to debug format issues diff --git a/docs/i18n/th/USER_GUIDE.md b/docs/i18n/th/docs/USER_GUIDE.md similarity index 82% rename from docs/i18n/th/USER_GUIDE.md rename to docs/i18n/th/docs/USER_GUIDE.md index d04877d472..b0193353d1 100644 --- a/docs/i18n/th/USER_GUIDE.md +++ b/docs/i18n/th/docs/USER_GUIDE.md @@ -1,8 +1,6 @@ # User Guide (เน„เธ—เธข) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/USER_GUIDE.md) - -> ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/USER_GUIDE.md) --- @@ -320,7 +318,7 @@ Model: cc/claude-opus-4-6 --- -## ๐Ÿš€ Deployment +## เธเธฒเธฃเธ›เธฃเธฑเธšเนƒเธŠเน‰ ### Global npm install (Recommended) @@ -511,23 +509,26 @@ post_install() { ### Environment Variables -| Variable | Default | Description | -| ------------------------- | ------------------------------------ | ------------------------------------------------------- | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | -| `INITIAL_PASSWORD` | `123456` | First login password | -| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | -| `PORT` | framework default | Service port (`20128` in examples) | -| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | -| `NODE_ENV` | runtime default | Set `production` for deploy | -| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | -| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | -| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | -| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | -| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | -| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | -| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | -| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | +| 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/*` | +| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand | +| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | For the full environment variable reference, see the [README](../README.md). @@ -598,6 +599,11 @@ curl -X POST http://localhost:20128/api/provider-models \ Or use Dashboard: **Providers โ†’ [Provider] โ†’ Custom Models**. +Notes: + +- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers. +- The **Custom Models** section is intended for providers that do not expose managed available-model imports. + ### Dedicated Provider Routes Route requests directly to a specific provider with model validation: @@ -642,6 +648,14 @@ Returns models grouped by provider with types (`chat`, `embedding`, `image`). - Automatic background sync with timeout + fail-fast - Prefer server-side `BASE_URL`/`CLOUD_URL` in production +### Cloudflare Quick Tunnel + +- Available in **Dashboard โ†’ Endpoints** for Docker and other self-hosted deployments +- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint +- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary +- Tunnel URLs are ephemeral and change every time you stop/start the tunnel +- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download + ### LLM Gateway Intelligence (Phase 9) - **Semantic Cache** โ€” Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) @@ -757,11 +771,11 @@ OmniRoute implements provider-level resilience with four components: 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 | +| 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 unless `DISABLE_SQLITE_AUTO_BACKUP=true` | ```bash # API: Export database @@ -787,10 +801,11 @@ curl -X POST http://localhost:20128/api/db-backups/import \ ### Settings Dashboard -The settings page is organized into 5 tabs for easy navigation: +The settings page is organized into 6 tabs for easy navigation: | Tab | Contents | | -------------- | ---------------------------------------------------------------------------------------------- | +| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility | | **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | | **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | | **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | diff --git a/docs/i18n/th/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/th/docs/VM_DEPLOYMENT_GUIDE.md new file mode 100644 index 0000000000..41fa05468b --- /dev/null +++ b/docs/i18n/th/docs/VM_DEPLOYMENT_GUIDE.md @@ -0,0 +1,403 @@ +# OmniRoute โ€” Deployment Guide on VM with Cloudflare (เน„เธ—เธข) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/VM_DEPLOYMENT_GUIDE.md) + +--- + +Complete guide to install and configure OmniRoute on a VM (VPS) with domain managed via Cloudflare. + +--- + +## Prerequisites + +| Item | Minimum | Recommended | +| ---------- | ------------------------ | ---------------- | +| **CPU** | 1 vCPU | 2 vCPU | +| **RAM** | 1 GB | 2 GB | +| **Disk** | 10 GB SSD | 25 GB SSD | +| **OS** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS | +| **Domain** | Registered on Cloudflare | โ€” | +| **Docker** | Docker Engine 24+ | Docker 27+ | + +**Tested providers**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. + +--- + +## 1. Configure the VM + +### 1.1 Create the instance + +On your preferred VPS provider: + +- Choose Ubuntu 24.04 LTS +- Select the minimum plan (1 vCPU / 1 GB RAM) +- Set a strong root password or configure SSH key +- Note the **public IP** (e.g., `203.0.113.10`) + +### 1.2 Connect via SSH + +```bash +ssh root@203.0.113.10 +``` + +### 1.3 Update the system + +```bash +apt update && apt upgrade -y +``` + +### 1.4 Install Docker + +```bash +# Install dependencies +apt install -y ca-certificates curl gnupg + +# Add official Docker repository +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 Install nginx + +```bash +apt install -y nginx +``` + +### 1.6 Configure 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 +``` + +> **Tip**: For maximum security, restrict ports 80 and 443 to Cloudflare IPs only. See the [Advanced Security](#advanced-security) section. + +--- + +## 2. Install OmniRoute + +### 2.1 Create configuration directory + +```bash +mkdir -p /opt/omniroute +``` + +### 2.2 Create environment variables file + +```bash +cat > /opt/omniroute/.env << โ€˜EOFโ€™ +# === Security === +JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY +INITIAL_PASSWORD=YourSecurePassword123! +API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY +STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY +STORAGE_ENCRYPTION_KEY_VERSION=v1 +MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT + +# === 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 (change to your domain) === +BASE_URL=https://llms.seudominio.com +NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com + +# === Cloud Sync (optional) === +# CLOUD_URL=https://cloud.omniroute.online +# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online +EOF +``` + +> โš ๏ธ **IMPORTANT**: Generate unique secret keys! Use `openssl rand -hex 32` for each key. + +### 2.3 Start the 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 Verify that it is running + +```bash +docker ps | grep omniroute +docker logs omniroute --tail 20 +``` + +It should display: `[DB] SQLite database ready` and `listening on port 20128`. + +--- + +## 3. Configure nginx (Reverse Proxy) + +### 3.1 Generate SSL certificate (Cloudflare Origin) + +In the Cloudflare dashboard: + +1. Go to **SSL/TLS โ†’ Origin Server** +2. Click **Create Certificate** +3. Keep the defaults (15 years, \*.yourdomain.com) +4. Copy the **Origin Certificate** and the **Private Key** + +```bash +mkdir -p /etc/nginx/ssl + +# Paste the certificate +nano /etc/nginx/ssl/origin.crt + +# Paste the private key +nano /etc/nginx/ssl/origin.key + +chmod 600 /etc/nginx/ssl/origin.key +``` + +### 3.2 Nginx Configuration + +```bash +cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ +# Default server โ€” blocks direct access via 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.yourdomain.com; # Change to your domain + + 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.yourdomain.com; + return 301 https://$server_name$request_uri; +} +NGINX +``` + +### 3.3 Enable and Test + +```bash +# Remove default configuration +rm -f /etc/nginx/sites-enabled/default + +# Enable OmniRoute +ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute + +# Test and reload +nginx -t && systemctl reload nginx +``` + +--- + +## 4. Configure Cloudflare DNS + +### 4.1 Add DNS record + +In the Cloudflare dashboard โ†’ DNS: + +| Type | Name | Content | Proxy | +| ---- | ------ | ---------------------- | ---------- | +| A | `llms` | `203.0.113.10` (VM IP) | โœ… Proxied | + +### 4.2 Configure SSL + +Under **SSL/TLS โ†’ Overview**: + +- Mode: **Full (Strict)** + +Under **SSL/TLS โ†’ Edge Certificates**: + +- Always Use HTTPS: โœ… On +- Minimum TLS Version: TLS 1.2 +- Automatic HTTPS Rewrites: โœ… On + +### 4.3 Testing + +```bash +curl -sI https://llms.seudominio.com/health +# Should return HTTP/2 200 +``` + +--- + +## 5. Operations and Maintenance + +### Upgrade to a new version + +```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 +``` + +### View logs + +```bash +docker logs -f omniroute # Real-time stream +docker logs omniroute --tail 50 # Last 50 lines +``` + +### Manual database backup + +```bash +# Copy data from the volume to the host +docker cp omniroute:/app/data ./backup-$(date +%F) + +# Or compress the entire volume +docker run --rm -v omniroute-data:/data -v $(pwd):/backup \ + alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data +``` + +### Restore from 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. Advanced Security + +### Restrict nginx to Cloudflare IPs + +```bash +cat > /etc/nginx/cloudflare-ips.conf << โ€˜CFโ€™ +# Cloudflare IPv4 ranges โ€” update periodically +# 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 +``` + +Add the following to `nginx.conf` inside the `http {}` block: + +```nginx +include /etc/nginx/cloudflare-ips.conf; +``` + +### Install fail2ban + +```bash +apt install -y fail2ban +systemctl enable fail2ban +systemctl start fail2ban + +# Check status +fail2ban-client status sshd +``` + +### Block direct access to the Docker port + +```bash +# Prevent direct external access to port 20128 +iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP +iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT + +# Persist the rules +apt install -y iptables-persistent +netfilter-persistent save +``` + +--- + +## 7. Deploy to Cloudflare Workers (Optional) + +For remote access via Cloudflare Workers (without exposing the VM directly): + +```bash +# In the local repository +cd omnirouteCloud +npm install +npx wrangler login +npx wrangler deploy +``` + +See the full documentation at [omnirouteCloud/README.md](../omnirouteCloud/README.md). + +--- + +## Port Summary + +| Port | Service | Access | +| ----- | ----------- | -------------------------- | +| 22 | SSH | Public (with fail2ban) | +| 80 | nginx HTTP | Redirect โ†’ HTTPS | +| 443 | nginx HTTPS | Via Cloudflare Proxy | +| 20128 | OmniRoute | Localhost only (via nginx) | diff --git a/docs/i18n/th/src/lib/a2a/README.md b/docs/i18n/th/src/lib/a2a/README.md new file mode 100644 index 0000000000..ddf130af53 --- /dev/null +++ b/docs/i18n/th/src/lib/a2a/README.md @@ -0,0 +1,752 @@ +# OmniRoute A2A Server (เน„เธ—เธข) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../../../src/lib/a2a/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../../../es/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../../../fr/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../../../de/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../../../it/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../../../ru/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../../../zh-CN/src/lib/a2a/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../../../ja/src/lib/a2a/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../../../ko/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../../../ar/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../../../in/src/lib/a2a/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../../../th/src/lib/a2a/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../../../vi/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../../../id/src/lib/a2a/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../../../ms/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../../../nl/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../../../pl/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../../../sv/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../../../no/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../../../da/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../../../fi/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../../../pt/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../../../ro/src/lib/a2a/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../../../hu/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../../../bg/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../../../sk/src/lib/a2a/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../../../uk-UA/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../../../he/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../../../phi/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../../../pt-BR/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../../../cs/src/lib/a2a/README.md) + +--- + +> **Agent-to-Agent Protocol v0.3** โ€” Enables any AI agent to use OmniRoute as an intelligent routing agent via JSON-RPC 2.0. + +The A2A Server exposes OmniRoute as a **first-class agent** that other agents can discover, delegate tasks to, and collaborate with using the [A2A Protocol](https://google.github.io/A2A/). + +--- + +## เธชเธ–เธฒเธ›เธฑเธ•เธขเธเธฃเธฃเธก + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Orchestrator Agent โ”‚ +โ”‚ (LangChain, CrewAI, AutoGen, Custom Agent) โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ 1. GET /.well-known/agent.json (discover) + โ”‚ 2. POST /a2a (JSON-RPC 2.0) + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ OmniRoute A2A Server โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Task Manager โ”‚ โ”‚ Skill Engine โ”‚ โ”‚ SSE Streaming โ”‚ โ”‚ +โ”‚ โ”‚ (lifecycle) โ”‚โ”€โ”€โ”‚ (registry) โ”‚โ”€โ”€โ”‚ (real-time) โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ +โ”‚ Skills: โ”‚ โ”‚ +โ”‚ โ”œโ”€ smart-routing โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ””โ”€ quota-management โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ Routing Decision Logger โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ OmniRoute Gateway (internal) + /v1/chat/completions, /api/combos, /api/usage/quota +``` + +--- + +## เน€เธฃเธดเนˆเธกเธ•เน‰เธ™เธญเธขเนˆเธฒเธ‡เธฃเธงเธ”เน€เธฃเน‡เธง + +### Agent Discovery + +Every A2A-compatible agent exposes an **Agent Card** at `/.well-known/agent.json`: + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +**Response:** + +```json +{ + "name": "OmniRoute", + "description": "Intelligent AI gateway with auto-routing across 50+ providers", + "url": "http://localhost:20128/a2a", + "version": "1.8.1", + "capabilities": { + "streaming": true, + "pushNotifications": false + }, + "skills": [ + { + "id": "smart-routing", + "name": "Smart Routing", + "description": "Routes prompts through OmniRoute intelligent pipeline", + "tags": ["routing", "llm", "multi-provider", "cost-optimization"], + "examples": [ + "Write a hello world in Python", + "Explain quantum computing using the cheapest provider" + ] + }, + { + "id": "quota-management", + "name": "Quota Management", + "description": "Natural-language queries about provider quotas", + "tags": ["quota", "analytics", "cost"], + "examples": [ + "Which provider has the most quota remaining?", + "Suggest a free combo for coding" + ] + } + ], + "authentication": { + "schemes": ["bearer"], + "apiKeyHeader": "Authorization" + } +} +``` + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Send a message to a skill and receive the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python hello world"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "a1b2c3d4-...", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "print('Hello, World!')" }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.0030)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "2026-03-04T..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"Quantum computing..."}}} + +: heartbeat 2026-03-04T21:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Running Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Skills Reference + +### `smart-routing` + +Routes prompts through OmniRoute's intelligent pipeline with full observability. + +**Parameters (in `metadata`):** + +| Parameter | Type | Default | Description | +| --------- | -------- | ------------ | ---------------------------------------------------------------------------------------- | +| `model` | `string` | `"auto"` | Target model (e.g., `claude-sonnet-4`, `gpt-4o`, `auto`) | +| `combo` | `string` | active combo | Specific combo to route through | +| `budget` | `number` | none | Maximum cost in USD for this request | +| `role` | `string` | none | Task role hint: `coding`, `review`, `planning`, `analysis`, `debugging`, `documentation` | + +**Returns:** + +| Field | Description | +| ------------------------------ | --------------------------------------------------------- | +| `artifacts[].content` | The LLM response text | +| `metadata.routing_explanation` | Human-readable explanation of routing decision | +| `metadata.cost_envelope` | Estimated vs actual cost with currency | +| `metadata.resilience_trace` | Array of events (primary_selected, fallback_needed, etc.) | +| `metadata.policy_verdict` | Whether the request was allowed and why | + +### `quota-management` + +Answers natural-language queries about provider quotas. + +**Query types (inferred from message content):** + +| Query Pattern | Response Type | +| ---------------------------------------------- | -------------------------------------------------------- | +| Contains `"ranking"`, `"most quota"`, `"best"` | Providers ranked by remaining quota | +| Contains `"free"`, `"suggest"` | Lists free combos or suggests free-tier providers | +| Default | Full quota summary with warnings for low-quota providers | + +--- + +## Task Lifecycle + +``` +submitted โ”€โ”€โ†’ working โ”€โ”€โ†’ completed + โ”€โ”€โ†’ failed + โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ†’ cancelled +``` + +| State | Description | +| ----------- | ----------------------------------------------------- | +| `submitted` | Task created, queued for execution | +| `working` | Skill handler is executing | +| `completed` | Execution succeeded, artifacts available | +| `failed` | Execution failed or task expired (TTL: 5 min default) | +| `cancelled` | Cancelled by client via `tasks/cancel` | + +- Terminal states: `completed`, `failed`, `cancelled` (no further transitions) +- Expired tasks in `submitted` or `working` are auto-marked as `failed` +- Tasks are garbage-collected after 2ร— TTL + +--- + +## Client Examples + +### Python โ€” Orchestrator Agent + +```python +""" +A2A Client โ€” Python example. +Discovers OmniRoute agent, sends a task, and processes the result. +""" +import requests +import json + +BASE_URL = "http://localhost:20128" +API_KEY = "your-api-key" +HEADERS = { + "Content-Type": "application/json", + "Authorization": f"Bearer {API_KEY}", +} + +# 1. Discover agent capabilities +agent_card = requests.get(f"{BASE_URL}/.well-known/agent.json").json() +print(f"Agent: {agent_card['name']} v{agent_card['version']}") +print(f"Skills: {[s['id'] for s in agent_card['skills']]}") + +# 2. Send a smart-routing task +response = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python quicksort implementation"}], + "metadata": { + "model": "auto", + "combo": "fast-coding", + "budget": 0.10, + } + } +}) +result = response.json()["result"] +print(f"\n๐Ÿ“ Response: {result['artifacts'][0]['content'][:200]}...") +print(f"๐Ÿ”€ Routing: {result['metadata']['routing_explanation']}") +print(f"๐Ÿ’ฐ Cost: ${result['metadata']['cost_envelope']['actual']}") +print(f"๐Ÿ›ก๏ธ Policy: {result['metadata']['policy_verdict']['reason']}") + +# 3. Query quota status +quota_resp = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-2", + "method": "message/send", + "params": { + "skill": "quota-management", + "messages": [{"role": "user", "content": "Which provider has the most quota remaining?"}], + } +}) +quota_result = quota_resp.json()["result"] +print(f"\n๐Ÿ“Š Quota: {quota_result['artifacts'][0]['content']}") +``` + +### TypeScript โ€” Multi-Agent Orchestrator + +```typescript +/** + * A2A Client โ€” TypeScript example. + * Shows agent discovery, task delegation, and streaming. + */ + +const BASE_URL = "http://localhost:20128"; +const API_KEY = "your-api-key"; + +interface JsonRpcResponse { + jsonrpc: "2.0"; + id: string | number; + result?: T; + error?: { code: number; message: string }; +} + +async function a2aCall(method: string, params: Record): Promise { + const resp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: `${method}-${Date.now()}`, + method, + params, + }), + }); + const json: JsonRpcResponse = await resp.json(); + if (json.error) throw new Error(`[${json.error.code}] ${json.error.message}`); + return json.result!; +} + +// โ”€โ”€ Agent Discovery โ”€โ”€ +const agentCard = await fetch(`${BASE_URL}/.well-known/agent.json`).then((r) => r.json()); +console.log(`Connected to: ${agentCard.name} (${agentCard.skills.length} skills)`); + +// โ”€โ”€ Smart Routing: Send a coding task โ”€โ”€ +const routingResult = await a2aCall("message/send", { + skill: "smart-routing", + messages: [{ role: "user", content: "Implement a Redis cache wrapper in TypeScript" }], + metadata: { model: "claude-sonnet-4", role: "coding" }, +}); +console.log("Response:", routingResult.artifacts[0].content); +console.log("Provider:", routingResult.metadata.routing_explanation); + +// โ”€โ”€ Quota Management: Find free alternatives โ”€โ”€ +const quotaResult = await a2aCall("message/send", { + skill: "quota-management", + messages: [{ role: "user", content: "Suggest free combos for documentation" }], +}); +console.log("Free combos:", quotaResult.artifacts[0].content); + +// โ”€โ”€ Streaming: Real-time response โ”€โ”€ +const streamResp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "stream-1", + method: "message/stream", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Explain microservices architecture" }], + }, + }), +}); + +const reader = streamResp.body!.getReader(); +const decoder = new TextDecoder(); +while (true) { + const { done, value } = await reader.read(); + if (done) break; + const chunk = decoder.decode(value); + for (const line of chunk.split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + if (event.params.chunk) { + process.stdout.write(event.params.chunk.content); + } + if (event.params.task.state === "completed") { + console.log("\nโœ… Stream completed"); + } + } + } +} +``` + +### Python โ€” LangChain A2A Integration + +```python +""" +LangChain integration โ€” Use OmniRoute A2A as a custom LLM. +""" +from langchain.llms.base import BaseLLM +from langchain.schema import LLMResult, Generation +import requests +from typing import List, Optional + +class OmniRouteA2A(BaseLLM): + base_url: str = "http://localhost:20128" + api_key: str = "" + model: str = "auto" + combo: Optional[str] = None + + @property + def _llm_type(self) -> str: + return "omniroute-a2a" + + def _call(self, prompt: str, stop: Optional[List[str]] = None, **kwargs) -> str: + response = requests.post( + f"{self.base_url}/a2a", + headers={ + "Content-Type": "application/json", + "Authorization": f"Bearer {self.api_key}", + }, + json={ + "jsonrpc": "2.0", + "id": "langchain-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": prompt}], + "metadata": { + "model": self.model, + **({"combo": self.combo} if self.combo else {}), + }, + }, + }, + ) + result = response.json()["result"] + return result["artifacts"][0]["content"] + + def _generate(self, prompts: List[str], stop=None, **kwargs) -> LLMResult: + return LLMResult( + generations=[[Generation(text=self._call(p, stop))] for p in prompts] + ) + +# Usage +llm = OmniRouteA2A( + base_url="http://localhost:20128", + api_key="your-key", + model="auto", + combo="fast-coding", +) +result = llm("Write a Python function to merge two sorted lists") +print(result) +``` + +### Go โ€” A2A Client + +```go +package main + +import ( + "bytes" + "encoding/json" + "fmt" + "io" + "net/http" +) + +const baseURL = "http://localhost:20128" +const apiKey = "your-api-key" + +type JsonRpcRequest struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Method string `json:"method"` + Params interface{} `json:"params"` +} + +type JsonRpcResponse struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Result interface{} `json:"result"` + Error *struct { + Code int `json:"code"` + Message string `json:"message"` + } `json:"error"` +} + +func a2aCall(method string, params interface{}) (*JsonRpcResponse, error) { + body, _ := json.Marshal(JsonRpcRequest{ + Jsonrpc: "2.0", + ID: "go-1", + Method: method, + Params: params, + }) + + req, _ := http.NewRequest("POST", baseURL+"/a2a", bytes.NewReader(body)) + req.Header.Set("Content-Type", "application/json") + req.Header.Set("Authorization", "Bearer "+apiKey) + + resp, err := http.DefaultClient.Do(req) + if err != nil { + return nil, err + } + defer resp.Body.Close() + data, _ := io.ReadAll(resp.Body) + + var result JsonRpcResponse + json.Unmarshal(data, &result) + return &result, nil +} + +func main() { + // Discover agent + resp, _ := http.Get(baseURL + "/.well-known/agent.json") + defer resp.Body.Close() + body, _ := io.ReadAll(resp.Body) + fmt.Println("Agent Card:", string(body)) + + // Send smart-routing task + result, _ := a2aCall("message/send", map[string]interface{}{ + "skill": "smart-routing", + "messages": []map[string]string{{"role": "user", "content": "Hello from Go!"}}, + "metadata": map[string]interface{}{"model": "auto"}, + }) + out, _ := json.MarshalIndent(result.Result, "", " ") + fmt.Println("Result:", string(out)) +} +``` + +--- + +## Use Cases + +### ๐Ÿค– Use Case 1: Multi-Agent Coding Pipeline + +An orchestrator agent delegates code generation to OmniRoute, then passes the output to a review agent. + +```python +def coding_pipeline(task: str): + # Step 1: Generate code via OmniRoute A2A + code_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Write production-quality code: {task}"} + ], metadata={"model": "auto", "role": "coding"}) + code = code_result["artifacts"][0]["content"] + + # Step 2: Review the code via OmniRoute A2A (different model) + review_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Review this code for bugs and improvements:\n\n{code}"} + ], metadata={"model": "auto", "role": "review"}) + review = review_result["artifacts"][0]["content"] + + # Step 3: Check costs + print(f"Code cost: ${code_result['metadata']['cost_envelope']['actual']}") + print(f"Review cost: ${review_result['metadata']['cost_envelope']['actual']}") + + return {"code": code, "review": review} +``` + +### ๐Ÿ’ก Use Case 2: Quota-Aware Agent Swarm + +Multiple agents share quota through OmniRoute, using the quota skill to coordinate. + +```python +async def quota_aware_agent(agent_name: str, task: str): + # Check quota before starting + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Which provider has the most quota remaining?"} + ]) + print(f"[{agent_name}] {quota['artifacts'][0]['content']}") + + # Send request with budget constraint + result = a2a_send("smart-routing", [ + {"role": "user", "content": task} + ], metadata={"budget": 0.05}) + + policy = result["metadata"]["policy_verdict"] + if not policy["allowed"]: + print(f"[{agent_name}] โš ๏ธ Budget exceeded: {policy['reason']}") + # Fall back to free combo + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Suggest free combos"} + ]) + print(f"[{agent_name}] Free alternatives: {quota['artifacts'][0]['content']}") + + return result +``` + +### ๐Ÿ“Š Use Case 3: Real-Time Streaming Dashboard + +A monitoring agent streams responses and displays progress in real-time. + +```typescript +async function streamingDashboard(prompt: string) { + const response = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { "Content-Type": "application/json", Authorization: `Bearer ${API_KEY}` }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "dash-1", + method: "message/stream", + params: { skill: "smart-routing", messages: [{ role: "user", content: prompt }] }, + }), + }); + + let totalChunks = 0; + const reader = response.body!.getReader(); + const decoder = new TextDecoder(); + + while (true) { + const { done, value } = await reader.read(); + if (done) break; + + for (const line of decoder.decode(value).split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + const state = event.params.task.state; + + if (state === "working" && event.params.chunk) { + totalChunks++; + process.stdout.write( + `\r[Chunk ${totalChunks}] ${event.params.chunk.content.slice(0, 50)}...` + ); + } + if (state === "completed") { + const meta = event.params.metadata; + console.log( + `\nโœ… Done | Cost: $${meta?.cost_envelope?.actual || 0} | Route: ${meta?.routing_explanation || "N/A"}` + ); + } + if (state === "failed") { + console.error(`\nโŒ Failed: ${event.params.metadata?.error}`); + } + } + } + } +} +``` + +### ๐Ÿ” Use Case 4: Task Polling Pattern + +For long-running tasks, poll the task status instead of waiting synchronously. + +```python +import time + +def poll_task(task_id: str, timeout: int = 60): + """Poll task status until completion or timeout.""" + start = time.time() + while time.time() - start < timeout: + result = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "poll-1", + "method": "tasks/get", + "params": {"taskId": task_id}, + }).json() + + task = result["result"]["task"] + state = task["state"] + print(f" Task {task_id[:8]}... state={state}") + + if state in ("completed", "failed", "cancelled"): + return task + time.sleep(2) + + # Timeout โ€” cancel the task + requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "cancel-1", + "method": "tasks/cancel", + "params": {"taskId": task_id}, + }) + raise TimeoutError(f"Task {task_id} timed out after {timeout}s") +``` + +--- + +## Error Codes + +| Code | Constant | Meaning | +| ------ | ------------------------ | ---------------------------------------- | +| -32700 | โ€” | Parse error (invalid JSON) | +| -32600 | `INVALID_REQUEST` | Invalid JSON-RPC request or unauthorized | +| -32601 | `METHOD_NOT_FOUND` | Unknown method or skill | +| -32602 | `INVALID_PARAMS` | Missing or invalid parameters | +| -32603 | `INTERNAL_ERROR` | Skill execution failed | +| -32001 | `TASK_NOT_FOUND` | Task ID not found | +| -32002 | `TASK_ALREADY_COMPLETED` | Cannot modify a completed task | +| -32003 | `UNAUTHORIZED` | Invalid or missing API key | +| -32004 | `BUDGET_EXCEEDED` | Request exceeds configured budget | +| -32005 | `PROVIDER_UNAVAILABLE` | No available providers | + +--- + +## Authentication + +All `/a2a` requests require a Bearer token via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server (`OMNIROUTE_API_KEY` is empty), authentication is bypassed. + +--- + +## File Structure + +``` +src/lib/a2a/ +โ”œโ”€โ”€ taskManager.ts # Task lifecycle (create/update/cancel/list), TTL, cleanup +โ”œโ”€โ”€ taskExecution.ts # Generic task executor with state management +โ”œโ”€โ”€ streaming.ts # SSE stream formatting, heartbeat, chunk/completion events +โ”œโ”€โ”€ routingLogger.ts # Routing decision logger (stats, history, retention) +โ””โ”€โ”€ skills/ + โ”œโ”€โ”€ smartRouting.ts # Smart routing skill (routes via /v1/chat/completions) + โ””โ”€โ”€ quotaManagement.ts # Quota management skill (natural-language quota queries) + +src/app/a2a/ +โ””โ”€โ”€ route.ts # Next.js API route handler (JSON-RPC 2.0 dispatch) + +open-sse/mcp-server/ +โ””โ”€โ”€ schemas/a2a.ts # Zod schemas (AgentCard, Task, JSON-RPC, SSE events) +``` + +--- + +## Comparison: MCP vs A2A + +| Feature | MCP Server | A2A Server | +| ----------------- | ---------------------------- | ------------------------------------------------- | +| **Protocol** | Model Context Protocol | Agent-to-Agent Protocol v0.3 | +| **Transport** | stdio / HTTP | HTTP (JSON-RPC 2.0) | +| **Discovery** | Tool listing via MCP | `/.well-known/agent.json` | +| **Granularity** | 16 individual tools | 2 high-level skills | +| **Best for** | IDE agents (Cursor, VS Code) | Multi-agent systems (LangChain, CrewAI) | +| **Streaming** | Not supported | SSE via `message/stream` | +| **Task tracking** | No | Full lifecycle (submitted โ†’ completed) | +| **Observability** | Audit log per tool call | Cost envelope + resilience trace + policy verdict | + +--- + +## เธชเธดเธ—เธ˜เธดเนŒเธเธฒเธฃเนƒเธŠเน‰เธ‡เธฒเธ™ + +Part of [OmniRoute](https://github.com/diegosouzapw/OmniRoute) โ€” MIT License. diff --git a/docs/i18n/uk-UA/A2A-SERVER.md b/docs/i18n/uk-UA/A2A-SERVER.md deleted file mode 100644 index 01531ff482..0000000000 --- a/docs/i18n/uk-UA/A2A-SERVER.md +++ /dev/null @@ -1,200 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/A2A-SERVER.md) - ---- - -# OmniRoute A2A Server Documentation - -> Agent-to-Agent Protocol v0.3 โ€” OmniRoute as an intelligent routing agent - -## Agent Discovery - -```bash -curl http://localhost:20128/.well-known/agent.json -``` - -Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements. - ---- - -## Authentication - -All `/a2a` requests require an API key via the `Authorization` header: - -``` -Authorization: Bearer YOUR_OMNIROUTE_API_KEY -``` - -If no API key is configured on the server, authentication is bypassed. - ---- - -## JSON-RPC 2.0 Methods - -### `message/send` โ€” Synchronous Execution - -Sends a message to a skill and waits for the complete response. - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{ - "jsonrpc": "2.0", - "id": "1", - "method": "message/send", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Write a hello world in Python"}], - "metadata": {"model": "auto", "combo": "fast-coding"} - } - }' -``` - -**Response:** - -```json -{ - "jsonrpc": "2.0", - "id": "1", - "result": { - "task": { "id": "uuid", "state": "completed" }, - "artifacts": [{ "type": "text", "content": "..." }], - "metadata": { - "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)", - "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, - "resilience_trace": [ - { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." } - ], - "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } - } - } -} -``` - -### `message/stream` โ€” SSE Streaming - -Same as `message/send` but returns Server-Sent Events for real-time streaming. - -```bash -curl -N -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{ - "jsonrpc": "2.0", - "id": "1", - "method": "message/stream", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Explain quantum computing"}] - } - }' -``` - -**SSE Events:** - -``` -data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}} - -: heartbeat 2026-03-03T17:00:00Z - -data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} -``` - -### `tasks/get` โ€” Query Task Status - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' -``` - -### `tasks/cancel` โ€” Cancel a Task - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' -``` - ---- - -## Available Skills - -| Skill | Description | -| :----------------- | :------------------------------------------------------------------------------------------------------------------------------ | -| `smart-routing` | Routes prompts through OmniRoute's intelligent pipeline. Returns response with routing explanation, cost, and resilience trace. | -| `quota-management` | Answers natural-language queries about provider quotas, suggests free combos, and provides quota rankings. | - ---- - -## Task Lifecycle - -``` -submitted โ†’ working โ†’ completed - โ†’ failed - โ†’ cancelled -``` - -- Tasks expire after 5 minutes (configurable) -- Terminal states: `completed`, `failed`, `cancelled` -- Event log tracks every state transition - ---- - -## Error Codes - -| Code | Meaning | -| :----- | :----------------------------- | -| -32700 | Parse error (invalid JSON) | -| -32600 | Invalid request / Unauthorized | -| -32601 | Method or skill not found | -| -32602 | Invalid params | -| -32603 | Internal error | - ---- - -## Integration Examples - -### Python (requests) - -```python -import requests - -resp = requests.post("http://localhost:20128/a2a", json={ - "jsonrpc": "2.0", "id": "1", - "method": "message/send", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Hello"}] - } -}, headers={"Authorization": "Bearer YOUR_KEY"}) - -result = resp.json()["result"] -print(result["artifacts"][0]["content"]) -print(result["metadata"]["routing_explanation"]) -``` - -### TypeScript (fetch) - -```typescript -const resp = await fetch("http://localhost:20128/a2a", { - method: "POST", - headers: { - "Content-Type": "application/json", - Authorization: "Bearer YOUR_KEY", - }, - body: JSON.stringify({ - jsonrpc: "2.0", - id: "1", - method: "message/send", - params: { - skill: "smart-routing", - messages: [{ role: "user", content: "Hello" }], - }, - }), -}); -const { result } = await resp.json(); -console.log(result.metadata.routing_explanation); -``` diff --git a/docs/i18n/uk-UA/API_REFERENCE.md b/docs/i18n/uk-UA/API_REFERENCE.md deleted file mode 100644 index b878605221..0000000000 --- a/docs/i18n/uk-UA/API_REFERENCE.md +++ /dev/null @@ -1,455 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/API_REFERENCE.md) - ---- - -# API Reference - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/API_REFERENCE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/API_REFERENCE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/API_REFERENCE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/API_REFERENCE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/API_REFERENCE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/API_REFERENCE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/API_REFERENCE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/API_REFERENCE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/API_REFERENCE.md) - -Complete reference for all OmniRoute API endpoints. - ---- - -## Table of Contents - -- [Chat Completions](#chat-completions) -- [Embeddings](#embeddings) -- [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`. - -### ACP Agents - -| Endpoint | Method | Description | -| ----------------- | ------ | -------------------------------------------------------- | -| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | -| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | -| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | - -GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). - -### Resilience & Rate Limits - -| Endpoint | Method | Description | -| ----------------------- | ------- | ------------------------------- | -| `/api/resilience` | 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` diff --git a/docs/i18n/uk-UA/ARCHITECTURE.md b/docs/i18n/uk-UA/ARCHITECTURE.md deleted file mode 100644 index 4ea06a29f2..0000000000 --- a/docs/i18n/uk-UA/ARCHITECTURE.md +++ /dev/null @@ -1,787 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/ARCHITECTURE.md) - ---- - -# OmniRoute Architecture - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/ARCHITECTURE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/ARCHITECTURE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/ARCHITECTURE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/ARCHITECTURE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/ARCHITECTURE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/ARCHITECTURE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/ARCHITECTURE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/ARCHITECTURE.md) - -_Last updated: 2026-03-04_ - -## 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 (`...`) for reasoning models -- Response sanitization for strict OpenAI SDK compatibility -- Role normalization (developerโ†’system, systemโ†’user) for cross-provider compatibility -- Structured output conversion (json_schema โ†’ Gemini responseSchema) -- Local persistence for providers, keys, aliases, combos, settings, pricing -- Usage/cost tracking and request logging -- Optional cloud sync for multi-device/state sync -- IP allowlist/blocklist for API access control -- Thinking budget management (passthrough/auto/custom/adaptive) -- Global system prompt injection -- Session tracking and fingerprinting -- Per-account enhanced rate limiting with provider-specific profiles -- Circuit breaker pattern for provider resilience -- Anti-thundering herd protection with mutex locking -- Signature-based request deduplication cache -- Domain layer: model availability, cost rules, fallback policy, lockout policy -- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) -- Policy engine for centralized request evaluation (lockout โ†’ budget โ†’ fallback) -- Request telemetry with p50/p95/p99 latency aggregation -- Correlation ID (X-Request-Id) for end-to-end tracing -- Compliance audit logging with opt-out per API key -- Eval framework for LLM quality assurance -- Resilience UI dashboard with real-time circuit breaker status -- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) - -Primary runtime model: - -- Next.js 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[(storage.sqlite)] - UDB[(usage tables + log artifacts)] - end - - subgraph Upstreams[Upstream Providers] - P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/Qoder/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/route.ts` (GET) -- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) -- OAuth: `src/app/api/oauth/*` -- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` -- Usage: `src/app/api/usage/*` -- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` -- CLI tooling helpers: `src/app/api/cli-tools/*` -- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) -- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) -- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) -- Sessions: `src/app/api/sessions` (GET) -- Rate limits: `src/app/api/rate-limits` (GET) -- Resilience: `src/app/api/resilience` (GET/PATCH) โ€” provider profiles, circuit breaker, rate limit state -- Resilience reset: `src/app/api/resilience/reset` (POST) โ€” reset breakers + cooldowns -- Cache stats: `src/app/api/cache/stats` (GET/DELETE) -- Model availability: `src/app/api/models/availability` (GET/POST) -- Telemetry: `src/app/api/telemetry/summary` (GET) -- Budget: `src/app/api/usage/budget` (GET/POST) -- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) -- Compliance audit: `src/app/api/compliance/audit-log` (GET) -- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) -- Policies: `src/app/api/policies` (GET/POST) - -## 2) SSE + 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` -- Response sanitization: `open-sse/handlers/responseSanitizer.ts` -- Role normalization: `open-sse/services/roleNormalizer.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`, `qoder.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 (SQLite): - -- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) -- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) -- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) -- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** - -Usage persistence: - -- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) -- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` -- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) -- legacy JSON files are migrated to SQLite by startup migrations when present - -Domain State DB (SQLite): - -- `src/lib/db/domainState.ts` โ€” CRUD operations 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: - -- primary runtime DB: `${DATA_DIR}/storage.sqlite` -- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) -- structured call payload archives: `${DATA_DIR}/call_logs/` -- optional translator/request debug sessions: `/logs/...` - -## Deployment Topology - -```mermaid -flowchart LR - 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[(storage.sqlite)] - UsageDB[(usage tables + log artifacts)] - end - - subgraph External[External Services] - Providers[AI Providers] - SyncCloud[Cloud Sync Service] - end - - CLI --> Next - Browser --> Next - Next --> Core - Next --> MainDB - Core --> MainDB - Core --> UsageDB - Core --> Providers - Next --> SyncCloud -``` - -## Module Mapping (Decision-Critical) - -### Route and API Modules - -- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs -- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) -- `src/app/api/providers*`: provider CRUD, validation, testing -- `src/app/api/provider-nodes*`: custom compatible node management -- `src/app/api/provider-models`: custom model management (CRUD) -- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) -- `src/app/api/oauth/*`: OAuth/device-code flows -- `src/app/api/keys*`: local API key lifecycle -- `src/app/api/models/alias`: alias management -- `src/app/api/combos*`: fallback combo management -- `src/app/api/pricing`: pricing overrides for cost calculation -- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) -- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) -- `src/app/api/usage/*`: usage and logs APIs -- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers -- `src/app/api/cli-tools/*`: local CLI config writers/checkers -- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) -- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) -- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) -- `src/app/api/sessions`: active session listing (GET) -- `src/app/api/rate-limits`: per-account rate limit status (GET) - -### Routing and Execution Core - -- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop -- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup -- `open-sse/executors/*`: provider-specific network and format behavior - -### Translation Registry and Format Converters - -- `open-sse/translator/index.ts`: translator registry and orchestration -- Request translators: `open-sse/translator/request/*` -- Response translators: `open-sse/translator/response/*` -- Format constants: `open-sse/translator/formats.ts` - -### Persistence - -- `src/lib/db/*`: persistent config/state and domain persistence on SQLite -- `src/lib/localDb.ts`: compatibility re-export for DB modules -- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables - -## Provider Executor Coverage (Strategy Pattern) - -Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. - -| Executor | Provider(s) | Special Handling | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | -| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, Qoder, 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 | -| Qoder | openai | OAuth (Basic) | โœ… | โœ… | โœ… | โš ๏ธ Per request | -| OpenRouter | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| GLM/Kimi/MiniMax | claude | API Key | โœ… | โœ… | โŒ | โŒ | -| DeepSeek | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Groq | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| xAI (Grok) | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Mistral | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Perplexity | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Together AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Fireworks AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Cerebras | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Cohere | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| NVIDIA NIM | openai | API Key | โœ… | โœ… | โŒ | โŒ | - -## Format Translation Coverage - -Detected source formats include: - -- `openai` -- `openai-responses` -- `claude` -- `gemini` - -Target formats include: - -- OpenAI chat/Responses -- Claude -- Gemini/Gemini-CLI/Antigravity envelope -- Kiro -- Cursor - -Translations use **OpenAI as the hub format** โ€” all conversions go through OpenAI as intermediate: - -``` -Source Format โ†’ OpenAI (hub) โ†’ Target Format -``` - -Translations are selected dynamically based on source payload shape and provider target format. - -Additional processing layers in the translation pipeline: - -- **Response sanitization** โ€” Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance -- **Role normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI targets; merges `system` โ†’ `user` for models that reject the system role (GLM, ERNIE) -- **Think tag extraction** โ€” Parses `...` blocks from content into `reasoning_content` field -- **Structured output** โ€” Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` - -## Supported API Endpoints - -| 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 `/logs//` 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 - -- SQLite schema migrations and auto-upgrade hooks at startup -- legacy JSON โ†’ SQLite migration compatibility path - -## Observability and Operational Signals - -Runtime visibility sources: - -- console logs from `src/sse/utils/logger.ts` -- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) -- textual request status log in `log.txt` (optional/compat) -- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` -- dashboard usage endpoints (`/api/usage/*`) for UI consumption - -## Security-Sensitive Boundaries - -- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing -- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning -- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format -- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level -- Cloud sync endpoints rely on API key auth + machine id semantics - -## Environment and Runtime Matrix - -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` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. -2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. -3. Request logger writes full headers/body when enabled; treat log directory as sensitive. -4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. -5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. -6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). -7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). -8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). - -## Operational Verification Checklist - -- Build from source: `npm run build` -- Build Docker image: `docker build -t omniroute .` -- Start service and verify: -- `GET /api/settings` -- `GET /api/v1/models` -- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/uk-UA/AUTO-COMBO.md b/docs/i18n/uk-UA/AUTO-COMBO.md deleted file mode 100644 index 2166e41dff..0000000000 --- a/docs/i18n/uk-UA/AUTO-COMBO.md +++ /dev/null @@ -1,67 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/AUTO-COMBO.md) - ---- - -# OmniRoute Auto-Combo Engine - -> Self-managing model chains with adaptive scoring - -## How It Works - -The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**: - -| Factor | Weight | Description | -| :--------- | :----- | :---------------------------------------------- | -| Quota | 0.20 | Remaining capacity [0..1] | -| Health | 0.25 | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 | -| CostInv | 0.20 | Inverse cost (cheaper = higher score) | -| LatencyInv | 0.15 | Inverse p95 latency (faster = higher) | -| TaskFit | 0.10 | Model ร— task type fitness score | -| Stability | 0.10 | Low variance in latency/errors | - -## Mode Packs - -| Pack | Focus | Key Weight | -| :---------------------- | :----------- | :--------------- | -| ๐Ÿš€ **Ship Fast** | Speed | latencyInv: 0.35 | -| ๐Ÿ’ฐ **Cost Saver** | Economy | costInv: 0.40 | -| ๐ŸŽฏ **Quality First** | Best model | taskFit: 0.40 | -| ๐Ÿ“ก **Offline Friendly** | Availability | quota: 0.40 | - -## Self-Healing - -- **Temporary exclusion**: Score < 0.2 โ†’ excluded for 5 min (progressive backoff, max 30 min) -- **Circuit breaker awareness**: OPEN โ†’ auto-excluded; HALF_OPEN โ†’ probe requests -- **Incident mode**: >50% OPEN โ†’ disable exploration, maximize stability -- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout - -## Bandit Exploration - -5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode. - -## API - -```bash -# Create auto-combo -curl -X POST http://localhost:20128/api/combos/auto \ - -H "Content-Type: application/json" \ - -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}' - -# List auto-combos -curl http://localhost:20128/api/combos/auto -``` - -## Task Fitness - -30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` โ†’ high coding score). - -## Files - -| File | Purpose | -| :------------------------------------------- | :------------------------------------ | -| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization | -| `open-sse/services/autoCombo/taskFitness.ts` | Model ร— task fitness lookup | -| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap | -| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode | -| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles | -| `src/app/api/combos/auto/route.ts` | REST API | diff --git a/docs/i18n/uk-UA/CHANGELOG.md b/docs/i18n/uk-UA/CHANGELOG.md index 2baf71ed98..4f582915b7 100644 --- a/docs/i18n/uk-UA/CHANGELOG.md +++ b/docs/i18n/uk-UA/CHANGELOG.md @@ -1,12 +1,92 @@ # Changelog (ะฃะบั€ะฐั—ะฝััŒะบะฐ) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CHANGELOG.md) --- - ## [Unreleased] +### ๐Ÿ› ๏ธ Maintenance + +- **AGENTS.md rewrite:** Condensed from 297โ†’153 lines. Added build/lint/test commands (including single-test execution), code style guidelines (Prettier, TypeScript, ESLint, naming, imports, error handling, security), and trimmed verbose architecture tables for AI agent consumption. + +## [3.4.2] - 2026-04-01 + +### ๐Ÿ› Bug Fixes + +- **CI Stabilization:** Fixed failing analytics/settings Playwright selectors and request assertions so GitHub Actions E2E runs pass reliably across localized UIs and switch-based controls. +- **Deterministic Tests:** Removed date-sensitive quota fixtures from Copilot usage tests and aligned idempotency/model catalog tests with the merged runtime behavior. +- **MCP Type Hardening:** Removed zero-budget explicit `any` regressions from the MCP server tool registration path, restoring the `check:any-budget:t11` workflow gate. + +### ๐Ÿ› ๏ธ Maintenance + +- **Release Branch Integration:** Consolidated the active feature branches into `release/v3.4.2` on top of current `main` and validated the branch with lint, unit, coverage, build, and CI-mode E2E runs. + +## [3.4.1] - 2026-03-31 + +> [!WARNING] +> **BREAKING CHANGE: request logging, retention, and logging environment variables have been redesigned.** +> On the first startup after upgrading, OmniRoute archives legacy request logs from `DATA_DIR/logs/`, legacy `DATA_DIR/call_logs/`, and `DATA_DIR/log.txt` into `DATA_DIR/log_archives/*.zip`, then removes the deprecated layout and switches to the new unified artifact format under `DATA_DIR/call_logs/`. + +### โœจ New Features + +- **.ENV Migration Utility:** Included `scripts/migrate-env.mjs` to seamlessly migrate ` Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` - ---- - -## Step 2 โ€” Install CLI Tools - -All npm-based tools require Node.js 18+: - -```bash -# Claude Code (Anthropic) -npm install -g @anthropic-ai/claude-code - -# OpenAI Codex -npm install -g @openai/codex - -# Gemini CLI (Google) -npm install -g @google/gemini-cli - -# OpenCode -npm install -g opencode-ai - -# Cline -npm install -g cline - -# KiloCode -npm install -g kilecode - -# Kiro CLI (Amazon โ€” requires curl + unzip) -apt-get install -y unzip # on Debian/Ubuntu -curl -fsSL https://cli.kiro.dev/install | bash -export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc -``` - -**Verify:** - -```bash -claude --version # 2.x.x -codex --version # 0.x.x -gemini --version # 0.x.x -opencode --version # x.x.x -cline --version # 2.x.x -kilocode --version # x.x.x (or: kilo --version) -kiro-cli --version # 1.x.x -``` - ---- - -## Step 3 โ€” Set Global Environment Variables - -Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`: - -```bash -# OmniRoute Universal Endpoint -export OPENAI_BASE_URL="http://localhost:20128/v1" -export OPENAI_API_KEY="sk-your-omniroute-key" -export ANTHROPIC_BASE_URL="http://localhost:20128/v1" -export ANTHROPIC_API_KEY="sk-your-omniroute-key" -export GEMINI_BASE_URL="http://localhost:20128/v1" -export GEMINI_API_KEY="sk-your-omniroute-key" -``` - -> For a **remote server** replace `localhost:20128` with the server IP or domain, -> e.g. `http://192.168.0.15:20128`. - ---- - -## Step 4 โ€” Configure Each Tool - -### Claude Code - -```bash -# Via CLI: -claude config set --global api-base-url http://localhost:20128/v1 - -# Or create ~/.claude/settings.json: -mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF -{ - "apiBaseUrl": "http://localhost:20128/v1", - "apiKey": "sk-your-omniroute-key" -} -EOF -``` - -**Test:** `claude "say hello"` - ---- - -### OpenAI Codex - -```bash -mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF -model: auto -apiKey: sk-your-omniroute-key -apiBaseUrl: http://localhost:20128/v1 -EOF -``` - -**Test:** `codex "what is 2+2?"` - ---- - -### Gemini CLI - -```bash -mkdir -p ~/.gemini && cat > ~/.gemini/settings.json << EOF -{ - "apiKey": "sk-your-omniroute-key", - "baseUrl": "http://localhost:20128/v1" -} -EOF -``` - -**Test:** `gemini "hello"` - ---- - -### OpenCode - -```bash -mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF -[provider.openai] -base_url = "http://localhost:20128/v1" -api_key = "sk-your-omniroute-key" -EOF -``` - -**Test:** `opencode` - ---- - -### Cline (CLI or VS Code) - -**CLI mode:** - -```bash -mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF -{ - "apiProvider": "openai", - "openAiBaseUrl": "http://localhost:20128/v1", - "openAiApiKey": "sk-your-omniroute-key" -} -EOF -``` - -**VS Code mode:** -Cline extension settings โ†’ API Provider: `OpenAI Compatible` โ†’ Base URL: `http://localhost:20128/v1` - -Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ Cline โ†’ Apply Config**. - ---- - -### KiloCode (CLI or VS Code) - -**CLI mode:** - -```bash -kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key -``` - -**VS Code settings:** - -```json -{ - "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", - "kilo-code.apiKey": "sk-your-omniroute-key" -} -``` - -Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ KiloCode โ†’ Apply Config**. - ---- - -### Continue (VS Code Extension) - -Edit `~/.continue/config.yaml`: - -```yaml -models: - - name: OmniRoute - provider: openai - model: auto - apiBase: http://localhost:20128/v1 - apiKey: sk-your-omniroute-key - default: true -``` - -Restart VS Code after editing. - ---- - -### Kiro CLI (Amazon) - -```bash -# Login to your AWS/Kiro account: -kiro-cli login - -# The CLI uses its own auth โ€” OmniRoute is not needed as backend for Kiro CLI itself. -# Use kiro-cli alongside OmniRoute for other tools. -kiro-cli status -``` - ---- - -### Cursor (Desktop App) - -> **Note:** Cursor routes requests through its cloud. For OmniRoute integration, -> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL. - -Via GUI: **Settings โ†’ Models โ†’ OpenAI API Key** - -- Base URL: `https://your-domain.com/v1` -- API Key: your OmniRoute key - ---- - -## Dashboard Auto-Configuration - -The OmniRoute dashboard automates configuration for most tools: - -1. Go to `http://localhost:20128/dashboard/cli-tools` -2. Expand any tool card -3. Select your API key from the dropdown -4. Click **Apply Config** (if tool is detected as installed) -5. Or copy the generated config snippet manually - ---- - -## Built-in Agents: Droid & OpenClaw - -**Droid** and **OpenClaw** are AI agents built directly into OmniRoute โ€” no installation needed. -They run as internal routes and use OmniRoute's model routing automatically. - -- Access: `http://localhost:20128/dashboard/agents` -- Configure: same combos and providers as all other tools -- No API key or CLI install required - ---- - -## Available API Endpoints - -| Endpoint | Description | Use For | -| -------------------------- | ----------------------------- | --------------------------- | -| `/v1/chat/completions` | Standard chat (all providers) | All modern tools | -| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows | -| `/v1/completions` | Legacy text completions | Older tools using `prompt:` | -| `/v1/embeddings` | Text embeddings | RAG, search | -| `/v1/images/generations` | Image generation | DALL-E, Flux, etc. | -| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS | -| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI | - ---- - -## Troubleshooting - -| Error | Cause | Fix | -| ------------------------- | ----------------------- | ------------------------------------------ | -| `Connection refused` | OmniRoute not running | `pm2 start omniroute` | -| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` | -| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` | -| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` | -| CLI shows "not installed" | Binary not in PATH | Check `which ` | -| `kiro-cli: not found` | Not in PATH | `export PATH="$HOME/.local/bin:$PATH"` | - ---- - -## Quick Setup Script (One Command) - -```bash -# Install all CLIs and configure for OmniRoute (replace with your key and server URL) -OMNIROUTE_URL="http://localhost:20128/v1" -OMNIROUTE_KEY="sk-your-omniroute-key" - -npm install -g @anthropic-ai/claude-code @openai/codex @google/gemini-cli opencode-ai cline kilecode - -# Kiro CLI -apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash - -# Write configs -mkdir -p ~/.claude ~/.codex ~/.gemini ~/.config/opencode ~/.continue - -cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" -cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" -cat > ~/.gemini/settings.json <<< "{\"apiKey\":\"$OMNIROUTE_KEY\",\"baseUrl\":\"$OMNIROUTE_URL\"}" -cat >> ~/.bashrc << EOF -export OPENAI_BASE_URL="$OMNIROUTE_URL" -export OPENAI_API_KEY="$OMNIROUTE_KEY" -export ANTHROPIC_BASE_URL="$OMNIROUTE_URL" -export ANTHROPIC_API_KEY="$OMNIROUTE_KEY" -EOF - -source ~/.bashrc -echo "โœ… All CLIs installed and configured for OmniRoute" -``` diff --git a/docs/i18n/uk-UA/CODEBASE_DOCUMENTATION.md b/docs/i18n/uk-UA/CODEBASE_DOCUMENTATION.md deleted file mode 100644 index e2d7950052..0000000000 --- a/docs/i18n/uk-UA/CODEBASE_DOCUMENTATION.md +++ /dev/null @@ -1,593 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CODEBASE_DOCUMENTATION.md) - ---- - -# omniroute โ€” Codebase Documentation - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) - -> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. - ---- - -## 1. 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
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, Qoder, 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 | -| Qoder | 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"] -``` diff --git a/docs/i18n/uk-UA/CONTRIBUTING.md b/docs/i18n/uk-UA/CONTRIBUTING.md new file mode 100644 index 0000000000..36a04ceae5 --- /dev/null +++ b/docs/i18n/uk-UA/CONTRIBUTING.md @@ -0,0 +1,299 @@ +# Contributing to OmniRoute (ะฃะบั€ะฐั—ะฝััŒะบะฐ) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CONTRIBUTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CONTRIBUTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CONTRIBUTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CONTRIBUTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CONTRIBUTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CONTRIBUTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CONTRIBUTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CONTRIBUTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CONTRIBUTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CONTRIBUTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CONTRIBUTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CONTRIBUTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CONTRIBUTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CONTRIBUTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CONTRIBUTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CONTRIBUTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CONTRIBUTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CONTRIBUTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CONTRIBUTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CONTRIBUTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CONTRIBUTING.md) + +--- + +Thank you for your interest in contributing! This guide covers everything you need to get started. + +--- + +## Development Setup + +### Prerequisites + +- **Node.js** >= 18 < 24 (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` | `20128` | Server port | +| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | Base URL for frontend | +| `JWT_SECRET` | (generate above) | JWT signing secret | +| `INITIAL_PASSWORD` | `CHANGEME` | First login password | +| `APP_LOG_LEVEL` | `info` | Log verbosity level | + +### Dashboard Settings + +The dashboard provides UI toggles for features that can also be configured via environment variables: + +| Setting Location | Toggle | Description | +| ------------------- | ------------------ | ------------------------------ | +| Settings โ†’ Advanced | Debug Mode | Enable debug request logs (UI) | +| Settings โ†’ General | Sidebar Visibility | Show/hide sidebar sections | + +These settings are stored in the database and persist across restarts, overriding env var defaults when set. + +### 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:20128/dashboard` +- **API**: `http://localhost:20128/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`, `mcp`, `a2a`, `memory`, `skills`. + +--- + +## Running Tests + +```bash +# All tests (unit + vitest + ecosystem + e2e) +npm run test:all + +# Single test file (Node.js native test runner โ€” most tests use this) +node --import tsx/esm --test tests/unit/your-file.test.mjs + +# Vitest (MCP server, autoCombo, cache) +npm run test:vitest + +# E2E tests (requires Playwright) +npm run test:e2e + +# Protocol clients E2E (MCP transports, A2A) +npm run test:protocols:e2e + +# Ecosystem compatibility tests +npm run test:ecosystem + +# Coverage (55% min statements/lines/functions; 60% branches) +npm run test:coverage +npm run coverage:report + +# Lint + format check +npm run lint +npm run check +``` + +Coverage notes: + +- `npm run test:coverage` measures source coverage for the main unit test suite, excludes `tests/**`, and includes `open-sse/**` +- `npm run coverage:report` prints the detailed file-by-file report from the latest coverage run +- `npm run test:coverage:legacy` preserves the older metric for historical comparison +- See `docs/COVERAGE_PLAN.md` for the phased coverage improvement roadmap + +Current test status: **122 unit test files** covering: + +- Provider translators and format conversion +- Rate limiting, circuit breaker, and resilience +- Semantic cache, idempotency, progress tracking +- Database operations and schema (21 DB modules) +- OAuth flows and authentication +- API endpoint validation (Zod v4) +- MCP server tools and scope enforcement +- Memory and Skills systems + +--- + +## Code Style + +- **ESLint** โ€” Run `npm run lint` before committing +- **Prettier** โ€” Auto-formatted via `lint-staged` on commit (2 spaces, semicolons, double quotes, 100 char width, es5 trailing commas) +- **TypeScript** โ€” All `src/` code uses `.ts`/`.tsx`; `open-sse/` uses `.ts`/`.js`; document with TSDoc (`@param`, `@returns`, `@throws`) +- **No `eval()`** โ€” ESLint enforces `no-eval`, `no-implied-eval`, `no-new-func` +- **Zod validation** โ€” Use Zod v4 schemas for all API input validation +- **Naming**: Files = camelCase/kebab-case, components = PascalCase, constants = UPPER_SNAKE + +--- + +## Project Structure + +``` +src/ # TypeScript (.ts / .tsx) +โ”œโ”€โ”€ app/ # Next.js 16 App Router +โ”‚ โ”œโ”€โ”€ (dashboard)/ # Dashboard pages (23 sections) +โ”‚ โ”œโ”€โ”€ api/ # API routes (51 directories) +โ”‚ โ””โ”€โ”€ login/ # Auth pages (.tsx) +โ”œโ”€โ”€ domain/ # Policy engine (policyEngine, comboResolver, costRules, etc.) +โ”œโ”€โ”€ lib/ # Core business logic (.ts) +โ”‚ โ”œโ”€โ”€ a2a/ # Agent-to-Agent v0.3 protocol server +โ”‚ โ”œโ”€โ”€ acp/ # Agent Communication Protocol registry +โ”‚ โ”œโ”€โ”€ compliance/ # Compliance policy engine +โ”‚ โ”œโ”€โ”€ db/ # SQLite database layer (21 modules + 16 migrations) +โ”‚ โ”œโ”€โ”€ memory/ # Persistent conversational memory +โ”‚ โ”œโ”€โ”€ oauth/ # OAuth providers, services, and utilities +โ”‚ โ”œโ”€โ”€ skills/ # Extensible skill framework +โ”‚ โ”œโ”€โ”€ usage/ # Usage tracking and cost calculation +โ”‚ โ””โ”€โ”€ localDb.ts # Re-export layer only โ€” never add logic here +โ”œโ”€โ”€ middleware/ # Request middleware (promptInjectionGuard) +โ”œโ”€โ”€ mitm/ # MITM proxy (cert, DNS, target routing) +โ”œโ”€โ”€ shared/ +โ”‚ โ”œโ”€โ”€ components/ # React components (.tsx) +โ”‚ โ”œโ”€โ”€ constants/ # Provider definitions (60+), MCP scopes, routing strategies +โ”‚ โ”œโ”€โ”€ utils/ # Circuit breaker, sanitizer, auth helpers +โ”‚ โ””โ”€โ”€ validation/ # Zod v4 schemas +โ””โ”€โ”€ sse/ # SSE proxy pipeline + +open-sse/ # @omniroute/open-sse workspace +โ”œโ”€โ”€ executors/ # 14 provider-specific request executors +โ”œโ”€โ”€ handlers/ # 11 request handlers (chat, responses, embeddings, images, etc.) +โ”œโ”€โ”€ mcp-server/ # MCP server (25 tools, 3 transports, 10 scopes) +โ”œโ”€โ”€ services/ # 36+ services (combo, autoCombo, rateLimitManager, etc.) +โ”œโ”€โ”€ translator/ # Format translators (OpenAI โ†” Claude โ†” Gemini โ†” Responses โ†” Ollama) +โ”œโ”€โ”€ transformer/ # Responses API transformer +โ””โ”€โ”€ utils/ # 22 utility modules (stream, TLS, proxy, logging) + +electron/ # Electron desktop app (cross-platform) + +tests/ +โ”œโ”€โ”€ unit/ # Node.js test runner (122 test files) +โ”œโ”€โ”€ integration/ # Integration tests +โ”œโ”€โ”€ e2e/ # Playwright tests +โ”œโ”€โ”€ security/ # Security tests +โ”œโ”€โ”€ translator/ # Translator-specific tests +โ””โ”€โ”€ load/ # Load tests + +docs/ # Documentation +โ”œโ”€โ”€ ARCHITECTURE.md # System architecture +โ”œโ”€โ”€ API_REFERENCE.md # All endpoints +โ”œโ”€โ”€ USER_GUIDE.md # Provider setup, CLI integration +โ”œโ”€โ”€ TROUBLESHOOTING.md # Common issues +โ”œโ”€โ”€ MCP-SERVER.md # MCP server (25 tools) +โ”œโ”€โ”€ A2A-SERVER.md # A2A agent protocol +โ”œโ”€โ”€ AUTO-COMBO.md # Auto-combo engine +โ”œโ”€โ”€ CLI-TOOLS.md # CLI tools integration +โ”œโ”€โ”€ COVERAGE_PLAN.md # Test coverage improvement plan +โ”œโ”€โ”€ openapi.yaml # OpenAPI specification +โ””โ”€โ”€ adr/ # Architecture Decision Records +``` + +--- + +## Adding a New Provider + +### Step 1: Register Provider Constants + +Add to `src/shared/constants/providers.ts` โ€” Zod-validated at module load. + +### Step 2: Add Executor (if custom logic needed) + +Create executor in `open-sse/executors/your-provider.ts` extending the base executor. + +### Step 3: Add Translator (if non-OpenAI format) + +Create request/response translators in `open-sse/translator/`. + +### Step 4: Add OAuth Config (if OAuth-based) + +Add OAuth credentials in `src/lib/oauth/constants/oauth.ts` and service in `src/lib/oauth/services/`. + +### Step 5: Register Models + +Add model definitions in `open-sse/config/providerRegistry.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 +- [ ] All inputs validated with Zod schemas +- [ ] CHANGELOG updated (if user-facing change) +- [ ] Documentation updated (if applicable) + +--- + +## Releasing + +Releases are managed via the `/generate-release` workflow. When a new GitHub Release is created, the package is **automatically published to npm** via GitHub Actions. + +--- + +## Getting Help + +- **Architecture**: See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) +- **API Reference**: See [`docs/API_REFERENCE.md`](docs/API_REFERENCE.md) +- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **ADRs**: See `docs/adr/` for architectural decision records diff --git a/docs/i18n/uk-UA/FEATURES.md b/docs/i18n/uk-UA/FEATURES.md deleted file mode 100644 index 319cd5ecf6..0000000000 --- a/docs/i18n/uk-UA/FEATURES.md +++ /dev/null @@ -1,147 +0,0 @@ -# OmniRoute โ€” Dashboard Features Gallery (ะฃะบั€ะฐั—ะฝััŒะบะฐ) - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) - -> ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../docs/FEATURES.md) - ---- - -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 (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. - -![Providers Dashboard](screenshots/01-providers.png) - ---- - -## ๐ŸŽจ Combos - -Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. - -![Combos Dashboard](screenshots/02-combos.png) - ---- - -## ๐Ÿ“Š Analytics - -Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. - -![Analytics Dashboard](screenshots/03-analytics.png) - ---- - -## ๐Ÿฅ System Health - -Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. - -![Health Dashboard](screenshots/04-health.png) - ---- - -## ๐Ÿ”ง Translator Playground - -Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). - -![Translator Playground](screenshots/05-translator.png) - ---- - -## ๐ŸŽฎ Model Playground _(v2.0.9+)_ - -Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. - ---- - -## ๐ŸŽจ Themes _(v2.0.5+)_ - -Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. - ---- - -## โš™๏ธ Settings - -Comprehensive settings panel with tabs: - -- **General** โ€” System storage, backup management (export/import database) -- **Appearance** โ€” Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls -- **Security** โ€” API endpoint protection, custom provider blocking, IP filtering, session info -- **Routing** โ€” Model aliases, background task degradation -- **Resilience** โ€” Rate limit persistence, circuit breaker tuning -- **Advanced** โ€” Configuration overrides - -![Settings Dashboard](screenshots/06-settings.png) - ---- - -## ๐Ÿ”ง CLI Tools - -One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. - -![CLI Tools Dashboard](screenshots/07-cli-tools.png) - ---- - -## ๐Ÿค– CLI Agents _(v2.0.11+)_ - -Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: - -- **Installation status** โ€” Installed / Not Found with version detection -- **Protocol badges** โ€” stdio, HTTP, etc. -- **Custom agents** โ€” Register any CLI tool via form (name, binary, version command, spawn args) -- **CLI Fingerprint Matching** โ€” Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP - ---- - -## ๐Ÿ–ผ๏ธ Media _(v2.0.3+)_ - -Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. - ---- - -## ๐Ÿ“ Request Logs - -Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. - -![Usage Logs](screenshots/08-usage.png) - ---- - -## ๐ŸŒ API Endpoint - -Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. - -![Endpoint Dashboard](screenshots/09-endpoint.png) - ---- - -## ๐Ÿ”‘ API Key Management - -Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. - ---- - -## ๐Ÿ“‹ Audit Log - -Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. - ---- - -## ๐Ÿ–ฅ๏ธ Desktop Application - -Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. - -Key features: - -- Server readiness polling (no blank screen on cold start) -- System tray with port management -- Content Security Policy -- Single-instance lock -- Auto-update on restart -- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) -- Hardened Electron build packaging โ€” symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+) - -๐Ÿ“– See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/uk-UA/MCP-SERVER.md b/docs/i18n/uk-UA/MCP-SERVER.md deleted file mode 100644 index 829acd30b1..0000000000 --- a/docs/i18n/uk-UA/MCP-SERVER.md +++ /dev/null @@ -1,87 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/MCP-SERVER.md) - ---- - -# OmniRoute MCP Server Documentation - -> Model Context Protocol server with 16 intelligent tools - -## Installation - -OmniRoute MCP is built-in. Start it with: - -```bash -omniroute --mcp -``` - -Or via the open-sse transport: - -```bash -# HTTP streamable transport (port 20130) -omniroute --dev # MCP auto-starts on /mcp endpoint -``` - -## IDE Configuration - -See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup. - ---- - -## Essential Tools (8) - -| Tool | Description | -| :------------------------------ | :--------------------------------------- | -| `omniroute_get_health` | Gateway health, circuit breakers, uptime | -| `omniroute_list_combos` | All configured combos with models | -| `omniroute_get_combo_metrics` | Performance metrics for a specific combo | -| `omniroute_switch_combo` | Switch active combo by ID/name | -| `omniroute_check_quota` | Quota status per provider or all | -| `omniroute_route_request` | Send a chat completion through OmniRoute | -| `omniroute_cost_report` | Cost analytics for a time period | -| `omniroute_list_models_catalog` | Full model catalog with capabilities | - -## Advanced Tools (8) - -| Tool | Description | -| :--------------------------------- | :---------------------------------------------- | -| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | -| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | -| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | -| `omniroute_test_combo` | Live-test all models in a combo | -| `omniroute_get_provider_metrics` | Detailed metrics for one provider | -| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | -| `omniroute_explain_route` | Explain a past routing decision | -| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | - -## Authentication - -MCP tools are authenticated via API key scopes. Each tool requires specific scopes: - -| Scope | Tools | -| :------------- | :----------------------------------------------- | -| `read:health` | get_health, get_provider_metrics | -| `read:combos` | list_combos, get_combo_metrics | -| `write:combos` | switch_combo | -| `read:quota` | check_quota | -| `write:route` | route_request, simulate_route, test_combo | -| `read:usage` | cost_report, get_session_snapshot, explain_route | -| `write:config` | set_budget_guard, set_resilience_profile | -| `read:models` | list_models_catalog, best_combo_for_task | - -## Audit Logging - -Every tool call is logged to `mcp_tool_audit` with: - -- Tool name, arguments, result -- Duration (ms), success/failure -- API key hash, timestamp - -## Files - -| File | Purpose | -| :------------------------------------------- | :------------------------------------------ | -| `open-sse/mcp-server/server.ts` | MCP server creation + 16 tool registrations | -| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport | -| `open-sse/mcp-server/auth.ts` | API key + scope validation | -| `open-sse/mcp-server/audit.ts` | Tool call audit logging | -| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers | diff --git a/docs/i18n/uk-UA/README.md b/docs/i18n/uk-UA/README.md index 2cc7cdeb4f..911331ddb0 100644 --- a/docs/i18n/uk-UA/README.md +++ b/docs/i18n/uk-UA/README.md @@ -1,12 +1,12 @@ # ๐Ÿš€ OmniRoute โ€” The Free AI Gateway (ะฃะบั€ะฐั—ะฝััŒะบะฐ) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/README.md) --- ### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback. -_Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._ +_Your universal API proxy โ€” one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._ **Chat Completions โ€ข Embeddings โ€ข Image Generation โ€ข Video โ€ข Music โ€ข Audio โ€ข Reranking โ€ข **Web Search** โ€ข MCP Server โ€ข A2A Protocol โ€ข 100% TypeScript** @@ -46,15 +46,17 @@ _Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now wi > - `APP_LOG_FILE_PATH` > - `APP_LOG_MAX_FILE_SIZE` > - `APP_LOG_RETENTION_DAYS` +> - `APP_LOG_MAX_FILES` > - `APP_LOG_LEVEL` > - `APP_LOG_FORMAT` > - `CALL_LOG_RETENTION_DAYS` +> - `CALL_LOG_MAX_ENTRIES` > > For release details and upgrade notes, see the [CHANGELOG](CHANGELOG.md). --- -## ๐Ÿ†• What's New in v3.0.0 +## ๐Ÿ†• What's New > **Upgrading from v2.9.5?** โ€” See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes. @@ -274,7 +276,7 @@ Developers pay $20โ€“200/month for Claude Pro, Codex Pro, or GitHub Copilot. Eve - **Smart 4-Tier Fallback** โ€” If subscription quota runs out, automatically redirects to API Key โ†’ Cheap โ†’ Free with zero manual intervention - **Real-Time Quota Tracking** โ€” Shows token consumption in real-time with reset countdown (5h, daily, weekly) - **Multi-Account Support** โ€” Multiple accounts per provider with auto round-robin โ€” when one runs out, switches to the next -- **Custom Combos** โ€” Customizable fallback chains with 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Custom Combos** โ€” Customizable fallback chains with 9 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random) - **Codex Business Quotas** โ€” Business/Team workspace quota monitoring directly in the dashboard @@ -286,7 +288,7 @@ OpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If **How OmniRoute solves it:** -- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 67+ providers +- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 60+ providers - **Format Translation** โ€” Automatic and transparent: OpenAI โ†” Claude โ†” Gemini โ†” Responses API - **Response Sanitization** โ€” Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+ - **Role Normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI providers; `system` โ†’ `user` for GLM/ERNIE @@ -372,7 +374,7 @@ Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code.. - **CLI Tools Dashboard** โ€” Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline - **GitHub Copilot Config Generator** โ€” Generates `chatLanguageModels.json` for VS Code with bulk model selection - **Onboarding Wizard** โ€” Guided 4-step setup for first-time users -- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 67+ providers +- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 60+ providers @@ -419,7 +421,7 @@ When a call fails, the dev doesn't know if it was a rate limit, expired token, w - **SQLite Proxy Logs** โ€” Persistent logs that survive server restarts - **Translator Playground** โ€” 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time) - **Request Telemetry** โ€” p50/p95/p99 latency + X-Request-Id tracing -- **File-Based Logging with Rotation** โ€” Console interceptor captures everything to JSON log with size-based rotation +- **File-Based Logging with Rotation** โ€” App logs rotate by size, retention days, and archive count; call log artifacts rotate by retention days and file count - **System Info Report** โ€” `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage. @@ -514,7 +516,7 @@ Developers who want all responses in a specific language, with a specific tone, - **System Prompt Injection** โ€” Global prompt applied to all requests - **Thinking Budget Validation** โ€” Reasoning token allocation control per request (passthrough, auto, custom, adaptive) -- **6 Routing Strategies** โ€” Global strategies that determine how requests are distributed +- **9 Routing Strategies** โ€” Global strategies that determine how requests are distributed - **Wildcard Router** โ€” `provider/*` patterns route dynamically to any provider - **Combo Enable/Disable Toggle** โ€” Toggle combos directly from the dashboard - **Provider Toggle** โ€” Enable/disable all connections for a provider with one click @@ -581,7 +583,7 @@ Different clients should have least-privilege access to tool categories. **How OmniRoute solves it:** -- 9 granular MCP scopes for controlled tool access +- 10 granular MCP scopes for controlled tool access - Scope enforcement and visibility in MCP management UI - Safe default posture for operational tooling @@ -1325,19 +1327,19 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. ### ๐Ÿค– Agent & Protocol Operations (v2.0) -| Feature | What It Does | -| ------------------------------------- | -------------------------------------------------------------------------------------------------- | -| ๐Ÿ”ง **MCP Server (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) | -| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | -| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | -| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | -| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | -| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | -| ๐Ÿ” **MCP Scope Enforcement** | 9 granular scope permissions for controlled tool access | -| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | -| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | -| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | -| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | +| Feature | What It Does | +| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| ๐Ÿ”ง **MCP Server (25 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools | +| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | +| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | +| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | +| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | +| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | +| ๐Ÿ” **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access | +| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | +| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | +| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | +| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | ### ๐Ÿง  Routing & Intelligence @@ -1348,7 +1350,7 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. | ๐Ÿ”„ **Format Translation** | OpenAI โ†” Claude โ†” Gemini โ†” Responses with schema-safe conversions | | ๐Ÿ‘ฅ **Multi-Account Support** | Multiple accounts per provider with intelligent selection | | ๐Ÿ”„ **Auto Token Refresh** | OAuth tokens refresh automatically with retry | -| ๐ŸŽจ **Custom Combos** | 6 balancing strategies + fallback chain control | +| ๐ŸŽจ **Custom Combos** | 9 balancing strategies + fallback chain control | | ๐ŸŒ **Wildcard Router** | `provider/*` dynamic routing | | ๐Ÿง  **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits | | ๐Ÿ”€ **Model Aliases** | Built-in + custom model aliasing and migration safety | @@ -1949,6 +1951,7 @@ opencode - Request artifacts are written to `DATA_DIR/call_logs/` as one JSON file per request - Enable pipeline capture from Dashboard โ†’ Logs โ†’ Request Logs if you need detailed per-stage payloads - Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log` +- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed **Connection test shows "Invalid" for OpenAI-compatible providers** diff --git a/docs/i18n/uk-UA/RELEASE_CHECKLIST.md b/docs/i18n/uk-UA/RELEASE_CHECKLIST.md deleted file mode 100644 index 903e812c3f..0000000000 --- a/docs/i18n/uk-UA/RELEASE_CHECKLIST.md +++ /dev/null @@ -1,37 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/RELEASE_CHECKLIST.md) - ---- - -# Release Checklist - -Use this checklist before tagging or publishing a new OmniRoute release. - -## Version and Changelog - -1. Bump `package.json` version (`x.y.z`) in the release branch. -2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: - - `## [x.y.z] โ€” YYYY-MM-DD` -3. Keep `## [Unreleased]` as the first changelog section for upcoming work. -4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. - -## API Docs - -1. Update `docs/openapi.yaml`: - - `info.version` must equal `package.json` version. -2. Validate endpoint examples if API contracts changed. - -## Runtime Docs - -1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. -2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. -3. Update localized docs if source docs changed significantly. - -## Automated Check - -Run the sync guard locally before opening PR: - -```bash -npm run check:docs-sync -``` - -CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/uk-UA/SECURITY.md b/docs/i18n/uk-UA/SECURITY.md new file mode 100644 index 0000000000..6bf6c59801 --- /dev/null +++ b/docs/i18n/uk-UA/SECURITY.md @@ -0,0 +1,179 @@ +# Security Policy (ะฃะบั€ะฐั—ะฝััŒะบะฐ) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../SECURITY.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/SECURITY.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/SECURITY.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/SECURITY.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/SECURITY.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/SECURITY.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/SECURITY.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/SECURITY.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/SECURITY.md) + +--- + +## 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 | +| ------- | -------------- | +| 3.4.x | โœ… Active | +| 3.0.x | โœ… Security | +| < 3.0.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 | +| **MCP Scopes** | 10 granular scopes for MCP tool access control | + +### ๐Ÿ›ก๏ธ 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:::` +- 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** | Allowlist/blocklist IP ranges in dashboard | +| **Rate Limiting** | Per-provider rate limits with automatic backoff | +| **Anti-Thundering Herd** | Mutex + per-connection locking prevents cascading 502s | +| **TLS Fingerprint** | Browser-like TLS fingerprint spoofing to reduce bot detection | +| **CLI Fingerprint** | Per-provider header/body ordering to match native CLI signatures | + +### ๐Ÿ”Œ Resilience & Availability + +| 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 `CALL_LOG_RETENTION_DAYS` | +| **No-Log Opt-out** | Per API key `noLog` flag disables request logging | +| **Audit Log** | Administrative actions tracked in `audit_log` table | +| **MCP Audit** | SQLite-backed audit logging for all MCP tool calls | +| **Zod Validation** | All API inputs validated with Zod v4 schemas at module load | + +--- + +## 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 +- Provider constants validated at module load via Zod (`src/shared/validation/providerSchema.ts`) diff --git a/docs/i18n/uk-UA/TROUBLESHOOTING.md b/docs/i18n/uk-UA/TROUBLESHOOTING.md deleted file mode 100644 index 63c148000a..0000000000 --- a/docs/i18n/uk-UA/TROUBLESHOOTING.md +++ /dev/null @@ -1,258 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/TROUBLESHOOTING.md) - ---- - -# Troubleshooting - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/TROUBLESHOOTING.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/TROUBLESHOOTING.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/TROUBLESHOOTING.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/TROUBLESHOOTING.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/TROUBLESHOOTING.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/TROUBLESHOOTING.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/TROUBLESHOOTING.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/TROUBLESHOOTING.md) - -Common problems and solutions for OmniRoute. - ---- - -## Quick Fixes - -| Problem | Solution | -| ----------------------------- | ------------------------------------------------------------------ | -| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | -| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | -| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | -| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | -| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | - ---- - -## Provider Issues - -### "Language model did not provide messages" - -**Cause:** Provider quota exhausted. - -**Fix:** - -1. 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, Qoder) 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}/storage.sqlite` (providers, combos, aliases, keys, settings) -- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` -- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) - ---- - -## Circuit Breaker Issues - -### Provider stuck in OPEN state - -When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. - -**Fix:** - -1. 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 -- **SDK returns raw string instead of object** โ€” Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures -- **GLM/ERNIE rejects `system` role** โ€” Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models -- **`developer` role not recognized** โ€” Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers -- **`json_schema` not working with Gemini** โ€” Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` - ---- - -## Resilience Settings - -### Auto rate-limit not triggering - -- 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. - ---- - -## Optional RAG / LLM failure taxonomy (16 problems) - -Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. - -In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. - -If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: - -- retrieval drift and broken context boundaries -- empty or stale indexes and vector stores -- embedding versus semantic mismatch -- prompt assembly and context window issues -- logic collapse and overconfident answers -- long chain and agent coordination failures -- multi agent memory and role drift -- deployment and bootstrap ordering problems - -The idea is simple: - -1. When you investigate a bad response, capture: - - user task and request - - route or provider combo in OmniRoute - - any RAG context used downstream (retrieved documents, tool calls, etc) -2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` โ€ฆ `No.16`). -3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. -4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. - -Full text and concrete recipes live here (MIT license, text only): - -[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) - -You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. - ---- - -## Still Stuck? - -- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details -- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints -- **Health Dashboard**: Check **Dashboard โ†’ Health** for real-time system status -- **Translator**: Use **Dashboard โ†’ Translator** to debug format issues diff --git a/docs/i18n/uk-UA/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/uk-UA/VM_DEPLOYMENT_GUIDE.md deleted file mode 100644 index fe3848fcff..0000000000 --- a/docs/i18n/uk-UA/VM_DEPLOYMENT_GUIDE.md +++ /dev/null @@ -1,401 +0,0 @@ -# OmniRoute โ€” ะฟะพัั–ะฑะฝะธะบ ั–ะท ั€ะพะทะณะพั€ั‚ะฐะฝะฝั ะฝะฐ ะฒั–ั€ั‚ัƒะฐะปัŒะฝั–ะน ะผะฐัˆะธะฝั– ะท Cloudflare - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](../pt-BR/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](../es/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](../fr/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](../it/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](../ru/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](../zh-CN/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](../de/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](../in/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](../th/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](../uk-UA/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](../ar/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](../ja/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](../vi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](../bg/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](../da/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](../fi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](../he/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](../hu/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](../id/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](../ko/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](../ms/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](../nl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](../no/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](../pt/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](../ro/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](../pl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](../sk/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](../sv/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](../phi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](../cs/VM_DEPLOYMENT_GUIDE.md) - -ะŸะพะฒะฝะธะน ะฟะพัั–ะฑะฝะธะบ ั–ะท ะฒัั‚ะฐะฝะพะฒะปะตะฝะฝั ั‚ะฐ ะฝะฐะปะฐัˆั‚ัƒะฒะฐะฝะฝั OmniRoute ะฝะฐ ะฒั–ั€ั‚ัƒะฐะปัŒะฝั–ะน ะผะฐัˆะธะฝั– (VPS) ั–ะท ะดะพะผะตะฝะพะผ, ะบะตั€ะพะฒะฐะฝะธะผ ั‡ะตั€ะตะท Cloudflare. - ---- - -## ะŸะตั€ะตะดัƒะผะพะฒะธ - -| ะŸัƒะฝะบั‚ | ะœั–ะฝั–ะผัƒะผ | ะ ะตะบะพะผะตะฝะดะพะฒะฐะฝะพ | -| --------- | --------------------------- | ---------------- | -| **ะฆะŸ** | 1 vCPU | 2 vCPU | -| **RAM** | 1 ะ“ะฑ | 2 ะ“ะ‘ | -| **ะ”ะธัะบ** | 10 ะ“ะ‘ SSD | 25 ะ“ะ‘ SSD | -| **ะžะก** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS | -| **ะ”ะพะผะตะฝ** | ะ—ะฐั€ะตั”ัั‚ั€ะพะฒะฐะฝะพ ะฝะฐ Cloudflare | โ€” | -| **ะ”ะพะบะตั€** | Docker Engine 24+ | ะ”ะพะบะตั€ 27+ | - -**ะŸะตั€ะตะฒั–ั€ะตะฝั– ะฟะพัั‚ะฐั‡ะฐะปัŒะฝะธะบะธ**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. - ---- - -## 1. ะะฐะปะฐัˆั‚ัƒะนั‚ะต ะฒั–ั€ั‚ัƒะฐะปัŒะฝัƒ ะผะฐัˆะธะฝัƒ - -### 1.1 ะกั‚ะฒะพั€ั–ั‚ัŒ ะตะบะทะตะผะฟะปัั€ - -ะฃ ะฑะฐะถะฐะฝะพะณะพ ะฟะพัั‚ะฐั‡ะฐะปัŒะฝะธะบะฐ VPS: - -- ะ’ะธะฑะตั€ั–ั‚ัŒ Ubuntu 24.04 LTS -- ะ’ะธะฑะตั€ั–ั‚ัŒ ะผั–ะฝั–ะผะฐะปัŒะฝะธะน ะฟะปะฐะฝ (1 vCPU / 1 GB RAM) -- ะ’ัั‚ะฐะฝะพะฒั–ั‚ัŒ ะฝะฐะดั–ะนะฝะธะน ะฟะฐั€ะพะปัŒ root ะฐะฑะพ ะฝะฐะปะฐัˆั‚ัƒะนั‚ะต ะบะปัŽั‡ SSH -- ะ—ะฒะตั€ะฝั–ั‚ัŒ ัƒะฒะฐะณัƒ ะฝะฐ **ะฟัƒะฑะปั–ั‡ะฝัƒ IP** (ะฝะฐะฟั€ะธะบะปะฐะด, `203.0.113.10`) - -### 1.2 ะŸั–ะดะบะปัŽั‡ั–ั‚ัŒัั ั‡ะตั€ะตะท SSH - -```bash -ssh root@203.0.113.10 -``` - -### 1.3 ะžะฝะพะฒั–ั‚ัŒ ัะธัั‚ะตะผัƒ - -```bash -apt update && apt upgrade -y -``` - -### 1.4 ะ’ัั‚ะฐะฝะพะฒั–ั‚ัŒ Docker - -```bash -# Install dependencies -apt install -y ca-certificates curl gnupg - -# Add official Docker repository -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 ะ’ัั‚ะฐะฝะพะฒั–ั‚ัŒ nginx - -```bash -apt install -y nginx -``` - -### 1.6 ะะฐะปะฐัˆั‚ัƒะฒะฐั‚ะธ ะฑั€ะฐะฝะดะผะฐัƒะตั€ (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 -``` - -> **ะŸะพั€ะฐะดะฐ**: ะดะปั ะผะฐะบัะธะผะฐะปัŒะฝะพั— ะฑะตะทะฟะตะบะธ ะพะฑะผะตะถั‚ะต ะฟะพั€ั‚ะธ 80 ั– 443 ะปะธัˆะต IP-ะฐะดั€ะตัะฐะผะธ Cloudflare. ะŸะตั€ะตะณะปัะฝัŒั‚ะต ั€ะพะทะดั–ะป [Advanced Security](#advanced-security). - ---- - -## 2. ะ’ัั‚ะฐะฝะพะฒั–ั‚ัŒ OmniRoute - -### 2.1 ะกั‚ะฒะพั€ั–ั‚ัŒ ะบะฐั‚ะฐะปะพะณ ะบะพะฝั„ั–ะณัƒั€ะฐั†ั–ั— - -```bash -mkdir -p /opt/omniroute -``` - -### 2.2 ะกั‚ะฒะพั€ั–ั‚ัŒ ั„ะฐะนะป ะทะผั–ะฝะฝะธั… ัะตั€ะตะดะพะฒะธั‰ะฐ - -```bash -cat > /opt/omniroute/.env << โ€˜EOFโ€™ -# === Security === -JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY -INITIAL_PASSWORD=YourSecurePassword123! -API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY -STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY -STORAGE_ENCRYPTION_KEY_VERSION=v1 -MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT - -# === 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 (change to your domain) === -BASE_URL=https://llms.seudominio.com -NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com - -# === Cloud Sync (optional) === -# CLOUD_URL=https://cloud.omniroute.online -# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online -EOF -``` - -> โš ๏ธ **ะ’ะะ–ะ›ะ˜ะ’ะž**: ะณะตะฝะตั€ัƒะนั‚ะต ัƒะฝั–ะบะฐะปัŒะฝั– ัะตะบั€ะตั‚ะฝั– ะบะปัŽั‡ั–! ะ’ะธะบะพั€ะธัั‚ะพะฒัƒะนั‚ะต `openssl rand -hex 32` ะดะปั ะบะพะถะฝะพะณะพ ะบะปัŽั‡ะฐ. - -### 2.3 ะ—ะฐะฟัƒัั‚ั–ั‚ัŒ ะบะพะฝั‚ะตะนะฝะตั€ - -```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 ะŸะตั€ะตะบะพะฝะฐะนั‚ะตัั, ั‰ะพ ะฒั–ะฝ ะฟั€ะฐั†ัŽั” - -```bash -docker ps | grep omniroute -docker logs omniroute --tail 20 -``` - -ะœะฐั” ะฒั–ะดะพะฑั€ะฐะถะฐั‚ะธัั: `[DB] SQLite database ready` ั‚ะฐ `listening on port 20128`. - ---- - -## 3. ะะฐะปะฐัˆั‚ัƒะฒะฐั‚ะธ nginx (ะทะฒะพั€ะพั‚ะฝะธะน ะฟั€ะพะบัั–) - -### 3.1 ะกั‚ะฒะพั€ะตะฝะฝั ัะตั€ั‚ะธั„ั–ะบะฐั‚ะฐ SSL (Cloudflare Origin) - -ะะฐ ั–ะฝั„ะพั€ะผะฐั†ั–ะนะฝั–ะน ะฟะฐะฝะตะปั– Cloudflare: - -1. ะŸะตั€ะตะนะดั–ั‚ัŒ ะดะพ **SSL/TLS โ†’ ะžั€ะธะณั–ะฝะฐะปัŒะฝะธะน ัะตั€ะฒะตั€** -2. ะะฐั‚ะธัะฝั–ั‚ัŒ **ะกั‚ะฒะพั€ะธั‚ะธ ัะตั€ั‚ะธั„ั–ะบะฐั‚** -3. ะ—ะฑะตั€ั–ะณะฐะนั‚ะต ะทะฝะฐั‡ะตะฝะฝั ะทะฐ ัƒะผะพะฒั‡ะฐะฝะฝัะผ (15 ั€ะพะบั–ะฒ, \*.yourdomain.com) -4. ะกะบะพะฟั–ัŽะนั‚ะต **ะกะตั€ั‚ะธั„ั–ะบะฐั‚ ะฟะพั…ะพะดะถะตะฝะฝั** ั‚ะฐ **ะŸั€ะธะฒะฐั‚ะฝะธะน ะบะปัŽั‡** - -```bash -mkdir -p /etc/nginx/ssl - -# Paste the certificate -nano /etc/nginx/ssl/origin.crt - -# Paste the private key -nano /etc/nginx/ssl/origin.key - -chmod 600 /etc/nginx/ssl/origin.key -``` - -### 3.2 ะšะพะฝั„ั–ะณัƒั€ะฐั†ั–ั Nginx - -```bash -cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ -# Default server โ€” blocks direct access via 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.yourdomain.com; # Change to your domain - - 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.yourdomain.com; - return 301 https://$server_name$request_uri; -} -NGINX -``` - -### 3.3 ะฃะฒั–ะผะบะฝัƒั‚ะธ ั‚ะฐ ะฟะตั€ะตะฒั–ั€ะธั‚ะธ - -```bash -# Remove default configuration -rm -f /etc/nginx/sites-enabled/default - -# Enable OmniRoute -ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute - -# Test and reload -nginx -t && systemctl reload nginx -``` - ---- - -## 4. ะะฐะปะฐัˆั‚ัƒะนั‚ะต DNS Cloudflare - -### 4.1 ะ”ะพะดะฐะนั‚ะต ะทะฐะฟะธั DNS - -ะะฐ ั–ะฝั„ะพั€ะผะฐั†ั–ะนะฝั–ะน ะฟะฐะฝะตะปั– Cloudflare โ†’ DNS: - -| ะขะธะฟ | ะ†ะผ'ั | ะ—ะผั–ัั‚ | ะŸั€ะพะบัั– | -| --- | ------ | --------------------------------------------- | --------- | -| A | `llms` | `203.0.113.10` (IP-ะฐะดั€ะตัะฐ ะฒั–ั€ั‚ัƒะฐะปัŒะฝะพั— ะผะฐัˆะธะฝะธ) | โœ… ะŸั€ะพะบัั– | - -### 4.2 ะะฐะปะฐัˆั‚ัƒะฒะฐั‚ะธ SSL - -ะฃ ั€ะพะทะดั–ะปั– **SSL/TLS โ†’ ะžะณะปัะด**: - -- ะ ะตะถะธะผ: **ะŸะพะฒะฝะธะน (ะกั‚ั€ะพะณะธะน)** - -ะฃ ั€ะพะทะดั–ะปั– **SSL/TLS โ†’ Edge Certificates**: - -- ะ—ะฐะฒะถะดะธ ะฒะธะบะพั€ะธัั‚ะพะฒัƒะฒะฐั‚ะธ HTTPS: โœ… ะฃะฒั–ะผะบ -- ะœั–ะฝั–ะผะฐะปัŒะฝะฐ ะฒะตั€ัั–ั TLS: TLS 1.2 -- ะะฒั‚ะพะผะฐั‚ะธั‡ะฝะต ะฟะตั€ะตะทะฐะฟะธั HTTPS: โœ… ะฃะฒั–ะผะบะฝะตะฝะพ - -### 4.3 ะขะตัั‚ัƒะฒะฐะฝะฝั - -```bash -curl -sI https://llms.seudominio.com/health -# Should return HTTP/2 200 -``` - ---- - -## 5. ะ•ะบัะฟะปัƒะฐั‚ะฐั†ั–ั ั‚ะฐ ั‚ะตั…ะฝั–ั‡ะฝะต ะพะฑัะปัƒะณะพะฒัƒะฒะฐะฝะฝั - -### ะžะฝะพะฒะปะตะฝะฝั ะดะพ ะฝะพะฒะพั— ะฒะตั€ัั–ั— - -```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 -``` - -### ะŸะตั€ะตะณะปัะฝัƒั‚ะธ ะถัƒั€ะฝะฐะปะธ - -```bash -docker logs -f omniroute # Real-time stream -docker logs omniroute --tail 50 # Last 50 lines -``` - -### ะ ะตะทะตั€ะฒะฝะต ะบะพะฟั–ัŽะฒะฐะฝะฝั ะฑะฐะทะธ ะดะฐะฝะธั… ะฒั€ัƒั‡ะฝัƒ - -```bash -# Copy data from the volume to the host -docker cp omniroute:/app/data ./backup-$(date +%F) - -# Or compress the entire volume -docker run --rm -v omniroute-data:/data -v $(pwd):/backup \ - alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data -``` - -### ะ’ั–ะดะฝะพะฒะธั‚ะธ ะท ั€ะตะทะตั€ะฒะฝะพั— ะบะพะฟั–ั— - -```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. ะ ะพะทัˆะธั€ะตะฝะธะน ะทะฐั…ะธัั‚ - -### ะžะฑะผะตะถะธั‚ะธ nginx IP-ะฐะดั€ะตัะฐะผะธ Cloudflare - -```bash -cat > /etc/nginx/cloudflare-ips.conf << โ€˜CFโ€™ -# Cloudflare IPv4 ranges โ€” update periodically -# 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 -``` - -ะ”ะพะดะฐะนั‚ะต ะฝะฐัั‚ัƒะฟะฝะต ะดะพ `nginx.conf` ะฒัะตั€ะตะดะธะฝั– ะฑะปะพะบัƒ `http {}`: - -```nginx -include /etc/nginx/cloudflare-ips.conf; -``` - -### ะ’ัั‚ะฐะฝะพะฒะธั‚ะธ fail2ban - -```bash -apt install -y fail2ban -systemctl enable fail2ban -systemctl start fail2ban - -# Check status -fail2ban-client status sshd -``` - -### ะ—ะฐะฑะปะพะบัƒะฒะฐั‚ะธ ะฟั€ัะผะธะน ะดะพัั‚ัƒะฟ ะดะพ ะฟะพั€ั‚ัƒ Docker - -```bash -# Prevent direct external access to port 20128 -iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP -iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT - -# Persist the rules -apt install -y iptables-persistent -netfilter-persistent save -``` - ---- - -## 7. ะ ะพะทะณะพั€ั‚ะฐะฝะฝั ะฒ Cloudflare Workers (ะฝะตะพะฑะพะฒโ€™ัะทะบะพะฒะพ) - -ะ”ะปั ะฒั–ะดะดะฐะปะตะฝะพะณะพ ะดะพัั‚ัƒะฟัƒ ั‡ะตั€ะตะท Cloudflare Workers (ะฑะตะท ะฑะตะทะฟะพัะตั€ะตะดะฝัŒะพะณะพ ะดะพัั‚ัƒะฟัƒ ะดะพ ะฒั–ั€ั‚ัƒะฐะปัŒะฝะพั— ะผะฐัˆะธะฝะธ): - -```bash -# In the local repository -cd omnirouteCloud -npm install -npx wrangler login -npx wrangler deploy -``` - -ะŸะตั€ะตะณะปัะฝัŒั‚ะต ะฟะพะฒะฝัƒ ะดะพะบัƒะผะตะฝั‚ะฐั†ั–ัŽ ะทะฐ ะฐะดั€ะตัะพัŽ [omnirouteCloud/README.md](../omnirouteCloud/README.md). - ---- - -## ะšะพั€ะพั‚ะบะธะน ะพะฟะธั ะฟะพั€ั‚ัƒ - -| ะŸะพั€ั‚ | ะกะตั€ะฒั–ั | ะ”ะพัั‚ัƒะฟ | -| ----- | ----------- | --------------------------------- | -| 22 | SSH | ะ—ะฐะณะฐะปัŒะฝะพะดะพัั‚ัƒะฟะฝะธะน (ะท fail2ban) | -| 80 | nginx HTTP | ะŸะตั€ะตะฝะฐะฟั€ะฐะฒะปะตะฝะฝั โ†’ HTTPS | -| 443 | nginx HTTPS | ะงะตั€ะตะท ะฟั€ะพะบัั– Cloudflare | -| 20128 | OmniRoute | ะ›ะธัˆะต ะปะพะบะฐะปัŒะฝะธะน ั…ะพัั‚ (ั‡ะตั€ะตะท nginx) | diff --git a/docs/i18n/uk-UA/docs/A2A-SERVER.md b/docs/i18n/uk-UA/docs/A2A-SERVER.md new file mode 100644 index 0000000000..67eb5e651d --- /dev/null +++ b/docs/i18n/uk-UA/docs/A2A-SERVER.md @@ -0,0 +1,200 @@ +# OmniRoute A2A Server Documentation (ะฃะบั€ะฐั—ะฝััŒะบะฐ) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/A2A-SERVER.md) + +--- + +> Agent-to-Agent Protocol v0.3 โ€” OmniRoute as an intelligent routing agent + +## Agent Discovery + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements. + +--- + +## Authentication + +All `/a2a` requests require an API key via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server, authentication is bypassed. + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Sends a message to a skill and waits for the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a hello world in Python"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "uuid", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "..." }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}} + +: heartbeat 2026-03-03T17:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Available Skills + +| Skill | Description | +| :----------------- | :------------------------------------------------------------------------------------------------------------------------------ | +| `smart-routing` | Routes prompts through OmniRoute's intelligent pipeline. Returns response with routing explanation, cost, and resilience trace. | +| `quota-management` | Answers natural-language queries about provider quotas, suggests free combos, and provides quota rankings. | + +--- + +## Task Lifecycle + +``` +submitted โ†’ working โ†’ completed + โ†’ failed + โ†’ cancelled +``` + +- Tasks expire after 5 minutes (configurable) +- Terminal states: `completed`, `failed`, `cancelled` +- Event log tracks every state transition + +--- + +## Error Codes + +| Code | Meaning | +| :----- | :----------------------------- | +| -32700 | Parse error (invalid JSON) | +| -32600 | Invalid request / Unauthorized | +| -32601 | Method or skill not found | +| -32602 | Invalid params | +| -32603 | Internal error | + +--- + +## Integration Examples + +### Python (requests) + +```python +import requests + +resp = requests.post("http://localhost:20128/a2a", json={ + "jsonrpc": "2.0", "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Hello"}] + } +}, headers={"Authorization": "Bearer YOUR_KEY"}) + +result = resp.json()["result"] +print(result["artifacts"][0]["content"]) +print(result["metadata"]["routing_explanation"]) +``` + +### TypeScript (fetch) + +```typescript +const resp = await fetch("http://localhost:20128/a2a", { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: "Bearer YOUR_KEY", + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "1", + method: "message/send", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Hello" }], + }, + }), +}); +const { result } = await resp.json(); +console.log(result.metadata.routing_explanation); +``` diff --git a/docs/i18n/uk-UA/docs/API_REFERENCE.md b/docs/i18n/uk-UA/docs/API_REFERENCE.md new file mode 100644 index 0000000000..a2bba372d7 --- /dev/null +++ b/docs/i18n/uk-UA/docs/API_REFERENCE.md @@ -0,0 +1,465 @@ +# API Reference (ะฃะบั€ะฐั—ะฝััŒะบะฐ) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/API_REFERENCE.md) + +--- + +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 | +| `X-Session-Id` | Request | Sticky session key for external session affinity | +| `x_session_id` | Request | Underscore variant also accepted (direct HTTP) | +| `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 | +| `X-OmniRoute-Session-Id` | Response | Effective session ID used by OmniRoute | + +> Nginx note: if you rely on underscore headers (for example `x_session_id`), enable `underscores_in_headers 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/stats + +# Clear all caches +DELETE /api/cache/stats +``` + +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/PATCH | 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 + provider summary (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`) | +| `/api/cache/stats` | 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 | + +### Tunnels + +| Endpoint | Method | Description | +| -------------------------- | ------ | ----------------------------------------------------------------------- | +| `/api/tunnels/cloudflared` | GET | Read Cloudflare Quick Tunnel install/runtime status for the dashboard | +| `/api/tunnels/cloudflared` | POST | Enable or disable the Cloudflare Quick Tunnel (`action=enable/disable`) | + +### 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`. + +### ACP Agents + +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | + +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). + +### Resilience & Rate Limits + +| Endpoint | Method | Description | +| ----------------------- | --------- | ------------------------------- | +| `/api/resilience` | GET/PATCH | 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` diff --git a/docs/i18n/uk-UA/docs/ARCHITECTURE.md b/docs/i18n/uk-UA/docs/ARCHITECTURE.md new file mode 100644 index 0000000000..bf7e765714 --- /dev/null +++ b/docs/i18n/uk-UA/docs/ARCHITECTURE.md @@ -0,0 +1,814 @@ +# OmniRoute Architecture (ะฃะบั€ะฐั—ะฝััŒะบะฐ) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/ARCHITECTURE.md) + +--- + +_Last updated: 2026-03-28_ + +## 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 (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developerโ†’system, systemโ†’user) for cross-provider compatibility +- Structured output conversion (json_schema โ†’ Gemini responseSchema) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) +- Global system prompt injection +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout โ†’ budget โ†’ fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) + +Primary runtime model: + +- Next.js 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.) + +## Dashboard Surface (Current) + +Main pages under `src/app/(dashboard)/dashboard/`: + +- `/dashboard` โ€” quick start + provider overview +- `/dashboard/endpoint` โ€” endpoint proxy + MCP + A2A + API endpoint tabs +- `/dashboard/providers` โ€” provider connections and credentials +- `/dashboard/combos` โ€” combo strategies, templates, model routing rules +- `/dashboard/costs` โ€” cost aggregation and pricing visibility +- `/dashboard/analytics` โ€” usage analytics and evaluations +- `/dashboard/limits` โ€” quota/rate controls +- `/dashboard/cli-tools` โ€” CLI onboarding, runtime detection, config generation +- `/dashboard/agents` โ€” detected ACP agents + custom agent registration +- `/dashboard/media` โ€” image/video/music playground +- `/dashboard/search-tools` โ€” search provider testing and history +- `/dashboard/health` โ€” uptime, circuit breakers, rate limits +- `/dashboard/logs` โ€” request/proxy/audit/console logs +- `/dashboard/settings` โ€” system settings tabs (general, routing, combo defaults, etc.) +- `/dashboard/api-manager` โ€” API key lifecycle and model permissions + +## 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[(storage.sqlite)] + UDB[(usage tables + log artifacts)] + end + + subgraph Upstreams[Upstream Providers] + P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/Qoder/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/route.ts` (GET) +- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- OAuth: `src/app/api/oauth/*` +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` +- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI tooling helpers: `src/app/api/cli-tools/*` +- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) +- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) โ€” provider profiles, circuit breaker, rate limit state +- Resilience reset: `src/app/api/resilience/reset` (POST) โ€” reset breakers + cooldowns +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) +- Telemetry: `src/app/api/telemetry/summary` (GET) +- Budget: `src/app/api/usage/budget` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Policies: `src/app/api/policies` (GET/POST) + +## 2) SSE + 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` +- Response sanitization: `open-sse/handlers/responseSanitizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.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`, `qoder.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 (SQLite): + +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** + +Usage persistence: + +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present + +Domain State DB (SQLite): + +- `src/lib/db/domainState.ts` โ€” CRUD operations 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`, `src/shared/services/modelSyncScheduler.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Periodic task: `src/shared/services/modelSyncScheduler.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. Combo routing adds one extra guard: provider-scoped 400s such as upstream content-block and role-validation failures are treated as model-local failures so later combo targets can still run. + +## 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: + +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` + +## Deployment Topology + +```mermaid +flowchart LR + 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[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] + end + + subgraph External[External Services] + Providers[AI Providers] + SyncCloud[Cloud Sync Service] + end + + CLI --> Next + Browser --> Next + Next --> Core + Next --> MainDB + Core --> MainDB + Core --> UsageDB + Core --> Providers + Next --> SyncCloud +``` + +## Module Mapping (Decision-Critical) + +### Route and API Modules + +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle +- `src/app/api/models/alias`: alias management +- `src/app/api/combos*`: fallback combo management +- `src/app/api/pricing`: pricing overrides for cost calculation +- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers +- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) +- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) +- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) +- `src/app/api/sessions`: active session listing (GET) +- `src/app/api/rate-limits`: per-account rate limit status (GET) + +### Routing and Execution Core + +- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior + +### Translation Registry and Format Converters + +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` +- Format constants: `open-sse/translator/formats.ts` + +### Persistence + +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables + +## Provider Executor Coverage (Strategy Pattern) + +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. + +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, Qoder, 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 | +| Qoder | openai | OAuth (Basic) | โœ… | โœ… | โœ… | โš ๏ธ Per request | +| OpenRouter | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| GLM/Kimi/MiniMax | claude | API Key | โœ… | โœ… | โŒ | โŒ | +| DeepSeek | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Groq | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| xAI (Grok) | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Mistral | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Perplexity | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Together AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Fireworks AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Cerebras | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Cohere | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| NVIDIA NIM | openai | API Key | โœ… | โœ… | โŒ | โŒ | + +## Format Translation Coverage + +Detected source formats include: + +- `openai` +- `openai-responses` +- `claude` +- `gemini` + +Target formats include: + +- OpenAI chat/Responses +- Claude +- Gemini/Gemini-CLI/Antigravity envelope +- Kiro +- Cursor + +Translations use **OpenAI as the hub format** โ€” all conversions go through OpenAI as intermediate: + +``` +Source Format โ†’ OpenAI (hub) โ†’ Target Format +``` + +Translations are selected dynamically based on source payload shape and provider target format. + +Additional processing layers in the translation pipeline: + +- **Response sanitization** โ€” Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI targets; merges `system` โ†’ `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** โ€” Parses `...` blocks from content into `reasoning_content` field +- **Structured output** โ€” Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` + +## Supported API Endpoints + +| 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` | Provider Models | Provider model metadata backing custom and managed available models | + +## 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 `/logs//` 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 + +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON โ†’ SQLite migration compatibility path + +## Observability and Operational Signals + +Runtime visibility sources: + +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- four-stage detailed payload captures in SQLite (`request_detail_logs`) when `settings.detailed_logs_enabled=true` +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption + +Detailed request payload capture stores up to four JSON payload stages per routed call: + +- raw request received from the client +- translated request actually sent upstream +- provider response reconstructed as JSON; streamed responses are compacted to the final summary plus stream metadata +- final client response returned by OmniRoute; streamed responses are stored in the same compact summary form + +## Security-Sensitive Boundaries + +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics + +## Environment and Runtime Matrix + +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` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). + +## Operational Verification Checklist + +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: +- `GET /api/settings` +- `GET /api/v1/models` +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/uk-UA/docs/AUTO-COMBO.md b/docs/i18n/uk-UA/docs/AUTO-COMBO.md new file mode 100644 index 0000000000..584f9886f1 --- /dev/null +++ b/docs/i18n/uk-UA/docs/AUTO-COMBO.md @@ -0,0 +1,67 @@ +# OmniRoute Auto-Combo Engine (ะฃะบั€ะฐั—ะฝััŒะบะฐ) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/AUTO-COMBO.md) + +--- + +> Self-managing model chains with adaptive scoring + +## How It Works + +The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**: + +| Factor | Weight | Description | +| :--------- | :----- | :---------------------------------------------- | +| Quota | 0.20 | Remaining capacity [0..1] | +| Health | 0.25 | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 | +| CostInv | 0.20 | Inverse cost (cheaper = higher score) | +| LatencyInv | 0.15 | Inverse p95 latency (faster = higher) | +| TaskFit | 0.10 | Model ร— task type fitness score | +| Stability | 0.10 | Low variance in latency/errors | + +## Mode Packs + +| Pack | Focus | Key Weight | +| :---------------------- | :----------- | :--------------- | +| ๐Ÿš€ **Ship Fast** | Speed | latencyInv: 0.35 | +| ๐Ÿ’ฐ **Cost Saver** | Economy | costInv: 0.40 | +| ๐ŸŽฏ **Quality First** | Best model | taskFit: 0.40 | +| ๐Ÿ“ก **Offline Friendly** | Availability | quota: 0.40 | + +## Self-Healing + +- **Temporary exclusion**: Score < 0.2 โ†’ excluded for 5 min (progressive backoff, max 30 min) +- **Circuit breaker awareness**: OPEN โ†’ auto-excluded; HALF_OPEN โ†’ probe requests +- **Incident mode**: >50% OPEN โ†’ disable exploration, maximize stability +- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout + +## Bandit Exploration + +5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode. + +## API + +```bash +# Create auto-combo +curl -X POST http://localhost:20128/api/combos/auto \ + -H "Content-Type: application/json" \ + -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}' + +# List auto-combos +curl http://localhost:20128/api/combos/auto +``` + +## Task Fitness + +30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` โ†’ high coding score). + +## Files + +| File | Purpose | +| :------------------------------------------- | :------------------------------------ | +| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization | +| `open-sse/services/autoCombo/taskFitness.ts` | Model ร— task fitness lookup | +| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap | +| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode | +| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles | +| `src/app/api/combos/auto/route.ts` | REST API | diff --git a/docs/i18n/uk-UA/docs/CLI-TOOLS.md b/docs/i18n/uk-UA/docs/CLI-TOOLS.md new file mode 100644 index 0000000000..bb366d747a --- /dev/null +++ b/docs/i18n/uk-UA/docs/CLI-TOOLS.md @@ -0,0 +1,348 @@ +# CLI Tools Setup Guide โ€” OmniRoute (ะฃะบั€ะฐั—ะฝััŒะบะฐ) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CLI-TOOLS.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CLI-TOOLS.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CLI-TOOLS.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CLI-TOOLS.md) + +--- + +This guide explains how to install and configure all supported AI coding CLI tools +to use **OmniRoute** as the unified backend, giving you centralized key management, +cost tracking, model switching, and request logging across every tool. + +--- + +## How It Works + +``` +Claude / Codex / OpenCode / Cline / KiloCode / Continue / Kiro / Cursor / Copilot + โ”‚ + โ–ผ (all point to OmniRoute) + http://YOUR_SERVER:20128/v1 + โ”‚ + โ–ผ (OmniRoute routes to the right provider) + Anthropic / OpenAI / Gemini / DeepSeek / Groq / Mistral / ... +``` + +**Benefits:** + +- One API key to manage all tools +- Cost tracking across all CLIs in the dashboard +- Model switching without reconfiguring every tool +- Works locally and on remote servers (VPS) + +--- + +## Supported Tools (Dashboard Source of Truth) + +The dashboard cards in `/dashboard/cli-tools` are generated from `src/shared/constants/cliTools.ts`. +Current list (v3.0.0-rc.16): + +| Tool | ID | Command | Setup Mode | Install Method | +| ------------------ | ------------- | ---------- | ---------- | -------------- | +| **Claude Code** | `claude` | `claude` | env | npm | +| **OpenAI Codex** | `codex` | `codex` | custom | npm | +| **Factory Droid** | `droid` | `droid` | custom | bundled/CLI | +| **OpenClaw** | `openclaw` | `openclaw` | custom | bundled/CLI | +| **Cursor** | `cursor` | app | guide | desktop app | +| **Cline** | `cline` | `cline` | custom | npm | +| **Kilo Code** | `kilo` | `kilocode` | custom | npm | +| **Continue** | `continue` | extension | guide | VS Code | +| **Antigravity** | `antigravity` | internal | mitm | OmniRoute | +| **GitHub Copilot** | `copilot` | extension | custom | VS Code | +| **OpenCode** | `opencode` | `opencode` | guide | npm | +| **Kiro AI** | `kiro` | app/cli | mitm | desktop/CLI | + +### CLI fingerprint sync (Agents + Settings) + +`/dashboard/agents` and `Settings > CLI Fingerprint` use `src/shared/constants/cliCompatProviders.ts`. +This keeps provider IDs aligned with CLI cards and legacy IDs. + +| CLI ID | Fingerprint Provider ID | +| ---------------------------------------------------------------------------------------------------- | ----------------------- | +| `kilo` | `kilocode` | +| `copilot` | `github` | +| `claude` / `codex` / `antigravity` / `kiro` / `cursor` / `cline` / `opencode` / `droid` / `openclaw` | same ID | + +Legacy IDs still accepted for compatibility: `copilot`, `kimi-coding`, `qwen`. + +--- + +## Step 1 โ€” Get an OmniRoute API Key + +1. Open the OmniRoute dashboard โ†’ **API Manager** (`/dashboard/api-manager`) +2. Click **Create API Key** +3. Give it a name (e.g. `cli-tools`) and select all permissions +4. Copy the key โ€” you'll need it for every CLI below + +> Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` + +--- + +## Step 2 โ€” Install CLI Tools + +All npm-based tools require Node.js 18+: + +```bash +# Claude Code (Anthropic) +npm install -g @anthropic-ai/claude-code + +# OpenAI Codex +npm install -g @openai/codex + +# OpenCode +npm install -g opencode-ai + +# Cline +npm install -g cline + +# KiloCode +npm install -g kilocode + +# Kiro CLI (Amazon โ€” requires curl + unzip) +apt-get install -y unzip # on Debian/Ubuntu +curl -fsSL https://cli.kiro.dev/install | bash +export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc +``` + +**Verify:** + +```bash +claude --version # 2.x.x +codex --version # 0.x.x +opencode --version # x.x.x +cline --version # 2.x.x +kilocode --version # x.x.x (or: kilo --version) +kiro-cli --version # 1.x.x +``` + +--- + +## Step 3 โ€” Set Global Environment Variables + +Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`: + +```bash +# OmniRoute Universal Endpoint +export OPENAI_BASE_URL="http://localhost:20128/v1" +export OPENAI_API_KEY="sk-your-omniroute-key" +export ANTHROPIC_BASE_URL="http://localhost:20128/v1" +export ANTHROPIC_API_KEY="sk-your-omniroute-key" +export GEMINI_BASE_URL="http://localhost:20128/v1" +export GEMINI_API_KEY="sk-your-omniroute-key" +``` + +> For a **remote server** replace `localhost:20128` with the server IP or domain, +> e.g. `http://192.168.0.15:20128`. + +--- + +## Step 4 โ€” Configure Each Tool + +### Claude Code + +```bash +# Via CLI: +claude config set --global api-base-url http://localhost:20128/v1 + +# Or create ~/.claude/settings.json: +mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF +{ + "apiBaseUrl": "http://localhost:20128/v1", + "apiKey": "sk-your-omniroute-key" +} +EOF +``` + +**Test:** `claude "say hello"` + +--- + +### OpenAI Codex + +```bash +mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF +model: auto +apiKey: sk-your-omniroute-key +apiBaseUrl: http://localhost:20128/v1 +EOF +``` + +**Test:** `codex "what is 2+2?"` + +--- + +### OpenCode + +```bash +mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF +[provider.openai] +base_url = "http://localhost:20128/v1" +api_key = "sk-your-omniroute-key" +EOF +``` + +**Test:** `opencode` + +--- + +### Cline (CLI or VS Code) + +**CLI mode:** + +```bash +mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF +{ + "apiProvider": "openai", + "openAiBaseUrl": "http://localhost:20128/v1", + "openAiApiKey": "sk-your-omniroute-key" +} +EOF +``` + +**VS Code mode:** +Cline extension settings โ†’ API Provider: `OpenAI Compatible` โ†’ Base URL: `http://localhost:20128/v1` + +Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ Cline โ†’ Apply Config**. + +--- + +### KiloCode (CLI or VS Code) + +**CLI mode:** + +```bash +kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key +``` + +**VS Code settings:** + +```json +{ + "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", + "kilo-code.apiKey": "sk-your-omniroute-key" +} +``` + +Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ KiloCode โ†’ Apply Config**. + +--- + +### Continue (VS Code Extension) + +Edit `~/.continue/config.yaml`: + +```yaml +models: + - name: OmniRoute + provider: openai + model: auto + apiBase: http://localhost:20128/v1 + apiKey: sk-your-omniroute-key + default: true +``` + +Restart VS Code after editing. + +--- + +### Kiro CLI (Amazon) + +```bash +# Login to your AWS/Kiro account: +kiro-cli login + +# The CLI uses its own auth โ€” OmniRoute is not needed as backend for Kiro CLI itself. +# Use kiro-cli alongside OmniRoute for other tools. +kiro-cli status +``` + +--- + +### Cursor (Desktop App) + +> **Note:** Cursor routes requests through its cloud. For OmniRoute integration, +> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL. + +Via GUI: **Settings โ†’ Models โ†’ OpenAI API Key** + +- Base URL: `https://your-domain.com/v1` +- API Key: your OmniRoute key + +--- + +## Dashboard Auto-Configuration + +The OmniRoute dashboard automates configuration for most tools: + +1. Go to `http://localhost:20128/dashboard/cli-tools` +2. Expand any tool card +3. Select your API key from the dropdown +4. Click **Apply Config** (if tool is detected as installed) +5. Or copy the generated config snippet manually + +--- + +## Built-in Agents: Droid & OpenClaw + +**Droid** and **OpenClaw** are AI agents built directly into OmniRoute โ€” no installation needed. +They run as internal routes and use OmniRoute's model routing automatically. + +- Access: `http://localhost:20128/dashboard/agents` +- Configure: same combos and providers as all other tools +- No API key or CLI install required + +--- + +## Available API Endpoints + +| Endpoint | Description | Use For | +| -------------------------- | ----------------------------- | --------------------------- | +| `/v1/chat/completions` | Standard chat (all providers) | All modern tools | +| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows | +| `/v1/completions` | Legacy text completions | Older tools using `prompt:` | +| `/v1/embeddings` | Text embeddings | RAG, search | +| `/v1/images/generations` | Image generation | DALL-E, Flux, etc. | +| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS | +| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI | + +--- + +## ะฃััƒะฝะตะฝะฝั ะฝะตัะฟั€ะฐะฒะฝะพัั‚ะตะน + +| Error | Cause | Fix | +| ------------------------- | ----------------------- | ------------------------------------------ | +| `Connection refused` | OmniRoute not running | `pm2 start omniroute` | +| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` | +| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` | +| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` | +| CLI shows "not installed" | Binary not in PATH | Check `which ` | +| `kiro-cli: not found` | Not in PATH | `export PATH="$HOME/.local/bin:$PATH"` | + +--- + +## Quick Setup Script (One Command) + +```bash +# Install all CLIs and configure for OmniRoute (replace with your key and server URL) +OMNIROUTE_URL="http://localhost:20128/v1" +OMNIROUTE_KEY="sk-your-omniroute-key" + +npm install -g @anthropic-ai/claude-code @openai/codex opencode-ai cline kilocode + +# Kiro CLI +apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash + +# Write configs +mkdir -p ~/.claude ~/.codex ~/.config/opencode ~/.continue + +cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" +cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" +cat >> ~/.bashrc << EOF +export OPENAI_BASE_URL="$OMNIROUTE_URL" +export OPENAI_API_KEY="$OMNIROUTE_KEY" +export ANTHROPIC_BASE_URL="$OMNIROUTE_URL" +export ANTHROPIC_API_KEY="$OMNIROUTE_KEY" +EOF + +source ~/.bashrc +echo "โœ… All CLIs installed and configured for OmniRoute" +``` diff --git a/docs/i18n/uk-UA/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/uk-UA/docs/CODEBASE_DOCUMENTATION.md new file mode 100644 index 0000000000..54a505669f --- /dev/null +++ b/docs/i18n/uk-UA/docs/CODEBASE_DOCUMENTATION.md @@ -0,0 +1,591 @@ +# omniroute โ€” Codebase Documentation (ะฃะบั€ะฐั—ะฝััŒะบะฐ) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CODEBASE_DOCUMENTATION.md) + +--- + +> 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
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, Qoder, 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. + +#### ะั€ั…ั–ั‚ะตะบั‚ัƒั€ะฐ + +```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 | +| Qoder | 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"] +``` diff --git a/docs/i18n/uk-UA/docs/COVERAGE_PLAN.md b/docs/i18n/uk-UA/docs/COVERAGE_PLAN.md new file mode 100644 index 0000000000..bdf9145d43 --- /dev/null +++ b/docs/i18n/uk-UA/docs/COVERAGE_PLAN.md @@ -0,0 +1,170 @@ +# Test Coverage Plan (ะฃะบั€ะฐั—ะฝััŒะบะฐ) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/COVERAGE_PLAN.md) + +--- + +Last updated: 2026-03-28 + +## Baseline + +There are multiple coverage numbers depending on how the report is computed. For planning, only one of them is useful. + +| Metric | Scope | Statements / Lines | Branches | Functions | Notes | +| -------------------- | ----------------------------------------------------- | -----------------: | -------: | --------: | --------------------------------------------------- | +| Legacy | Old `npm run test:coverage` | 79.42% | 75.15% | 67.94% | Inflated: counts test files and excludes `open-sse` | +| Diagnostic | Source-only, excluding tests and excluding `open-sse` | 68.16% | 63.55% | 64.06% | Useful only to isolate `src/**` | +| Recommended baseline | Source-only, excluding tests and including `open-sse` | 56.95% | 66.05% | 57.80% | This is the project-wide baseline to improve | + +The recommended baseline is the number to optimize against. + +## Rules + +- Coverage targets apply to source files, not to `tests/**`. +- `open-sse/**` is part of the product and must remain in scope. +- New code should not reduce coverage in touched areas. +- Prefer testing behavior and branch outcomes over implementation details. +- Prefer temp SQLite databases and small fixtures over broad mocks for `src/lib/db/**`. + +## Current command set + +- `npm run test:coverage` + - Main source coverage gate for the unit test suite + - Generates `text-summary`, `html`, `json-summary`, and `lcov` +- `npm run coverage:report` + - Detailed file-by-file report from the latest run +- `npm run test:coverage:legacy` + - Historical comparison only + +## Milestones + +| Phase | Target | Focus | +| ------- | ---------------------: | ------------------------------------------------- | +| Phase 1 | 60% statements / lines | Quick wins and low-risk utility coverage | +| Phase 2 | 65% statements / lines | DB and route foundations | +| Phase 3 | 70% statements / lines | Provider validation and usage analytics | +| Phase 4 | 75% statements / lines | `open-sse` translators and helpers | +| Phase 5 | 80% statements / lines | `open-sse` handlers and executor branches | +| Phase 6 | 85% statements / lines | Harder edge cases, branch debt, regression suites | +| Phase 7 | 90% statements / lines | Final sweep, gap closure, strict ratchet | + +Branches and functions should ratchet upward with each phase, but the primary hard target is statements / lines. + +## Priority hotspots + +These files or areas offer the best return for the next phases: + +1. `open-sse/handlers` + - `chatCore.ts` at 7.57% + - Overall directory at 29.07% +2. `open-sse/translator/request` + - Overall directory at 36.39% + - Many translators are still near single-digit coverage +3. `open-sse/translator/response` + - Overall directory at 8.07% +4. `open-sse/executors` + - Overall directory at 36.62% +5. `src/lib/db` + - `models.ts` at 20.66% + - `registeredKeys.ts` at 34.46% + - `modelComboMappings.ts` at 36.25% + - `settings.ts` at 46.40% + - `webhooks.ts` at 33.33% +6. `src/lib/usage` + - `usageHistory.ts` at 21.12% + - `usageStats.ts` at 9.56% + - `costCalculator.ts` at 30.00% +7. `src/lib/providers` + - `validation.ts` at 41.16% +8. Low-risk utility and API files for early gains + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/api/errorResponse.ts` + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +## Execution checklist + +### Phase 1: 56.95% -> 60% + +- [x] Fix coverage metric so it reflects source code instead of test files +- [x] Keep a legacy coverage script for comparison +- [x] Record the baseline and hotspots in-repo +- [ ] Add focused tests for low-risk utilities: + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/fetchTimeout.ts` + - `src/lib/api/errorResponse.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/display/names.ts` +- [ ] Add route tests for: + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +### Phase 2: 60% -> 65% + +- [ ] Add DB-backed tests for: + - `src/lib/db/modelComboMappings.ts` + - `src/lib/db/settings.ts` + - `src/lib/db/registeredKeys.ts` +- [ ] Cover branch behavior in: + - `src/lib/providers/validation.ts` + - `src/app/api/v1/embeddings/route.ts` + - `src/app/api/v1/moderations/route.ts` + +### Phase 3: 65% -> 70% + +- [ ] Add usage analytics tests for: + - `src/lib/usage/usageHistory.ts` + - `src/lib/usage/usageStats.ts` + - `src/lib/usage/costCalculator.ts` +- [ ] Expand route coverage for proxy management and settings branches + +### Phase 4: 70% -> 75% + +- [ ] Cover translator helpers and central translation paths: + - `open-sse/translator/index.ts` + - `open-sse/translator/helpers/*` + - `open-sse/translator/request/*` + - `open-sse/translator/response/*` + +### Phase 5: 75% -> 80% + +- [ ] Add handler-level tests for: + - `open-sse/handlers/chatCore.ts` + - `open-sse/handlers/responsesHandler.js` + - `open-sse/handlers/imageGeneration.js` + - `open-sse/handlers/embeddings.js` +- [ ] Add executor branch coverage for provider-specific auth, retries, and endpoint overrides + +### Phase 6: 80% -> 85% + +- [ ] Merge more edge-case suites into the main coverage path +- [ ] Increase function coverage for DB modules with weak constructor/helper coverage +- [ ] Close branch gaps in `settings.ts`, `registeredKeys.ts`, `validation.ts`, and translator helpers + +### Phase 7: 85% -> 90% + +- [ ] Treat the remaining low-coverage files as blockers +- [ ] Add regression tests for every uncovered production bug fixed during the push to 90% +- [ ] Raise the coverage gate in CI only after the local baseline is stable for at least two consecutive runs + +## Ratchet policy + +Update `npm run test:coverage` thresholds only after the project actually exceeds the next milestone with a comfortable buffer. + +Recommended ratchet sequence: + +1. 55/60/55 +2. 60/62/58 +3. 65/64/62 +4. 70/66/66 +5. 75/70/72 +6. 80/75/78 +7. 85/80/84 +8. 90/85/88 + +Order is `statements-lines / branches / functions`. + +## Known gap + +The current coverage command measures the main Node unit suite and includes source reached from it, including `open-sse`. It does not yet merge Vitest coverage into a single unified report. That merge is worth doing later, but it is not a blocker for starting the 60% -> 80% climb. diff --git a/docs/i18n/uk-UA/docs/FEATURES.md b/docs/i18n/uk-UA/docs/FEATURES.md index b94f1b810c..5425a8e81e 100644 --- a/docs/i18n/uk-UA/docs/FEATURES.md +++ b/docs/i18n/uk-UA/docs/FEATURES.md @@ -1,6 +1,6 @@ # OmniRoute โ€” Dashboard Features Gallery (ะฃะบั€ะฐั—ะฝััŒะบะฐ) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/FEATURES.md) --- @@ -10,7 +10,7 @@ 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). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. ![Providers Dashboard](screenshots/01-providers.png) diff --git a/docs/i18n/uk-UA/docs/MCP-SERVER.md b/docs/i18n/uk-UA/docs/MCP-SERVER.md new file mode 100644 index 0000000000..f1ca3d8b29 --- /dev/null +++ b/docs/i18n/uk-UA/docs/MCP-SERVER.md @@ -0,0 +1,87 @@ +# OmniRoute MCP Server Documentation (ะฃะบั€ะฐั—ะฝััŒะบะฐ) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/MCP-SERVER.md) + +--- + +> Model Context Protocol server with 16 intelligent tools + +## ะ’ัั‚ะฐะฝะพะฒะธั‚ะธ + +OmniRoute MCP is built-in. Start it with: + +```bash +omniroute --mcp +``` + +Or via the open-sse transport: + +```bash +# HTTP streamable transport (port 20130) +omniroute --dev # MCP auto-starts on /mcp endpoint +``` + +## IDE Configuration + +See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup. + +--- + +## Essential Tools (8) + +| Tool | Description | +| :------------------------------ | :--------------------------------------- | +| `omniroute_get_health` | Gateway health, circuit breakers, uptime | +| `omniroute_list_combos` | All configured combos with models | +| `omniroute_get_combo_metrics` | Performance metrics for a specific combo | +| `omniroute_switch_combo` | Switch active combo by ID/name | +| `omniroute_check_quota` | Quota status per provider or all | +| `omniroute_route_request` | Send a chat completion through OmniRoute | +| `omniroute_cost_report` | Cost analytics for a time period | +| `omniroute_list_models_catalog` | Full model catalog with capabilities | + +## Advanced Tools (8) + +| Tool | Description | +| :--------------------------------- | :---------------------------------------------------------- | +| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | +| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | +| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | +| `omniroute_test_combo` | Live-test all models in a combo via a real upstream request | +| `omniroute_get_provider_metrics` | Detailed metrics for one provider | +| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | +| `omniroute_explain_route` | Explain a past routing decision | +| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | + +## Authentication + +MCP tools are authenticated via API key scopes. Each tool requires specific scopes: + +| Scope | Tools | +| :------------- | :----------------------------------------------- | +| `read:health` | get_health, get_provider_metrics | +| `read:combos` | list_combos, get_combo_metrics | +| `write:combos` | switch_combo | +| `read:quota` | check_quota | +| `write:route` | route_request, simulate_route, test_combo | +| `read:usage` | cost_report, get_session_snapshot, explain_route | +| `write:config` | set_budget_guard, set_resilience_profile | +| `read:models` | list_models_catalog, best_combo_for_task | + +## Audit Logging + +Every tool call is logged to `mcp_tool_audit` with: + +- Tool name, arguments, result +- Duration (ms), success/failure +- API key hash, timestamp + +## Files + +| File | Purpose | +| :------------------------------------------- | :------------------------------------------ | +| `open-sse/mcp-server/server.ts` | MCP server creation + 16 tool registrations | +| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport | +| `open-sse/mcp-server/auth.ts` | API key + scope validation | +| `open-sse/mcp-server/audit.ts` | Tool call audit logging | +| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers | diff --git a/docs/i18n/uk-UA/docs/RELEASE_CHECKLIST.md b/docs/i18n/uk-UA/docs/RELEASE_CHECKLIST.md new file mode 100644 index 0000000000..3cf079140a --- /dev/null +++ b/docs/i18n/uk-UA/docs/RELEASE_CHECKLIST.md @@ -0,0 +1,37 @@ +# Release Checklist (ะฃะบั€ะฐั—ะฝััŒะบะฐ) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/RELEASE_CHECKLIST.md) + +--- + +Use this checklist before tagging or publishing a new OmniRoute release. + +## Version and Changelog + +1. Bump `package.json` version (`x.y.z`) in the release branch. +2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: + - `## [x.y.z] โ€” YYYY-MM-DD` +3. Keep `## [Unreleased]` as the first changelog section for upcoming work. +4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. + +## API Docs + +1. Update `docs/openapi.yaml`: + - `info.version` must equal `package.json` version. +2. Validate endpoint examples if API contracts changed. + +## Runtime Docs + +1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. +2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. +3. Update localized docs if source docs changed significantly. + +## Automated Check + +Run the sync guard locally before opening PR: + +```bash +npm run check:docs-sync +``` + +CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/uk-UA/docs/TROUBLESHOOTING.md b/docs/i18n/uk-UA/docs/TROUBLESHOOTING.md new file mode 100644 index 0000000000..854d92cbef --- /dev/null +++ b/docs/i18n/uk-UA/docs/TROUBLESHOOTING.md @@ -0,0 +1,256 @@ +# Troubleshooting (ะฃะบั€ะฐั—ะฝััŒะบะฐ) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/TROUBLESHOOTING.md) + +--- + +Common problems and solutions for OmniRoute. + +--- + +## Quick Fixes + +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | + +--- + +## Provider Issues + +### "Language model did not provide messages" + +**Cause:** Provider quota exhausted. + +**Fix:** + +1. 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, Qoder) 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}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) + +--- + +## Circuit Breaker Issues + +### Provider stuck in OPEN state + +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. + +**Fix:** + +1. 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 +- **SDK returns raw string instead of object** โ€” Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** โ€” Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** โ€” Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** โ€” Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` + +--- + +## Resilience Settings + +### Auto rate-limit not triggering + +- 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. + +--- + +## Optional RAG / LLM failure taxonomy (16 problems) + +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` โ€ฆ `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard โ†’ Health** for real-time system status +- **Translator**: Use **Dashboard โ†’ Translator** to debug format issues diff --git a/docs/i18n/uk-UA/USER_GUIDE.md b/docs/i18n/uk-UA/docs/USER_GUIDE.md similarity index 82% rename from docs/i18n/uk-UA/USER_GUIDE.md rename to docs/i18n/uk-UA/docs/USER_GUIDE.md index d0312f2b27..8797ffb888 100644 --- a/docs/i18n/uk-UA/USER_GUIDE.md +++ b/docs/i18n/uk-UA/docs/USER_GUIDE.md @@ -1,8 +1,6 @@ # User Guide (ะฃะบั€ะฐั—ะฝััŒะบะฐ) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/USER_GUIDE.md) - -> ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/USER_GUIDE.md) --- @@ -320,7 +318,7 @@ Model: cc/claude-opus-4-6 --- -## ๐Ÿš€ Deployment +## ะ ะพะทะณะพั€ั‚ะฐะฝะฝั ### Global npm install (Recommended) @@ -511,23 +509,26 @@ post_install() { ### Environment Variables -| Variable | Default | Description | -| ------------------------- | ------------------------------------ | ------------------------------------------------------- | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | -| `INITIAL_PASSWORD` | `123456` | First login password | -| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | -| `PORT` | framework default | Service port (`20128` in examples) | -| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | -| `NODE_ENV` | runtime default | Set `production` for deploy | -| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | -| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | -| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | -| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | -| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | -| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | -| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | -| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | +| 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/*` | +| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand | +| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | For the full environment variable reference, see the [README](../README.md). @@ -598,6 +599,11 @@ curl -X POST http://localhost:20128/api/provider-models \ Or use Dashboard: **Providers โ†’ [Provider] โ†’ Custom Models**. +Notes: + +- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers. +- The **Custom Models** section is intended for providers that do not expose managed available-model imports. + ### Dedicated Provider Routes Route requests directly to a specific provider with model validation: @@ -642,6 +648,14 @@ Returns models grouped by provider with types (`chat`, `embedding`, `image`). - Automatic background sync with timeout + fail-fast - Prefer server-side `BASE_URL`/`CLOUD_URL` in production +### Cloudflare Quick Tunnel + +- Available in **Dashboard โ†’ Endpoints** for Docker and other self-hosted deployments +- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint +- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary +- Tunnel URLs are ephemeral and change every time you stop/start the tunnel +- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download + ### LLM Gateway Intelligence (Phase 9) - **Semantic Cache** โ€” Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) @@ -757,11 +771,11 @@ OmniRoute implements provider-level resilience with four components: 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 | +| 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 unless `DISABLE_SQLITE_AUTO_BACKUP=true` | ```bash # API: Export database @@ -787,10 +801,11 @@ curl -X POST http://localhost:20128/api/db-backups/import \ ### Settings Dashboard -The settings page is organized into 5 tabs for easy navigation: +The settings page is organized into 6 tabs for easy navigation: | Tab | Contents | | -------------- | ---------------------------------------------------------------------------------------------- | +| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility | | **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | | **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | | **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | diff --git a/docs/i18n/uk-UA/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/uk-UA/docs/VM_DEPLOYMENT_GUIDE.md new file mode 100644 index 0000000000..84e3abad6f --- /dev/null +++ b/docs/i18n/uk-UA/docs/VM_DEPLOYMENT_GUIDE.md @@ -0,0 +1,403 @@ +# OmniRoute โ€” Deployment Guide on VM with Cloudflare (ะฃะบั€ะฐั—ะฝััŒะบะฐ) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/VM_DEPLOYMENT_GUIDE.md) + +--- + +Complete guide to install and configure OmniRoute on a VM (VPS) with domain managed via Cloudflare. + +--- + +## Prerequisites + +| Item | Minimum | Recommended | +| ---------- | ------------------------ | ---------------- | +| **CPU** | 1 vCPU | 2 vCPU | +| **RAM** | 1 GB | 2 GB | +| **Disk** | 10 GB SSD | 25 GB SSD | +| **OS** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS | +| **Domain** | Registered on Cloudflare | โ€” | +| **Docker** | Docker Engine 24+ | Docker 27+ | + +**Tested providers**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. + +--- + +## 1. Configure the VM + +### 1.1 Create the instance + +On your preferred VPS provider: + +- Choose Ubuntu 24.04 LTS +- Select the minimum plan (1 vCPU / 1 GB RAM) +- Set a strong root password or configure SSH key +- Note the **public IP** (e.g., `203.0.113.10`) + +### 1.2 Connect via SSH + +```bash +ssh root@203.0.113.10 +``` + +### 1.3 Update the system + +```bash +apt update && apt upgrade -y +``` + +### 1.4 Install Docker + +```bash +# Install dependencies +apt install -y ca-certificates curl gnupg + +# Add official Docker repository +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 Install nginx + +```bash +apt install -y nginx +``` + +### 1.6 Configure 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 +``` + +> **Tip**: For maximum security, restrict ports 80 and 443 to Cloudflare IPs only. See the [Advanced Security](#advanced-security) section. + +--- + +## 2. Install OmniRoute + +### 2.1 Create configuration directory + +```bash +mkdir -p /opt/omniroute +``` + +### 2.2 Create environment variables file + +```bash +cat > /opt/omniroute/.env << โ€˜EOFโ€™ +# === Security === +JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY +INITIAL_PASSWORD=YourSecurePassword123! +API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY +STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY +STORAGE_ENCRYPTION_KEY_VERSION=v1 +MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT + +# === 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 (change to your domain) === +BASE_URL=https://llms.seudominio.com +NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com + +# === Cloud Sync (optional) === +# CLOUD_URL=https://cloud.omniroute.online +# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online +EOF +``` + +> โš ๏ธ **IMPORTANT**: Generate unique secret keys! Use `openssl rand -hex 32` for each key. + +### 2.3 Start the 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 Verify that it is running + +```bash +docker ps | grep omniroute +docker logs omniroute --tail 20 +``` + +It should display: `[DB] SQLite database ready` and `listening on port 20128`. + +--- + +## 3. Configure nginx (Reverse Proxy) + +### 3.1 Generate SSL certificate (Cloudflare Origin) + +In the Cloudflare dashboard: + +1. Go to **SSL/TLS โ†’ Origin Server** +2. Click **Create Certificate** +3. Keep the defaults (15 years, \*.yourdomain.com) +4. Copy the **Origin Certificate** and the **Private Key** + +```bash +mkdir -p /etc/nginx/ssl + +# Paste the certificate +nano /etc/nginx/ssl/origin.crt + +# Paste the private key +nano /etc/nginx/ssl/origin.key + +chmod 600 /etc/nginx/ssl/origin.key +``` + +### 3.2 Nginx Configuration + +```bash +cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ +# Default server โ€” blocks direct access via 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.yourdomain.com; # Change to your domain + + 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.yourdomain.com; + return 301 https://$server_name$request_uri; +} +NGINX +``` + +### 3.3 Enable and Test + +```bash +# Remove default configuration +rm -f /etc/nginx/sites-enabled/default + +# Enable OmniRoute +ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute + +# Test and reload +nginx -t && systemctl reload nginx +``` + +--- + +## 4. Configure Cloudflare DNS + +### 4.1 Add DNS record + +In the Cloudflare dashboard โ†’ DNS: + +| Type | Name | Content | Proxy | +| ---- | ------ | ---------------------- | ---------- | +| A | `llms` | `203.0.113.10` (VM IP) | โœ… Proxied | + +### 4.2 Configure SSL + +Under **SSL/TLS โ†’ Overview**: + +- Mode: **Full (Strict)** + +Under **SSL/TLS โ†’ Edge Certificates**: + +- Always Use HTTPS: โœ… On +- Minimum TLS Version: TLS 1.2 +- Automatic HTTPS Rewrites: โœ… On + +### 4.3 Testing + +```bash +curl -sI https://llms.seudominio.com/health +# Should return HTTP/2 200 +``` + +--- + +## 5. Operations and Maintenance + +### Upgrade to a new version + +```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 +``` + +### View logs + +```bash +docker logs -f omniroute # Real-time stream +docker logs omniroute --tail 50 # Last 50 lines +``` + +### Manual database backup + +```bash +# Copy data from the volume to the host +docker cp omniroute:/app/data ./backup-$(date +%F) + +# Or compress the entire volume +docker run --rm -v omniroute-data:/data -v $(pwd):/backup \ + alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data +``` + +### Restore from 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. Advanced Security + +### Restrict nginx to Cloudflare IPs + +```bash +cat > /etc/nginx/cloudflare-ips.conf << โ€˜CFโ€™ +# Cloudflare IPv4 ranges โ€” update periodically +# 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 +``` + +Add the following to `nginx.conf` inside the `http {}` block: + +```nginx +include /etc/nginx/cloudflare-ips.conf; +``` + +### Install fail2ban + +```bash +apt install -y fail2ban +systemctl enable fail2ban +systemctl start fail2ban + +# Check status +fail2ban-client status sshd +``` + +### Block direct access to the Docker port + +```bash +# Prevent direct external access to port 20128 +iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP +iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT + +# Persist the rules +apt install -y iptables-persistent +netfilter-persistent save +``` + +--- + +## 7. Deploy to Cloudflare Workers (Optional) + +For remote access via Cloudflare Workers (without exposing the VM directly): + +```bash +# In the local repository +cd omnirouteCloud +npm install +npx wrangler login +npx wrangler deploy +``` + +See the full documentation at [omnirouteCloud/README.md](../omnirouteCloud/README.md). + +--- + +## Port Summary + +| Port | Service | Access | +| ----- | ----------- | -------------------------- | +| 22 | SSH | Public (with fail2ban) | +| 80 | nginx HTTP | Redirect โ†’ HTTPS | +| 443 | nginx HTTPS | Via Cloudflare Proxy | +| 20128 | OmniRoute | Localhost only (via nginx) | diff --git a/docs/i18n/uk-UA/src/lib/a2a/README.md b/docs/i18n/uk-UA/src/lib/a2a/README.md new file mode 100644 index 0000000000..cbfe282cf0 --- /dev/null +++ b/docs/i18n/uk-UA/src/lib/a2a/README.md @@ -0,0 +1,752 @@ +# OmniRoute A2A Server (ะฃะบั€ะฐั—ะฝััŒะบะฐ) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../../../src/lib/a2a/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../../../es/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../../../fr/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../../../de/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../../../it/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../../../ru/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../../../zh-CN/src/lib/a2a/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../../../ja/src/lib/a2a/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../../../ko/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../../../ar/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../../../in/src/lib/a2a/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../../../th/src/lib/a2a/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../../../vi/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../../../id/src/lib/a2a/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../../../ms/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../../../nl/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../../../pl/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../../../sv/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../../../no/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../../../da/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../../../fi/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../../../pt/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../../../ro/src/lib/a2a/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../../../hu/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../../../bg/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../../../sk/src/lib/a2a/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../../../uk-UA/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../../../he/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../../../phi/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../../../pt-BR/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../../../cs/src/lib/a2a/README.md) + +--- + +> **Agent-to-Agent Protocol v0.3** โ€” Enables any AI agent to use OmniRoute as an intelligent routing agent via JSON-RPC 2.0. + +The A2A Server exposes OmniRoute as a **first-class agent** that other agents can discover, delegate tasks to, and collaborate with using the [A2A Protocol](https://google.github.io/A2A/). + +--- + +## ะั€ั…ั–ั‚ะตะบั‚ัƒั€ะฐ + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Orchestrator Agent โ”‚ +โ”‚ (LangChain, CrewAI, AutoGen, Custom Agent) โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ 1. GET /.well-known/agent.json (discover) + โ”‚ 2. POST /a2a (JSON-RPC 2.0) + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ OmniRoute A2A Server โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Task Manager โ”‚ โ”‚ Skill Engine โ”‚ โ”‚ SSE Streaming โ”‚ โ”‚ +โ”‚ โ”‚ (lifecycle) โ”‚โ”€โ”€โ”‚ (registry) โ”‚โ”€โ”€โ”‚ (real-time) โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ +โ”‚ Skills: โ”‚ โ”‚ +โ”‚ โ”œโ”€ smart-routing โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ””โ”€ quota-management โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ Routing Decision Logger โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ OmniRoute Gateway (internal) + /v1/chat/completions, /api/combos, /api/usage/quota +``` + +--- + +## ะจะฒะธะดะบะธะน ัั‚ะฐั€ั‚ + +### Agent Discovery + +Every A2A-compatible agent exposes an **Agent Card** at `/.well-known/agent.json`: + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +**Response:** + +```json +{ + "name": "OmniRoute", + "description": "Intelligent AI gateway with auto-routing across 50+ providers", + "url": "http://localhost:20128/a2a", + "version": "1.8.1", + "capabilities": { + "streaming": true, + "pushNotifications": false + }, + "skills": [ + { + "id": "smart-routing", + "name": "Smart Routing", + "description": "Routes prompts through OmniRoute intelligent pipeline", + "tags": ["routing", "llm", "multi-provider", "cost-optimization"], + "examples": [ + "Write a hello world in Python", + "Explain quantum computing using the cheapest provider" + ] + }, + { + "id": "quota-management", + "name": "Quota Management", + "description": "Natural-language queries about provider quotas", + "tags": ["quota", "analytics", "cost"], + "examples": [ + "Which provider has the most quota remaining?", + "Suggest a free combo for coding" + ] + } + ], + "authentication": { + "schemes": ["bearer"], + "apiKeyHeader": "Authorization" + } +} +``` + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Send a message to a skill and receive the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python hello world"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "a1b2c3d4-...", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "print('Hello, World!')" }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.0030)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "2026-03-04T..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"Quantum computing..."}}} + +: heartbeat 2026-03-04T21:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Running Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Skills Reference + +### `smart-routing` + +Routes prompts through OmniRoute's intelligent pipeline with full observability. + +**Parameters (in `metadata`):** + +| Parameter | Type | Default | Description | +| --------- | -------- | ------------ | ---------------------------------------------------------------------------------------- | +| `model` | `string` | `"auto"` | Target model (e.g., `claude-sonnet-4`, `gpt-4o`, `auto`) | +| `combo` | `string` | active combo | Specific combo to route through | +| `budget` | `number` | none | Maximum cost in USD for this request | +| `role` | `string` | none | Task role hint: `coding`, `review`, `planning`, `analysis`, `debugging`, `documentation` | + +**Returns:** + +| Field | Description | +| ------------------------------ | --------------------------------------------------------- | +| `artifacts[].content` | The LLM response text | +| `metadata.routing_explanation` | Human-readable explanation of routing decision | +| `metadata.cost_envelope` | Estimated vs actual cost with currency | +| `metadata.resilience_trace` | Array of events (primary_selected, fallback_needed, etc.) | +| `metadata.policy_verdict` | Whether the request was allowed and why | + +### `quota-management` + +Answers natural-language queries about provider quotas. + +**Query types (inferred from message content):** + +| Query Pattern | Response Type | +| ---------------------------------------------- | -------------------------------------------------------- | +| Contains `"ranking"`, `"most quota"`, `"best"` | Providers ranked by remaining quota | +| Contains `"free"`, `"suggest"` | Lists free combos or suggests free-tier providers | +| Default | Full quota summary with warnings for low-quota providers | + +--- + +## Task Lifecycle + +``` +submitted โ”€โ”€โ†’ working โ”€โ”€โ†’ completed + โ”€โ”€โ†’ failed + โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ†’ cancelled +``` + +| State | Description | +| ----------- | ----------------------------------------------------- | +| `submitted` | Task created, queued for execution | +| `working` | Skill handler is executing | +| `completed` | Execution succeeded, artifacts available | +| `failed` | Execution failed or task expired (TTL: 5 min default) | +| `cancelled` | Cancelled by client via `tasks/cancel` | + +- Terminal states: `completed`, `failed`, `cancelled` (no further transitions) +- Expired tasks in `submitted` or `working` are auto-marked as `failed` +- Tasks are garbage-collected after 2ร— TTL + +--- + +## Client Examples + +### Python โ€” Orchestrator Agent + +```python +""" +A2A Client โ€” Python example. +Discovers OmniRoute agent, sends a task, and processes the result. +""" +import requests +import json + +BASE_URL = "http://localhost:20128" +API_KEY = "your-api-key" +HEADERS = { + "Content-Type": "application/json", + "Authorization": f"Bearer {API_KEY}", +} + +# 1. Discover agent capabilities +agent_card = requests.get(f"{BASE_URL}/.well-known/agent.json").json() +print(f"Agent: {agent_card['name']} v{agent_card['version']}") +print(f"Skills: {[s['id'] for s in agent_card['skills']]}") + +# 2. Send a smart-routing task +response = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python quicksort implementation"}], + "metadata": { + "model": "auto", + "combo": "fast-coding", + "budget": 0.10, + } + } +}) +result = response.json()["result"] +print(f"\n๐Ÿ“ Response: {result['artifacts'][0]['content'][:200]}...") +print(f"๐Ÿ”€ Routing: {result['metadata']['routing_explanation']}") +print(f"๐Ÿ’ฐ Cost: ${result['metadata']['cost_envelope']['actual']}") +print(f"๐Ÿ›ก๏ธ Policy: {result['metadata']['policy_verdict']['reason']}") + +# 3. Query quota status +quota_resp = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-2", + "method": "message/send", + "params": { + "skill": "quota-management", + "messages": [{"role": "user", "content": "Which provider has the most quota remaining?"}], + } +}) +quota_result = quota_resp.json()["result"] +print(f"\n๐Ÿ“Š Quota: {quota_result['artifacts'][0]['content']}") +``` + +### TypeScript โ€” Multi-Agent Orchestrator + +```typescript +/** + * A2A Client โ€” TypeScript example. + * Shows agent discovery, task delegation, and streaming. + */ + +const BASE_URL = "http://localhost:20128"; +const API_KEY = "your-api-key"; + +interface JsonRpcResponse { + jsonrpc: "2.0"; + id: string | number; + result?: T; + error?: { code: number; message: string }; +} + +async function a2aCall(method: string, params: Record): Promise { + const resp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: `${method}-${Date.now()}`, + method, + params, + }), + }); + const json: JsonRpcResponse = await resp.json(); + if (json.error) throw new Error(`[${json.error.code}] ${json.error.message}`); + return json.result!; +} + +// โ”€โ”€ Agent Discovery โ”€โ”€ +const agentCard = await fetch(`${BASE_URL}/.well-known/agent.json`).then((r) => r.json()); +console.log(`Connected to: ${agentCard.name} (${agentCard.skills.length} skills)`); + +// โ”€โ”€ Smart Routing: Send a coding task โ”€โ”€ +const routingResult = await a2aCall("message/send", { + skill: "smart-routing", + messages: [{ role: "user", content: "Implement a Redis cache wrapper in TypeScript" }], + metadata: { model: "claude-sonnet-4", role: "coding" }, +}); +console.log("Response:", routingResult.artifacts[0].content); +console.log("Provider:", routingResult.metadata.routing_explanation); + +// โ”€โ”€ Quota Management: Find free alternatives โ”€โ”€ +const quotaResult = await a2aCall("message/send", { + skill: "quota-management", + messages: [{ role: "user", content: "Suggest free combos for documentation" }], +}); +console.log("Free combos:", quotaResult.artifacts[0].content); + +// โ”€โ”€ Streaming: Real-time response โ”€โ”€ +const streamResp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "stream-1", + method: "message/stream", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Explain microservices architecture" }], + }, + }), +}); + +const reader = streamResp.body!.getReader(); +const decoder = new TextDecoder(); +while (true) { + const { done, value } = await reader.read(); + if (done) break; + const chunk = decoder.decode(value); + for (const line of chunk.split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + if (event.params.chunk) { + process.stdout.write(event.params.chunk.content); + } + if (event.params.task.state === "completed") { + console.log("\nโœ… Stream completed"); + } + } + } +} +``` + +### Python โ€” LangChain A2A Integration + +```python +""" +LangChain integration โ€” Use OmniRoute A2A as a custom LLM. +""" +from langchain.llms.base import BaseLLM +from langchain.schema import LLMResult, Generation +import requests +from typing import List, Optional + +class OmniRouteA2A(BaseLLM): + base_url: str = "http://localhost:20128" + api_key: str = "" + model: str = "auto" + combo: Optional[str] = None + + @property + def _llm_type(self) -> str: + return "omniroute-a2a" + + def _call(self, prompt: str, stop: Optional[List[str]] = None, **kwargs) -> str: + response = requests.post( + f"{self.base_url}/a2a", + headers={ + "Content-Type": "application/json", + "Authorization": f"Bearer {self.api_key}", + }, + json={ + "jsonrpc": "2.0", + "id": "langchain-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": prompt}], + "metadata": { + "model": self.model, + **({"combo": self.combo} if self.combo else {}), + }, + }, + }, + ) + result = response.json()["result"] + return result["artifacts"][0]["content"] + + def _generate(self, prompts: List[str], stop=None, **kwargs) -> LLMResult: + return LLMResult( + generations=[[Generation(text=self._call(p, stop))] for p in prompts] + ) + +# Usage +llm = OmniRouteA2A( + base_url="http://localhost:20128", + api_key="your-key", + model="auto", + combo="fast-coding", +) +result = llm("Write a Python function to merge two sorted lists") +print(result) +``` + +### Go โ€” A2A Client + +```go +package main + +import ( + "bytes" + "encoding/json" + "fmt" + "io" + "net/http" +) + +const baseURL = "http://localhost:20128" +const apiKey = "your-api-key" + +type JsonRpcRequest struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Method string `json:"method"` + Params interface{} `json:"params"` +} + +type JsonRpcResponse struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Result interface{} `json:"result"` + Error *struct { + Code int `json:"code"` + Message string `json:"message"` + } `json:"error"` +} + +func a2aCall(method string, params interface{}) (*JsonRpcResponse, error) { + body, _ := json.Marshal(JsonRpcRequest{ + Jsonrpc: "2.0", + ID: "go-1", + Method: method, + Params: params, + }) + + req, _ := http.NewRequest("POST", baseURL+"/a2a", bytes.NewReader(body)) + req.Header.Set("Content-Type", "application/json") + req.Header.Set("Authorization", "Bearer "+apiKey) + + resp, err := http.DefaultClient.Do(req) + if err != nil { + return nil, err + } + defer resp.Body.Close() + data, _ := io.ReadAll(resp.Body) + + var result JsonRpcResponse + json.Unmarshal(data, &result) + return &result, nil +} + +func main() { + // Discover agent + resp, _ := http.Get(baseURL + "/.well-known/agent.json") + defer resp.Body.Close() + body, _ := io.ReadAll(resp.Body) + fmt.Println("Agent Card:", string(body)) + + // Send smart-routing task + result, _ := a2aCall("message/send", map[string]interface{}{ + "skill": "smart-routing", + "messages": []map[string]string{{"role": "user", "content": "Hello from Go!"}}, + "metadata": map[string]interface{}{"model": "auto"}, + }) + out, _ := json.MarshalIndent(result.Result, "", " ") + fmt.Println("Result:", string(out)) +} +``` + +--- + +## Use Cases + +### ๐Ÿค– Use Case 1: Multi-Agent Coding Pipeline + +An orchestrator agent delegates code generation to OmniRoute, then passes the output to a review agent. + +```python +def coding_pipeline(task: str): + # Step 1: Generate code via OmniRoute A2A + code_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Write production-quality code: {task}"} + ], metadata={"model": "auto", "role": "coding"}) + code = code_result["artifacts"][0]["content"] + + # Step 2: Review the code via OmniRoute A2A (different model) + review_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Review this code for bugs and improvements:\n\n{code}"} + ], metadata={"model": "auto", "role": "review"}) + review = review_result["artifacts"][0]["content"] + + # Step 3: Check costs + print(f"Code cost: ${code_result['metadata']['cost_envelope']['actual']}") + print(f"Review cost: ${review_result['metadata']['cost_envelope']['actual']}") + + return {"code": code, "review": review} +``` + +### ๐Ÿ’ก Use Case 2: Quota-Aware Agent Swarm + +Multiple agents share quota through OmniRoute, using the quota skill to coordinate. + +```python +async def quota_aware_agent(agent_name: str, task: str): + # Check quota before starting + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Which provider has the most quota remaining?"} + ]) + print(f"[{agent_name}] {quota['artifacts'][0]['content']}") + + # Send request with budget constraint + result = a2a_send("smart-routing", [ + {"role": "user", "content": task} + ], metadata={"budget": 0.05}) + + policy = result["metadata"]["policy_verdict"] + if not policy["allowed"]: + print(f"[{agent_name}] โš ๏ธ Budget exceeded: {policy['reason']}") + # Fall back to free combo + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Suggest free combos"} + ]) + print(f"[{agent_name}] Free alternatives: {quota['artifacts'][0]['content']}") + + return result +``` + +### ๐Ÿ“Š Use Case 3: Real-Time Streaming Dashboard + +A monitoring agent streams responses and displays progress in real-time. + +```typescript +async function streamingDashboard(prompt: string) { + const response = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { "Content-Type": "application/json", Authorization: `Bearer ${API_KEY}` }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "dash-1", + method: "message/stream", + params: { skill: "smart-routing", messages: [{ role: "user", content: prompt }] }, + }), + }); + + let totalChunks = 0; + const reader = response.body!.getReader(); + const decoder = new TextDecoder(); + + while (true) { + const { done, value } = await reader.read(); + if (done) break; + + for (const line of decoder.decode(value).split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + const state = event.params.task.state; + + if (state === "working" && event.params.chunk) { + totalChunks++; + process.stdout.write( + `\r[Chunk ${totalChunks}] ${event.params.chunk.content.slice(0, 50)}...` + ); + } + if (state === "completed") { + const meta = event.params.metadata; + console.log( + `\nโœ… Done | Cost: $${meta?.cost_envelope?.actual || 0} | Route: ${meta?.routing_explanation || "N/A"}` + ); + } + if (state === "failed") { + console.error(`\nโŒ Failed: ${event.params.metadata?.error}`); + } + } + } + } +} +``` + +### ๐Ÿ” Use Case 4: Task Polling Pattern + +For long-running tasks, poll the task status instead of waiting synchronously. + +```python +import time + +def poll_task(task_id: str, timeout: int = 60): + """Poll task status until completion or timeout.""" + start = time.time() + while time.time() - start < timeout: + result = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "poll-1", + "method": "tasks/get", + "params": {"taskId": task_id}, + }).json() + + task = result["result"]["task"] + state = task["state"] + print(f" Task {task_id[:8]}... state={state}") + + if state in ("completed", "failed", "cancelled"): + return task + time.sleep(2) + + # Timeout โ€” cancel the task + requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "cancel-1", + "method": "tasks/cancel", + "params": {"taskId": task_id}, + }) + raise TimeoutError(f"Task {task_id} timed out after {timeout}s") +``` + +--- + +## Error Codes + +| Code | Constant | Meaning | +| ------ | ------------------------ | ---------------------------------------- | +| -32700 | โ€” | Parse error (invalid JSON) | +| -32600 | `INVALID_REQUEST` | Invalid JSON-RPC request or unauthorized | +| -32601 | `METHOD_NOT_FOUND` | Unknown method or skill | +| -32602 | `INVALID_PARAMS` | Missing or invalid parameters | +| -32603 | `INTERNAL_ERROR` | Skill execution failed | +| -32001 | `TASK_NOT_FOUND` | Task ID not found | +| -32002 | `TASK_ALREADY_COMPLETED` | Cannot modify a completed task | +| -32003 | `UNAUTHORIZED` | Invalid or missing API key | +| -32004 | `BUDGET_EXCEEDED` | Request exceeds configured budget | +| -32005 | `PROVIDER_UNAVAILABLE` | No available providers | + +--- + +## Authentication + +All `/a2a` requests require a Bearer token via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server (`OMNIROUTE_API_KEY` is empty), authentication is bypassed. + +--- + +## File Structure + +``` +src/lib/a2a/ +โ”œโ”€โ”€ taskManager.ts # Task lifecycle (create/update/cancel/list), TTL, cleanup +โ”œโ”€โ”€ taskExecution.ts # Generic task executor with state management +โ”œโ”€โ”€ streaming.ts # SSE stream formatting, heartbeat, chunk/completion events +โ”œโ”€โ”€ routingLogger.ts # Routing decision logger (stats, history, retention) +โ””โ”€โ”€ skills/ + โ”œโ”€โ”€ smartRouting.ts # Smart routing skill (routes via /v1/chat/completions) + โ””โ”€โ”€ quotaManagement.ts # Quota management skill (natural-language quota queries) + +src/app/a2a/ +โ””โ”€โ”€ route.ts # Next.js API route handler (JSON-RPC 2.0 dispatch) + +open-sse/mcp-server/ +โ””โ”€โ”€ schemas/a2a.ts # Zod schemas (AgentCard, Task, JSON-RPC, SSE events) +``` + +--- + +## Comparison: MCP vs A2A + +| Feature | MCP Server | A2A Server | +| ----------------- | ---------------------------- | ------------------------------------------------- | +| **Protocol** | Model Context Protocol | Agent-to-Agent Protocol v0.3 | +| **Transport** | stdio / HTTP | HTTP (JSON-RPC 2.0) | +| **Discovery** | Tool listing via MCP | `/.well-known/agent.json` | +| **Granularity** | 16 individual tools | 2 high-level skills | +| **Best for** | IDE agents (Cursor, VS Code) | Multi-agent systems (LangChain, CrewAI) | +| **Streaming** | Not supported | SSE via `message/stream` | +| **Task tracking** | No | Full lifecycle (submitted โ†’ completed) | +| **Observability** | Audit log per tool call | Cost envelope + resilience trace + policy verdict | + +--- + +## ะ›ั–ั†ะตะฝะทั–ั + +Part of [OmniRoute](https://github.com/diegosouzapw/OmniRoute) โ€” MIT License. diff --git a/docs/i18n/vi/A2A-SERVER.md b/docs/i18n/vi/A2A-SERVER.md deleted file mode 100644 index 01531ff482..0000000000 --- a/docs/i18n/vi/A2A-SERVER.md +++ /dev/null @@ -1,200 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/A2A-SERVER.md) - ---- - -# OmniRoute A2A Server Documentation - -> Agent-to-Agent Protocol v0.3 โ€” OmniRoute as an intelligent routing agent - -## Agent Discovery - -```bash -curl http://localhost:20128/.well-known/agent.json -``` - -Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements. - ---- - -## Authentication - -All `/a2a` requests require an API key via the `Authorization` header: - -``` -Authorization: Bearer YOUR_OMNIROUTE_API_KEY -``` - -If no API key is configured on the server, authentication is bypassed. - ---- - -## JSON-RPC 2.0 Methods - -### `message/send` โ€” Synchronous Execution - -Sends a message to a skill and waits for the complete response. - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{ - "jsonrpc": "2.0", - "id": "1", - "method": "message/send", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Write a hello world in Python"}], - "metadata": {"model": "auto", "combo": "fast-coding"} - } - }' -``` - -**Response:** - -```json -{ - "jsonrpc": "2.0", - "id": "1", - "result": { - "task": { "id": "uuid", "state": "completed" }, - "artifacts": [{ "type": "text", "content": "..." }], - "metadata": { - "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)", - "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, - "resilience_trace": [ - { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." } - ], - "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } - } - } -} -``` - -### `message/stream` โ€” SSE Streaming - -Same as `message/send` but returns Server-Sent Events for real-time streaming. - -```bash -curl -N -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{ - "jsonrpc": "2.0", - "id": "1", - "method": "message/stream", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Explain quantum computing"}] - } - }' -``` - -**SSE Events:** - -``` -data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}} - -: heartbeat 2026-03-03T17:00:00Z - -data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} -``` - -### `tasks/get` โ€” Query Task Status - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' -``` - -### `tasks/cancel` โ€” Cancel a Task - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' -``` - ---- - -## Available Skills - -| Skill | Description | -| :----------------- | :------------------------------------------------------------------------------------------------------------------------------ | -| `smart-routing` | Routes prompts through OmniRoute's intelligent pipeline. Returns response with routing explanation, cost, and resilience trace. | -| `quota-management` | Answers natural-language queries about provider quotas, suggests free combos, and provides quota rankings. | - ---- - -## Task Lifecycle - -``` -submitted โ†’ working โ†’ completed - โ†’ failed - โ†’ cancelled -``` - -- Tasks expire after 5 minutes (configurable) -- Terminal states: `completed`, `failed`, `cancelled` -- Event log tracks every state transition - ---- - -## Error Codes - -| Code | Meaning | -| :----- | :----------------------------- | -| -32700 | Parse error (invalid JSON) | -| -32600 | Invalid request / Unauthorized | -| -32601 | Method or skill not found | -| -32602 | Invalid params | -| -32603 | Internal error | - ---- - -## Integration Examples - -### Python (requests) - -```python -import requests - -resp = requests.post("http://localhost:20128/a2a", json={ - "jsonrpc": "2.0", "id": "1", - "method": "message/send", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Hello"}] - } -}, headers={"Authorization": "Bearer YOUR_KEY"}) - -result = resp.json()["result"] -print(result["artifacts"][0]["content"]) -print(result["metadata"]["routing_explanation"]) -``` - -### TypeScript (fetch) - -```typescript -const resp = await fetch("http://localhost:20128/a2a", { - method: "POST", - headers: { - "Content-Type": "application/json", - Authorization: "Bearer YOUR_KEY", - }, - body: JSON.stringify({ - jsonrpc: "2.0", - id: "1", - method: "message/send", - params: { - skill: "smart-routing", - messages: [{ role: "user", content: "Hello" }], - }, - }), -}); -const { result } = await resp.json(); -console.log(result.metadata.routing_explanation); -``` diff --git a/docs/i18n/vi/API_REFERENCE.md b/docs/i18n/vi/API_REFERENCE.md deleted file mode 100644 index b878605221..0000000000 --- a/docs/i18n/vi/API_REFERENCE.md +++ /dev/null @@ -1,455 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/API_REFERENCE.md) - ---- - -# API Reference - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/API_REFERENCE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/API_REFERENCE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/API_REFERENCE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/API_REFERENCE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/API_REFERENCE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/API_REFERENCE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/API_REFERENCE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/API_REFERENCE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/API_REFERENCE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/API_REFERENCE.md) - -Complete reference for all OmniRoute API endpoints. - ---- - -## Table of Contents - -- [Chat Completions](#chat-completions) -- [Embeddings](#embeddings) -- [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`. - -### ACP Agents - -| Endpoint | Method | Description | -| ----------------- | ------ | -------------------------------------------------------- | -| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | -| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | -| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | - -GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). - -### Resilience & Rate Limits - -| Endpoint | Method | Description | -| ----------------------- | ------- | ------------------------------- | -| `/api/resilience` | 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` diff --git a/docs/i18n/vi/ARCHITECTURE.md b/docs/i18n/vi/ARCHITECTURE.md deleted file mode 100644 index 4ea06a29f2..0000000000 --- a/docs/i18n/vi/ARCHITECTURE.md +++ /dev/null @@ -1,787 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/ARCHITECTURE.md) - ---- - -# OmniRoute Architecture - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/ARCHITECTURE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/ARCHITECTURE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/ARCHITECTURE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/ARCHITECTURE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/ARCHITECTURE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/ARCHITECTURE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/ARCHITECTURE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/ARCHITECTURE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/ARCHITECTURE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/ARCHITECTURE.md) - -_Last updated: 2026-03-04_ - -## 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 (`...`) for reasoning models -- Response sanitization for strict OpenAI SDK compatibility -- Role normalization (developerโ†’system, systemโ†’user) for cross-provider compatibility -- Structured output conversion (json_schema โ†’ Gemini responseSchema) -- Local persistence for providers, keys, aliases, combos, settings, pricing -- Usage/cost tracking and request logging -- Optional cloud sync for multi-device/state sync -- IP allowlist/blocklist for API access control -- Thinking budget management (passthrough/auto/custom/adaptive) -- Global system prompt injection -- Session tracking and fingerprinting -- Per-account enhanced rate limiting with provider-specific profiles -- Circuit breaker pattern for provider resilience -- Anti-thundering herd protection with mutex locking -- Signature-based request deduplication cache -- Domain layer: model availability, cost rules, fallback policy, lockout policy -- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) -- Policy engine for centralized request evaluation (lockout โ†’ budget โ†’ fallback) -- Request telemetry with p50/p95/p99 latency aggregation -- Correlation ID (X-Request-Id) for end-to-end tracing -- Compliance audit logging with opt-out per API key -- Eval framework for LLM quality assurance -- Resilience UI dashboard with real-time circuit breaker status -- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) - -Primary runtime model: - -- Next.js 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[(storage.sqlite)] - UDB[(usage tables + log artifacts)] - end - - subgraph Upstreams[Upstream Providers] - P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/Qoder/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/route.ts` (GET) -- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) -- OAuth: `src/app/api/oauth/*` -- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` -- Usage: `src/app/api/usage/*` -- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` -- CLI tooling helpers: `src/app/api/cli-tools/*` -- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) -- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) -- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) -- Sessions: `src/app/api/sessions` (GET) -- Rate limits: `src/app/api/rate-limits` (GET) -- Resilience: `src/app/api/resilience` (GET/PATCH) โ€” provider profiles, circuit breaker, rate limit state -- Resilience reset: `src/app/api/resilience/reset` (POST) โ€” reset breakers + cooldowns -- Cache stats: `src/app/api/cache/stats` (GET/DELETE) -- Model availability: `src/app/api/models/availability` (GET/POST) -- Telemetry: `src/app/api/telemetry/summary` (GET) -- Budget: `src/app/api/usage/budget` (GET/POST) -- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) -- Compliance audit: `src/app/api/compliance/audit-log` (GET) -- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) -- Policies: `src/app/api/policies` (GET/POST) - -## 2) SSE + 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` -- Response sanitization: `open-sse/handlers/responseSanitizer.ts` -- Role normalization: `open-sse/services/roleNormalizer.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`, `qoder.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 (SQLite): - -- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) -- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) -- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) -- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** - -Usage persistence: - -- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) -- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` -- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) -- legacy JSON files are migrated to SQLite by startup migrations when present - -Domain State DB (SQLite): - -- `src/lib/db/domainState.ts` โ€” CRUD operations 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: - -- primary runtime DB: `${DATA_DIR}/storage.sqlite` -- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) -- structured call payload archives: `${DATA_DIR}/call_logs/` -- optional translator/request debug sessions: `/logs/...` - -## Deployment Topology - -```mermaid -flowchart LR - 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[(storage.sqlite)] - UsageDB[(usage tables + log artifacts)] - end - - subgraph External[External Services] - Providers[AI Providers] - SyncCloud[Cloud Sync Service] - end - - CLI --> Next - Browser --> Next - Next --> Core - Next --> MainDB - Core --> MainDB - Core --> UsageDB - Core --> Providers - Next --> SyncCloud -``` - -## Module Mapping (Decision-Critical) - -### Route and API Modules - -- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs -- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) -- `src/app/api/providers*`: provider CRUD, validation, testing -- `src/app/api/provider-nodes*`: custom compatible node management -- `src/app/api/provider-models`: custom model management (CRUD) -- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) -- `src/app/api/oauth/*`: OAuth/device-code flows -- `src/app/api/keys*`: local API key lifecycle -- `src/app/api/models/alias`: alias management -- `src/app/api/combos*`: fallback combo management -- `src/app/api/pricing`: pricing overrides for cost calculation -- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) -- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) -- `src/app/api/usage/*`: usage and logs APIs -- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers -- `src/app/api/cli-tools/*`: local CLI config writers/checkers -- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) -- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) -- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) -- `src/app/api/sessions`: active session listing (GET) -- `src/app/api/rate-limits`: per-account rate limit status (GET) - -### Routing and Execution Core - -- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop -- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup -- `open-sse/executors/*`: provider-specific network and format behavior - -### Translation Registry and Format Converters - -- `open-sse/translator/index.ts`: translator registry and orchestration -- Request translators: `open-sse/translator/request/*` -- Response translators: `open-sse/translator/response/*` -- Format constants: `open-sse/translator/formats.ts` - -### Persistence - -- `src/lib/db/*`: persistent config/state and domain persistence on SQLite -- `src/lib/localDb.ts`: compatibility re-export for DB modules -- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables - -## Provider Executor Coverage (Strategy Pattern) - -Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. - -| Executor | Provider(s) | Special Handling | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | -| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, Qoder, 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 | -| Qoder | openai | OAuth (Basic) | โœ… | โœ… | โœ… | โš ๏ธ Per request | -| OpenRouter | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| GLM/Kimi/MiniMax | claude | API Key | โœ… | โœ… | โŒ | โŒ | -| DeepSeek | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Groq | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| xAI (Grok) | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Mistral | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Perplexity | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Together AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Fireworks AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Cerebras | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| Cohere | openai | API Key | โœ… | โœ… | โŒ | โŒ | -| NVIDIA NIM | openai | API Key | โœ… | โœ… | โŒ | โŒ | - -## Format Translation Coverage - -Detected source formats include: - -- `openai` -- `openai-responses` -- `claude` -- `gemini` - -Target formats include: - -- OpenAI chat/Responses -- Claude -- Gemini/Gemini-CLI/Antigravity envelope -- Kiro -- Cursor - -Translations use **OpenAI as the hub format** โ€” all conversions go through OpenAI as intermediate: - -``` -Source Format โ†’ OpenAI (hub) โ†’ Target Format -``` - -Translations are selected dynamically based on source payload shape and provider target format. - -Additional processing layers in the translation pipeline: - -- **Response sanitization** โ€” Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance -- **Role normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI targets; merges `system` โ†’ `user` for models that reject the system role (GLM, ERNIE) -- **Think tag extraction** โ€” Parses `...` blocks from content into `reasoning_content` field -- **Structured output** โ€” Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` - -## Supported API Endpoints - -| 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 `/logs//` 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 - -- SQLite schema migrations and auto-upgrade hooks at startup -- legacy JSON โ†’ SQLite migration compatibility path - -## Observability and Operational Signals - -Runtime visibility sources: - -- console logs from `src/sse/utils/logger.ts` -- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) -- textual request status log in `log.txt` (optional/compat) -- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` -- dashboard usage endpoints (`/api/usage/*`) for UI consumption - -## Security-Sensitive Boundaries - -- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing -- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning -- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format -- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level -- Cloud sync endpoints rely on API key auth + machine id semantics - -## Environment and Runtime Matrix - -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` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. -2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. -3. Request logger writes full headers/body when enabled; treat log directory as sensitive. -4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. -5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. -6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). -7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). -8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). - -## Operational Verification Checklist - -- Build from source: `npm run build` -- Build Docker image: `docker build -t omniroute .` -- Start service and verify: -- `GET /api/settings` -- `GET /api/v1/models` -- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/vi/AUTO-COMBO.md b/docs/i18n/vi/AUTO-COMBO.md deleted file mode 100644 index 2166e41dff..0000000000 --- a/docs/i18n/vi/AUTO-COMBO.md +++ /dev/null @@ -1,67 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/AUTO-COMBO.md) - ---- - -# OmniRoute Auto-Combo Engine - -> Self-managing model chains with adaptive scoring - -## How It Works - -The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**: - -| Factor | Weight | Description | -| :--------- | :----- | :---------------------------------------------- | -| Quota | 0.20 | Remaining capacity [0..1] | -| Health | 0.25 | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 | -| CostInv | 0.20 | Inverse cost (cheaper = higher score) | -| LatencyInv | 0.15 | Inverse p95 latency (faster = higher) | -| TaskFit | 0.10 | Model ร— task type fitness score | -| Stability | 0.10 | Low variance in latency/errors | - -## Mode Packs - -| Pack | Focus | Key Weight | -| :---------------------- | :----------- | :--------------- | -| ๐Ÿš€ **Ship Fast** | Speed | latencyInv: 0.35 | -| ๐Ÿ’ฐ **Cost Saver** | Economy | costInv: 0.40 | -| ๐ŸŽฏ **Quality First** | Best model | taskFit: 0.40 | -| ๐Ÿ“ก **Offline Friendly** | Availability | quota: 0.40 | - -## Self-Healing - -- **Temporary exclusion**: Score < 0.2 โ†’ excluded for 5 min (progressive backoff, max 30 min) -- **Circuit breaker awareness**: OPEN โ†’ auto-excluded; HALF_OPEN โ†’ probe requests -- **Incident mode**: >50% OPEN โ†’ disable exploration, maximize stability -- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout - -## Bandit Exploration - -5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode. - -## API - -```bash -# Create auto-combo -curl -X POST http://localhost:20128/api/combos/auto \ - -H "Content-Type: application/json" \ - -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}' - -# List auto-combos -curl http://localhost:20128/api/combos/auto -``` - -## Task Fitness - -30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` โ†’ high coding score). - -## Files - -| File | Purpose | -| :------------------------------------------- | :------------------------------------ | -| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization | -| `open-sse/services/autoCombo/taskFitness.ts` | Model ร— task fitness lookup | -| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap | -| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode | -| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles | -| `src/app/api/combos/auto/route.ts` | REST API | diff --git a/docs/i18n/vi/CHANGELOG.md b/docs/i18n/vi/CHANGELOG.md index a5cd1ddc7a..66d72ef64f 100644 --- a/docs/i18n/vi/CHANGELOG.md +++ b/docs/i18n/vi/CHANGELOG.md @@ -1,12 +1,92 @@ # Changelog (Tiแบฟng Viแป‡t) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CHANGELOG.md) --- - ## [Unreleased] +### ๐Ÿ› ๏ธ Maintenance + +- **AGENTS.md rewrite:** Condensed from 297โ†’153 lines. Added build/lint/test commands (including single-test execution), code style guidelines (Prettier, TypeScript, ESLint, naming, imports, error handling, security), and trimmed verbose architecture tables for AI agent consumption. + +## [3.4.2] - 2026-04-01 + +### ๐Ÿ› Bug Fixes + +- **CI Stabilization:** Fixed failing analytics/settings Playwright selectors and request assertions so GitHub Actions E2E runs pass reliably across localized UIs and switch-based controls. +- **Deterministic Tests:** Removed date-sensitive quota fixtures from Copilot usage tests and aligned idempotency/model catalog tests with the merged runtime behavior. +- **MCP Type Hardening:** Removed zero-budget explicit `any` regressions from the MCP server tool registration path, restoring the `check:any-budget:t11` workflow gate. + +### ๐Ÿ› ๏ธ Maintenance + +- **Release Branch Integration:** Consolidated the active feature branches into `release/v3.4.2` on top of current `main` and validated the branch with lint, unit, coverage, build, and CI-mode E2E runs. + +## [3.4.1] - 2026-03-31 + +> [!WARNING] +> **BREAKING CHANGE: request logging, retention, and logging environment variables have been redesigned.** +> On the first startup after upgrading, OmniRoute archives legacy request logs from `DATA_DIR/logs/`, legacy `DATA_DIR/call_logs/`, and `DATA_DIR/log.txt` into `DATA_DIR/log_archives/*.zip`, then removes the deprecated layout and switches to the new unified artifact format under `DATA_DIR/call_logs/`. + +### โœจ New Features + +- **.ENV Migration Utility:** Included `scripts/migrate-env.mjs` to seamlessly migrate ` Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` - ---- - -## Step 2 โ€” Install CLI Tools - -All npm-based tools require Node.js 18+: - -```bash -# Claude Code (Anthropic) -npm install -g @anthropic-ai/claude-code - -# OpenAI Codex -npm install -g @openai/codex - -# Gemini CLI (Google) -npm install -g @google/gemini-cli - -# OpenCode -npm install -g opencode-ai - -# Cline -npm install -g cline - -# KiloCode -npm install -g kilecode - -# Kiro CLI (Amazon โ€” requires curl + unzip) -apt-get install -y unzip # on Debian/Ubuntu -curl -fsSL https://cli.kiro.dev/install | bash -export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc -``` - -**Verify:** - -```bash -claude --version # 2.x.x -codex --version # 0.x.x -gemini --version # 0.x.x -opencode --version # x.x.x -cline --version # 2.x.x -kilocode --version # x.x.x (or: kilo --version) -kiro-cli --version # 1.x.x -``` - ---- - -## Step 3 โ€” Set Global Environment Variables - -Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`: - -```bash -# OmniRoute Universal Endpoint -export OPENAI_BASE_URL="http://localhost:20128/v1" -export OPENAI_API_KEY="sk-your-omniroute-key" -export ANTHROPIC_BASE_URL="http://localhost:20128/v1" -export ANTHROPIC_API_KEY="sk-your-omniroute-key" -export GEMINI_BASE_URL="http://localhost:20128/v1" -export GEMINI_API_KEY="sk-your-omniroute-key" -``` - -> For a **remote server** replace `localhost:20128` with the server IP or domain, -> e.g. `http://192.168.0.15:20128`. - ---- - -## Step 4 โ€” Configure Each Tool - -### Claude Code - -```bash -# Via CLI: -claude config set --global api-base-url http://localhost:20128/v1 - -# Or create ~/.claude/settings.json: -mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF -{ - "apiBaseUrl": "http://localhost:20128/v1", - "apiKey": "sk-your-omniroute-key" -} -EOF -``` - -**Test:** `claude "say hello"` - ---- - -### OpenAI Codex - -```bash -mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF -model: auto -apiKey: sk-your-omniroute-key -apiBaseUrl: http://localhost:20128/v1 -EOF -``` - -**Test:** `codex "what is 2+2?"` - ---- - -### Gemini CLI - -```bash -mkdir -p ~/.gemini && cat > ~/.gemini/settings.json << EOF -{ - "apiKey": "sk-your-omniroute-key", - "baseUrl": "http://localhost:20128/v1" -} -EOF -``` - -**Test:** `gemini "hello"` - ---- - -### OpenCode - -```bash -mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF -[provider.openai] -base_url = "http://localhost:20128/v1" -api_key = "sk-your-omniroute-key" -EOF -``` - -**Test:** `opencode` - ---- - -### Cline (CLI or VS Code) - -**CLI mode:** - -```bash -mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF -{ - "apiProvider": "openai", - "openAiBaseUrl": "http://localhost:20128/v1", - "openAiApiKey": "sk-your-omniroute-key" -} -EOF -``` - -**VS Code mode:** -Cline extension settings โ†’ API Provider: `OpenAI Compatible` โ†’ Base URL: `http://localhost:20128/v1` - -Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ Cline โ†’ Apply Config**. - ---- - -### KiloCode (CLI or VS Code) - -**CLI mode:** - -```bash -kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key -``` - -**VS Code settings:** - -```json -{ - "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", - "kilo-code.apiKey": "sk-your-omniroute-key" -} -``` - -Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ KiloCode โ†’ Apply Config**. - ---- - -### Continue (VS Code Extension) - -Edit `~/.continue/config.yaml`: - -```yaml -models: - - name: OmniRoute - provider: openai - model: auto - apiBase: http://localhost:20128/v1 - apiKey: sk-your-omniroute-key - default: true -``` - -Restart VS Code after editing. - ---- - -### Kiro CLI (Amazon) - -```bash -# Login to your AWS/Kiro account: -kiro-cli login - -# The CLI uses its own auth โ€” OmniRoute is not needed as backend for Kiro CLI itself. -# Use kiro-cli alongside OmniRoute for other tools. -kiro-cli status -``` - ---- - -### Cursor (Desktop App) - -> **Note:** Cursor routes requests through its cloud. For OmniRoute integration, -> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL. - -Via GUI: **Settings โ†’ Models โ†’ OpenAI API Key** - -- Base URL: `https://your-domain.com/v1` -- API Key: your OmniRoute key - ---- - -## Dashboard Auto-Configuration - -The OmniRoute dashboard automates configuration for most tools: - -1. Go to `http://localhost:20128/dashboard/cli-tools` -2. Expand any tool card -3. Select your API key from the dropdown -4. Click **Apply Config** (if tool is detected as installed) -5. Or copy the generated config snippet manually - ---- - -## Built-in Agents: Droid & OpenClaw - -**Droid** and **OpenClaw** are AI agents built directly into OmniRoute โ€” no installation needed. -They run as internal routes and use OmniRoute's model routing automatically. - -- Access: `http://localhost:20128/dashboard/agents` -- Configure: same combos and providers as all other tools -- No API key or CLI install required - ---- - -## Available API Endpoints - -| Endpoint | Description | Use For | -| -------------------------- | ----------------------------- | --------------------------- | -| `/v1/chat/completions` | Standard chat (all providers) | All modern tools | -| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows | -| `/v1/completions` | Legacy text completions | Older tools using `prompt:` | -| `/v1/embeddings` | Text embeddings | RAG, search | -| `/v1/images/generations` | Image generation | DALL-E, Flux, etc. | -| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS | -| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI | - ---- - -## Troubleshooting - -| Error | Cause | Fix | -| ------------------------- | ----------------------- | ------------------------------------------ | -| `Connection refused` | OmniRoute not running | `pm2 start omniroute` | -| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` | -| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` | -| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` | -| CLI shows "not installed" | Binary not in PATH | Check `which ` | -| `kiro-cli: not found` | Not in PATH | `export PATH="$HOME/.local/bin:$PATH"` | - ---- - -## Quick Setup Script (One Command) - -```bash -# Install all CLIs and configure for OmniRoute (replace with your key and server URL) -OMNIROUTE_URL="http://localhost:20128/v1" -OMNIROUTE_KEY="sk-your-omniroute-key" - -npm install -g @anthropic-ai/claude-code @openai/codex @google/gemini-cli opencode-ai cline kilecode - -# Kiro CLI -apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash - -# Write configs -mkdir -p ~/.claude ~/.codex ~/.gemini ~/.config/opencode ~/.continue - -cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" -cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" -cat > ~/.gemini/settings.json <<< "{\"apiKey\":\"$OMNIROUTE_KEY\",\"baseUrl\":\"$OMNIROUTE_URL\"}" -cat >> ~/.bashrc << EOF -export OPENAI_BASE_URL="$OMNIROUTE_URL" -export OPENAI_API_KEY="$OMNIROUTE_KEY" -export ANTHROPIC_BASE_URL="$OMNIROUTE_URL" -export ANTHROPIC_API_KEY="$OMNIROUTE_KEY" -EOF - -source ~/.bashrc -echo "โœ… All CLIs installed and configured for OmniRoute" -``` diff --git a/docs/i18n/vi/CODEBASE_DOCUMENTATION.md b/docs/i18n/vi/CODEBASE_DOCUMENTATION.md deleted file mode 100644 index e2d7950052..0000000000 --- a/docs/i18n/vi/CODEBASE_DOCUMENTATION.md +++ /dev/null @@ -1,593 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CODEBASE_DOCUMENTATION.md) - ---- - -# omniroute โ€” Codebase Documentation - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/CODEBASE_DOCUMENTATION.md) - -> A comprehensive, beginner-friendly guide to the **omniroute** multi-provider AI proxy router. - ---- - -## 1. 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
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, Qoder, 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 | -| Qoder | 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"] -``` diff --git a/docs/i18n/vi/CONTRIBUTING.md b/docs/i18n/vi/CONTRIBUTING.md new file mode 100644 index 0000000000..ecfaee5c75 --- /dev/null +++ b/docs/i18n/vi/CONTRIBUTING.md @@ -0,0 +1,299 @@ +# Contributing to OmniRoute (Tiแบฟng Viแป‡t) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CONTRIBUTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CONTRIBUTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CONTRIBUTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CONTRIBUTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CONTRIBUTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CONTRIBUTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CONTRIBUTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CONTRIBUTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CONTRIBUTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CONTRIBUTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CONTRIBUTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CONTRIBUTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CONTRIBUTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CONTRIBUTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CONTRIBUTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CONTRIBUTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CONTRIBUTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CONTRIBUTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CONTRIBUTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CONTRIBUTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CONTRIBUTING.md) + +--- + +Thank you for your interest in contributing! This guide covers everything you need to get started. + +--- + +## Development Setup + +### Prerequisites + +- **Node.js** >= 18 < 24 (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` | `20128` | Server port | +| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | Base URL for frontend | +| `JWT_SECRET` | (generate above) | JWT signing secret | +| `INITIAL_PASSWORD` | `CHANGEME` | First login password | +| `APP_LOG_LEVEL` | `info` | Log verbosity level | + +### Dashboard Settings + +The dashboard provides UI toggles for features that can also be configured via environment variables: + +| Setting Location | Toggle | Description | +| ------------------- | ------------------ | ------------------------------ | +| Settings โ†’ Advanced | Debug Mode | Enable debug request logs (UI) | +| Settings โ†’ General | Sidebar Visibility | Show/hide sidebar sections | + +These settings are stored in the database and persist across restarts, overriding env var defaults when set. + +### 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:20128/dashboard` +- **API**: `http://localhost:20128/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`, `mcp`, `a2a`, `memory`, `skills`. + +--- + +## Running Tests + +```bash +# All tests (unit + vitest + ecosystem + e2e) +npm run test:all + +# Single test file (Node.js native test runner โ€” most tests use this) +node --import tsx/esm --test tests/unit/your-file.test.mjs + +# Vitest (MCP server, autoCombo, cache) +npm run test:vitest + +# E2E tests (requires Playwright) +npm run test:e2e + +# Protocol clients E2E (MCP transports, A2A) +npm run test:protocols:e2e + +# Ecosystem compatibility tests +npm run test:ecosystem + +# Coverage (55% min statements/lines/functions; 60% branches) +npm run test:coverage +npm run coverage:report + +# Lint + format check +npm run lint +npm run check +``` + +Coverage notes: + +- `npm run test:coverage` measures source coverage for the main unit test suite, excludes `tests/**`, and includes `open-sse/**` +- `npm run coverage:report` prints the detailed file-by-file report from the latest coverage run +- `npm run test:coverage:legacy` preserves the older metric for historical comparison +- See `docs/COVERAGE_PLAN.md` for the phased coverage improvement roadmap + +Current test status: **122 unit test files** covering: + +- Provider translators and format conversion +- Rate limiting, circuit breaker, and resilience +- Semantic cache, idempotency, progress tracking +- Database operations and schema (21 DB modules) +- OAuth flows and authentication +- API endpoint validation (Zod v4) +- MCP server tools and scope enforcement +- Memory and Skills systems + +--- + +## Code Style + +- **ESLint** โ€” Run `npm run lint` before committing +- **Prettier** โ€” Auto-formatted via `lint-staged` on commit (2 spaces, semicolons, double quotes, 100 char width, es5 trailing commas) +- **TypeScript** โ€” All `src/` code uses `.ts`/`.tsx`; `open-sse/` uses `.ts`/`.js`; document with TSDoc (`@param`, `@returns`, `@throws`) +- **No `eval()`** โ€” ESLint enforces `no-eval`, `no-implied-eval`, `no-new-func` +- **Zod validation** โ€” Use Zod v4 schemas for all API input validation +- **Naming**: Files = camelCase/kebab-case, components = PascalCase, constants = UPPER_SNAKE + +--- + +## Project Structure + +``` +src/ # TypeScript (.ts / .tsx) +โ”œโ”€โ”€ app/ # Next.js 16 App Router +โ”‚ โ”œโ”€โ”€ (dashboard)/ # Dashboard pages (23 sections) +โ”‚ โ”œโ”€โ”€ api/ # API routes (51 directories) +โ”‚ โ””โ”€โ”€ login/ # Auth pages (.tsx) +โ”œโ”€โ”€ domain/ # Policy engine (policyEngine, comboResolver, costRules, etc.) +โ”œโ”€โ”€ lib/ # Core business logic (.ts) +โ”‚ โ”œโ”€โ”€ a2a/ # Agent-to-Agent v0.3 protocol server +โ”‚ โ”œโ”€โ”€ acp/ # Agent Communication Protocol registry +โ”‚ โ”œโ”€โ”€ compliance/ # Compliance policy engine +โ”‚ โ”œโ”€โ”€ db/ # SQLite database layer (21 modules + 16 migrations) +โ”‚ โ”œโ”€โ”€ memory/ # Persistent conversational memory +โ”‚ โ”œโ”€โ”€ oauth/ # OAuth providers, services, and utilities +โ”‚ โ”œโ”€โ”€ skills/ # Extensible skill framework +โ”‚ โ”œโ”€โ”€ usage/ # Usage tracking and cost calculation +โ”‚ โ””โ”€โ”€ localDb.ts # Re-export layer only โ€” never add logic here +โ”œโ”€โ”€ middleware/ # Request middleware (promptInjectionGuard) +โ”œโ”€โ”€ mitm/ # MITM proxy (cert, DNS, target routing) +โ”œโ”€โ”€ shared/ +โ”‚ โ”œโ”€โ”€ components/ # React components (.tsx) +โ”‚ โ”œโ”€โ”€ constants/ # Provider definitions (60+), MCP scopes, routing strategies +โ”‚ โ”œโ”€โ”€ utils/ # Circuit breaker, sanitizer, auth helpers +โ”‚ โ””โ”€โ”€ validation/ # Zod v4 schemas +โ””โ”€โ”€ sse/ # SSE proxy pipeline + +open-sse/ # @omniroute/open-sse workspace +โ”œโ”€โ”€ executors/ # 14 provider-specific request executors +โ”œโ”€โ”€ handlers/ # 11 request handlers (chat, responses, embeddings, images, etc.) +โ”œโ”€โ”€ mcp-server/ # MCP server (25 tools, 3 transports, 10 scopes) +โ”œโ”€โ”€ services/ # 36+ services (combo, autoCombo, rateLimitManager, etc.) +โ”œโ”€โ”€ translator/ # Format translators (OpenAI โ†” Claude โ†” Gemini โ†” Responses โ†” Ollama) +โ”œโ”€โ”€ transformer/ # Responses API transformer +โ””โ”€โ”€ utils/ # 22 utility modules (stream, TLS, proxy, logging) + +electron/ # Electron desktop app (cross-platform) + +tests/ +โ”œโ”€โ”€ unit/ # Node.js test runner (122 test files) +โ”œโ”€โ”€ integration/ # Integration tests +โ”œโ”€โ”€ e2e/ # Playwright tests +โ”œโ”€โ”€ security/ # Security tests +โ”œโ”€โ”€ translator/ # Translator-specific tests +โ””โ”€โ”€ load/ # Load tests + +docs/ # Documentation +โ”œโ”€โ”€ ARCHITECTURE.md # System architecture +โ”œโ”€โ”€ API_REFERENCE.md # All endpoints +โ”œโ”€โ”€ USER_GUIDE.md # Provider setup, CLI integration +โ”œโ”€โ”€ TROUBLESHOOTING.md # Common issues +โ”œโ”€โ”€ MCP-SERVER.md # MCP server (25 tools) +โ”œโ”€โ”€ A2A-SERVER.md # A2A agent protocol +โ”œโ”€โ”€ AUTO-COMBO.md # Auto-combo engine +โ”œโ”€โ”€ CLI-TOOLS.md # CLI tools integration +โ”œโ”€โ”€ COVERAGE_PLAN.md # Test coverage improvement plan +โ”œโ”€โ”€ openapi.yaml # OpenAPI specification +โ””โ”€โ”€ adr/ # Architecture Decision Records +``` + +--- + +## Adding a New Provider + +### Step 1: Register Provider Constants + +Add to `src/shared/constants/providers.ts` โ€” Zod-validated at module load. + +### Step 2: Add Executor (if custom logic needed) + +Create executor in `open-sse/executors/your-provider.ts` extending the base executor. + +### Step 3: Add Translator (if non-OpenAI format) + +Create request/response translators in `open-sse/translator/`. + +### Step 4: Add OAuth Config (if OAuth-based) + +Add OAuth credentials in `src/lib/oauth/constants/oauth.ts` and service in `src/lib/oauth/services/`. + +### Step 5: Register Models + +Add model definitions in `open-sse/config/providerRegistry.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 +- [ ] All inputs validated with Zod schemas +- [ ] CHANGELOG updated (if user-facing change) +- [ ] Documentation updated (if applicable) + +--- + +## Releasing + +Releases are managed via the `/generate-release` workflow. When a new GitHub Release is created, the package is **automatically published to npm** via GitHub Actions. + +--- + +## Getting Help + +- **Architecture**: See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) +- **API Reference**: See [`docs/API_REFERENCE.md`](docs/API_REFERENCE.md) +- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **ADRs**: See `docs/adr/` for architectural decision records diff --git a/docs/i18n/vi/FEATURES.md b/docs/i18n/vi/FEATURES.md deleted file mode 100644 index 0bb0827f2c..0000000000 --- a/docs/i18n/vi/FEATURES.md +++ /dev/null @@ -1,147 +0,0 @@ -# OmniRoute โ€” Dashboard Features Gallery (Tiแบฟng Viแป‡t) - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) - -> ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../docs/FEATURES.md) - ---- - -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 (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. - -![Providers Dashboard](screenshots/01-providers.png) - ---- - -## ๐ŸŽจ Combos - -Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. - -![Combos Dashboard](screenshots/02-combos.png) - ---- - -## ๐Ÿ“Š Analytics - -Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. - -![Analytics Dashboard](screenshots/03-analytics.png) - ---- - -## ๐Ÿฅ System Health - -Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. - -![Health Dashboard](screenshots/04-health.png) - ---- - -## ๐Ÿ”ง Translator Playground - -Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). - -![Translator Playground](screenshots/05-translator.png) - ---- - -## ๐ŸŽฎ Model Playground _(v2.0.9+)_ - -Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. - ---- - -## ๐ŸŽจ Themes _(v2.0.5+)_ - -Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. - ---- - -## โš™๏ธ Settings - -Comprehensive settings panel with tabs: - -- **General** โ€” System storage, backup management (export/import database) -- **Appearance** โ€” Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls -- **Security** โ€” API endpoint protection, custom provider blocking, IP filtering, session info -- **Routing** โ€” Model aliases, background task degradation -- **Resilience** โ€” Rate limit persistence, circuit breaker tuning -- **Advanced** โ€” Configuration overrides - -![Settings Dashboard](screenshots/06-settings.png) - ---- - -## ๐Ÿ”ง CLI Tools - -One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. - -![CLI Tools Dashboard](screenshots/07-cli-tools.png) - ---- - -## ๐Ÿค– CLI Agents _(v2.0.11+)_ - -Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: - -- **Installation status** โ€” Installed / Not Found with version detection -- **Protocol badges** โ€” stdio, HTTP, etc. -- **Custom agents** โ€” Register any CLI tool via form (name, binary, version command, spawn args) -- **CLI Fingerprint Matching** โ€” Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP - ---- - -## ๐Ÿ–ผ๏ธ Media _(v2.0.3+)_ - -Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. - ---- - -## ๐Ÿ“ Request Logs - -Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. - -![Usage Logs](screenshots/08-usage.png) - ---- - -## ๐ŸŒ API Endpoint - -Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloud proxy support for remote access. - -![Endpoint Dashboard](screenshots/09-endpoint.png) - ---- - -## ๐Ÿ”‘ API Key Management - -Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. - ---- - -## ๐Ÿ“‹ Audit Log - -Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. - ---- - -## ๐Ÿ–ฅ๏ธ Desktop Application - -Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. - -Key features: - -- Server readiness polling (no blank screen on cold start) -- System tray with port management -- Content Security Policy -- Single-instance lock -- Auto-update on restart -- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) -- Hardened Electron build packaging โ€” symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+) - -๐Ÿ“– See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/vi/MCP-SERVER.md b/docs/i18n/vi/MCP-SERVER.md deleted file mode 100644 index 829acd30b1..0000000000 --- a/docs/i18n/vi/MCP-SERVER.md +++ /dev/null @@ -1,87 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/MCP-SERVER.md) - ---- - -# OmniRoute MCP Server Documentation - -> Model Context Protocol server with 16 intelligent tools - -## Installation - -OmniRoute MCP is built-in. Start it with: - -```bash -omniroute --mcp -``` - -Or via the open-sse transport: - -```bash -# HTTP streamable transport (port 20130) -omniroute --dev # MCP auto-starts on /mcp endpoint -``` - -## IDE Configuration - -See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup. - ---- - -## Essential Tools (8) - -| Tool | Description | -| :------------------------------ | :--------------------------------------- | -| `omniroute_get_health` | Gateway health, circuit breakers, uptime | -| `omniroute_list_combos` | All configured combos with models | -| `omniroute_get_combo_metrics` | Performance metrics for a specific combo | -| `omniroute_switch_combo` | Switch active combo by ID/name | -| `omniroute_check_quota` | Quota status per provider or all | -| `omniroute_route_request` | Send a chat completion through OmniRoute | -| `omniroute_cost_report` | Cost analytics for a time period | -| `omniroute_list_models_catalog` | Full model catalog with capabilities | - -## Advanced Tools (8) - -| Tool | Description | -| :--------------------------------- | :---------------------------------------------- | -| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | -| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | -| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | -| `omniroute_test_combo` | Live-test all models in a combo | -| `omniroute_get_provider_metrics` | Detailed metrics for one provider | -| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | -| `omniroute_explain_route` | Explain a past routing decision | -| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | - -## Authentication - -MCP tools are authenticated via API key scopes. Each tool requires specific scopes: - -| Scope | Tools | -| :------------- | :----------------------------------------------- | -| `read:health` | get_health, get_provider_metrics | -| `read:combos` | list_combos, get_combo_metrics | -| `write:combos` | switch_combo | -| `read:quota` | check_quota | -| `write:route` | route_request, simulate_route, test_combo | -| `read:usage` | cost_report, get_session_snapshot, explain_route | -| `write:config` | set_budget_guard, set_resilience_profile | -| `read:models` | list_models_catalog, best_combo_for_task | - -## Audit Logging - -Every tool call is logged to `mcp_tool_audit` with: - -- Tool name, arguments, result -- Duration (ms), success/failure -- API key hash, timestamp - -## Files - -| File | Purpose | -| :------------------------------------------- | :------------------------------------------ | -| `open-sse/mcp-server/server.ts` | MCP server creation + 16 tool registrations | -| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport | -| `open-sse/mcp-server/auth.ts` | API key + scope validation | -| `open-sse/mcp-server/audit.ts` | Tool call audit logging | -| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers | diff --git a/docs/i18n/vi/README.md b/docs/i18n/vi/README.md index 02e4dd7a94..4f5fead77a 100644 --- a/docs/i18n/vi/README.md +++ b/docs/i18n/vi/README.md @@ -1,12 +1,12 @@ # ๐Ÿš€ OmniRoute โ€” The Free AI Gateway (Tiแบฟng Viแป‡t) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/README.md) --- ### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback. -_Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now with **MCP & A2A** agent orchestration._ +_Your universal API proxy โ€” one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._ **Chat Completions โ€ข Embeddings โ€ข Image Generation โ€ข Video โ€ข Music โ€ข Audio โ€ข Reranking โ€ข **Web Search** โ€ข MCP Server โ€ข A2A Protocol โ€ข 100% TypeScript** @@ -46,15 +46,17 @@ _Your universal API proxy โ€” one endpoint, 67+ providers, zero downtime. Now wi > - `APP_LOG_FILE_PATH` > - `APP_LOG_MAX_FILE_SIZE` > - `APP_LOG_RETENTION_DAYS` +> - `APP_LOG_MAX_FILES` > - `APP_LOG_LEVEL` > - `APP_LOG_FORMAT` > - `CALL_LOG_RETENTION_DAYS` +> - `CALL_LOG_MAX_ENTRIES` > > For release details and upgrade notes, see the [CHANGELOG](CHANGELOG.md). --- -## ๐Ÿ†• What's New in v3.0.0 +## ๐Ÿ†• What's New > **Upgrading from v2.9.5?** โ€” See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes. @@ -274,7 +276,7 @@ Developers pay $20โ€“200/month for Claude Pro, Codex Pro, or GitHub Copilot. Eve - **Smart 4-Tier Fallback** โ€” If subscription quota runs out, automatically redirects to API Key โ†’ Cheap โ†’ Free with zero manual intervention - **Real-Time Quota Tracking** โ€” Shows token consumption in real-time with reset countdown (5h, daily, weekly) - **Multi-Account Support** โ€” Multiple accounts per provider with auto round-robin โ€” when one runs out, switches to the next -- **Custom Combos** โ€” Customizable fallback chains with 6 balancing strategies (fill-first, round-robin, P2C, random, least-used, cost-optimized) +- **Custom Combos** โ€” Customizable fallback chains with 9 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random) - **Codex Business Quotas** โ€” Business/Team workspace quota monitoring directly in the dashboard @@ -286,7 +288,7 @@ OpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If **How OmniRoute solves it:** -- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 67+ providers +- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 60+ providers - **Format Translation** โ€” Automatic and transparent: OpenAI โ†” Claude โ†” Gemini โ†” Responses API - **Response Sanitization** โ€” Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+ - **Role Normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI providers; `system` โ†’ `user` for GLM/ERNIE @@ -372,7 +374,7 @@ Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code.. - **CLI Tools Dashboard** โ€” Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline - **GitHub Copilot Config Generator** โ€” Generates `chatLanguageModels.json` for VS Code with bulk model selection - **Onboarding Wizard** โ€” Guided 4-step setup for first-time users -- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 67+ providers +- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 60+ providers @@ -419,7 +421,7 @@ When a call fails, the dev doesn't know if it was a rate limit, expired token, w - **SQLite Proxy Logs** โ€” Persistent logs that survive server restarts - **Translator Playground** โ€” 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time) - **Request Telemetry** โ€” p50/p95/p99 latency + X-Request-Id tracing -- **File-Based Logging with Rotation** โ€” Console interceptor captures everything to JSON log with size-based rotation +- **File-Based Logging with Rotation** โ€” App logs rotate by size, retention days, and archive count; call log artifacts rotate by retention days and file count - **System Info Report** โ€” `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage. @@ -514,7 +516,7 @@ Developers who want all responses in a specific language, with a specific tone, - **System Prompt Injection** โ€” Global prompt applied to all requests - **Thinking Budget Validation** โ€” Reasoning token allocation control per request (passthrough, auto, custom, adaptive) -- **6 Routing Strategies** โ€” Global strategies that determine how requests are distributed +- **9 Routing Strategies** โ€” Global strategies that determine how requests are distributed - **Wildcard Router** โ€” `provider/*` patterns route dynamically to any provider - **Combo Enable/Disable Toggle** โ€” Toggle combos directly from the dashboard - **Provider Toggle** โ€” Enable/disable all connections for a provider with one click @@ -581,7 +583,7 @@ Different clients should have least-privilege access to tool categories. **How OmniRoute solves it:** -- 9 granular MCP scopes for controlled tool access +- 10 granular MCP scopes for controlled tool access - Scope enforcement and visibility in MCP management UI - Safe default posture for operational tooling @@ -1325,19 +1327,19 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. ### ๐Ÿค– Agent & Protocol Operations (v2.0) -| Feature | What It Does | -| ------------------------------------- | -------------------------------------------------------------------------------------------------- | -| ๐Ÿ”ง **MCP Server (16 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`) | -| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | -| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | -| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | -| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | -| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | -| ๐Ÿ” **MCP Scope Enforcement** | 9 granular scope permissions for controlled tool access | -| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | -| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | -| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | -| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | +| Feature | What It Does | +| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| ๐Ÿ”ง **MCP Server (25 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools | +| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | +| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | +| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | +| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | +| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | +| ๐Ÿ” **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access | +| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | +| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | +| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | +| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | ### ๐Ÿง  Routing & Intelligence @@ -1348,7 +1350,7 @@ OmniRoute v2.0 is built as an operational platform, not just a relay proxy. | ๐Ÿ”„ **Format Translation** | OpenAI โ†” Claude โ†” Gemini โ†” Responses with schema-safe conversions | | ๐Ÿ‘ฅ **Multi-Account Support** | Multiple accounts per provider with intelligent selection | | ๐Ÿ”„ **Auto Token Refresh** | OAuth tokens refresh automatically with retry | -| ๐ŸŽจ **Custom Combos** | 6 balancing strategies + fallback chain control | +| ๐ŸŽจ **Custom Combos** | 9 balancing strategies + fallback chain control | | ๐ŸŒ **Wildcard Router** | `provider/*` dynamic routing | | ๐Ÿง  **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits | | ๐Ÿ”€ **Model Aliases** | Built-in + custom model aliasing and migration safety | @@ -1949,6 +1951,7 @@ opencode - Request artifacts are written to `DATA_DIR/call_logs/` as one JSON file per request - Enable pipeline capture from Dashboard โ†’ Logs โ†’ Request Logs if you need detailed per-stage payloads - Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log` +- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed **Connection test shows "Invalid" for OpenAI-compatible providers** diff --git a/docs/i18n/vi/RELEASE_CHECKLIST.md b/docs/i18n/vi/RELEASE_CHECKLIST.md deleted file mode 100644 index 903e812c3f..0000000000 --- a/docs/i18n/vi/RELEASE_CHECKLIST.md +++ /dev/null @@ -1,37 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/RELEASE_CHECKLIST.md) - ---- - -# Release Checklist - -Use this checklist before tagging or publishing a new OmniRoute release. - -## Version and Changelog - -1. Bump `package.json` version (`x.y.z`) in the release branch. -2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: - - `## [x.y.z] โ€” YYYY-MM-DD` -3. Keep `## [Unreleased]` as the first changelog section for upcoming work. -4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. - -## API Docs - -1. Update `docs/openapi.yaml`: - - `info.version` must equal `package.json` version. -2. Validate endpoint examples if API contracts changed. - -## Runtime Docs - -1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. -2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. -3. Update localized docs if source docs changed significantly. - -## Automated Check - -Run the sync guard locally before opening PR: - -```bash -npm run check:docs-sync -``` - -CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/vi/SECURITY.md b/docs/i18n/vi/SECURITY.md new file mode 100644 index 0000000000..1adb36e79c --- /dev/null +++ b/docs/i18n/vi/SECURITY.md @@ -0,0 +1,179 @@ +# Security Policy (Tiแบฟng Viแป‡t) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../SECURITY.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/SECURITY.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/SECURITY.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/SECURITY.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/SECURITY.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/SECURITY.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/SECURITY.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/SECURITY.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/SECURITY.md) + +--- + +## 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 | +| ------- | -------------- | +| 3.4.x | โœ… Active | +| 3.0.x | โœ… Security | +| < 3.0.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 | +| **MCP Scopes** | 10 granular scopes for MCP tool access control | + +### ๐Ÿ›ก๏ธ 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:::` +- 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** | Allowlist/blocklist IP ranges in dashboard | +| **Rate Limiting** | Per-provider rate limits with automatic backoff | +| **Anti-Thundering Herd** | Mutex + per-connection locking prevents cascading 502s | +| **TLS Fingerprint** | Browser-like TLS fingerprint spoofing to reduce bot detection | +| **CLI Fingerprint** | Per-provider header/body ordering to match native CLI signatures | + +### ๐Ÿ”Œ Resilience & Availability + +| 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 `CALL_LOG_RETENTION_DAYS` | +| **No-Log Opt-out** | Per API key `noLog` flag disables request logging | +| **Audit Log** | Administrative actions tracked in `audit_log` table | +| **MCP Audit** | SQLite-backed audit logging for all MCP tool calls | +| **Zod Validation** | All API inputs validated with Zod v4 schemas at module load | + +--- + +## 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 +- Provider constants validated at module load via Zod (`src/shared/validation/providerSchema.ts`) diff --git a/docs/i18n/vi/TROUBLESHOOTING.md b/docs/i18n/vi/TROUBLESHOOTING.md deleted file mode 100644 index 63c148000a..0000000000 --- a/docs/i18n/vi/TROUBLESHOOTING.md +++ /dev/null @@ -1,258 +0,0 @@ -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/TROUBLESHOOTING.md) - ---- - -# Troubleshooting - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](i18n/pt-BR/TROUBLESHOOTING.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](i18n/es/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](i18n/fr/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](i18n/it/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](i18n/ru/TROUBLESHOOTING.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](i18n/zh-CN/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](i18n/de/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](i18n/in/TROUBLESHOOTING.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](i18n/th/TROUBLESHOOTING.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](i18n/uk-UA/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](i18n/ar/TROUBLESHOOTING.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](i18n/ja/TROUBLESHOOTING.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](i18n/vi/TROUBLESHOOTING.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](i18n/bg/TROUBLESHOOTING.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](i18n/da/TROUBLESHOOTING.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](i18n/fi/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](i18n/he/TROUBLESHOOTING.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](i18n/hu/TROUBLESHOOTING.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](i18n/id/TROUBLESHOOTING.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](i18n/ko/TROUBLESHOOTING.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](i18n/ms/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](i18n/nl/TROUBLESHOOTING.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](i18n/no/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](i18n/pt/TROUBLESHOOTING.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](i18n/ro/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](i18n/pl/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](i18n/sk/TROUBLESHOOTING.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](i18n/sv/TROUBLESHOOTING.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](i18n/phi/TROUBLESHOOTING.md) - -Common problems and solutions for OmniRoute. - ---- - -## Quick Fixes - -| Problem | Solution | -| ----------------------------- | ------------------------------------------------------------------ | -| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | -| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | -| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | -| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | -| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | - ---- - -## Provider Issues - -### "Language model did not provide messages" - -**Cause:** Provider quota exhausted. - -**Fix:** - -1. 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, Qoder) 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}/storage.sqlite` (providers, combos, aliases, keys, settings) -- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` -- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) - ---- - -## Circuit Breaker Issues - -### Provider stuck in OPEN state - -When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. - -**Fix:** - -1. 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 -- **SDK returns raw string instead of object** โ€” Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures -- **GLM/ERNIE rejects `system` role** โ€” Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models -- **`developer` role not recognized** โ€” Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers -- **`json_schema` not working with Gemini** โ€” Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` - ---- - -## Resilience Settings - -### Auto rate-limit not triggering - -- 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. - ---- - -## Optional RAG / LLM failure taxonomy (16 problems) - -Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. - -In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. - -If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: - -- retrieval drift and broken context boundaries -- empty or stale indexes and vector stores -- embedding versus semantic mismatch -- prompt assembly and context window issues -- logic collapse and overconfident answers -- long chain and agent coordination failures -- multi agent memory and role drift -- deployment and bootstrap ordering problems - -The idea is simple: - -1. When you investigate a bad response, capture: - - user task and request - - route or provider combo in OmniRoute - - any RAG context used downstream (retrieved documents, tool calls, etc) -2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` โ€ฆ `No.16`). -3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. -4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. - -Full text and concrete recipes live here (MIT license, text only): - -[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) - -You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. - ---- - -## Still Stuck? - -- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details -- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints -- **Health Dashboard**: Check **Dashboard โ†’ Health** for real-time system status -- **Translator**: Use **Dashboard โ†’ Translator** to debug format issues diff --git a/docs/i18n/vi/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/vi/VM_DEPLOYMENT_GUIDE.md deleted file mode 100644 index de3427f413..0000000000 --- a/docs/i18n/vi/VM_DEPLOYMENT_GUIDE.md +++ /dev/null @@ -1,401 +0,0 @@ -# OmniRoute โ€” Hฦฐแป›ng dแบซn triแปƒn khai trรชn VM vแป›i Cloudflare - -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](../pt-BR/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](../es/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](../fr/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](../it/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](../ru/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](../zh-CN/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](../de/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](../in/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](../th/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](../uk-UA/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](../ar/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](../ja/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](../vi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](../bg/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](../da/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](../fi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](../he/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](../hu/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](../id/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](../ko/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](../ms/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](../nl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](../no/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](../pt/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](../ro/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](../pl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](../sk/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](../sv/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](../phi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](../cs/VM_DEPLOYMENT_GUIDE.md) - -Hฦฐแป›ng dแบซn ฤ‘แบงy ฤ‘แปง ฤ‘แปƒ cร i ฤ‘แบทt vร  ฤ‘แป‹nh cแบฅu hรฌnh OmniRoute trรชn VM (VPS) vแป›i miแปn ฤ‘ฦฐแปฃc quแบฃn lรฝ qua Cloudflare. - ---- - -## ฤiแปu kiแป‡n tiรชn quyแบฟt - -| Mแปฅc | Tแป‘i thiแปƒu | ฤฦฐแปฃc ฤ‘แป xuแบฅt | -| ---------- | -------------------------- | ---------------- | -| **CPU** | 1 vCPU | 2 vCPU | -| **RAM** | 1 GB | 2 GB | -| **ฤฤฉa** | SSD 10GB | SSD 25 GB | -| **HฤH** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS | -| **Miแปn** | ฤรฃ ฤ‘ฤƒng kรฝ trรชn Cloudflare | โ€” | -| **Docker** | Cรดng cแปฅ Docker 24+ | Docker 27+ | - -**Cรกc nhร  cung cแบฅp ฤ‘รฃ ฤ‘ฦฐแปฃc thแปญ nghiแป‡m**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. - ---- - -## 1. Cแบฅu hรฌnh VM - -### 1.1 Tแบกo phiรชn bแบฃn - -Trรชn nhร  cung cแบฅp VPS ฦฐa thรญch cแปงa bแบกn: - -- Chแปn Ubuntu 24.04 LTS -- Chแปn gรณi tแป‘i thiแปƒu (1 vCPU / 1 GB RAM) -- ฤแบทt mแบญt khแบฉu root mแบกnh hoแบทc ฤ‘แป‹nh cแบฅu hรฌnh khรณa SSH -- Lฦฐu รฝ **IP cรดng cแป™ng** (vรญ dแปฅ: `203.0.113.10`) - -### 1.2 Kแบฟt nแป‘i qua SSH - -```bash -ssh root@203.0.113.10 -``` - -### 1.3 Cแบญp nhแบญt hแป‡ thแป‘ng - -```bash -apt update && apt upgrade -y -``` - -### 1.4 Cร i ฤ‘แบทt Docker - -```bash -# Install dependencies -apt install -y ca-certificates curl gnupg - -# Add official Docker repository -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 Cร i ฤ‘แบทt nginx - -```bash -apt install -y nginx -``` - -### 1.6 Cแบฅu hรฌnh tฦฐแปng lแปญa (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 -``` - -> **Mแบนo**: ฤแปƒ bแบฃo mแบญt tแป‘i ฤ‘a, hรฃy hแบกn chแบฟ cแป•ng 80 vร  443 ฤ‘แป‘i vแป›i IP Cloudflare. Xem phแบงn [Advanced Security](#advanced-security). - ---- - -## 2. Cร i ฤ‘แบทt OmniRoute - -### 2.1 Tแบกo thฦฐ mแปฅc cแบฅu hรฌnh - -```bash -mkdir -p /opt/omniroute -``` - -### 2.2 Tแบกo tแป‡p biแบฟn mรดi trฦฐแปng - -```bash -cat > /opt/omniroute/.env << โ€˜EOFโ€™ -# === Security === -JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY -INITIAL_PASSWORD=YourSecurePassword123! -API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY -STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY -STORAGE_ENCRYPTION_KEY_VERSION=v1 -MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT - -# === 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 (change to your domain) === -BASE_URL=https://llms.seudominio.com -NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com - -# === Cloud Sync (optional) === -# CLOUD_URL=https://cloud.omniroute.online -# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online -EOF -``` - -> โš ๏ธ **QUAN TRแปŒNG**: Tแบกo cรกc khรณa bรญ mแบญt duy nhแบฅt! Sแปญ dแปฅng `openssl rand -hex 32` cho mแป—i khรณa. - -### 2.3 KhแปŸi ฤ‘แป™ng 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 Xรกc minh rแบฑng nรณ ฤ‘ang chแบกy - -```bash -docker ps | grep omniroute -docker logs omniroute --tail 20 -``` - -Nรณ sแบฝ hiแปƒn thแป‹: `[DB] SQLite database ready` vร  `listening on port 20128`. - ---- - -## 3. Cแบฅu hรฌnh nginx (Proxy ngฦฐแปฃc) - -### 3.1 Tแบกo chแปฉng chแป‰ SSL (Nguแป“n gแป‘c Cloudflare) - -Trong bแบฃng ฤ‘iแปu khiแปƒn Cloudflare: - -1. ฤi tแป›i **SSL/TLS โ†’ Mรกy chแปง gแป‘c** -2. Nhแบฅp vร o **Tแบกo chแปฉng chแป‰** -3. Giแปฏ nguyรชn giรก trแป‹ mแบทc ฤ‘แป‹nh (15 nฤƒm, \*.yourdomain.com) -4. Sao chรฉp **Chแปฉng chแป‰ xuแบฅt xแปฉ** vร  **Khรณa riรชng** - -```bash -mkdir -p /etc/nginx/ssl - -# Paste the certificate -nano /etc/nginx/ssl/origin.crt - -# Paste the private key -nano /etc/nginx/ssl/origin.key - -chmod 600 /etc/nginx/ssl/origin.key -``` - -### 3.2 Cแบฅu hรฌnh Nginx - -```bash -cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ -# Default server โ€” blocks direct access via 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.yourdomain.com; # Change to your domain - - 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.yourdomain.com; - return 301 https://$server_name$request_uri; -} -NGINX -``` - -### 3.3 Kรญch hoแบกt vร  kiแปƒm tra - -```bash -# Remove default configuration -rm -f /etc/nginx/sites-enabled/default - -# Enable OmniRoute -ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute - -# Test and reload -nginx -t && systemctl reload nginx -``` - ---- - -## 4. Cแบฅu hรฌnh DNS Cloudflare - -### 4.1 Thรชm bแบฃn ghi DNS - -Trong bแบฃng ฤ‘iแปu khiแปƒn Cloudflare โ†’ DNS: - -| Loแบกi | Tรชn | Nแป™i dung | แปฆy nhiแป‡m | -| ---- | ------ | ---------------------- | ---------------- | -| A | `llms` | `203.0.113.10` (IP VM) | โœ… ฤฦฐแปฃc แปงy quyแปn | - -### 4.2 ฤแป‹nh cแบฅu hรฌnh SSL - -Trong **SSL/TLS โ†’ Tแป•ng quan**: - -- Chแบฟ ฤ‘แป™: **ฤแบงy ฤ‘แปง (Nghiรชm ngแบทt)** - -Trong **SSL/TLS โ†’ Chแปฉng chแป‰ biรชn**: - -- Luรดn sแปญ dแปฅng HTTPS: โœ… Bแบญt -- Phiรชn bแบฃn TLS tแป‘i thiแปƒu: TLS 1.2 -- Tแปฑ ฤ‘แป™ng ghi lแบกi HTTPS: โœ… Bแบญt - -### 4.3 Kiแปƒm tra - -```bash -curl -sI https://llms.seudominio.com/health -# Should return HTTP/2 200 -``` - ---- - -## 5. Vแบญn hร nh vร  bแบฃo trรฌ - -### Nรขng cแบฅp lรชn phiรชn bแบฃn mแป›i - -```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 -``` - -### Xem nhแบญt kรฝ - -```bash -docker logs -f omniroute # Real-time stream -docker logs omniroute --tail 50 # Last 50 lines -``` - -### Sao lฦฐu cฦก sแปŸ dแปฏ liแป‡u thแปง cรดng - -```bash -# Copy data from the volume to the host -docker cp omniroute:/app/data ./backup-$(date +%F) - -# Or compress the entire volume -docker run --rm -v omniroute-data:/data -v $(pwd):/backup \ - alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data -``` - -### Khรดi phแปฅc tแปซ bแบฃn sao lฦฐu - -```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. Bแบฃo mแบญt nรขng cao - -### Hแบกn chแบฟ nginx ฤ‘แป‘i vแป›i IP Cloudflare - -```bash -cat > /etc/nginx/cloudflare-ips.conf << โ€˜CFโ€™ -# Cloudflare IPv4 ranges โ€” update periodically -# 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 -``` - -Thรชm phแบงn sau vร o `nginx.conf` bรชn trong khแป‘i `http {}`: - -```nginx -include /etc/nginx/cloudflare-ips.conf; -``` - -### Cร i ฤ‘แบทt failed2ban - -```bash -apt install -y fail2ban -systemctl enable fail2ban -systemctl start fail2ban - -# Check status -fail2ban-client status sshd -``` - -### Chแบทn quyแปn truy cแบญp trแปฑc tiแบฟp vร o cแป•ng Docker - -```bash -# Prevent direct external access to port 20128 -iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP -iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT - -# Persist the rules -apt install -y iptables-persistent -netfilter-persistent save -``` - ---- - -## 7. Triแปƒn khai lรชn Cloudflare Workers (Tรนy chแปn) - -ฤแปƒ truy cแบญp tแปซ xa thรดng qua Cloudflare Workers (khรดng ฤ‘แปƒ lแป™ trแปฑc tiแบฟp VM): - -```bash -# In the local repository -cd omnirouteCloud -npm install -npx wrangler login -npx wrangler deploy -``` - -Xem tร i liแป‡u ฤ‘แบงy ฤ‘แปง tแบกi [omnirouteCloud/README.md](../omnirouteCloud/README.md). - ---- - -## Tรณm tแบฏt cแป•ng - -| Cแบฃng | Dแป‹ch vแปฅ | Truy cแบญp | -| ----- | ----------- | ------------------------------- | -| 22 | SSH | Cรดng khai (vแป›i Fail2ban) | -| 80 | nginx HTTP | Chuyแปƒn hฦฐแป›ng โ†’ HTTPS | -| 443 | nginx HTTPS | Qua Proxy Cloudflare | -| 20128 | OmniRoute | Chแป‰ Localhost (thรดng qua nginx) | diff --git a/docs/i18n/vi/docs/A2A-SERVER.md b/docs/i18n/vi/docs/A2A-SERVER.md new file mode 100644 index 0000000000..60b1a7317e --- /dev/null +++ b/docs/i18n/vi/docs/A2A-SERVER.md @@ -0,0 +1,200 @@ +# OmniRoute A2A Server Documentation (Tiแบฟng Viแป‡t) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/A2A-SERVER.md) + +--- + +> Agent-to-Agent Protocol v0.3 โ€” OmniRoute as an intelligent routing agent + +## Agent Discovery + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements. + +--- + +## Authentication + +All `/a2a` requests require an API key via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server, authentication is bypassed. + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Sends a message to a skill and waits for the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a hello world in Python"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "uuid", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "..." }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}} + +: heartbeat 2026-03-03T17:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Available Skills + +| Skill | Description | +| :----------------- | :------------------------------------------------------------------------------------------------------------------------------ | +| `smart-routing` | Routes prompts through OmniRoute's intelligent pipeline. Returns response with routing explanation, cost, and resilience trace. | +| `quota-management` | Answers natural-language queries about provider quotas, suggests free combos, and provides quota rankings. | + +--- + +## Task Lifecycle + +``` +submitted โ†’ working โ†’ completed + โ†’ failed + โ†’ cancelled +``` + +- Tasks expire after 5 minutes (configurable) +- Terminal states: `completed`, `failed`, `cancelled` +- Event log tracks every state transition + +--- + +## Error Codes + +| Code | Meaning | +| :----- | :----------------------------- | +| -32700 | Parse error (invalid JSON) | +| -32600 | Invalid request / Unauthorized | +| -32601 | Method or skill not found | +| -32602 | Invalid params | +| -32603 | Internal error | + +--- + +## Integration Examples + +### Python (requests) + +```python +import requests + +resp = requests.post("http://localhost:20128/a2a", json={ + "jsonrpc": "2.0", "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Hello"}] + } +}, headers={"Authorization": "Bearer YOUR_KEY"}) + +result = resp.json()["result"] +print(result["artifacts"][0]["content"]) +print(result["metadata"]["routing_explanation"]) +``` + +### TypeScript (fetch) + +```typescript +const resp = await fetch("http://localhost:20128/a2a", { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: "Bearer YOUR_KEY", + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "1", + method: "message/send", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Hello" }], + }, + }), +}); +const { result } = await resp.json(); +console.log(result.metadata.routing_explanation); +``` diff --git a/docs/i18n/vi/docs/API_REFERENCE.md b/docs/i18n/vi/docs/API_REFERENCE.md new file mode 100644 index 0000000000..ff5c29b975 --- /dev/null +++ b/docs/i18n/vi/docs/API_REFERENCE.md @@ -0,0 +1,465 @@ +# API Reference (Tiแบฟng Viแป‡t) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/API_REFERENCE.md) + +--- + +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 | +| `X-Session-Id` | Request | Sticky session key for external session affinity | +| `x_session_id` | Request | Underscore variant also accepted (direct HTTP) | +| `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 | +| `X-OmniRoute-Session-Id` | Response | Effective session ID used by OmniRoute | + +> Nginx note: if you rely on underscore headers (for example `x_session_id`), enable `underscores_in_headers 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/stats + +# Clear all caches +DELETE /api/cache/stats +``` + +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/PATCH | 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 + provider summary (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`) | +| `/api/cache/stats` | 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 | + +### Tunnels + +| Endpoint | Method | Description | +| -------------------------- | ------ | ----------------------------------------------------------------------- | +| `/api/tunnels/cloudflared` | GET | Read Cloudflare Quick Tunnel install/runtime status for the dashboard | +| `/api/tunnels/cloudflared` | POST | Enable or disable the Cloudflare Quick Tunnel (`action=enable/disable`) | + +### 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`. + +### ACP Agents + +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | + +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). + +### Resilience & Rate Limits + +| Endpoint | Method | Description | +| ----------------------- | --------- | ------------------------------- | +| `/api/resilience` | GET/PATCH | 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` diff --git a/docs/i18n/vi/docs/ARCHITECTURE.md b/docs/i18n/vi/docs/ARCHITECTURE.md new file mode 100644 index 0000000000..d15923372e --- /dev/null +++ b/docs/i18n/vi/docs/ARCHITECTURE.md @@ -0,0 +1,814 @@ +# OmniRoute Architecture (Tiแบฟng Viแป‡t) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/ARCHITECTURE.md) + +--- + +_Last updated: 2026-03-28_ + +## 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 (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developerโ†’system, systemโ†’user) for cross-provider compatibility +- Structured output conversion (json_schema โ†’ Gemini responseSchema) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) +- Global system prompt injection +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout โ†’ budget โ†’ fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) + +Primary runtime model: + +- Next.js 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.) + +## Dashboard Surface (Current) + +Main pages under `src/app/(dashboard)/dashboard/`: + +- `/dashboard` โ€” quick start + provider overview +- `/dashboard/endpoint` โ€” endpoint proxy + MCP + A2A + API endpoint tabs +- `/dashboard/providers` โ€” provider connections and credentials +- `/dashboard/combos` โ€” combo strategies, templates, model routing rules +- `/dashboard/costs` โ€” cost aggregation and pricing visibility +- `/dashboard/analytics` โ€” usage analytics and evaluations +- `/dashboard/limits` โ€” quota/rate controls +- `/dashboard/cli-tools` โ€” CLI onboarding, runtime detection, config generation +- `/dashboard/agents` โ€” detected ACP agents + custom agent registration +- `/dashboard/media` โ€” image/video/music playground +- `/dashboard/search-tools` โ€” search provider testing and history +- `/dashboard/health` โ€” uptime, circuit breakers, rate limits +- `/dashboard/logs` โ€” request/proxy/audit/console logs +- `/dashboard/settings` โ€” system settings tabs (general, routing, combo defaults, etc.) +- `/dashboard/api-manager` โ€” API key lifecycle and model permissions + +## 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[(storage.sqlite)] + UDB[(usage tables + log artifacts)] + end + + subgraph Upstreams[Upstream Providers] + P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/Qoder/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/route.ts` (GET) +- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- OAuth: `src/app/api/oauth/*` +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` +- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI tooling helpers: `src/app/api/cli-tools/*` +- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) +- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) โ€” provider profiles, circuit breaker, rate limit state +- Resilience reset: `src/app/api/resilience/reset` (POST) โ€” reset breakers + cooldowns +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) +- Telemetry: `src/app/api/telemetry/summary` (GET) +- Budget: `src/app/api/usage/budget` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Policies: `src/app/api/policies` (GET/POST) + +## 2) SSE + 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` +- Response sanitization: `open-sse/handlers/responseSanitizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.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`, `qoder.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 (SQLite): + +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** + +Usage persistence: + +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present + +Domain State DB (SQLite): + +- `src/lib/db/domainState.ts` โ€” CRUD operations 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`, `src/shared/services/modelSyncScheduler.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Periodic task: `src/shared/services/modelSyncScheduler.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. Combo routing adds one extra guard: provider-scoped 400s such as upstream content-block and role-validation failures are treated as model-local failures so later combo targets can still run. + +## 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: + +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` + +## Deployment Topology + +```mermaid +flowchart LR + 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[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] + end + + subgraph External[External Services] + Providers[AI Providers] + SyncCloud[Cloud Sync Service] + end + + CLI --> Next + Browser --> Next + Next --> Core + Next --> MainDB + Core --> MainDB + Core --> UsageDB + Core --> Providers + Next --> SyncCloud +``` + +## Module Mapping (Decision-Critical) + +### Route and API Modules + +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle +- `src/app/api/models/alias`: alias management +- `src/app/api/combos*`: fallback combo management +- `src/app/api/pricing`: pricing overrides for cost calculation +- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers +- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) +- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) +- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) +- `src/app/api/sessions`: active session listing (GET) +- `src/app/api/rate-limits`: per-account rate limit status (GET) + +### Routing and Execution Core + +- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior + +### Translation Registry and Format Converters + +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` +- Format constants: `open-sse/translator/formats.ts` + +### Persistence + +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables + +## Provider Executor Coverage (Strategy Pattern) + +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. + +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, Qoder, 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 | +| Qoder | openai | OAuth (Basic) | โœ… | โœ… | โœ… | โš ๏ธ Per request | +| OpenRouter | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| GLM/Kimi/MiniMax | claude | API Key | โœ… | โœ… | โŒ | โŒ | +| DeepSeek | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Groq | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| xAI (Grok) | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Mistral | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Perplexity | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Together AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Fireworks AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Cerebras | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Cohere | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| NVIDIA NIM | openai | API Key | โœ… | โœ… | โŒ | โŒ | + +## Format Translation Coverage + +Detected source formats include: + +- `openai` +- `openai-responses` +- `claude` +- `gemini` + +Target formats include: + +- OpenAI chat/Responses +- Claude +- Gemini/Gemini-CLI/Antigravity envelope +- Kiro +- Cursor + +Translations use **OpenAI as the hub format** โ€” all conversions go through OpenAI as intermediate: + +``` +Source Format โ†’ OpenAI (hub) โ†’ Target Format +``` + +Translations are selected dynamically based on source payload shape and provider target format. + +Additional processing layers in the translation pipeline: + +- **Response sanitization** โ€” Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI targets; merges `system` โ†’ `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** โ€” Parses `...` blocks from content into `reasoning_content` field +- **Structured output** โ€” Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` + +## Supported API Endpoints + +| 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` | Provider Models | Provider model metadata backing custom and managed available models | + +## 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 `/logs//` 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 + +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON โ†’ SQLite migration compatibility path + +## Observability and Operational Signals + +Runtime visibility sources: + +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- four-stage detailed payload captures in SQLite (`request_detail_logs`) when `settings.detailed_logs_enabled=true` +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption + +Detailed request payload capture stores up to four JSON payload stages per routed call: + +- raw request received from the client +- translated request actually sent upstream +- provider response reconstructed as JSON; streamed responses are compacted to the final summary plus stream metadata +- final client response returned by OmniRoute; streamed responses are stored in the same compact summary form + +## Security-Sensitive Boundaries + +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics + +## Environment and Runtime Matrix + +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` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). + +## Operational Verification Checklist + +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: +- `GET /api/settings` +- `GET /api/v1/models` +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/vi/docs/AUTO-COMBO.md b/docs/i18n/vi/docs/AUTO-COMBO.md new file mode 100644 index 0000000000..28171a8f4c --- /dev/null +++ b/docs/i18n/vi/docs/AUTO-COMBO.md @@ -0,0 +1,67 @@ +# OmniRoute Auto-Combo Engine (Tiแบฟng Viแป‡t) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/AUTO-COMBO.md) + +--- + +> Self-managing model chains with adaptive scoring + +## How It Works + +The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**: + +| Factor | Weight | Description | +| :--------- | :----- | :---------------------------------------------- | +| Quota | 0.20 | Remaining capacity [0..1] | +| Health | 0.25 | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 | +| CostInv | 0.20 | Inverse cost (cheaper = higher score) | +| LatencyInv | 0.15 | Inverse p95 latency (faster = higher) | +| TaskFit | 0.10 | Model ร— task type fitness score | +| Stability | 0.10 | Low variance in latency/errors | + +## Mode Packs + +| Pack | Focus | Key Weight | +| :---------------------- | :----------- | :--------------- | +| ๐Ÿš€ **Ship Fast** | Speed | latencyInv: 0.35 | +| ๐Ÿ’ฐ **Cost Saver** | Economy | costInv: 0.40 | +| ๐ŸŽฏ **Quality First** | Best model | taskFit: 0.40 | +| ๐Ÿ“ก **Offline Friendly** | Availability | quota: 0.40 | + +## Self-Healing + +- **Temporary exclusion**: Score < 0.2 โ†’ excluded for 5 min (progressive backoff, max 30 min) +- **Circuit breaker awareness**: OPEN โ†’ auto-excluded; HALF_OPEN โ†’ probe requests +- **Incident mode**: >50% OPEN โ†’ disable exploration, maximize stability +- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout + +## Bandit Exploration + +5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode. + +## API + +```bash +# Create auto-combo +curl -X POST http://localhost:20128/api/combos/auto \ + -H "Content-Type: application/json" \ + -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}' + +# List auto-combos +curl http://localhost:20128/api/combos/auto +``` + +## Task Fitness + +30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` โ†’ high coding score). + +## Files + +| File | Purpose | +| :------------------------------------------- | :------------------------------------ | +| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization | +| `open-sse/services/autoCombo/taskFitness.ts` | Model ร— task fitness lookup | +| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap | +| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode | +| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles | +| `src/app/api/combos/auto/route.ts` | REST API | diff --git a/docs/i18n/vi/docs/CLI-TOOLS.md b/docs/i18n/vi/docs/CLI-TOOLS.md new file mode 100644 index 0000000000..ff3ecec952 --- /dev/null +++ b/docs/i18n/vi/docs/CLI-TOOLS.md @@ -0,0 +1,348 @@ +# CLI Tools Setup Guide โ€” OmniRoute (Tiแบฟng Viแป‡t) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CLI-TOOLS.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CLI-TOOLS.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CLI-TOOLS.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CLI-TOOLS.md) + +--- + +This guide explains how to install and configure all supported AI coding CLI tools +to use **OmniRoute** as the unified backend, giving you centralized key management, +cost tracking, model switching, and request logging across every tool. + +--- + +## How It Works + +``` +Claude / Codex / OpenCode / Cline / KiloCode / Continue / Kiro / Cursor / Copilot + โ”‚ + โ–ผ (all point to OmniRoute) + http://YOUR_SERVER:20128/v1 + โ”‚ + โ–ผ (OmniRoute routes to the right provider) + Anthropic / OpenAI / Gemini / DeepSeek / Groq / Mistral / ... +``` + +**Benefits:** + +- One API key to manage all tools +- Cost tracking across all CLIs in the dashboard +- Model switching without reconfiguring every tool +- Works locally and on remote servers (VPS) + +--- + +## Supported Tools (Dashboard Source of Truth) + +The dashboard cards in `/dashboard/cli-tools` are generated from `src/shared/constants/cliTools.ts`. +Current list (v3.0.0-rc.16): + +| Tool | ID | Command | Setup Mode | Install Method | +| ------------------ | ------------- | ---------- | ---------- | -------------- | +| **Claude Code** | `claude` | `claude` | env | npm | +| **OpenAI Codex** | `codex` | `codex` | custom | npm | +| **Factory Droid** | `droid` | `droid` | custom | bundled/CLI | +| **OpenClaw** | `openclaw` | `openclaw` | custom | bundled/CLI | +| **Cursor** | `cursor` | app | guide | desktop app | +| **Cline** | `cline` | `cline` | custom | npm | +| **Kilo Code** | `kilo` | `kilocode` | custom | npm | +| **Continue** | `continue` | extension | guide | VS Code | +| **Antigravity** | `antigravity` | internal | mitm | OmniRoute | +| **GitHub Copilot** | `copilot` | extension | custom | VS Code | +| **OpenCode** | `opencode` | `opencode` | guide | npm | +| **Kiro AI** | `kiro` | app/cli | mitm | desktop/CLI | + +### CLI fingerprint sync (Agents + Settings) + +`/dashboard/agents` and `Settings > CLI Fingerprint` use `src/shared/constants/cliCompatProviders.ts`. +This keeps provider IDs aligned with CLI cards and legacy IDs. + +| CLI ID | Fingerprint Provider ID | +| ---------------------------------------------------------------------------------------------------- | ----------------------- | +| `kilo` | `kilocode` | +| `copilot` | `github` | +| `claude` / `codex` / `antigravity` / `kiro` / `cursor` / `cline` / `opencode` / `droid` / `openclaw` | same ID | + +Legacy IDs still accepted for compatibility: `copilot`, `kimi-coding`, `qwen`. + +--- + +## Step 1 โ€” Get an OmniRoute API Key + +1. Open the OmniRoute dashboard โ†’ **API Manager** (`/dashboard/api-manager`) +2. Click **Create API Key** +3. Give it a name (e.g. `cli-tools`) and select all permissions +4. Copy the key โ€” you'll need it for every CLI below + +> Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` + +--- + +## Step 2 โ€” Install CLI Tools + +All npm-based tools require Node.js 18+: + +```bash +# Claude Code (Anthropic) +npm install -g @anthropic-ai/claude-code + +# OpenAI Codex +npm install -g @openai/codex + +# OpenCode +npm install -g opencode-ai + +# Cline +npm install -g cline + +# KiloCode +npm install -g kilocode + +# Kiro CLI (Amazon โ€” requires curl + unzip) +apt-get install -y unzip # on Debian/Ubuntu +curl -fsSL https://cli.kiro.dev/install | bash +export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc +``` + +**Verify:** + +```bash +claude --version # 2.x.x +codex --version # 0.x.x +opencode --version # x.x.x +cline --version # 2.x.x +kilocode --version # x.x.x (or: kilo --version) +kiro-cli --version # 1.x.x +``` + +--- + +## Step 3 โ€” Set Global Environment Variables + +Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`: + +```bash +# OmniRoute Universal Endpoint +export OPENAI_BASE_URL="http://localhost:20128/v1" +export OPENAI_API_KEY="sk-your-omniroute-key" +export ANTHROPIC_BASE_URL="http://localhost:20128/v1" +export ANTHROPIC_API_KEY="sk-your-omniroute-key" +export GEMINI_BASE_URL="http://localhost:20128/v1" +export GEMINI_API_KEY="sk-your-omniroute-key" +``` + +> For a **remote server** replace `localhost:20128` with the server IP or domain, +> e.g. `http://192.168.0.15:20128`. + +--- + +## Step 4 โ€” Configure Each Tool + +### Claude Code + +```bash +# Via CLI: +claude config set --global api-base-url http://localhost:20128/v1 + +# Or create ~/.claude/settings.json: +mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF +{ + "apiBaseUrl": "http://localhost:20128/v1", + "apiKey": "sk-your-omniroute-key" +} +EOF +``` + +**Test:** `claude "say hello"` + +--- + +### OpenAI Codex + +```bash +mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF +model: auto +apiKey: sk-your-omniroute-key +apiBaseUrl: http://localhost:20128/v1 +EOF +``` + +**Test:** `codex "what is 2+2?"` + +--- + +### OpenCode + +```bash +mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF +[provider.openai] +base_url = "http://localhost:20128/v1" +api_key = "sk-your-omniroute-key" +EOF +``` + +**Test:** `opencode` + +--- + +### Cline (CLI or VS Code) + +**CLI mode:** + +```bash +mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF +{ + "apiProvider": "openai", + "openAiBaseUrl": "http://localhost:20128/v1", + "openAiApiKey": "sk-your-omniroute-key" +} +EOF +``` + +**VS Code mode:** +Cline extension settings โ†’ API Provider: `OpenAI Compatible` โ†’ Base URL: `http://localhost:20128/v1` + +Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ Cline โ†’ Apply Config**. + +--- + +### KiloCode (CLI or VS Code) + +**CLI mode:** + +```bash +kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key +``` + +**VS Code settings:** + +```json +{ + "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", + "kilo-code.apiKey": "sk-your-omniroute-key" +} +``` + +Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ KiloCode โ†’ Apply Config**. + +--- + +### Continue (VS Code Extension) + +Edit `~/.continue/config.yaml`: + +```yaml +models: + - name: OmniRoute + provider: openai + model: auto + apiBase: http://localhost:20128/v1 + apiKey: sk-your-omniroute-key + default: true +``` + +Restart VS Code after editing. + +--- + +### Kiro CLI (Amazon) + +```bash +# Login to your AWS/Kiro account: +kiro-cli login + +# The CLI uses its own auth โ€” OmniRoute is not needed as backend for Kiro CLI itself. +# Use kiro-cli alongside OmniRoute for other tools. +kiro-cli status +``` + +--- + +### Cursor (Desktop App) + +> **Note:** Cursor routes requests through its cloud. For OmniRoute integration, +> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL. + +Via GUI: **Settings โ†’ Models โ†’ OpenAI API Key** + +- Base URL: `https://your-domain.com/v1` +- API Key: your OmniRoute key + +--- + +## Dashboard Auto-Configuration + +The OmniRoute dashboard automates configuration for most tools: + +1. Go to `http://localhost:20128/dashboard/cli-tools` +2. Expand any tool card +3. Select your API key from the dropdown +4. Click **Apply Config** (if tool is detected as installed) +5. Or copy the generated config snippet manually + +--- + +## Built-in Agents: Droid & OpenClaw + +**Droid** and **OpenClaw** are AI agents built directly into OmniRoute โ€” no installation needed. +They run as internal routes and use OmniRoute's model routing automatically. + +- Access: `http://localhost:20128/dashboard/agents` +- Configure: same combos and providers as all other tools +- No API key or CLI install required + +--- + +## Available API Endpoints + +| Endpoint | Description | Use For | +| -------------------------- | ----------------------------- | --------------------------- | +| `/v1/chat/completions` | Standard chat (all providers) | All modern tools | +| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows | +| `/v1/completions` | Legacy text completions | Older tools using `prompt:` | +| `/v1/embeddings` | Text embeddings | RAG, search | +| `/v1/images/generations` | Image generation | DALL-E, Flux, etc. | +| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS | +| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI | + +--- + +## Xแปญ lรฝ sแปฑ cแป‘ + +| Error | Cause | Fix | +| ------------------------- | ----------------------- | ------------------------------------------ | +| `Connection refused` | OmniRoute not running | `pm2 start omniroute` | +| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` | +| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` | +| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` | +| CLI shows "not installed" | Binary not in PATH | Check `which ` | +| `kiro-cli: not found` | Not in PATH | `export PATH="$HOME/.local/bin:$PATH"` | + +--- + +## Quick Setup Script (One Command) + +```bash +# Install all CLIs and configure for OmniRoute (replace with your key and server URL) +OMNIROUTE_URL="http://localhost:20128/v1" +OMNIROUTE_KEY="sk-your-omniroute-key" + +npm install -g @anthropic-ai/claude-code @openai/codex opencode-ai cline kilocode + +# Kiro CLI +apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash + +# Write configs +mkdir -p ~/.claude ~/.codex ~/.config/opencode ~/.continue + +cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" +cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" +cat >> ~/.bashrc << EOF +export OPENAI_BASE_URL="$OMNIROUTE_URL" +export OPENAI_API_KEY="$OMNIROUTE_KEY" +export ANTHROPIC_BASE_URL="$OMNIROUTE_URL" +export ANTHROPIC_API_KEY="$OMNIROUTE_KEY" +EOF + +source ~/.bashrc +echo "โœ… All CLIs installed and configured for OmniRoute" +``` diff --git a/docs/i18n/vi/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/vi/docs/CODEBASE_DOCUMENTATION.md new file mode 100644 index 0000000000..4de7ffbdaa --- /dev/null +++ b/docs/i18n/vi/docs/CODEBASE_DOCUMENTATION.md @@ -0,0 +1,591 @@ +# omniroute โ€” Codebase Documentation (Tiแบฟng Viแป‡t) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CODEBASE_DOCUMENTATION.md) + +--- + +> 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
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, Qoder, 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. + +#### Kiแบฟn trรบc + +```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 | +| Qoder | 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"] +``` diff --git a/docs/i18n/vi/docs/COVERAGE_PLAN.md b/docs/i18n/vi/docs/COVERAGE_PLAN.md new file mode 100644 index 0000000000..99e57d6089 --- /dev/null +++ b/docs/i18n/vi/docs/COVERAGE_PLAN.md @@ -0,0 +1,170 @@ +# Test Coverage Plan (Tiแบฟng Viแป‡t) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/COVERAGE_PLAN.md) + +--- + +Last updated: 2026-03-28 + +## Baseline + +There are multiple coverage numbers depending on how the report is computed. For planning, only one of them is useful. + +| Metric | Scope | Statements / Lines | Branches | Functions | Notes | +| -------------------- | ----------------------------------------------------- | -----------------: | -------: | --------: | --------------------------------------------------- | +| Legacy | Old `npm run test:coverage` | 79.42% | 75.15% | 67.94% | Inflated: counts test files and excludes `open-sse` | +| Diagnostic | Source-only, excluding tests and excluding `open-sse` | 68.16% | 63.55% | 64.06% | Useful only to isolate `src/**` | +| Recommended baseline | Source-only, excluding tests and including `open-sse` | 56.95% | 66.05% | 57.80% | This is the project-wide baseline to improve | + +The recommended baseline is the number to optimize against. + +## Rules + +- Coverage targets apply to source files, not to `tests/**`. +- `open-sse/**` is part of the product and must remain in scope. +- New code should not reduce coverage in touched areas. +- Prefer testing behavior and branch outcomes over implementation details. +- Prefer temp SQLite databases and small fixtures over broad mocks for `src/lib/db/**`. + +## Current command set + +- `npm run test:coverage` + - Main source coverage gate for the unit test suite + - Generates `text-summary`, `html`, `json-summary`, and `lcov` +- `npm run coverage:report` + - Detailed file-by-file report from the latest run +- `npm run test:coverage:legacy` + - Historical comparison only + +## Milestones + +| Phase | Target | Focus | +| ------- | ---------------------: | ------------------------------------------------- | +| Phase 1 | 60% statements / lines | Quick wins and low-risk utility coverage | +| Phase 2 | 65% statements / lines | DB and route foundations | +| Phase 3 | 70% statements / lines | Provider validation and usage analytics | +| Phase 4 | 75% statements / lines | `open-sse` translators and helpers | +| Phase 5 | 80% statements / lines | `open-sse` handlers and executor branches | +| Phase 6 | 85% statements / lines | Harder edge cases, branch debt, regression suites | +| Phase 7 | 90% statements / lines | Final sweep, gap closure, strict ratchet | + +Branches and functions should ratchet upward with each phase, but the primary hard target is statements / lines. + +## Priority hotspots + +These files or areas offer the best return for the next phases: + +1. `open-sse/handlers` + - `chatCore.ts` at 7.57% + - Overall directory at 29.07% +2. `open-sse/translator/request` + - Overall directory at 36.39% + - Many translators are still near single-digit coverage +3. `open-sse/translator/response` + - Overall directory at 8.07% +4. `open-sse/executors` + - Overall directory at 36.62% +5. `src/lib/db` + - `models.ts` at 20.66% + - `registeredKeys.ts` at 34.46% + - `modelComboMappings.ts` at 36.25% + - `settings.ts` at 46.40% + - `webhooks.ts` at 33.33% +6. `src/lib/usage` + - `usageHistory.ts` at 21.12% + - `usageStats.ts` at 9.56% + - `costCalculator.ts` at 30.00% +7. `src/lib/providers` + - `validation.ts` at 41.16% +8. Low-risk utility and API files for early gains + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/api/errorResponse.ts` + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +## Execution checklist + +### Phase 1: 56.95% -> 60% + +- [x] Fix coverage metric so it reflects source code instead of test files +- [x] Keep a legacy coverage script for comparison +- [x] Record the baseline and hotspots in-repo +- [ ] Add focused tests for low-risk utilities: + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/fetchTimeout.ts` + - `src/lib/api/errorResponse.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/display/names.ts` +- [ ] Add route tests for: + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +### Phase 2: 60% -> 65% + +- [ ] Add DB-backed tests for: + - `src/lib/db/modelComboMappings.ts` + - `src/lib/db/settings.ts` + - `src/lib/db/registeredKeys.ts` +- [ ] Cover branch behavior in: + - `src/lib/providers/validation.ts` + - `src/app/api/v1/embeddings/route.ts` + - `src/app/api/v1/moderations/route.ts` + +### Phase 3: 65% -> 70% + +- [ ] Add usage analytics tests for: + - `src/lib/usage/usageHistory.ts` + - `src/lib/usage/usageStats.ts` + - `src/lib/usage/costCalculator.ts` +- [ ] Expand route coverage for proxy management and settings branches + +### Phase 4: 70% -> 75% + +- [ ] Cover translator helpers and central translation paths: + - `open-sse/translator/index.ts` + - `open-sse/translator/helpers/*` + - `open-sse/translator/request/*` + - `open-sse/translator/response/*` + +### Phase 5: 75% -> 80% + +- [ ] Add handler-level tests for: + - `open-sse/handlers/chatCore.ts` + - `open-sse/handlers/responsesHandler.js` + - `open-sse/handlers/imageGeneration.js` + - `open-sse/handlers/embeddings.js` +- [ ] Add executor branch coverage for provider-specific auth, retries, and endpoint overrides + +### Phase 6: 80% -> 85% + +- [ ] Merge more edge-case suites into the main coverage path +- [ ] Increase function coverage for DB modules with weak constructor/helper coverage +- [ ] Close branch gaps in `settings.ts`, `registeredKeys.ts`, `validation.ts`, and translator helpers + +### Phase 7: 85% -> 90% + +- [ ] Treat the remaining low-coverage files as blockers +- [ ] Add regression tests for every uncovered production bug fixed during the push to 90% +- [ ] Raise the coverage gate in CI only after the local baseline is stable for at least two consecutive runs + +## Ratchet policy + +Update `npm run test:coverage` thresholds only after the project actually exceeds the next milestone with a comfortable buffer. + +Recommended ratchet sequence: + +1. 55/60/55 +2. 60/62/58 +3. 65/64/62 +4. 70/66/66 +5. 75/70/72 +6. 80/75/78 +7. 85/80/84 +8. 90/85/88 + +Order is `statements-lines / branches / functions`. + +## Known gap + +The current coverage command measures the main Node unit suite and includes source reached from it, including `open-sse`. It does not yet merge Vitest coverage into a single unified report. That merge is worth doing later, but it is not a blocker for starting the 60% -> 80% climb. diff --git a/docs/i18n/vi/docs/FEATURES.md b/docs/i18n/vi/docs/FEATURES.md index 659da83094..c9baa21c4c 100644 --- a/docs/i18n/vi/docs/FEATURES.md +++ b/docs/i18n/vi/docs/FEATURES.md @@ -1,6 +1,6 @@ # OmniRoute โ€” Dashboard Features Gallery (Tiแบฟng Viแป‡t) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/FEATURES.md) --- @@ -10,7 +10,7 @@ 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). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. ![Providers Dashboard](screenshots/01-providers.png) diff --git a/docs/i18n/vi/docs/MCP-SERVER.md b/docs/i18n/vi/docs/MCP-SERVER.md new file mode 100644 index 0000000000..29c17fbe4a --- /dev/null +++ b/docs/i18n/vi/docs/MCP-SERVER.md @@ -0,0 +1,87 @@ +# OmniRoute MCP Server Documentation (Tiแบฟng Viแป‡t) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/MCP-SERVER.md) + +--- + +> Model Context Protocol server with 16 intelligent tools + +## Cร i ฤ‘แบทt + +OmniRoute MCP is built-in. Start it with: + +```bash +omniroute --mcp +``` + +Or via the open-sse transport: + +```bash +# HTTP streamable transport (port 20130) +omniroute --dev # MCP auto-starts on /mcp endpoint +``` + +## IDE Configuration + +See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup. + +--- + +## Essential Tools (8) + +| Tool | Description | +| :------------------------------ | :--------------------------------------- | +| `omniroute_get_health` | Gateway health, circuit breakers, uptime | +| `omniroute_list_combos` | All configured combos with models | +| `omniroute_get_combo_metrics` | Performance metrics for a specific combo | +| `omniroute_switch_combo` | Switch active combo by ID/name | +| `omniroute_check_quota` | Quota status per provider or all | +| `omniroute_route_request` | Send a chat completion through OmniRoute | +| `omniroute_cost_report` | Cost analytics for a time period | +| `omniroute_list_models_catalog` | Full model catalog with capabilities | + +## Advanced Tools (8) + +| Tool | Description | +| :--------------------------------- | :---------------------------------------------------------- | +| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | +| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | +| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | +| `omniroute_test_combo` | Live-test all models in a combo via a real upstream request | +| `omniroute_get_provider_metrics` | Detailed metrics for one provider | +| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | +| `omniroute_explain_route` | Explain a past routing decision | +| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | + +## Authentication + +MCP tools are authenticated via API key scopes. Each tool requires specific scopes: + +| Scope | Tools | +| :------------- | :----------------------------------------------- | +| `read:health` | get_health, get_provider_metrics | +| `read:combos` | list_combos, get_combo_metrics | +| `write:combos` | switch_combo | +| `read:quota` | check_quota | +| `write:route` | route_request, simulate_route, test_combo | +| `read:usage` | cost_report, get_session_snapshot, explain_route | +| `write:config` | set_budget_guard, set_resilience_profile | +| `read:models` | list_models_catalog, best_combo_for_task | + +## Audit Logging + +Every tool call is logged to `mcp_tool_audit` with: + +- Tool name, arguments, result +- Duration (ms), success/failure +- API key hash, timestamp + +## Files + +| File | Purpose | +| :------------------------------------------- | :------------------------------------------ | +| `open-sse/mcp-server/server.ts` | MCP server creation + 16 tool registrations | +| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport | +| `open-sse/mcp-server/auth.ts` | API key + scope validation | +| `open-sse/mcp-server/audit.ts` | Tool call audit logging | +| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers | diff --git a/docs/i18n/vi/docs/RELEASE_CHECKLIST.md b/docs/i18n/vi/docs/RELEASE_CHECKLIST.md new file mode 100644 index 0000000000..e0847fc158 --- /dev/null +++ b/docs/i18n/vi/docs/RELEASE_CHECKLIST.md @@ -0,0 +1,37 @@ +# Release Checklist (Tiแบฟng Viแป‡t) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/RELEASE_CHECKLIST.md) + +--- + +Use this checklist before tagging or publishing a new OmniRoute release. + +## Version and Changelog + +1. Bump `package.json` version (`x.y.z`) in the release branch. +2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: + - `## [x.y.z] โ€” YYYY-MM-DD` +3. Keep `## [Unreleased]` as the first changelog section for upcoming work. +4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. + +## API Docs + +1. Update `docs/openapi.yaml`: + - `info.version` must equal `package.json` version. +2. Validate endpoint examples if API contracts changed. + +## Runtime Docs + +1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. +2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. +3. Update localized docs if source docs changed significantly. + +## Automated Check + +Run the sync guard locally before opening PR: + +```bash +npm run check:docs-sync +``` + +CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/vi/docs/TROUBLESHOOTING.md b/docs/i18n/vi/docs/TROUBLESHOOTING.md new file mode 100644 index 0000000000..570e665950 --- /dev/null +++ b/docs/i18n/vi/docs/TROUBLESHOOTING.md @@ -0,0 +1,256 @@ +# Troubleshooting (Tiแบฟng Viแป‡t) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/TROUBLESHOOTING.md) + +--- + +Common problems and solutions for OmniRoute. + +--- + +## Quick Fixes + +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | + +--- + +## Provider Issues + +### "Language model did not provide messages" + +**Cause:** Provider quota exhausted. + +**Fix:** + +1. 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, Qoder) 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}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) + +--- + +## Circuit Breaker Issues + +### Provider stuck in OPEN state + +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. + +**Fix:** + +1. 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 +- **SDK returns raw string instead of object** โ€” Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** โ€” Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** โ€” Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** โ€” Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` + +--- + +## Resilience Settings + +### Auto rate-limit not triggering + +- 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. + +--- + +## Optional RAG / LLM failure taxonomy (16 problems) + +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` โ€ฆ `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard โ†’ Health** for real-time system status +- **Translator**: Use **Dashboard โ†’ Translator** to debug format issues diff --git a/docs/i18n/vi/USER_GUIDE.md b/docs/i18n/vi/docs/USER_GUIDE.md similarity index 82% rename from docs/i18n/vi/USER_GUIDE.md rename to docs/i18n/vi/docs/USER_GUIDE.md index a1b68a53d6..76b26dc508 100644 --- a/docs/i18n/vi/USER_GUIDE.md +++ b/docs/i18n/vi/docs/USER_GUIDE.md @@ -1,8 +1,6 @@ # User Guide (Tiแบฟng Viแป‡t) -๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/USER_GUIDE.md) - -> ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/USER_GUIDE.md) --- @@ -320,7 +318,7 @@ Model: cc/claude-opus-4-6 --- -## ๐Ÿš€ Deployment +## Triแปƒn khai ### Global npm install (Recommended) @@ -511,23 +509,26 @@ post_install() { ### Environment Variables -| Variable | Default | Description | -| ------------------------- | ------------------------------------ | ------------------------------------------------------- | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT signing secret (**change in production**) | -| `INITIAL_PASSWORD` | `123456` | First login password | -| `DATA_DIR` | `~/.omniroute` | Data directory (db, usage, logs) | -| `PORT` | framework default | Service port (`20128` in examples) | -| `HOSTNAME` | framework default | Bind host (Docker defaults to `0.0.0.0`) | -| `NODE_ENV` | runtime default | Set `production` for deploy | -| `BASE_URL` | `http://localhost:20128` | Server-side internal base URL | -| `CLOUD_URL` | `https://omniroute.dev` | Cloud sync endpoint base URL | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | HMAC secret for generated API keys | -| `REQUIRE_API_KEY` | `false` | Enforce Bearer API key on `/v1/*` | -| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | -| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | -| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | -| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | -| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | +| 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/*` | +| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand | +| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | For the full environment variable reference, see the [README](../README.md). @@ -598,6 +599,11 @@ curl -X POST http://localhost:20128/api/provider-models \ Or use Dashboard: **Providers โ†’ [Provider] โ†’ Custom Models**. +Notes: + +- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers. +- The **Custom Models** section is intended for providers that do not expose managed available-model imports. + ### Dedicated Provider Routes Route requests directly to a specific provider with model validation: @@ -642,6 +648,14 @@ Returns models grouped by provider with types (`chat`, `embedding`, `image`). - Automatic background sync with timeout + fail-fast - Prefer server-side `BASE_URL`/`CLOUD_URL` in production +### Cloudflare Quick Tunnel + +- Available in **Dashboard โ†’ Endpoints** for Docker and other self-hosted deployments +- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint +- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary +- Tunnel URLs are ephemeral and change every time you stop/start the tunnel +- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download + ### LLM Gateway Intelligence (Phase 9) - **Semantic Cache** โ€” Auto-caches non-streaming, temperature=0 responses (bypass with `X-OmniRoute-No-Cache: true`) @@ -757,11 +771,11 @@ OmniRoute implements provider-level resilience with four components: 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 | +| 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 unless `DISABLE_SQLITE_AUTO_BACKUP=true` | ```bash # API: Export database @@ -787,10 +801,11 @@ curl -X POST http://localhost:20128/api/db-backups/import \ ### Settings Dashboard -The settings page is organized into 5 tabs for easy navigation: +The settings page is organized into 6 tabs for easy navigation: | Tab | Contents | | -------------- | ---------------------------------------------------------------------------------------------- | +| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility | | **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | | **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | | **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | diff --git a/docs/i18n/vi/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/vi/docs/VM_DEPLOYMENT_GUIDE.md new file mode 100644 index 0000000000..b4de955145 --- /dev/null +++ b/docs/i18n/vi/docs/VM_DEPLOYMENT_GUIDE.md @@ -0,0 +1,403 @@ +# OmniRoute โ€” Deployment Guide on VM with Cloudflare (Tiแบฟng Viแป‡t) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/VM_DEPLOYMENT_GUIDE.md) + +--- + +Complete guide to install and configure OmniRoute on a VM (VPS) with domain managed via Cloudflare. + +--- + +## Prerequisites + +| Item | Minimum | Recommended | +| ---------- | ------------------------ | ---------------- | +| **CPU** | 1 vCPU | 2 vCPU | +| **RAM** | 1 GB | 2 GB | +| **Disk** | 10 GB SSD | 25 GB SSD | +| **OS** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS | +| **Domain** | Registered on Cloudflare | โ€” | +| **Docker** | Docker Engine 24+ | Docker 27+ | + +**Tested providers**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. + +--- + +## 1. Configure the VM + +### 1.1 Create the instance + +On your preferred VPS provider: + +- Choose Ubuntu 24.04 LTS +- Select the minimum plan (1 vCPU / 1 GB RAM) +- Set a strong root password or configure SSH key +- Note the **public IP** (e.g., `203.0.113.10`) + +### 1.2 Connect via SSH + +```bash +ssh root@203.0.113.10 +``` + +### 1.3 Update the system + +```bash +apt update && apt upgrade -y +``` + +### 1.4 Install Docker + +```bash +# Install dependencies +apt install -y ca-certificates curl gnupg + +# Add official Docker repository +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 Install nginx + +```bash +apt install -y nginx +``` + +### 1.6 Configure 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 +``` + +> **Tip**: For maximum security, restrict ports 80 and 443 to Cloudflare IPs only. See the [Advanced Security](#advanced-security) section. + +--- + +## 2. Install OmniRoute + +### 2.1 Create configuration directory + +```bash +mkdir -p /opt/omniroute +``` + +### 2.2 Create environment variables file + +```bash +cat > /opt/omniroute/.env << โ€˜EOFโ€™ +# === Security === +JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY +INITIAL_PASSWORD=YourSecurePassword123! +API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY +STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY +STORAGE_ENCRYPTION_KEY_VERSION=v1 +MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT + +# === 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 (change to your domain) === +BASE_URL=https://llms.seudominio.com +NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com + +# === Cloud Sync (optional) === +# CLOUD_URL=https://cloud.omniroute.online +# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online +EOF +``` + +> โš ๏ธ **IMPORTANT**: Generate unique secret keys! Use `openssl rand -hex 32` for each key. + +### 2.3 Start the 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 Verify that it is running + +```bash +docker ps | grep omniroute +docker logs omniroute --tail 20 +``` + +It should display: `[DB] SQLite database ready` and `listening on port 20128`. + +--- + +## 3. Configure nginx (Reverse Proxy) + +### 3.1 Generate SSL certificate (Cloudflare Origin) + +In the Cloudflare dashboard: + +1. Go to **SSL/TLS โ†’ Origin Server** +2. Click **Create Certificate** +3. Keep the defaults (15 years, \*.yourdomain.com) +4. Copy the **Origin Certificate** and the **Private Key** + +```bash +mkdir -p /etc/nginx/ssl + +# Paste the certificate +nano /etc/nginx/ssl/origin.crt + +# Paste the private key +nano /etc/nginx/ssl/origin.key + +chmod 600 /etc/nginx/ssl/origin.key +``` + +### 3.2 Nginx Configuration + +```bash +cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ +# Default server โ€” blocks direct access via 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.yourdomain.com; # Change to your domain + + 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.yourdomain.com; + return 301 https://$server_name$request_uri; +} +NGINX +``` + +### 3.3 Enable and Test + +```bash +# Remove default configuration +rm -f /etc/nginx/sites-enabled/default + +# Enable OmniRoute +ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute + +# Test and reload +nginx -t && systemctl reload nginx +``` + +--- + +## 4. Configure Cloudflare DNS + +### 4.1 Add DNS record + +In the Cloudflare dashboard โ†’ DNS: + +| Type | Name | Content | Proxy | +| ---- | ------ | ---------------------- | ---------- | +| A | `llms` | `203.0.113.10` (VM IP) | โœ… Proxied | + +### 4.2 Configure SSL + +Under **SSL/TLS โ†’ Overview**: + +- Mode: **Full (Strict)** + +Under **SSL/TLS โ†’ Edge Certificates**: + +- Always Use HTTPS: โœ… On +- Minimum TLS Version: TLS 1.2 +- Automatic HTTPS Rewrites: โœ… On + +### 4.3 Testing + +```bash +curl -sI https://llms.seudominio.com/health +# Should return HTTP/2 200 +``` + +--- + +## 5. Operations and Maintenance + +### Upgrade to a new version + +```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 +``` + +### View logs + +```bash +docker logs -f omniroute # Real-time stream +docker logs omniroute --tail 50 # Last 50 lines +``` + +### Manual database backup + +```bash +# Copy data from the volume to the host +docker cp omniroute:/app/data ./backup-$(date +%F) + +# Or compress the entire volume +docker run --rm -v omniroute-data:/data -v $(pwd):/backup \ + alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data +``` + +### Restore from 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. Advanced Security + +### Restrict nginx to Cloudflare IPs + +```bash +cat > /etc/nginx/cloudflare-ips.conf << โ€˜CFโ€™ +# Cloudflare IPv4 ranges โ€” update periodically +# 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 +``` + +Add the following to `nginx.conf` inside the `http {}` block: + +```nginx +include /etc/nginx/cloudflare-ips.conf; +``` + +### Install fail2ban + +```bash +apt install -y fail2ban +systemctl enable fail2ban +systemctl start fail2ban + +# Check status +fail2ban-client status sshd +``` + +### Block direct access to the Docker port + +```bash +# Prevent direct external access to port 20128 +iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP +iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT + +# Persist the rules +apt install -y iptables-persistent +netfilter-persistent save +``` + +--- + +## 7. Deploy to Cloudflare Workers (Optional) + +For remote access via Cloudflare Workers (without exposing the VM directly): + +```bash +# In the local repository +cd omnirouteCloud +npm install +npx wrangler login +npx wrangler deploy +``` + +See the full documentation at [omnirouteCloud/README.md](../omnirouteCloud/README.md). + +--- + +## Port Summary + +| Port | Service | Access | +| ----- | ----------- | -------------------------- | +| 22 | SSH | Public (with fail2ban) | +| 80 | nginx HTTP | Redirect โ†’ HTTPS | +| 443 | nginx HTTPS | Via Cloudflare Proxy | +| 20128 | OmniRoute | Localhost only (via nginx) | diff --git a/docs/i18n/vi/src/lib/a2a/README.md b/docs/i18n/vi/src/lib/a2a/README.md new file mode 100644 index 0000000000..0a878c6726 --- /dev/null +++ b/docs/i18n/vi/src/lib/a2a/README.md @@ -0,0 +1,752 @@ +# OmniRoute A2A Server (Tiแบฟng Viแป‡t) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../../../src/lib/a2a/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../../../es/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../../../fr/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../../../de/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../../../it/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../../../ru/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../../../zh-CN/src/lib/a2a/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../../../ja/src/lib/a2a/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../../../ko/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../../../ar/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../../../in/src/lib/a2a/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../../../th/src/lib/a2a/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../../../vi/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../../../id/src/lib/a2a/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../../../ms/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../../../nl/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../../../pl/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../../../sv/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../../../no/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../../../da/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../../../fi/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../../../pt/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../../../ro/src/lib/a2a/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../../../hu/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../../../bg/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../../../sk/src/lib/a2a/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../../../uk-UA/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../../../he/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../../../phi/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../../../pt-BR/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../../../cs/src/lib/a2a/README.md) + +--- + +> **Agent-to-Agent Protocol v0.3** โ€” Enables any AI agent to use OmniRoute as an intelligent routing agent via JSON-RPC 2.0. + +The A2A Server exposes OmniRoute as a **first-class agent** that other agents can discover, delegate tasks to, and collaborate with using the [A2A Protocol](https://google.github.io/A2A/). + +--- + +## Kiแบฟn trรบc + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Orchestrator Agent โ”‚ +โ”‚ (LangChain, CrewAI, AutoGen, Custom Agent) โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ 1. GET /.well-known/agent.json (discover) + โ”‚ 2. POST /a2a (JSON-RPC 2.0) + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ OmniRoute A2A Server โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Task Manager โ”‚ โ”‚ Skill Engine โ”‚ โ”‚ SSE Streaming โ”‚ โ”‚ +โ”‚ โ”‚ (lifecycle) โ”‚โ”€โ”€โ”‚ (registry) โ”‚โ”€โ”€โ”‚ (real-time) โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ +โ”‚ Skills: โ”‚ โ”‚ +โ”‚ โ”œโ”€ smart-routing โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ””โ”€ quota-management โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ Routing Decision Logger โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ OmniRoute Gateway (internal) + /v1/chat/completions, /api/combos, /api/usage/quota +``` + +--- + +## Bแบฏt ฤ‘แบงu nhanh + +### Agent Discovery + +Every A2A-compatible agent exposes an **Agent Card** at `/.well-known/agent.json`: + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +**Response:** + +```json +{ + "name": "OmniRoute", + "description": "Intelligent AI gateway with auto-routing across 50+ providers", + "url": "http://localhost:20128/a2a", + "version": "1.8.1", + "capabilities": { + "streaming": true, + "pushNotifications": false + }, + "skills": [ + { + "id": "smart-routing", + "name": "Smart Routing", + "description": "Routes prompts through OmniRoute intelligent pipeline", + "tags": ["routing", "llm", "multi-provider", "cost-optimization"], + "examples": [ + "Write a hello world in Python", + "Explain quantum computing using the cheapest provider" + ] + }, + { + "id": "quota-management", + "name": "Quota Management", + "description": "Natural-language queries about provider quotas", + "tags": ["quota", "analytics", "cost"], + "examples": [ + "Which provider has the most quota remaining?", + "Suggest a free combo for coding" + ] + } + ], + "authentication": { + "schemes": ["bearer"], + "apiKeyHeader": "Authorization" + } +} +``` + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Send a message to a skill and receive the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python hello world"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "a1b2c3d4-...", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "print('Hello, World!')" }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.0030)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "2026-03-04T..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"Quantum computing..."}}} + +: heartbeat 2026-03-04T21:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Running Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Skills Reference + +### `smart-routing` + +Routes prompts through OmniRoute's intelligent pipeline with full observability. + +**Parameters (in `metadata`):** + +| Parameter | Type | Default | Description | +| --------- | -------- | ------------ | ---------------------------------------------------------------------------------------- | +| `model` | `string` | `"auto"` | Target model (e.g., `claude-sonnet-4`, `gpt-4o`, `auto`) | +| `combo` | `string` | active combo | Specific combo to route through | +| `budget` | `number` | none | Maximum cost in USD for this request | +| `role` | `string` | none | Task role hint: `coding`, `review`, `planning`, `analysis`, `debugging`, `documentation` | + +**Returns:** + +| Field | Description | +| ------------------------------ | --------------------------------------------------------- | +| `artifacts[].content` | The LLM response text | +| `metadata.routing_explanation` | Human-readable explanation of routing decision | +| `metadata.cost_envelope` | Estimated vs actual cost with currency | +| `metadata.resilience_trace` | Array of events (primary_selected, fallback_needed, etc.) | +| `metadata.policy_verdict` | Whether the request was allowed and why | + +### `quota-management` + +Answers natural-language queries about provider quotas. + +**Query types (inferred from message content):** + +| Query Pattern | Response Type | +| ---------------------------------------------- | -------------------------------------------------------- | +| Contains `"ranking"`, `"most quota"`, `"best"` | Providers ranked by remaining quota | +| Contains `"free"`, `"suggest"` | Lists free combos or suggests free-tier providers | +| Default | Full quota summary with warnings for low-quota providers | + +--- + +## Task Lifecycle + +``` +submitted โ”€โ”€โ†’ working โ”€โ”€โ†’ completed + โ”€โ”€โ†’ failed + โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ†’ cancelled +``` + +| State | Description | +| ----------- | ----------------------------------------------------- | +| `submitted` | Task created, queued for execution | +| `working` | Skill handler is executing | +| `completed` | Execution succeeded, artifacts available | +| `failed` | Execution failed or task expired (TTL: 5 min default) | +| `cancelled` | Cancelled by client via `tasks/cancel` | + +- Terminal states: `completed`, `failed`, `cancelled` (no further transitions) +- Expired tasks in `submitted` or `working` are auto-marked as `failed` +- Tasks are garbage-collected after 2ร— TTL + +--- + +## Client Examples + +### Python โ€” Orchestrator Agent + +```python +""" +A2A Client โ€” Python example. +Discovers OmniRoute agent, sends a task, and processes the result. +""" +import requests +import json + +BASE_URL = "http://localhost:20128" +API_KEY = "your-api-key" +HEADERS = { + "Content-Type": "application/json", + "Authorization": f"Bearer {API_KEY}", +} + +# 1. Discover agent capabilities +agent_card = requests.get(f"{BASE_URL}/.well-known/agent.json").json() +print(f"Agent: {agent_card['name']} v{agent_card['version']}") +print(f"Skills: {[s['id'] for s in agent_card['skills']]}") + +# 2. Send a smart-routing task +response = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python quicksort implementation"}], + "metadata": { + "model": "auto", + "combo": "fast-coding", + "budget": 0.10, + } + } +}) +result = response.json()["result"] +print(f"\n๐Ÿ“ Response: {result['artifacts'][0]['content'][:200]}...") +print(f"๐Ÿ”€ Routing: {result['metadata']['routing_explanation']}") +print(f"๐Ÿ’ฐ Cost: ${result['metadata']['cost_envelope']['actual']}") +print(f"๐Ÿ›ก๏ธ Policy: {result['metadata']['policy_verdict']['reason']}") + +# 3. Query quota status +quota_resp = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-2", + "method": "message/send", + "params": { + "skill": "quota-management", + "messages": [{"role": "user", "content": "Which provider has the most quota remaining?"}], + } +}) +quota_result = quota_resp.json()["result"] +print(f"\n๐Ÿ“Š Quota: {quota_result['artifacts'][0]['content']}") +``` + +### TypeScript โ€” Multi-Agent Orchestrator + +```typescript +/** + * A2A Client โ€” TypeScript example. + * Shows agent discovery, task delegation, and streaming. + */ + +const BASE_URL = "http://localhost:20128"; +const API_KEY = "your-api-key"; + +interface JsonRpcResponse { + jsonrpc: "2.0"; + id: string | number; + result?: T; + error?: { code: number; message: string }; +} + +async function a2aCall(method: string, params: Record): Promise { + const resp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: `${method}-${Date.now()}`, + method, + params, + }), + }); + const json: JsonRpcResponse = await resp.json(); + if (json.error) throw new Error(`[${json.error.code}] ${json.error.message}`); + return json.result!; +} + +// โ”€โ”€ Agent Discovery โ”€โ”€ +const agentCard = await fetch(`${BASE_URL}/.well-known/agent.json`).then((r) => r.json()); +console.log(`Connected to: ${agentCard.name} (${agentCard.skills.length} skills)`); + +// โ”€โ”€ Smart Routing: Send a coding task โ”€โ”€ +const routingResult = await a2aCall("message/send", { + skill: "smart-routing", + messages: [{ role: "user", content: "Implement a Redis cache wrapper in TypeScript" }], + metadata: { model: "claude-sonnet-4", role: "coding" }, +}); +console.log("Response:", routingResult.artifacts[0].content); +console.log("Provider:", routingResult.metadata.routing_explanation); + +// โ”€โ”€ Quota Management: Find free alternatives โ”€โ”€ +const quotaResult = await a2aCall("message/send", { + skill: "quota-management", + messages: [{ role: "user", content: "Suggest free combos for documentation" }], +}); +console.log("Free combos:", quotaResult.artifacts[0].content); + +// โ”€โ”€ Streaming: Real-time response โ”€โ”€ +const streamResp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "stream-1", + method: "message/stream", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Explain microservices architecture" }], + }, + }), +}); + +const reader = streamResp.body!.getReader(); +const decoder = new TextDecoder(); +while (true) { + const { done, value } = await reader.read(); + if (done) break; + const chunk = decoder.decode(value); + for (const line of chunk.split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + if (event.params.chunk) { + process.stdout.write(event.params.chunk.content); + } + if (event.params.task.state === "completed") { + console.log("\nโœ… Stream completed"); + } + } + } +} +``` + +### Python โ€” LangChain A2A Integration + +```python +""" +LangChain integration โ€” Use OmniRoute A2A as a custom LLM. +""" +from langchain.llms.base import BaseLLM +from langchain.schema import LLMResult, Generation +import requests +from typing import List, Optional + +class OmniRouteA2A(BaseLLM): + base_url: str = "http://localhost:20128" + api_key: str = "" + model: str = "auto" + combo: Optional[str] = None + + @property + def _llm_type(self) -> str: + return "omniroute-a2a" + + def _call(self, prompt: str, stop: Optional[List[str]] = None, **kwargs) -> str: + response = requests.post( + f"{self.base_url}/a2a", + headers={ + "Content-Type": "application/json", + "Authorization": f"Bearer {self.api_key}", + }, + json={ + "jsonrpc": "2.0", + "id": "langchain-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": prompt}], + "metadata": { + "model": self.model, + **({"combo": self.combo} if self.combo else {}), + }, + }, + }, + ) + result = response.json()["result"] + return result["artifacts"][0]["content"] + + def _generate(self, prompts: List[str], stop=None, **kwargs) -> LLMResult: + return LLMResult( + generations=[[Generation(text=self._call(p, stop))] for p in prompts] + ) + +# Usage +llm = OmniRouteA2A( + base_url="http://localhost:20128", + api_key="your-key", + model="auto", + combo="fast-coding", +) +result = llm("Write a Python function to merge two sorted lists") +print(result) +``` + +### Go โ€” A2A Client + +```go +package main + +import ( + "bytes" + "encoding/json" + "fmt" + "io" + "net/http" +) + +const baseURL = "http://localhost:20128" +const apiKey = "your-api-key" + +type JsonRpcRequest struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Method string `json:"method"` + Params interface{} `json:"params"` +} + +type JsonRpcResponse struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Result interface{} `json:"result"` + Error *struct { + Code int `json:"code"` + Message string `json:"message"` + } `json:"error"` +} + +func a2aCall(method string, params interface{}) (*JsonRpcResponse, error) { + body, _ := json.Marshal(JsonRpcRequest{ + Jsonrpc: "2.0", + ID: "go-1", + Method: method, + Params: params, + }) + + req, _ := http.NewRequest("POST", baseURL+"/a2a", bytes.NewReader(body)) + req.Header.Set("Content-Type", "application/json") + req.Header.Set("Authorization", "Bearer "+apiKey) + + resp, err := http.DefaultClient.Do(req) + if err != nil { + return nil, err + } + defer resp.Body.Close() + data, _ := io.ReadAll(resp.Body) + + var result JsonRpcResponse + json.Unmarshal(data, &result) + return &result, nil +} + +func main() { + // Discover agent + resp, _ := http.Get(baseURL + "/.well-known/agent.json") + defer resp.Body.Close() + body, _ := io.ReadAll(resp.Body) + fmt.Println("Agent Card:", string(body)) + + // Send smart-routing task + result, _ := a2aCall("message/send", map[string]interface{}{ + "skill": "smart-routing", + "messages": []map[string]string{{"role": "user", "content": "Hello from Go!"}}, + "metadata": map[string]interface{}{"model": "auto"}, + }) + out, _ := json.MarshalIndent(result.Result, "", " ") + fmt.Println("Result:", string(out)) +} +``` + +--- + +## Use Cases + +### ๐Ÿค– Use Case 1: Multi-Agent Coding Pipeline + +An orchestrator agent delegates code generation to OmniRoute, then passes the output to a review agent. + +```python +def coding_pipeline(task: str): + # Step 1: Generate code via OmniRoute A2A + code_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Write production-quality code: {task}"} + ], metadata={"model": "auto", "role": "coding"}) + code = code_result["artifacts"][0]["content"] + + # Step 2: Review the code via OmniRoute A2A (different model) + review_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Review this code for bugs and improvements:\n\n{code}"} + ], metadata={"model": "auto", "role": "review"}) + review = review_result["artifacts"][0]["content"] + + # Step 3: Check costs + print(f"Code cost: ${code_result['metadata']['cost_envelope']['actual']}") + print(f"Review cost: ${review_result['metadata']['cost_envelope']['actual']}") + + return {"code": code, "review": review} +``` + +### ๐Ÿ’ก Use Case 2: Quota-Aware Agent Swarm + +Multiple agents share quota through OmniRoute, using the quota skill to coordinate. + +```python +async def quota_aware_agent(agent_name: str, task: str): + # Check quota before starting + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Which provider has the most quota remaining?"} + ]) + print(f"[{agent_name}] {quota['artifacts'][0]['content']}") + + # Send request with budget constraint + result = a2a_send("smart-routing", [ + {"role": "user", "content": task} + ], metadata={"budget": 0.05}) + + policy = result["metadata"]["policy_verdict"] + if not policy["allowed"]: + print(f"[{agent_name}] โš ๏ธ Budget exceeded: {policy['reason']}") + # Fall back to free combo + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Suggest free combos"} + ]) + print(f"[{agent_name}] Free alternatives: {quota['artifacts'][0]['content']}") + + return result +``` + +### ๐Ÿ“Š Use Case 3: Real-Time Streaming Dashboard + +A monitoring agent streams responses and displays progress in real-time. + +```typescript +async function streamingDashboard(prompt: string) { + const response = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { "Content-Type": "application/json", Authorization: `Bearer ${API_KEY}` }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "dash-1", + method: "message/stream", + params: { skill: "smart-routing", messages: [{ role: "user", content: prompt }] }, + }), + }); + + let totalChunks = 0; + const reader = response.body!.getReader(); + const decoder = new TextDecoder(); + + while (true) { + const { done, value } = await reader.read(); + if (done) break; + + for (const line of decoder.decode(value).split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + const state = event.params.task.state; + + if (state === "working" && event.params.chunk) { + totalChunks++; + process.stdout.write( + `\r[Chunk ${totalChunks}] ${event.params.chunk.content.slice(0, 50)}...` + ); + } + if (state === "completed") { + const meta = event.params.metadata; + console.log( + `\nโœ… Done | Cost: $${meta?.cost_envelope?.actual || 0} | Route: ${meta?.routing_explanation || "N/A"}` + ); + } + if (state === "failed") { + console.error(`\nโŒ Failed: ${event.params.metadata?.error}`); + } + } + } + } +} +``` + +### ๐Ÿ” Use Case 4: Task Polling Pattern + +For long-running tasks, poll the task status instead of waiting synchronously. + +```python +import time + +def poll_task(task_id: str, timeout: int = 60): + """Poll task status until completion or timeout.""" + start = time.time() + while time.time() - start < timeout: + result = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "poll-1", + "method": "tasks/get", + "params": {"taskId": task_id}, + }).json() + + task = result["result"]["task"] + state = task["state"] + print(f" Task {task_id[:8]}... state={state}") + + if state in ("completed", "failed", "cancelled"): + return task + time.sleep(2) + + # Timeout โ€” cancel the task + requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "cancel-1", + "method": "tasks/cancel", + "params": {"taskId": task_id}, + }) + raise TimeoutError(f"Task {task_id} timed out after {timeout}s") +``` + +--- + +## Error Codes + +| Code | Constant | Meaning | +| ------ | ------------------------ | ---------------------------------------- | +| -32700 | โ€” | Parse error (invalid JSON) | +| -32600 | `INVALID_REQUEST` | Invalid JSON-RPC request or unauthorized | +| -32601 | `METHOD_NOT_FOUND` | Unknown method or skill | +| -32602 | `INVALID_PARAMS` | Missing or invalid parameters | +| -32603 | `INTERNAL_ERROR` | Skill execution failed | +| -32001 | `TASK_NOT_FOUND` | Task ID not found | +| -32002 | `TASK_ALREADY_COMPLETED` | Cannot modify a completed task | +| -32003 | `UNAUTHORIZED` | Invalid or missing API key | +| -32004 | `BUDGET_EXCEEDED` | Request exceeds configured budget | +| -32005 | `PROVIDER_UNAVAILABLE` | No available providers | + +--- + +## Authentication + +All `/a2a` requests require a Bearer token via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server (`OMNIROUTE_API_KEY` is empty), authentication is bypassed. + +--- + +## File Structure + +``` +src/lib/a2a/ +โ”œโ”€โ”€ taskManager.ts # Task lifecycle (create/update/cancel/list), TTL, cleanup +โ”œโ”€โ”€ taskExecution.ts # Generic task executor with state management +โ”œโ”€โ”€ streaming.ts # SSE stream formatting, heartbeat, chunk/completion events +โ”œโ”€โ”€ routingLogger.ts # Routing decision logger (stats, history, retention) +โ””โ”€โ”€ skills/ + โ”œโ”€โ”€ smartRouting.ts # Smart routing skill (routes via /v1/chat/completions) + โ””โ”€โ”€ quotaManagement.ts # Quota management skill (natural-language quota queries) + +src/app/a2a/ +โ””โ”€โ”€ route.ts # Next.js API route handler (JSON-RPC 2.0 dispatch) + +open-sse/mcp-server/ +โ””โ”€โ”€ schemas/a2a.ts # Zod schemas (AgentCard, Task, JSON-RPC, SSE events) +``` + +--- + +## Comparison: MCP vs A2A + +| Feature | MCP Server | A2A Server | +| ----------------- | ---------------------------- | ------------------------------------------------- | +| **Protocol** | Model Context Protocol | Agent-to-Agent Protocol v0.3 | +| **Transport** | stdio / HTTP | HTTP (JSON-RPC 2.0) | +| **Discovery** | Tool listing via MCP | `/.well-known/agent.json` | +| **Granularity** | 16 individual tools | 2 high-level skills | +| **Best for** | IDE agents (Cursor, VS Code) | Multi-agent systems (LangChain, CrewAI) | +| **Streaming** | Not supported | SSE via `message/stream` | +| **Task tracking** | No | Full lifecycle (submitted โ†’ completed) | +| **Observability** | Audit log per tool call | Cost envelope + resilience trace + policy verdict | + +--- + +## Giแบฅy phรฉp + +Part of [OmniRoute](https://github.com/diegosouzapw/OmniRoute) โ€” MIT License. diff --git a/docs/i18n/zh-CN/A2A-SERVER.md b/docs/i18n/zh-CN/A2A-SERVER.md deleted file mode 100644 index 1a3c8b0f92..0000000000 --- a/docs/i18n/zh-CN/A2A-SERVER.md +++ /dev/null @@ -1,198 +0,0 @@ -# OmniRoute A2A ๆœๅŠกๅ™จๆ–‡ๆกฃ - -๐ŸŒ **่ฏญ่จ€:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/A2A-SERVER.md) - -> Agent-to-Agent Protocol v0.3 โ€” OmniRoute ไฝœไธบๆ™บ่ƒฝ่ทฏ็”ฑไปฃ็† - -## ไปฃ็†ๅ‘็Žฐ - -```bash -curl http://localhost:20128/.well-known/agent.json -``` - -่ฟ”ๅ›žๆ่ฟฐ OmniRoute ่ƒฝๅŠ›ใ€ๆŠ€่ƒฝๅ’Œ่บซไปฝ้ชŒ่ฏ่ฆๆฑ‚็š„ Agent Cardใ€‚ - ---- - -## ่บซไปฝ้ชŒ่ฏ - -ๆ‰€ๆœ‰ `/a2a` ่ฏทๆฑ‚้œ€่ฆ้€š่ฟ‡ `Authorization` ๅคด้ƒจๆไพ› API ๅฏ†้’ฅ๏ผš - -``` -Authorization: Bearer YOUR_OMNIROUTE_API_KEY -``` - -ๅฆ‚ๆžœๆœๅŠกๅ™จๆœช้…็ฝฎ API ๅฏ†้’ฅ๏ผŒๅˆ™่ทณ่ฟ‡่บซไปฝ้ชŒ่ฏใ€‚ - ---- - -## JSON-RPC 2.0 ๆ–นๆณ• - -### `message/send` โ€” ๅŒๆญฅๆ‰ง่กŒ - -ๅ‘ๆŠ€่ƒฝๅ‘้€ๆถˆๆฏๅนถ็ญ‰ๅพ…ๅฎŒๆ•ดๅ“ๅบ”ใ€‚ - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{ - "jsonrpc": "2.0", - "id": "1", - "method": "message/send", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Write a hello world in Python"}], - "metadata": {"model": "auto", "combo": "fast-coding"} - } - }' -``` - -**ๅ“ๅบ”:** - -```json -{ - "jsonrpc": "2.0", - "id": "1", - "result": { - "task": { "id": "uuid", "state": "completed" }, - "artifacts": [{ "type": "text", "content": "..." }], - "metadata": { - "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)", - "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, - "resilience_trace": [ - { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." } - ], - "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } - } - } -} -``` - -### `message/stream` โ€” SSE ๆตๅผไผ ่พ“ - -ไธŽ `message/send` ็›ธๅŒ๏ผŒไฝ†่ฟ”ๅ›ž Server-Sent Events ่ฟ›่กŒๅฎžๆ—ถๆตๅผไผ ่พ“ใ€‚ - -```bash -curl -N -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{ - "jsonrpc": "2.0", - "id": "1", - "method": "message/stream", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Explain quantum computing"}] - } - }' -``` - -**SSE ไบ‹ไปถ:** - -``` -data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}} - -: heartbeat 2026-03-03T17:00:00Z - -data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} -``` - -### `tasks/get` โ€” ๆŸฅ่ฏขไปปๅŠก็Šถๆ€ - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' -``` - -### `tasks/cancel` โ€” ๅ–ๆถˆไปปๅŠก - -```bash -curl -X POST http://localhost:20128/a2a \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer YOUR_KEY" \ - -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' -``` - ---- - -## ๅฏ็”จๆŠ€่ƒฝ - -| ๆŠ€่ƒฝ | ๆ่ฟฐ | -| :----------------- | :---------------------------------------------------------------------------------------------- | -| `smart-routing` | ้€š่ฟ‡ OmniRoute ็š„ๆ™บ่ƒฝ็ฎก้“่ทฏ็”ฑๆ็คบใ€‚่ฟ”ๅ›žๅธฆๆœ‰่ทฏ็”ฑ่ฏดๆ˜Žใ€ๆˆๆœฌๅ’Œๅผนๆ€ง่ฟฝ่ธช็š„ๅ“ๅบ”ใ€‚ | -| `quota-management` | ๅ›ž็ญ”ๅ…ณไบŽๆœๅŠกๅ•†้…้ข็š„่‡ช็„ถ่ฏญ่จ€ๆŸฅ่ฏข๏ผŒๅปบ่ฎฎๅ…่ดน็ป„ๅˆ๏ผŒๅนถๆไพ›้…้ขๆŽ’ๅใ€‚ | - ---- - -## ไปปๅŠก็”Ÿๅ‘ฝๅ‘จๆœŸ - -``` -submitted โ†’ working โ†’ completed - โ†’ failed - โ†’ cancelled -``` - -- ไปปๅŠกๅœจ 5 ๅˆ†้’ŸๅŽ่ฟ‡ๆœŸ๏ผˆๅฏ้…็ฝฎ๏ผ‰ -- ็ปˆๆญข็Šถๆ€๏ผš`completed`ใ€`failed`ใ€`cancelled` -- ไบ‹ไปถๆ—ฅๅฟ—่ทŸ่ธชๆฏไธช็Šถๆ€่ฝฌๆข - ---- - -## ้”™่ฏฏไปฃ็  - -| ไปฃ็  | ๅซไน‰ | -| :----- | :-------------------------- | -| -32700 | ่งฃๆž้”™่ฏฏ๏ผˆๆ— ๆ•ˆ JSON๏ผ‰ | -| -32600 | ๆ— ๆ•ˆ่ฏทๆฑ‚ / ๆœชๆŽˆๆƒ | -| -32601 | ๆ–นๆณ•ๆˆ–ๆŠ€่ƒฝๆœชๆ‰พๅˆฐ | -| -32602 | ๆ— ๆ•ˆๅ‚ๆ•ฐ | -| -32603 | ๅ†…้ƒจ้”™่ฏฏ | - ---- - -## ้›†ๆˆ็คบไพ‹ - -### Python (requests) - -```python -import requests - -resp = requests.post("http://localhost:20128/a2a", json={ - "jsonrpc": "2.0", "id": "1", - "method": "message/send", - "params": { - "skill": "smart-routing", - "messages": [{"role": "user", "content": "Hello"}] - } -}, headers={"Authorization": "Bearer YOUR_KEY"}) - -result = resp.json()["result"] -print(result["artifacts"][0]["content"]) -print(result["metadata"]["routing_explanation"]) -``` - -### TypeScript (fetch) - -```typescript -const resp = await fetch("http://localhost:20128/a2a", { - method: "POST", - headers: { - "Content-Type": "application/json", - Authorization: "Bearer YOUR_KEY", - }, - body: JSON.stringify({ - jsonrpc: "2.0", - id: "1", - method: "message/send", - params: { - skill: "smart-routing", - messages: [{ role: "user", content: "Hello" }], - }, - }), -}); -const { result } = await resp.json(); -console.log(result.metadata.routing_explanation); -``` diff --git a/docs/i18n/zh-CN/API_REFERENCE.md b/docs/i18n/zh-CN/API_REFERENCE.md deleted file mode 100644 index 5f28a0c5d7..0000000000 --- a/docs/i18n/zh-CN/API_REFERENCE.md +++ /dev/null @@ -1,463 +0,0 @@ -# API ๅ‚่€ƒ - -๐ŸŒ **่ฏญ่จ€:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](../pt-BR/API_REFERENCE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](../es/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](../fr/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](../it/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](../ru/API_REFERENCE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](../zh-CN/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](../de/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](../in/API_REFERENCE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](../th/API_REFERENCE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](../uk-UA/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](../ar/API_REFERENCE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](../ja/API_REFERENCE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](../vi/API_REFERENCE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](../bg/API_REFERENCE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](../da/API_REFERENCE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](../fi/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](../he/API_REFERENCE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](../hu/API_REFERENCE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](../id/API_REFERENCE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](../ko/API_REFERENCE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](../ms/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](../nl/API_REFERENCE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](../no/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](../pt/API_REFERENCE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](../ro/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](../pl/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](../sk/API_REFERENCE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](../sv/API_REFERENCE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](../phi/API_REFERENCE.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](../cs/API_REFERENCE.md) - -ๆ‰€ๆœ‰ OmniRoute API ็ซฏ็‚น็š„ๅฎŒๆ•ดๅ‚่€ƒใ€‚ - ---- - -## ็›ฎๅฝ• - -- [Chat Completions](#chat-completions) -- [Embeddings](#embeddings) -- [ๅ›พๅƒ็”Ÿๆˆ](#ๅ›พๅƒ็”Ÿๆˆ) -- [ๆจกๅž‹ๅˆ—่กจ](#ๆจกๅž‹ๅˆ—่กจ) -- [ๅ…ผๅฎนๆ€ง็ซฏ็‚น](#ๅ…ผๅฎนๆ€ง็ซฏ็‚น) -- [่ฏญไน‰็ผ“ๅญ˜](#่ฏญไน‰็ผ“ๅญ˜) -- [Dashboard ไธŽ็ฎก็†](#dashboard-ไธŽ็ฎก็†) -- [่ฏทๆฑ‚ๅค„็†](#่ฏทๆฑ‚ๅค„็†) -- [่ฎค่ฏ](#่ฎค่ฏ) - ---- - -## 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 -} -``` - -### ่‡ชๅฎšไน‰่ฏทๆฑ‚ๅคด - -| ่ฏทๆฑ‚ๅคด | ๆ–นๅ‘ | ๆ่ฟฐ | -| ------------------------ | ------ | ------------------------------------- | -| `X-OmniRoute-No-Cache` | ่ฏทๆฑ‚ | ่ฎพไธบ `true` ็ป•่ฟ‡็ผ“ๅญ˜ | -| `X-OmniRoute-Progress` | ่ฏทๆฑ‚ | ่ฎพไธบ `true` ๅฏ็”จ่ฟ›ๅบฆไบ‹ไปถ | -| `X-Session-Id` | ่ฏทๆฑ‚ | ็”จไบŽๅค–้ƒจไผš่ฏไบฒๅ’Œๆ€ง็š„็ฒ˜ๆ€งไผš่ฏๅฏ†้’ฅ | -| `x_session_id` | ่ฏทๆฑ‚ | ไธ‹ๅˆ’็บฟๅ˜ไฝ“ไนŸ่ขซๆŽฅๅ—๏ผˆ็›ดๆŽฅ HTTP๏ผ‰ | -| `Idempotency-Key` | ่ฏทๆฑ‚ | ๅŽป้‡ๅฏ†้’ฅ๏ผˆ5็ง’็ช—ๅฃ๏ผ‰ | -| `X-Request-Id` | ่ฏทๆฑ‚ | ๅค‡็”จๅŽป้‡ๅฏ†้’ฅ | -| `X-OmniRoute-Cache` | ๅ“ๅบ” | `HIT` ๆˆ– `MISS`๏ผˆ้žๆตๅผ๏ผ‰ | -| `X-OmniRoute-Idempotent` | ๅ“ๅบ” | ๅฆ‚ๆžœๅทฒๅŽป้‡ๅˆ™ไธบ `true` | -| `X-OmniRoute-Progress` | ๅ“ๅบ” | ๅฆ‚ๆžœๅฏ็”จ่ฟ›ๅบฆ่ฟฝ่ธชๅˆ™ไธบ `enabled` | -| `X-OmniRoute-Session-Id` | ๅ“ๅบ” | OmniRoute ไฝฟ็”จ็š„ๆœ‰ๆ•ˆไผš่ฏ ID | - -> **Nginx ๆณจๆ„**: ๅฆ‚ๆžœๆ‚จไพ่ต–ไธ‹ๅˆ’็บฟ่ฏทๆฑ‚ๅคด๏ผˆไพ‹ๅฆ‚ `x_session_id`๏ผ‰๏ผŒ่ฏทๅฏ็”จ `underscores_in_headers 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" -} -``` - -ๅฏ็”จๆไพ›ๅ•†๏ผšNebiusใ€OpenAIใ€Mistralใ€Together AIใ€Fireworksใ€NVIDIAใ€‚ - -```bash -# ๅˆ—ๅ‡บๆ‰€ๆœ‰ Embedding ๆจกๅž‹ -GET /v1/embeddings -``` - ---- - -## ๅ›พๅƒ็”Ÿๆˆ - -```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" -} -``` - -ๅฏ็”จๆไพ›ๅ•†๏ผšOpenAI (DALL-E)ใ€xAI (Grok Image)ใ€Together AI (FLUX)ใ€Fireworks AIใ€‚ - -```bash -# ๅˆ—ๅ‡บๆ‰€ๆœ‰ๅ›พๅƒๆจกๅž‹ -GET /v1/images/generations -``` - ---- - -## ๆจกๅž‹ๅˆ—่กจ - -```bash -GET /v1/models -Authorization: Bearer your-api-key - -โ†’ ไปฅ OpenAI ๆ ผๅผ่ฟ”ๅ›žๆ‰€ๆœ‰ chatใ€embedding ๅ’Œ image ๆจกๅž‹ + combos -``` - ---- - -## ๅ…ผๅฎนๆ€ง็ซฏ็‚น - -| ๆ–นๆณ• | ่ทฏๅพ„ | ๆ ผๅผ | -| ---- | --------------------------- | -------------------- | -| 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 | - -### ไธ“็”จๆไพ›ๅ•†่ทฏ็”ฑ - -```bash -POST /v1/providers/{provider}/chat/completions -POST /v1/providers/{provider}/embeddings -POST /v1/providers/{provider}/images/generations -``` - -ๅฆ‚ๆžœ็ผบๅฐ‘ๆไพ›ๅ•†ๅ‰็ผ€ๅˆ™่‡ชๅŠจๆทปๅŠ ใ€‚ๆจกๅž‹ไธๅŒน้…ๆ—ถ่ฟ”ๅ›ž `400`ใ€‚ - ---- - -## ่ฏญไน‰็ผ“ๅญ˜ - -```bash -# ่Žทๅ–็ผ“ๅญ˜็ปŸ่ฎก -GET /api/cache/stats - -# ๆธ…้™คๆ‰€ๆœ‰็ผ“ๅญ˜ -DELETE /api/cache/stats -``` - -ๅ“ๅบ”็คบไพ‹๏ผš - -```json -{ - "semanticCache": { - "memorySize": 42, - "memoryMaxSize": 500, - "dbSize": 128, - "hitRate": 0.65 - }, - "idempotency": { - "activeKeys": 3, - "windowMs": 5000 - } -} -``` - ---- - -## Dashboard ไธŽ็ฎก็† - -### ่ฎค่ฏ - -| ็ซฏ็‚น | ๆ–นๆณ• | ๆ่ฟฐ | -| ----------------------------- | ------- | ---------------- | -| `/api/auth/login` | POST | ็™ปๅฝ• | -| `/api/auth/logout` | POST | ็™ปๅ‡บ | -| `/api/settings/require-login` | GET/PUT | ๅˆ‡ๆขๆ˜ฏๅฆ้œ€่ฆ็™ปๅฝ• | - -### ๆไพ›ๅ•†็ฎก็† - -| ็ซฏ็‚น | ๆ–นๆณ• | ๆ่ฟฐ | -| ---------------------------- | --------------- | ---------------- | -| `/api/providers` | GET/POST | ๅˆ—ๅ‡บ/ๅˆ›ๅปบๆไพ›ๅ•† | -| `/api/providers/[id]` | GET/PUT/DELETE | ็ฎก็†ๆไพ›ๅ•† | -| `/api/providers/[id]/test` | POST | ๆต‹่ฏ•ๆไพ›ๅ•†่ฟžๆŽฅ | -| `/api/providers/[id]/models` | GET | ๅˆ—ๅ‡บๆไพ›ๅ•†ๆจกๅž‹ | -| `/api/providers/validate` | POST | ้ชŒ่ฏๆไพ›ๅ•†้…็ฝฎ | -| `/api/provider-nodes*` | ๅคš็ง | ๆไพ›ๅ•†่Š‚็‚น็ฎก็† | -| `/api/provider-models` | GET/POST/DELETE | ่‡ชๅฎšไน‰ๆจกๅž‹ | - -### OAuth ๆต็จ‹ - -| ็ซฏ็‚น | ๆ–นๆณ• | ๆ่ฟฐ | -| -------------------------------- | ----- | ------------------ | -| `/api/oauth/[provider]/[action]` | ๅคš็ง | ๆไพ›ๅ•†็‰นๅฎš็š„ OAuth | - -### ่ทฏ็”ฑไธŽ้…็ฝฎ - -| ็ซฏ็‚น | ๆ–นๆณ• | ๆ่ฟฐ | -| --------------------- | -------- | -------------------------- | -| `/api/models/alias` | GET/POST | ๆจกๅž‹ๅˆซๅ | -| `/api/models/catalog` | GET | ๆŒ‰ๆไพ›ๅ•† + ็ฑปๅž‹็š„ๆ‰€ๆœ‰ๆจกๅž‹ | -| `/api/combos*` | ๅคš็ง | Combo ็ฎก็† | -| `/api/keys*` | ๅคš็ง | API ๅฏ†้’ฅ็ฎก็† | -| `/api/pricing` | GET | ๆจกๅž‹ๅฎšไปท | - -### ็”จ้‡ไธŽๅˆ†ๆž - -| ็ซฏ็‚น | ๆ–นๆณ• | ๆ่ฟฐ | -| --------------------------- | ---- | ---------------- | -| `/api/usage/history` | GET | ็”จ้‡ๅŽ†ๅฒ | -| `/api/usage/logs` | GET | ็”จ้‡ๆ—ฅๅฟ— | -| `/api/usage/request-logs` | GET | ่ฏทๆฑ‚็บงๅˆซๆ—ฅๅฟ— | -| `/api/usage/[connectionId]` | GET | ๆŒ‰่ฟžๆŽฅ็š„็”จ้‡ | - -### ่ฎพ็ฝฎ - -| ็ซฏ็‚น | ๆ–นๆณ• | ๆ่ฟฐ | -| ------------------------------- | ------------- | ------------------ | -| `/api/settings` | GET/PUT/PATCH | ๅธธ่ง„่ฎพ็ฝฎ | -| `/api/settings/proxy` | GET/PUT | ็ฝ‘็ปœไปฃ็†้…็ฝฎ | -| `/api/settings/proxy/test` | POST | ๆต‹่ฏ•ไปฃ็†่ฟžๆŽฅ | -| `/api/settings/ip-filter` | GET/PUT | IP ็™ฝๅๅ•/้ป‘ๅๅ• | -| `/api/settings/thinking-budget` | GET/PUT | ๆŽจ็† token ้ข„็ฎ— | -| `/api/settings/system-prompt` | GET/PUT | ๅ…จๅฑ€็ณป็ปŸๆ็คบ่ฏ | - -### ็›‘ๆŽง - -| ็ซฏ็‚น | ๆ–นๆณ• | ๆ่ฟฐ | -| ------------------------ | ---------- | ----------------------------------------------------------- | -| `/api/sessions` | GET | ๆดป่ทƒไผš่ฏ่ฟฝ่ธช | -| `/api/rate-limits` | GET | ๆฏ่ดฆๆˆท้€Ÿ็Ž‡้™ๅˆถ | -| `/api/monitoring/health` | GET | ๅฅๅบทๆฃ€ๆŸฅ + ๆไพ›ๅ•†ๆ‘˜่ฆ๏ผˆ`catalogCount`ใ€`configuredCount`ใ€`activeCount`ใ€`monitoredCount`๏ผ‰ | -| `/api/cache/stats` | GET/DELETE | ็ผ“ๅญ˜็ปŸ่ฎก / ๆธ…้™ค | - -### ๅค‡ไปฝไธŽๅฏผๅ‡บ/ๅฏผๅ…ฅ - -| ็ซฏ็‚น | ๆ–นๆณ• | ๆ่ฟฐ | -| --------------------------- | ---- | ------------------------------ | -| `/api/db-backups` | GET | ๅˆ—ๅ‡บๅฏ็”จๅค‡ไปฝ | -| `/api/db-backups` | PUT | ๅˆ›ๅปบๆ‰‹ๅŠจๅค‡ไปฝ | -| `/api/db-backups` | POST | ไปŽ็‰นๅฎšๅค‡ไปฝๆขๅค | -| `/api/db-backups/export` | GET | ไธ‹่ฝฝๆ•ฐๆฎๅบ“ไธบ .sqlite ๆ–‡ไปถ | -| `/api/db-backups/import` | POST | ไธŠไผ  .sqlite ๆ–‡ไปถๆ›ฟๆขๆ•ฐๆฎๅบ“ | -| `/api/db-backups/exportAll` | GET | ไธ‹่ฝฝๅฎŒๆ•ดๅค‡ไปฝไธบ .tar.gz ๅฝ’ๆกฃ | - -### ไบ‘ๅŒๆญฅ - -| ็ซฏ็‚น | ๆ–นๆณ• | ๆ่ฟฐ | -| ---------------------- | ----- | ------------ | -| `/api/sync/cloud` | ๅคš็ง | ไบ‘ๅŒๆญฅๆ“ไฝœ | -| `/api/sync/initialize` | POST | ๅˆๅง‹ๅŒ–ๅŒๆญฅ | -| `/api/cloud/*` | ๅคš็ง | ไบ‘็ฎก็† | - -### ้šง้“ - -| ็ซฏ็‚น | ๆ–นๆณ• | ๆ่ฟฐ | -| -------------------------- | ---- | ----------------------------------------------------------- | -| `/api/tunnels/cloudflared` | GET | ่ฏปๅ– Dashboard ไฝฟ็”จ็š„ Cloudflare Quick Tunnel ๅฎ‰่ฃ…/่ฟ่กŒ็Šถๆ€ | -| `/api/tunnels/cloudflared` | POST | ๅฏ็”จๆˆ–็ฆ็”จ Cloudflare Quick Tunnel๏ผˆ`action=enable/disable`๏ผ‰ | - -### CLI ๅทฅๅ…ท - -| ็ซฏ็‚น | ๆ–นๆณ• | ๆ่ฟฐ | -| ---------------------------------- | ---- | ---------------- | -| `/api/cli-tools/claude-settings` | GET | Claude CLI ็Šถๆ€ | -| `/api/cli-tools/codex-settings` | GET | Codex CLI ็Šถๆ€ | -| `/api/cli-tools/droid-settings` | GET | Droid CLI ็Šถๆ€ | -| `/api/cli-tools/openclaw-settings` | GET | OpenClaw CLI ็Šถๆ€| -| `/api/cli-tools/runtime/[toolId]` | GET | ้€š็”จ CLI ่ฟ่กŒๆ—ถ | - -CLI ๅ“ๅบ”ๅŒ…ๆ‹ฌ๏ผš`installed`ใ€`runnable`ใ€`command`ใ€`commandPath`ใ€`runtimeMode`ใ€`reason`ใ€‚ - -### ACP ไปฃ็† - -| ็ซฏ็‚น | ๆ–นๆณ• | ๆ่ฟฐ | -| ----------------- | ------ | ---------------------------------------------- | -| `/api/acp/agents` | GET | ๅˆ—ๅ‡บๆ‰€ๆœ‰ๆฃ€ๆต‹ๅˆฐ็š„ไปฃ็†๏ผˆๅ†…็ฝฎ + ่‡ชๅฎšไน‰๏ผ‰ๅŠ็Šถๆ€ | -| `/api/acp/agents` | POST | ๆทปๅŠ ่‡ชๅฎšไน‰ไปฃ็†ๆˆ–ๅˆทๆ–ฐๆฃ€ๆต‹็ผ“ๅญ˜ | -| `/api/acp/agents` | DELETE | ้€š่ฟ‡ `id` ๆŸฅ่ฏขๅ‚ๆ•ฐๅˆ ้™ค่‡ชๅฎšไน‰ไปฃ็† | - -GET ๅ“ๅบ”ๅŒ…ๆ‹ฌ `agents[]`๏ผˆidใ€nameใ€binaryใ€versionใ€installedใ€protocolใ€isCustom๏ผ‰ๅ’Œ `summary`๏ผˆtotalใ€installedใ€notFoundใ€builtInใ€custom๏ผ‰ใ€‚ - -### ๅผนๆ€งไธŽ้€Ÿ็Ž‡้™ๅˆถ - -| ็ซฏ็‚น | ๆ–นๆณ• | ๆ่ฟฐ | -| ----------------------- | ------- | ---------------------- | -| `/api/resilience` | GET/PUT | ่Žทๅ–/ๆ›ดๆ–ฐๅผนๆ€ง้…็ฝฎๆ–‡ไปถ | -| `/api/resilience/reset` | POST | ้‡็ฝฎ็†”ๆ–ญๅ™จ | -| `/api/rate-limits` | GET | ๆฏ่ดฆๆˆท้€Ÿ็Ž‡้™ๅˆถ็Šถๆ€ | -| `/api/rate-limit` | GET | ๅ…จๅฑ€้€Ÿ็Ž‡้™ๅˆถ้…็ฝฎ | - -### ่ฏ„ไผฐ - -| ็ซฏ็‚น | ๆ–นๆณ• | ๆ่ฟฐ | -| ------------ | -------- | ------------------------ | -| `/api/evals` | GET/POST | ๅˆ—ๅ‡บ่ฏ„ไผฐๅฅ—ไปถ/่ฟ่กŒ่ฏ„ไผฐ | - -### ็ญ–็•ฅ - -| ็ซฏ็‚น | ๆ–นๆณ• | ๆ่ฟฐ | -| --------------- | --------------- | -------------- | -| `/api/policies` | GET/POST/DELETE | ็ฎก็†่ทฏ็”ฑ็ญ–็•ฅ | - -### ๅˆ่ง„ - -| ็ซฏ็‚น | ๆ–นๆณ• | ๆ่ฟฐ | -| --------------------------- | ---- | -------------------------- | -| `/api/compliance/audit-log` | GET | ๅˆ่ง„ๅฎก่ฎกๆ—ฅๅฟ—๏ผˆๆœ€ๅŽ N ๆก๏ผ‰ | - -### v1beta๏ผˆGemini ๅ…ผๅฎน๏ผ‰ - -| ็ซฏ็‚น | ๆ–นๆณ• | ๆ่ฟฐ | -| -------------------------- | ---- | --------------------------- | -| `/v1beta/models` | GET | ไปฅ Gemini ๆ ผๅผๅˆ—ๅ‡บๆจกๅž‹ | -| `/v1beta/models/{...path}` | POST | Gemini `generateContent` ็ซฏ็‚น | - -่ฟ™ไบ›็ซฏ็‚น้•œๅƒ Gemini ็š„ API ๆ ผๅผ๏ผŒ็”จไบŽๆœŸๆœ›ๅŽŸ็”Ÿ Gemini SDK ๅ…ผๅฎนๆ€ง็š„ๅฎขๆˆท็ซฏใ€‚ - -### ๅ†…้ƒจ/็ณป็ปŸ API - -| ็ซฏ็‚น | ๆ–นๆณ• | ๆ่ฟฐ | -| --------------- | ---- | ------------------------------------------------ | -| `/api/init` | GET | ๅบ”็”จๅˆๅง‹ๅŒ–ๆฃ€ๆŸฅ๏ผˆ้ฆ–ๆฌก่ฟ่กŒๆ—ถไฝฟ็”จ๏ผ‰ | -| `/api/tags` | GET | Ollama ๅ…ผๅฎน็š„ๆจกๅž‹ๆ ‡็ญพ๏ผˆ็”จไบŽ Ollama ๅฎขๆˆท็ซฏ๏ผ‰ | -| `/api/restart` | POST | ่งฆๅ‘ไผ˜้›…็š„ๆœๅŠกๅ™จ้‡ๅฏ | -| `/api/shutdown` | POST | ่งฆๅ‘ไผ˜้›…็š„ๆœๅŠกๅ™จๅ…ณ้—ญ | - -> **ๆณจๆ„๏ผš** ่ฟ™ไบ›็ซฏ็‚น็”ฑ็ณป็ปŸๅ†…้ƒจไฝฟ็”จๆˆ–็”จไบŽ Ollama ๅฎขๆˆท็ซฏๅ…ผๅฎนๆ€งใ€‚็ปˆ็ซฏ็”จๆˆท้€šๅธธไธ้œ€่ฆ่ฐƒ็”จๅฎƒไปฌใ€‚ - ---- - -## ้Ÿณ้ข‘่ฝฌๅฝ• - -```bash -POST /v1/audio/transcriptions -Authorization: Bearer your-api-key -Content-Type: multipart/form-data -``` - -ไฝฟ็”จ Deepgram ๆˆ– AssemblyAI ่ฝฌๅฝ•้Ÿณ้ข‘ๆ–‡ไปถใ€‚ - -**่ฏทๆฑ‚๏ผš** - -```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" -``` - -**ๅ“ๅบ”๏ผš** - -```json -{ - "text": "Hello, this is the transcribed audio content.", - "task": "transcribe", - "language": "en", - "duration": 12.5 -} -``` - -**ๆ”ฏๆŒ็š„ๆไพ›ๅ•†๏ผš** `deepgram/nova-3`ใ€`assemblyai/best`ใ€‚ - -**ๆ”ฏๆŒ็š„ๆ ผๅผ๏ผš** `mp3`ใ€`wav`ใ€`m4a`ใ€`flac`ใ€`ogg`ใ€`webm`ใ€‚ - ---- - -## Ollama ๅ…ผๅฎนๆ€ง - -็”จไบŽไฝฟ็”จ Ollama API ๆ ผๅผ็š„ๅฎขๆˆท็ซฏ๏ผš - -```bash -# Chat ็ซฏ็‚น๏ผˆOllama ๆ ผๅผ๏ผ‰ -POST /v1/api/chat - -# ๆจกๅž‹ๅˆ—่กจ๏ผˆOllama ๆ ผๅผ๏ผ‰ -GET /api/tags -``` - -่ฏทๆฑ‚ไผš่‡ชๅŠจๅœจ Ollama ๅ’Œๅ†…้ƒจๆ ผๅผไน‹้—ด่ฝฌๆขใ€‚ - ---- - -## ้ฅๆต‹ - -```bash -# ่Žทๅ–ๅปถ่ฟŸ้ฅๆต‹ๆ‘˜่ฆ๏ผˆๆฏๆไพ›ๅ•†็š„ p50/p95/p99๏ผ‰ -GET /api/telemetry/summary -``` - -**ๅ“ๅบ”๏ผš** - -```json -{ - "providers": { - "claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 }, - "github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 } - } -} -``` - ---- - -## ้ข„็ฎ— - -```bash -# ่Žทๅ–ๆ‰€ๆœ‰ API ๅฏ†้’ฅ็š„้ข„็ฎ—็Šถๆ€ -GET /api/usage/budget - -# ่ฎพ็ฝฎๆˆ–ๆ›ดๆ–ฐ้ข„็ฎ— -POST /api/usage/budget -Content-Type: application/json - -{ - "keyId": "key-123", - "limit": 50.00, - "period": "monthly" -} -``` - ---- - -## ๆจกๅž‹ๅฏ็”จๆ€ง - -```bash -# ่Žทๅ–ๆ‰€ๆœ‰ๆไพ›ๅ•†็š„ๅฎžๆ—ถๆจกๅž‹ๅฏ็”จๆ€ง -GET /api/models/availability - -# ๆฃ€ๆŸฅ็‰นๅฎšๆจกๅž‹็š„ๅฏ็”จๆ€ง -POST /api/models/availability -Content-Type: application/json - -{ - "model": "claude-sonnet-4-5-20250929" -} -``` - ---- - -## ่ฏทๆฑ‚ๅค„็† - -1. ๅฎขๆˆท็ซฏๅ‘ `/v1/*` ๅ‘้€่ฏทๆฑ‚ -2. ่ทฏ็”ฑๅค„็†ๅ™จ่ฐƒ็”จ `handleChat`ใ€`handleEmbedding`ใ€`handleAudioTranscription` ๆˆ– `handleImageGeneration` -3. ่งฃๆžๆจกๅž‹๏ผˆ็›ดๆŽฅ provider/model ๆˆ– alias/combo๏ผ‰ -4. ไปŽๆœฌๅœฐๆ•ฐๆฎๅบ“้€‰ๆ‹ฉๅ‡ญๆฎ๏ผŒๅนถ่ฟ‡ๆปค่ดฆๆˆทๅฏ็”จๆ€ง -5. ๅฏนไบŽ chat๏ผš`handleChatCore` โ€” ๆ ผๅผๆฃ€ๆต‹ใ€็ฟป่ฏ‘ใ€็ผ“ๅญ˜ๆฃ€ๆŸฅใ€ๅน‚็ญ‰ๆ€งๆฃ€ๆŸฅ -6. ๆไพ›ๅ•†ๆ‰ง่กŒๅ™จๅ‘้€ไธŠๆธธ่ฏทๆฑ‚ -7. ๅ“ๅบ”็ฟป่ฏ‘ๅ›žๅฎขๆˆท็ซฏๆ ผๅผ๏ผˆchat๏ผ‰ๆˆ–็›ดๆŽฅ่ฟ”ๅ›ž๏ผˆembeddings/images/audio๏ผ‰ -8. ่ฎฐๅฝ•็”จ้‡/ๆ—ฅๅฟ— -9. ๆ นๆฎ combo ่ง„ๅˆ™ๅœจ้”™่ฏฏๆ—ถๅบ”็”จๅŽๅค‡ - -ๅฎŒๆ•ดๆžถๆž„ๅ‚่€ƒ๏ผš[`ARCHITECTURE.md`](ARCHITECTURE.md) - ---- - -## ่ฎค่ฏ - -- Dashboard ่ทฏ็”ฑ๏ผˆ`/dashboard/*`๏ผ‰ไฝฟ็”จ `auth_token` cookie -- ็™ปๅฝ•ไฝฟ็”จไฟๅญ˜็š„ๅฏ†็ ๅ“ˆๅธŒ๏ผ›ๅ›ž้€€ๅˆฐ `INITIAL_PASSWORD` -- `requireLogin` ๅฏ้€š่ฟ‡ `/api/settings/require-login` ๅˆ‡ๆข -- ๅฝ“ `REQUIRE_API_KEY=true` ๆ—ถ๏ผŒ`/v1/*` ่ทฏ็”ฑๅฏ้€‰ๅœฐ้œ€่ฆ Bearer API ๅฏ†้’ฅ diff --git a/docs/i18n/zh-CN/ARCHITECTURE.md b/docs/i18n/zh-CN/ARCHITECTURE.md deleted file mode 100644 index d362ef2cc5..0000000000 --- a/docs/i18n/zh-CN/ARCHITECTURE.md +++ /dev/null @@ -1,812 +0,0 @@ -# OmniRoute ๆžถๆž„ - -๐ŸŒ **่ฏญ่จ€:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](../pt-BR/ARCHITECTURE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](../es/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](../fr/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](../it/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](../ru/ARCHITECTURE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](../zh-CN/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](../de/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](../in/ARCHITECTURE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](../th/ARCHITECTURE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](../uk-UA/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](../ar/ARCHITECTURE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](../ja/ARCHITECTURE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](../vi/ARCHITECTURE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](../bg/ARCHITECTURE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](../da/ARCHITECTURE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](../fi/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](../he/ARCHITECTURE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](../hu/ARCHITECTURE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](../id/ARCHITECTURE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](../ko/ARCHITECTURE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](../ms/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](../nl/ARCHITECTURE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](../no/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](../pt/ARCHITECTURE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](../ro/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](../pl/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](../sk/ARCHITECTURE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](../sv/ARCHITECTURE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](../phi/ARCHITECTURE.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](../cs/ARCHITECTURE.md) - -_ๆœ€ๅŽๆ›ดๆ–ฐ๏ผš2026-03-28_ - -## ๆฆ‚่ฟฐ - -OmniRoute ๆ˜ฏไธ€ไธชๅŸบไบŽ Next.js ๆž„ๅปบ็š„ๆœฌๅœฐ AI ่ทฏ็”ฑ็ฝ‘ๅ…ณๅ’Œไปช่กจ็›˜ใ€‚ -ๅฎƒๆไพ›ๅ•ไธ€็š„ OpenAI ๅ…ผๅฎน็ซฏ็‚น๏ผˆ`/v1/*`๏ผ‰๏ผŒๅนถๅฐ†ๆต้‡่ทฏ็”ฑๅˆฐๅคšไธชไธŠๆธธๆไพ›ๅ•†๏ผŒๆ”ฏๆŒ็ฟป่ฏ‘ใ€ๅŽๅค‡ใ€Token ๅˆทๆ–ฐๅ’Œ็”จ้‡่ฟฝ่ธชใ€‚ - -ๆ ธๅฟƒ่ƒฝๅŠ›๏ผš - -- ้ขๅ‘ CLI/ๅทฅๅ…ท็š„ OpenAI ๅ…ผๅฎน API ๆŽฅๅฃ๏ผˆ28 ไธชๆไพ›ๅ•†๏ผ‰ -- ่ทจๆไพ›ๅ•†ๆ ผๅผ็š„่ฏทๆฑ‚/ๅ“ๅบ”็ฟป่ฏ‘ -- ๆจกๅž‹ Combo ๅŽๅค‡๏ผˆๅคšๆจกๅž‹ๅบๅˆ—๏ผ‰ -- ่ดฆๆˆท็บงๅŽๅค‡๏ผˆๆฏไธชๆไพ›ๅ•†ๅคš่ดฆๆˆท๏ผ‰ -- OAuth + API ๅฏ†้’ฅๆไพ›ๅ•†่ฟžๆŽฅ็ฎก็† -- ้€š่ฟ‡ `/v1/embeddings` ็”Ÿๆˆ Embedding๏ผˆ6 ไธชๆไพ›ๅ•†๏ผŒ9 ไธชๆจกๅž‹๏ผ‰ -- ้€š่ฟ‡ `/v1/images/generations` ็”Ÿๆˆๅ›พๅƒ๏ผˆ4 ไธชๆไพ›ๅ•†๏ผŒ9 ไธชๆจกๅž‹๏ผ‰ -- Think ๆ ‡็ญพ่งฃๆž๏ผˆ`...`๏ผ‰็”จไบŽๆŽจ็†ๆจกๅž‹ -- ๅ“ๅบ”ๆธ…็†ไปฅๅฎž็Žฐไธฅๆ ผ็š„ OpenAI SDK ๅ…ผๅฎนๆ€ง -- ่ง’่‰ฒ่ง„่ŒƒๅŒ–๏ผˆdeveloperโ†’system๏ผŒsystemโ†’user๏ผ‰ๅฎž็Žฐ่ทจๆไพ›ๅ•†ๅ…ผๅฎน -- ็ป“ๆž„ๅŒ–่พ“ๅ‡บ่ฝฌๆข๏ผˆjson_schema โ†’ Gemini responseSchema๏ผ‰ -- ๆœฌๅœฐๆŒไน…ๅŒ–๏ผšๆไพ›ๅ•†ใ€ๅฏ†้’ฅใ€ๅˆซๅใ€Comboใ€่ฎพ็ฝฎใ€ๅฎšไปท -- ็”จ้‡/ๆˆๆœฌ่ฟฝ่ธชๅ’Œ่ฏทๆฑ‚ๆ—ฅๅฟ— -- ๅฏ้€‰็š„ไบ‘ๅŒๆญฅ็”จไบŽๅคš่ฎพๅค‡/็Šถๆ€ๅŒๆญฅ -- API ่ฎฟ้—ฎๆŽงๅˆถ็š„ IP ็™ฝๅๅ•/้ป‘ๅๅ• -- Thinking ้ข„็ฎ—็ฎก็†๏ผˆpassthrough/auto/custom/adaptive๏ผ‰ -- ๅ…จๅฑ€็ณป็ปŸๆ็คบ่ฏๆณจๅ…ฅ -- ไผš่ฏ่ฟฝ่ธชๅ’ŒๆŒ‡็บน่ฏ†ๅˆซ -- ๆฏ่ดฆๆˆทๅขžๅผบ้€Ÿ็Ž‡้™ๅˆถ๏ผŒๆ”ฏๆŒๆไพ›ๅ•†็‰นๅฎš้…็ฝฎๆ–‡ไปถ -- ๆไพ›ๅ•†ๅผนๆ€ง็š„็†”ๆ–ญๅ™จๆจกๅผ -- ไฝฟ็”จไบ’ๆ–ฅ้”็š„้˜ฒๆƒŠ็พคไฟๆŠค -- ๅŸบไบŽ็ญพๅ็š„่ฏทๆฑ‚ๅŽป้‡็ผ“ๅญ˜ -- ้ข†ๅŸŸๅฑ‚๏ผšๆจกๅž‹ๅฏ็”จๆ€งใ€ๆˆๆœฌ่ง„ๅˆ™ใ€ๅŽๅค‡็ญ–็•ฅใ€้”ๅฎš็ญ–็•ฅ -- ้ข†ๅŸŸ็Šถๆ€ๆŒไน…ๅŒ–๏ผˆSQLite ๅ†™ๅ…ฅ็ผ“ๅญ˜็”จไบŽๅŽๅค‡ใ€้ข„็ฎ—ใ€้”ๅฎšใ€็†”ๆ–ญๅ™จ๏ผ‰ -- ้›†ไธญ่ฏทๆฑ‚่ฏ„ไผฐ็š„็ญ–็•ฅๅผ•ๆ“Ž๏ผˆ้”ๅฎš โ†’ ้ข„็ฎ— โ†’ ๅŽๅค‡๏ผ‰ -- ่ฏทๆฑ‚้ฅๆต‹๏ผŒๆ”ฏๆŒ p50/p95/p99 ๅปถ่ฟŸ่šๅˆ -- ๅ…ณ่” ID๏ผˆX-Request-Id๏ผ‰็”จไบŽ็ซฏๅˆฐ็ซฏ่ฟฝ่ธช -- ๅˆ่ง„ๅฎก่ฎกๆ—ฅๅฟ—๏ผŒๆ”ฏๆŒๆŒ‰ API ๅฏ†้’ฅ้€‰ๆ‹ฉ้€€ๅ‡บ -- ็”จไบŽ LLM ่ดจ้‡ไฟ่ฏ็š„่ฏ„ไผฐๆก†ๆžถ -- ๅฎžๆ—ถ็†”ๆ–ญๅ™จ็Šถๆ€็š„ๅผนๆ€ง UI ไปช่กจ็›˜ -- ๆจกๅ—ๅŒ– OAuth ๆไพ›ๅ•†๏ผˆ`src/lib/oauth/providers/` ไธ‹็š„ 12 ไธช็‹ฌ็ซ‹ๆจกๅ—๏ผ‰ - -ไธป่ฆ่ฟ่กŒๆ—ถๆจกๅž‹๏ผš - -- `src/app/api/*` ไธ‹็š„ Next.js app routes ๅŒๆ—ถๅฎž็Žฐ Dashboard API ๅ’Œๅ…ผๅฎนๆ€ง API -- `src/sse/*` + `open-sse/*` ไธญ็š„ๅ…ฑไบซ SSE/่ทฏ็”ฑๆ ธๅฟƒๅค„็†ๆไพ›ๅ•†ๆ‰ง่กŒใ€็ฟป่ฏ‘ใ€ๆตๅผไผ ่พ“ใ€ๅŽๅค‡ๅ’Œ็”จ้‡ - -## ่Œƒๅ›ดไธŽ่พน็•Œ - -### ่Œƒๅ›ดๅ†… - -- ๆœฌๅœฐ็ฝ‘ๅ…ณ่ฟ่กŒๆ—ถ -- Dashboard ็ฎก็† API -- ๆไพ›ๅ•†่ฎค่ฏๅ’Œ Token ๅˆทๆ–ฐ -- ่ฏทๆฑ‚็ฟป่ฏ‘ๅ’Œ SSE ๆตๅผไผ ่พ“ -- ๆœฌๅœฐ็Šถๆ€ + ็”จ้‡ๆŒไน…ๅŒ– -- ๅฏ้€‰็š„ไบ‘ๅŒๆญฅ็ผ–ๆŽ’ - -### ่Œƒๅ›ดๅค– - -- `NEXT_PUBLIC_CLOUD_URL` ๅŽ้ข็š„ไบ‘ๆœๅŠกๅฎž็Žฐ -- ๆœฌๅœฐ่ฟ›็จ‹ไน‹ๅค–็š„ๆไพ›ๅ•† SLA/ๆŽงๅˆถๅนณ้ข -- ๅค–้ƒจ CLI ไบŒ่ฟ›ๅˆถๆ–‡ไปถๆœฌ่บซ๏ผˆClaude CLIใ€Codex CLI ็ญ‰๏ผ‰ - -## Dashboard ็•Œ้ข๏ผˆๅฝ“ๅ‰๏ผ‰ - -`src/app/(dashboard)/dashboard/` ไธ‹็š„ไธป่ฆ้กต้ข๏ผš - -- `/dashboard` โ€” ๅฟซ้€Ÿๅ…ฅ้—จ + ๆœๅŠกๅ•†ๆฆ‚่งˆ -- `/dashboard/endpoint` โ€” ็ซฏ็‚นไปฃ็† + MCP + A2A + API ็ซฏ็‚นๆ ‡็ญพ้กต -- `/dashboard/providers` โ€” ๆœๅŠกๅ•†่ฟžๆŽฅๅ’Œๅ‡ญ่ฏ -- `/dashboard/combos` โ€” Combo ็ญ–็•ฅใ€ๆจกๆฟใ€ๆจกๅž‹่ทฏ็”ฑ่ง„ๅˆ™ -- `/dashboard/costs` โ€” ๆˆๆœฌๆฑ‡ๆ€ปๅ’Œๅฎšไปทๅฏ่งๆ€ง -- `/dashboard/analytics` โ€” ไฝฟ็”จๅˆ†ๆžๅ’Œ่ฏ„ไผฐ -- `/dashboard/limits` โ€” ้…้ข/้€Ÿ็Ž‡ๆŽงๅˆถ -- `/dashboard/cli-tools` โ€” CLI ๅผ•ๅฏผใ€่ฟ่กŒๆ—ถๆฃ€ๆต‹ใ€้…็ฝฎ็”Ÿๆˆ -- `/dashboard/agents` โ€” ๆฃ€ๆต‹ๅˆฐ็š„ ACP ไปฃ็† + ่‡ชๅฎšไน‰ไปฃ็†ๆณจๅ†Œ -- `/dashboard/media` โ€” ๅ›พๅƒ/่ง†้ข‘/้Ÿณไน playground -- `/dashboard/search-tools` โ€” ๆœ็ดขๆœๅŠกๅ•†ๆต‹่ฏ•ๅ’ŒๅŽ†ๅฒ -- `/dashboard/health` โ€” ๆญฃๅธธ่ฟ่กŒๆ—ถ้—ดใ€็†”ๆ–ญๅ™จใ€้€Ÿ็Ž‡้™ๅˆถ -- `/dashboard/logs` โ€” ่ฏทๆฑ‚/ไปฃ็†/ๅฎก่ฎก/ๆŽงๅˆถๅฐๆ—ฅๅฟ— -- `/dashboard/settings` โ€” ็ณป็ปŸ่ฎพ็ฝฎๆ ‡็ญพ้กต๏ผˆ้€š็”จใ€่ทฏ็”ฑใ€Combo ้ป˜่ฎคๅ€ผ็ญ‰๏ผ‰ -- `/dashboard/api-manager` โ€” API ๅฏ†้’ฅ็”Ÿๅ‘ฝๅ‘จๆœŸๅ’Œๆจกๅž‹ๆƒ้™ - -## ้ซ˜ๅฑ‚็ณป็ปŸไธŠไธ‹ๆ–‡ - -```mermaid -flowchart LR - subgraph Clients[ๅผ€ๅ‘่€…ๅฎขๆˆท็ซฏ] - C1[Claude Code] - C2[Codex CLI] - C3[OpenClaw / Droid / Cline / Continue / Roo] - C4[่‡ชๅฎšไน‰ OpenAI ๅ…ผๅฎนๅฎขๆˆท็ซฏ] - BROWSER[ๆต่งˆๅ™จไปช่กจ็›˜] - end - - subgraph Router[OmniRoute ๆœฌๅœฐ่ฟ›็จ‹] - API[V1 ๅ…ผๅฎนๆ€ง API\n/v1/*] - DASH[Dashboard + ็ฎก็† API\n/api/*] - CORE[SSE + ็ฟป่ฏ‘ๆ ธๅฟƒ\nopen-sse + src/sse] - DB[(storage.sqlite)] - UDB[(็”จ้‡่กจ + ๆ—ฅๅฟ—ๆ–‡ไปถ)] - end - - subgraph Upstreams[ไธŠๆธธๆไพ›ๅ•†] - P1[OAuth ๆไพ›ๅ•†\nClaude/Codex/Gemini/Qwen/Qoder/GitHub/Kiro/Cursor/Antigravity] - P2[API ๅฏ†้’ฅๆไพ›ๅ•†\nOpenAI/Anthropic/OpenRouter/GLM/Kimi/MiniMax\nDeepSeek/Groq/xAI/Mistral/Perplexity\nTogether/Fireworks/Cerebras/Cohere/NVIDIA] - P3[ๅ…ผๅฎน่Š‚็‚น\nOpenAI ๅ…ผๅฎน / Anthropic ๅ…ผๅฎน] - end - - subgraph Cloud[ๅฏ้€‰ไบ‘ๅŒๆญฅ] - CLOUD[ไบ‘ๅŒๆญฅ็ซฏ็‚น\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 -``` - -## ๆ ธๅฟƒ่ฟ่กŒๆ—ถ็ป„ไปถ - -## 1) API ๅ’Œ่ทฏ็”ฑๅฑ‚๏ผˆNext.js App Routes๏ผ‰ - -ไธป่ฆ็›ฎๅฝ•๏ผš - -- `src/app/api/v1/*` ๅ’Œ `src/app/api/v1beta/*` ็”จไบŽๅ…ผๅฎนๆ€ง API -- `src/app/api/*` ็”จไบŽ็ฎก็†/้…็ฝฎ API -- `next.config.mjs` ไธญ็š„ Next ้‡ๅ†™ๅฐ† `/v1/*` ๆ˜ ๅฐ„ๅˆฐ `/api/v1/*` - -้‡่ฆ็š„ๅ…ผๅฎนๆ€ง่ทฏ็”ฑ๏ผš - -- `src/app/api/v1/chat/completions/route.ts` -- `src/app/api/v1/messages/route.ts` -- `src/app/api/v1/responses/route.ts` -- `src/app/api/v1/models/route.ts` โ€” ๅŒ…ๅซ `custom: true` ็š„่‡ชๅฎšไน‰ๆจกๅž‹ -- `src/app/api/v1/embeddings/route.ts` โ€” Embedding ็”Ÿๆˆ๏ผˆ6 ไธชๆไพ›ๅ•†๏ผ‰ -- `src/app/api/v1/images/generations/route.ts` โ€” ๅ›พๅƒ็”Ÿๆˆ๏ผˆ4+ ไธชๆไพ›ๅ•†๏ผŒๅŒ…ๆ‹ฌ Antigravity/Nebius๏ผ‰ -- `src/app/api/v1/messages/count_tokens/route.ts` -- `src/app/api/v1/providers/[provider]/chat/completions/route.ts` โ€” ไธ“็”จ็š„ๆฏๆไพ›ๅ•†่Šๅคฉ -- `src/app/api/v1/providers/[provider]/embeddings/route.ts` โ€” ไธ“็”จ็š„ๆฏๆไพ›ๅ•† Embedding -- `src/app/api/v1/providers/[provider]/images/generations/route.ts` โ€” ไธ“็”จ็š„ๆฏๆไพ›ๅ•†ๅ›พๅƒ -- `src/app/api/v1beta/models/route.ts` -- `src/app/api/v1beta/models/[...path]/route.ts` - -็ฎก็†้ข†ๅŸŸ๏ผš - -- ่ฎค่ฏ/่ฎพ็ฝฎ๏ผš`src/app/api/auth/*`ใ€`src/app/api/settings/*` -- ๆไพ›ๅ•†/่ฟžๆŽฅ๏ผš`src/app/api/providers*` -- ๆไพ›ๅ•†่Š‚็‚น๏ผš`src/app/api/provider-nodes*` -- ่‡ชๅฎšไน‰ๆจกๅž‹๏ผš`src/app/api/provider-models`๏ผˆGET/POST/DELETE๏ผ‰ -- ๆจกๅž‹็›ฎๅฝ•๏ผš`src/app/api/models/route.ts`๏ผˆGET๏ผ‰ -- ไปฃ็†้…็ฝฎ๏ผš`src/app/api/settings/proxy`๏ผˆGET/PUT/DELETE๏ผ‰+ `src/app/api/settings/proxy/test`๏ผˆPOST๏ผ‰ -- OAuth๏ผš`src/app/api/oauth/*` -- ๅฏ†้’ฅ/ๅˆซๅ/Combo/ๅฎšไปท๏ผš`src/app/api/keys*`ใ€`src/app/api/models/alias`ใ€`src/app/api/combos*`ใ€`src/app/api/pricing` -- ็”จ้‡๏ผš`src/app/api/usage/*` -- ๅŒๆญฅ/ไบ‘๏ผš`src/app/api/sync/*`ใ€`src/app/api/cloud/*` -- CLI ๅทฅๅ…ทๅŠฉๆ‰‹๏ผš`src/app/api/cli-tools/*` -- IP ่ฟ‡ๆปค๏ผš`src/app/api/settings/ip-filter`๏ผˆGET/PUT๏ผ‰ -- Thinking ้ข„็ฎ—๏ผš`src/app/api/settings/thinking-budget`๏ผˆGET/PUT๏ผ‰ -- ็ณป็ปŸๆ็คบ่ฏ๏ผš`src/app/api/settings/system-prompt`๏ผˆGET/PUT๏ผ‰ -- ไผš่ฏ๏ผš`src/app/api/sessions`๏ผˆGET๏ผ‰ -- ้€Ÿ็Ž‡้™ๅˆถ๏ผš`src/app/api/rate-limits`๏ผˆGET๏ผ‰ -- ๅผนๆ€ง๏ผš`src/app/api/resilience`๏ผˆGET/PATCH๏ผ‰โ€” ๆไพ›ๅ•†้…็ฝฎๆ–‡ไปถใ€็†”ๆ–ญๅ™จใ€้€Ÿ็Ž‡้™ๅˆถ็Šถๆ€ -- ๅผนๆ€ง้‡็ฝฎ๏ผš`src/app/api/resilience/reset`๏ผˆPOST๏ผ‰โ€” ้‡็ฝฎ็†”ๆ–ญๅ™จ + ๅ†ทๅด -- ็ผ“ๅญ˜็ปŸ่ฎก๏ผš`src/app/api/cache/stats`๏ผˆGET/DELETE๏ผ‰ -- ๆจกๅž‹ๅฏ็”จๆ€ง๏ผš`src/app/api/models/availability`๏ผˆGET/POST๏ผ‰ -- ้ฅๆต‹๏ผš`src/app/api/telemetry/summary`๏ผˆGET๏ผ‰ -- ้ข„็ฎ—๏ผš`src/app/api/usage/budget`๏ผˆGET/POST๏ผ‰ -- ๅŽๅค‡้“พ๏ผš`src/app/api/fallback/chains`๏ผˆGET/POST/DELETE๏ผ‰ -- ๅˆ่ง„ๅฎก่ฎก๏ผš`src/app/api/compliance/audit-log`๏ผˆGET๏ผ‰ -- ่ฏ„ไผฐ๏ผš`src/app/api/evals`๏ผˆGET/POST๏ผ‰ใ€`src/app/api/evals/[suiteId]`๏ผˆGET๏ผ‰ -- ็ญ–็•ฅ๏ผš`src/app/api/policies`๏ผˆGET/POST๏ผ‰ - -## 2) SSE + ็ฟป่ฏ‘ๆ ธๅฟƒ - -ไธป่ฆๆต็จ‹ๆจกๅ—๏ผš - -- ๅ…ฅๅฃ๏ผš`src/sse/handlers/chat.ts` -- ๆ ธๅฟƒ็ผ–ๆŽ’๏ผš`open-sse/handlers/chatCore.ts` -- ๆไพ›ๅ•†ๆ‰ง่กŒ้€‚้…ๅ™จ๏ผš`open-sse/executors/*` -- ๆ ผๅผๆฃ€ๆต‹/ๆไพ›ๅ•†้…็ฝฎ๏ผš`open-sse/services/provider.ts` -- ๆจกๅž‹่งฃๆž/่งฃๆž๏ผš`src/sse/services/model.ts`ใ€`open-sse/services/model.ts` -- ่ดฆๆˆทๅŽๅค‡้€ป่พ‘๏ผš`open-sse/services/accountFallback.ts` -- ็ฟป่ฏ‘ๆณจๅ†Œ่กจ๏ผš`open-sse/translator/index.ts` -- ๆต่ฝฌๆข๏ผš`open-sse/utils/stream.ts`ใ€`open-sse/utils/streamHandler.ts` -- ็”จ้‡ๆๅ–/่ง„่ŒƒๅŒ–๏ผš`open-sse/utils/usageTracking.ts` -- Think ๆ ‡็ญพ่งฃๆžๅ™จ๏ผš`open-sse/utils/thinkTagParser.ts` -- Embedding ๅค„็†ๅ™จ๏ผš`open-sse/handlers/embeddings.ts` -- Embedding ๆไพ›ๅ•†ๆณจๅ†Œ่กจ๏ผš`open-sse/config/embeddingRegistry.ts` -- ๅ›พๅƒ็”Ÿๆˆๅค„็†ๅ™จ๏ผš`open-sse/handlers/imageGeneration.ts` -- ๅ›พๅƒๆไพ›ๅ•†ๆณจๅ†Œ่กจ๏ผš`open-sse/config/imageRegistry.ts` -- ๅ“ๅบ”ๆธ…็†๏ผš`open-sse/handlers/responseSanitizer.ts` -- ่ง’่‰ฒ่ง„่ŒƒๅŒ–๏ผš`open-sse/services/roleNormalizer.ts` - -ๆœๅŠก๏ผˆไธšๅŠก้€ป่พ‘๏ผ‰๏ผš - -- ่ดฆๆˆท้€‰ๆ‹ฉ/่ฏ„ๅˆ†๏ผš`open-sse/services/accountSelector.ts` -- ไธŠไธ‹ๆ–‡็”Ÿๅ‘ฝๅ‘จๆœŸ็ฎก็†๏ผš`open-sse/services/contextManager.ts` -- IP ่ฟ‡ๆปคๆ‰ง่กŒ๏ผš`open-sse/services/ipFilter.ts` -- ไผš่ฏ่ฟฝ่ธช๏ผš`open-sse/services/sessionManager.ts` -- ่ฏทๆฑ‚ๅŽป้‡๏ผš`open-sse/services/signatureCache.ts` -- ็ณป็ปŸๆ็คบ่ฏๆณจๅ…ฅ๏ผš`open-sse/services/systemPrompt.ts` -- Thinking ้ข„็ฎ—็ฎก็†๏ผš`open-sse/services/thinkingBudget.ts` -- ้€š้…็ฌฆๆจกๅž‹่ทฏ็”ฑ๏ผš`open-sse/services/wildcardRouter.ts` -- ้€Ÿ็Ž‡้™ๅˆถ็ฎก็†๏ผš`open-sse/services/rateLimitManager.ts` -- ็†”ๆ–ญๅ™จ๏ผš`open-sse/services/circuitBreaker.ts` - -้ข†ๅŸŸๅฑ‚ๆจกๅ—๏ผš - -- ๆจกๅž‹ๅฏ็”จๆ€ง๏ผš`src/lib/domain/modelAvailability.ts` -- ๆˆๆœฌ่ง„ๅˆ™/้ข„็ฎ—๏ผš`src/lib/domain/costRules.ts` -- ๅŽๅค‡็ญ–็•ฅ๏ผš`src/lib/domain/fallbackPolicy.ts` -- Combo ่งฃๆžๅ™จ๏ผš`src/lib/domain/comboResolver.ts` -- ้”ๅฎš็ญ–็•ฅ๏ผš`src/lib/domain/lockoutPolicy.ts` -- ็ญ–็•ฅๅผ•ๆ“Ž๏ผš`src/domain/policyEngine.ts` โ€” ้›†ไธญ็š„้”ๅฎš โ†’ ้ข„็ฎ— โ†’ ๅŽๅค‡่ฏ„ไผฐ -- ้”™่ฏฏ็ ็›ฎๅฝ•๏ผš`src/lib/domain/errorCodes.ts` -- ่ฏทๆฑ‚ ID๏ผš`src/lib/domain/requestId.ts` -- Fetch ่ถ…ๆ—ถ๏ผš`src/lib/domain/fetchTimeout.ts` -- ่ฏทๆฑ‚้ฅๆต‹๏ผš`src/lib/domain/requestTelemetry.ts` -- ๅˆ่ง„/ๅฎก่ฎก๏ผš`src/lib/domain/compliance/index.ts` -- ่ฏ„ไผฐ่ฟ่กŒๅ™จ๏ผš`src/lib/domain/evalRunner.ts` -- ้ข†ๅŸŸ็Šถๆ€ๆŒไน…ๅŒ–๏ผš`src/lib/db/domainState.ts` โ€” ๅŽๅค‡้“พใ€้ข„็ฎ—ใ€ๆˆๆœฌๅŽ†ๅฒใ€้”ๅฎš็Šถๆ€ใ€็†”ๆ–ญๅ™จ็š„ SQLite CRUD - -OAuth ๆไพ›ๅ•†ๆจกๅ—๏ผˆ`src/lib/oauth/providers/` ไธ‹็š„ 12 ไธช็‹ฌ็ซ‹ๆ–‡ไปถ๏ผ‰๏ผš - -- ๆณจๅ†Œ่กจ็ดขๅผ•๏ผš`src/lib/oauth/providers/index.ts` -- ็‹ฌ็ซ‹ๆไพ›ๅ•†๏ผš`claude.ts`ใ€`codex.ts`ใ€`gemini.ts`ใ€`antigravity.ts`ใ€`qoder.ts`ใ€`qwen.ts`ใ€`kimi-coding.ts`ใ€`github.ts`ใ€`kiro.ts`ใ€`cursor.ts`ใ€`kilocode.ts`ใ€`cline.ts` -- ่–„ๅŒ…่ฃ…ๅ™จ๏ผš`src/lib/oauth/providers.ts` โ€” ไปŽ็‹ฌ็ซ‹ๆจกๅ—้‡ๆ–ฐๅฏผๅ‡บ - -## 3) ๆŒไน…ๅŒ–ๅฑ‚ - -ไธป่ฆ็Šถๆ€ๆ•ฐๆฎๅบ“๏ผˆSQLite๏ผ‰๏ผš - -- ๆ ธๅฟƒๅŸบ็ก€่ฎพๆ–ฝ๏ผš`src/lib/db/core.ts`๏ผˆbetter-sqlite3ใ€่ฟ็งปใ€WAL๏ผ‰ -- ้‡ๆ–ฐๅฏผๅ‡บๅค–่ง‚๏ผš`src/lib/localDb.ts`๏ผˆ้ขๅ‘่ฐƒ็”จ่€…็š„่–„ๅ…ผๅฎนๅฑ‚๏ผ‰ -- ๆ–‡ไปถ๏ผš`${DATA_DIR}/storage.sqlite`๏ผˆๆˆ–่ฎพ็ฝฎ `$XDG_CONFIG_HOME/omniroute/storage.sqlite` ๆ—ถไฝฟ็”จ่ฏฅ่ทฏๅพ„๏ผŒๅฆๅˆ™ไธบ `~/.omniroute/storage.sqlite`๏ผ‰ -- ๅฎžไฝ“๏ผˆ่กจ + KV ๅ‘ฝๅ็ฉบ้—ด๏ผ‰๏ผšproviderConnectionsใ€providerNodesใ€modelAliasesใ€combosใ€apiKeysใ€settingsใ€pricingใ€**customModels**ใ€**proxyConfig**ใ€**ipFilter**ใ€**thinkingBudget**ใ€**systemPrompt** - -็”จ้‡ๆŒไน…ๅŒ–๏ผš - -- ๅค–่ง‚๏ผš`src/lib/usageDb.ts`๏ผˆๅˆ†่งฃๆจกๅ—ๅœจ `src/lib/usage/*`๏ผ‰ -- `storage.sqlite` ไธญ็š„ SQLite ่กจ๏ผš`usage_history`ใ€`call_logs`ใ€`proxy_logs` -- ๅฏ้€‰็š„ๆ–‡ไปถๅทฅไปถไธบๅ…ผๅฎนๆ€ง/่ฐƒ่ฏ•ไฟ็•™๏ผˆ`${DATA_DIR}/log.txt`ใ€`${DATA_DIR}/call_logs/`ใ€`/logs/...`๏ผ‰ -- ๆ—ง็‰ˆ JSON ๆ–‡ไปถๅœจๅฏๅŠจ่ฟ็งปๆ—ถไผš่ขซ่ฟ็งปๅˆฐ SQLite - -้ข†ๅŸŸ็Šถๆ€ๆ•ฐๆฎๅบ“๏ผˆSQLite๏ผ‰๏ผš - -- `src/lib/db/domainState.ts` โ€” ้ข†ๅŸŸ็Šถๆ€็š„ CRUD ๆ“ไฝœ -- ่กจ๏ผˆๅœจ `src/lib/db/core.ts` ไธญๅˆ›ๅปบ๏ผ‰๏ผš`domain_fallback_chains`ใ€`domain_budgets`ใ€`domain_cost_history`ใ€`domain_lockout_state`ใ€`domain_circuit_breakers` -- ๅ†™ๅ…ฅ็ผ“ๅญ˜ๆจกๅผ๏ผšๅ†…ๅญ˜ไธญ็š„ Map ๅœจ่ฟ่กŒๆ—ถๆ˜ฏๆƒๅจ็š„๏ผ›ๅ˜ๆ›ดๅŒๆญฅๅ†™ๅ…ฅ SQLite๏ผ›็Šถๆ€ๅœจๅ†ทๅฏๅŠจๆ—ถไปŽๆ•ฐๆฎๅบ“ๆขๅค - -## 4) ่ฎค่ฏ + ๅฎ‰ๅ…จๆŽฅๅฃ - -- Dashboard Cookie ่ฎค่ฏ๏ผš`src/proxy.ts`ใ€`src/app/api/auth/login/route.ts` -- API ๅฏ†้’ฅ็”Ÿๆˆ/้ชŒ่ฏ๏ผš`src/shared/utils/apiKey.ts` -- ๆไพ›ๅ•†ๅฏ†้’ฅๆŒไน…ๅŒ–ๅœจ `providerConnections` ๆก็›ฎไธญ -- ้€š่ฟ‡ `open-sse/utils/proxyFetch.ts`๏ผˆ็Žฏๅขƒๅ˜้‡๏ผ‰ๅ’Œ `open-sse/utils/networkProxy.ts`๏ผˆๅฏ้…็ฝฎ็š„ๆฏๆไพ›ๅ•†ๆˆ–ๅ…จๅฑ€๏ผ‰ๆ”ฏๆŒๅ‡บ็ซ™ไปฃ็† - -## 5) ไบ‘ๅŒๆญฅ - -- ่ฐƒๅบฆๅ™จๅˆๅง‹ๅŒ–๏ผš`src/lib/initCloudSync.ts`ใ€`src/shared/services/initializeCloudSync.ts`ใ€`src/shared/services/modelSyncScheduler.ts` -- ๅ‘จๆœŸๆ€งไปปๅŠก๏ผš`src/shared/services/cloudSyncScheduler.ts` -- ๅ‘จๆœŸๆ€งไปปๅŠก๏ผš`src/shared/services/modelSyncScheduler.ts` -- ๆŽงๅˆถ่ทฏ็”ฑ๏ผš`src/app/api/sync/cloud/route.ts` - -## ่ฏทๆฑ‚็”Ÿๅ‘ฝๅ‘จๆœŸ๏ผˆ`/v1/chat/completions`๏ผ‰ - -```mermaid -sequenceDiagram - autonumber - participant Client as CLI/SDK ๅฎขๆˆท็ซฏ - participant Route as /api/v1/chat/completions - participant Chat as src/sse/handlers/chat - participant Core as open-sse/handlers/chatCore - participant Model as ๆจกๅž‹่งฃๆžๅ™จ - participant Auth as ๅ‡ญ่ฏ้€‰ๆ‹ฉๅ™จ - participant Exec as ๆไพ›ๅ•†ๆ‰ง่กŒๅ™จ - participant Prov as ไธŠๆธธๆไพ›ๅ•† - participant Stream as ๆต็ฟป่ฏ‘ๅ™จ - participant Usage as usageDb - - Client->>Route: POST /v1/chat/completions - Route->>Chat: handleChat(request) - Chat->>Model: ่งฃๆž/่งฃๆžๆจกๅž‹ๆˆ– Combo - - alt Combo ๆจกๅž‹ - Chat->>Chat: ่ฟญไปฃ Combo ๆจกๅž‹๏ผˆhandleComboChat๏ผ‰ - end - - Chat->>Auth: getProviderCredentials(provider) - Auth-->>Chat: ๆดปๅŠจ่ดฆๆˆท + Token/API ๅฏ†้’ฅ - - Chat->>Core: handleChatCore(body, modelInfo, credentials) - Core->>Core: ๆฃ€ๆต‹ๆบๆ ผๅผ - Core->>Core: ๅฐ†่ฏทๆฑ‚็ฟป่ฏ‘ไธบ็›ฎๆ ‡ๆ ผๅผ - Core->>Exec: execute(provider, transformedBody) - Exec->>Prov: ไธŠๆธธ API ่ฐƒ็”จ - Prov-->>Exec: SSE/JSON ๅ“ๅบ” - Exec-->>Core: ๅ“ๅบ” + ๅ…ƒๆ•ฐๆฎ - - alt 401/403 - Core->>Exec: refreshCredentials() - Exec-->>Core: ๆ›ดๆ–ฐ็š„ Token - Core->>Exec: ้‡่ฏ•่ฏทๆฑ‚ - end - - Core->>Stream: ็ฟป่ฏ‘/่ง„่ŒƒๅŒ–ๆตๅˆฐๅฎขๆˆท็ซฏๆ ผๅผ - Stream-->>Client: SSE ๅ— / JSON ๅ“ๅบ” - - Stream->>Usage: ๆๅ–็”จ้‡ + ๆŒไน…ๅŒ–ๅŽ†ๅฒ/ๆ—ฅๅฟ— -``` - -## Combo + ่ดฆๆˆทๅŽๅค‡ๆต็จ‹ - -```mermaid -flowchart TD - A[ไผ ๅ…ฅ็š„ๆจกๅž‹ๅญ—็ฌฆไธฒ] --> B{ๆ˜ฏ Combo ๅ็งฐ๏ผŸ} - B -- ๆ˜ฏ --> C[ๅŠ ่ฝฝ Combo ๆจกๅž‹ๅบๅˆ—] - B -- ๅฆ --> D[ๅ•ๆจกๅž‹่ทฏๅพ„] - - C --> E[ๅฐ่ฏ•ๆจกๅž‹ N] - E --> F[่งฃๆžๆไพ›ๅ•†/ๆจกๅž‹] - D --> F - - F --> G[้€‰ๆ‹ฉ่ดฆๆˆทๅ‡ญ่ฏ] - G --> H{ๅ‡ญ่ฏๅฏ็”จ๏ผŸ} - H -- ๅฆ --> I[่ฟ”ๅ›žๆไพ›ๅ•†ไธๅฏ็”จ] - H -- ๆ˜ฏ --> J[ๆ‰ง่กŒ่ฏทๆฑ‚] - - J --> K{ๆˆๅŠŸ๏ผŸ} - K -- ๆ˜ฏ --> L[่ฟ”ๅ›žๅ“ๅบ”] - K -- ๅฆ --> M{ๅฏๅŽๅค‡้”™่ฏฏ๏ผŸ} - - M -- ๅฆ --> N[่ฟ”ๅ›ž้”™่ฏฏ] - M -- ๆ˜ฏ --> O[ๆ ‡่ฎฐ่ดฆๆˆทไธๅฏ็”จๅ†ทๅด] - O --> P{ๅŒไธ€ๆไพ›ๅ•†ๆœ‰ๅ…ถไป–่ดฆๆˆท๏ผŸ} - P -- ๆ˜ฏ --> G - P -- ๅฆ --> Q{ๅœจๆœ‰ไธ‹ไธ€ไธชๆจกๅž‹็š„ Combo ไธญ๏ผŸ} - Q -- ๆ˜ฏ --> E - Q -- ๅฆ --> R[่ฟ”ๅ›žๅ…จ้ƒจไธๅฏ็”จ] -``` - -ๅŽๅค‡ๅ†ณ็ญ–็”ฑ `open-sse/services/accountFallback.ts` ไฝฟ็”จ็Šถๆ€็ ๅ’Œ้”™่ฏฏๆถˆๆฏๅฏๅ‘ๅผ้ฉฑๅŠจใ€‚ - -## OAuth ๅผ•ๅฏผๅ’Œ Token ๅˆทๆ–ฐ็”Ÿๅ‘ฝๅ‘จๆœŸ - -```mermaid -sequenceDiagram - autonumber - participant UI as Dashboard UI - participant OAuth as /api/oauth/[provider]/[action] - participant ProvAuth as ๆไพ›ๅ•†่ฎค่ฏๆœๅŠกๅ™จ - participant DB as localDb - participant Test as /api/providers/[id]/test - participant Exec as ๆไพ›ๅ•†ๆ‰ง่กŒๅ™จ - - UI->>OAuth: GET authorize ๆˆ– device-code - OAuth->>ProvAuth: ๅˆ›ๅปบ่ฎค่ฏ/่ฎพๅค‡ๆต็จ‹ - ProvAuth-->>OAuth: ่ฎค่ฏ URL ๆˆ–่ฎพๅค‡็ ่ดŸ่ฝฝ - OAuth-->>UI: ๆต็จ‹ๆ•ฐๆฎ - - UI->>OAuth: POST exchange ๆˆ– poll - OAuth->>ProvAuth: Token ไบคๆข/่ฝฎ่ฏข - ProvAuth-->>OAuth: ่ฎฟ้—ฎ/ๅˆทๆ–ฐ Token - OAuth->>DB: createProviderConnection(oauth ๆ•ฐๆฎ) - OAuth-->>UI: ๆˆๅŠŸ + ่ฟžๆŽฅ ID - - UI->>Test: POST /api/providers/[id]/test - Test->>Exec: ้ชŒ่ฏๅ‡ญ่ฏ / ๅฏ้€‰ๅˆทๆ–ฐ - Exec-->>Test: ๆœ‰ๆ•ˆๆˆ–ๅˆทๆ–ฐๅŽ็š„ Token ไฟกๆฏ - Test->>DB: ๆ›ดๆ–ฐ็Šถๆ€/Token/้”™่ฏฏ - Test-->>UI: ้ชŒ่ฏ็ป“ๆžœ -``` - -ๅฎžๆ—ถๆต้‡ๆœŸ้—ด็š„ๅˆทๆ–ฐๅœจ `open-sse/handlers/chatCore.ts` ๅ†…้€š่ฟ‡ๆ‰ง่กŒๅ™จ `refreshCredentials()` ๆ‰ง่กŒใ€‚ - -## ไบ‘ๅŒๆญฅ็”Ÿๅ‘ฝๅ‘จๆœŸ๏ผˆๅฏ็”จ / ๅŒๆญฅ / ็ฆ็”จ๏ผ‰ - -```mermaid -sequenceDiagram - autonumber - participant UI as ็ซฏ็‚น้กต้ข UI - participant Sync as /api/sync/cloud - participant DB as localDb - participant Cloud as ๅค–้ƒจไบ‘ๅŒๆญฅ - participant Claude as ~/.claude/settings.json - - UI->>Sync: POST action=enable - Sync->>DB: ่ฎพ็ฝฎ cloudEnabled=true - Sync->>DB: ็กฎไฟ API ๅฏ†้’ฅๅญ˜ๅœจ - Sync->>Cloud: POST /sync/{machineId}๏ผˆproviders/aliases/combos/keys๏ผ‰ - Cloud-->>Sync: ๅŒๆญฅ็ป“ๆžœ - Sync->>Cloud: GET /{machineId}/v1/verify - Sync-->>UI: ๅทฒๅฏ็”จ + ้ชŒ่ฏ็Šถๆ€ - - UI->>Sync: POST action=sync - Sync->>Cloud: POST /sync/{machineId} - Cloud-->>Sync: ่ฟœ็จ‹ๆ•ฐๆฎ - Sync->>DB: ๆ›ดๆ–ฐ่พƒๆ–ฐ็š„ๆœฌๅœฐ Token/็Šถๆ€ - Sync-->>UI: ๅทฒๅŒๆญฅ - - UI->>Sync: POST action=disable - Sync->>DB: ่ฎพ็ฝฎ cloudEnabled=false - Sync->>Cloud: DELETE /sync/{machineId} - Sync->>Claude: ๅฐ† ANTHROPIC_BASE_URL ๅˆ‡ๆขๅ›žๆœฌๅœฐ๏ผˆๅฆ‚้œ€่ฆ๏ผ‰ - Sync-->>UI: ๅทฒ็ฆ็”จ -``` - -ๅ‘จๆœŸๆ€งๅŒๆญฅๅœจไบ‘ๅฏ็”จๆ—ถ็”ฑ `CloudSyncScheduler` ่งฆๅ‘ใ€‚ - -## ๆ•ฐๆฎๆจกๅž‹ๅ’Œๅญ˜ๅ‚จๆ˜ ๅฐ„ - -```mermaid -erDiagram - SETTINGS ||--o{ PROVIDER_CONNECTION : ๆŽงๅˆถ - PROVIDER_NODE ||--o{ PROVIDER_CONNECTION : ๆ”ฏๆŒๅ…ผๅฎนๆไพ›ๅ•† - PROVIDER_CONNECTION ||--o{ USAGE_ENTRY : ไบง็”Ÿ็”จ้‡ - - 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 - } -``` - -็‰ฉ็†ๅญ˜ๅ‚จๆ–‡ไปถ๏ผš - -- ไธป่ฟ่กŒๆ—ถๆ•ฐๆฎๅบ“๏ผš`${DATA_DIR}/storage.sqlite` -- ่ฏทๆฑ‚ๆ—ฅๅฟ—่กŒ๏ผš`${DATA_DIR}/log.txt`๏ผˆๅ…ผๅฎนๆ€ง/่ฐƒ่ฏ•ๅทฅไปถ๏ผ‰ -- ็ป“ๆž„ๅŒ–่ฐƒ็”จ่ดŸ่ฝฝๅฝ’ๆกฃ๏ผš`${DATA_DIR}/call_logs/` -- ๅฏ้€‰็š„็ฟป่ฏ‘ๅ™จ/่ฏทๆฑ‚่ฐƒ่ฏ•ไผš่ฏ๏ผš`/logs/...` - -## ้ƒจ็ฝฒๆ‹“ๆ‰‘ - -```mermaid -flowchart LR - subgraph LocalHost[ๅผ€ๅ‘่€…ไธปๆœบ] - CLI[CLI ๅทฅๅ…ท] - Browser[Dashboard ๆต่งˆๅ™จ] - end - - subgraph ContainerOrProcess[OmniRoute ่ฟ่กŒๆ—ถ] - Next[Next.js ๆœๅŠกๅ™จ\nPORT=20128] - Core[SSE ๆ ธๅฟƒ + ๆ‰ง่กŒๅ™จ] - MainDB[(storage.sqlite)] - UsageDB[(็”จ้‡่กจ + ๆ—ฅๅฟ—ๅทฅไปถ)] - end - - subgraph External[ๅค–้ƒจๆœๅŠก] - Providers[AI ๆไพ›ๅ•†] - SyncCloud[ไบ‘ๅŒๆญฅๆœๅŠก] - end - - CLI --> Next - Browser --> Next - Next --> Core - Next --> MainDB - Core --> MainDB - Core --> UsageDB - Core --> Providers - Next --> SyncCloud -``` - -## ๆจกๅ—ๆ˜ ๅฐ„๏ผˆๅ…ณ้”ฎๅ†ณ็ญ–๏ผ‰ - -### ่ทฏ็”ฑๅ’Œ API ๆจกๅ— - -- `src/app/api/v1/*`ใ€`src/app/api/v1beta/*`๏ผšๅ…ผๅฎนๆ€ง API -- `src/app/api/v1/providers/[provider]/*`๏ผšไธ“็”จ็š„ๆฏๆไพ›ๅ•†่ทฏ็”ฑ๏ผˆ่Šๅคฉใ€Embeddingใ€ๅ›พๅƒ๏ผ‰ -- `src/app/api/providers*`๏ผšๆไพ›ๅ•† CRUDใ€้ชŒ่ฏใ€ๆต‹่ฏ• -- `src/app/api/provider-nodes*`๏ผš่‡ชๅฎšไน‰ๅ…ผๅฎน่Š‚็‚น็ฎก็† -- `src/app/api/provider-models`๏ผš่‡ชๅฎšไน‰ๆจกๅž‹็ฎก็†๏ผˆCRUD๏ผ‰ -- `src/app/api/models/route.ts`๏ผšๆจกๅž‹็›ฎๅฝ• API๏ผˆๅˆซๅ + ่‡ชๅฎšไน‰ๆจกๅž‹๏ผ‰ -- `src/app/api/oauth/*`๏ผšOAuth/่ฎพๅค‡็ ๆต็จ‹ -- `src/app/api/keys*`๏ผšๆœฌๅœฐ API ๅฏ†้’ฅ็”Ÿๅ‘ฝๅ‘จๆœŸ -- `src/app/api/models/alias`๏ผšๅˆซๅ็ฎก็† -- `src/app/api/combos*`๏ผšๅŽๅค‡ Combo ็ฎก็† -- `src/app/api/pricing`๏ผšๆˆๆœฌ่ฎก็ฎ—็š„ๅฎšไปท่ฆ†็›– -- `src/app/api/settings/proxy`๏ผšไปฃ็†้…็ฝฎ๏ผˆGET/PUT/DELETE๏ผ‰ -- `src/app/api/settings/proxy/test`๏ผšๅ‡บ็ซ™ไปฃ็†่ฟžๆŽฅๆต‹่ฏ•๏ผˆPOST๏ผ‰ -- `src/app/api/usage/*`๏ผš็”จ้‡ๅ’Œๆ—ฅๅฟ— API -- `src/app/api/sync/*` + `src/app/api/cloud/*`๏ผšไบ‘ๅŒๆญฅๅ’Œ้ขๅ‘ไบ‘็š„ๅŠฉๆ‰‹ -- `src/app/api/cli-tools/*`๏ผšๆœฌๅœฐ CLI ้…็ฝฎๅ†™ๅ…ฅๅ™จ/ๆฃ€ๆŸฅๅ™จ -- `src/app/api/settings/ip-filter`๏ผšIP ็™ฝๅๅ•/้ป‘ๅๅ•๏ผˆGET/PUT๏ผ‰ -- `src/app/api/settings/thinking-budget`๏ผšThinking Token ้ข„็ฎ—้…็ฝฎ๏ผˆGET/PUT๏ผ‰ -- `src/app/api/settings/system-prompt`๏ผšๅ…จๅฑ€็ณป็ปŸๆ็คบ่ฏ๏ผˆGET/PUT๏ผ‰ -- `src/app/api/sessions`๏ผšๆดปๅŠจไผš่ฏๅˆ—่กจ๏ผˆGET๏ผ‰ -- `src/app/api/rate-limits`๏ผšๆฏ่ดฆๆˆท้€Ÿ็Ž‡้™ๅˆถ็Šถๆ€๏ผˆGET๏ผ‰ - -### ่ทฏ็”ฑๅ’Œๆ‰ง่กŒๆ ธๅฟƒ - -- `src/sse/handlers/chat.ts`๏ผš่ฏทๆฑ‚่งฃๆžใ€Combo ๅค„็†ใ€่ดฆๆˆท้€‰ๆ‹ฉๅพช็Žฏ -- `open-sse/handlers/chatCore.ts`๏ผš็ฟป่ฏ‘ใ€ๆ‰ง่กŒๅ™จ่ฐƒๅบฆใ€้‡่ฏ•/ๅˆทๆ–ฐๅค„็†ใ€ๆต่ฎพ็ฝฎ -- `open-sse/executors/*`๏ผšๆไพ›ๅ•†็‰นๅฎš็š„็ฝ‘็ปœๅ’Œๆ ผๅผ่กŒไธบ - -### ็ฟป่ฏ‘ๆณจๅ†Œ่กจๅ’Œๆ ผๅผ่ฝฌๆขๅ™จ - -- `open-sse/translator/index.ts`๏ผš็ฟป่ฏ‘ๅ™จๆณจๅ†Œ่กจๅ’Œ็ผ–ๆŽ’ -- ่ฏทๆฑ‚็ฟป่ฏ‘ๅ™จ๏ผš`open-sse/translator/request/*` -- ๅ“ๅบ”็ฟป่ฏ‘ๅ™จ๏ผš`open-sse/translator/response/*` -- ๆ ผๅผๅธธ้‡๏ผš`open-sse/translator/formats.ts` - -### ๆŒไน…ๅŒ– - -- `src/lib/db/*`๏ผšSQLite ไธŠ็š„ๆŒไน…ๅŒ–้…็ฝฎ/็Šถๆ€ๅ’Œ้ข†ๅŸŸๆŒไน…ๅŒ– -- `src/lib/localDb.ts`๏ผšๆ•ฐๆฎๅบ“ๆจกๅ—็š„ๅ…ผๅฎนๆ€ง้‡ๆ–ฐๅฏผๅ‡บ -- `src/lib/usageDb.ts`๏ผšๅŸบไบŽ SQLite ่กจ็š„็”จ้‡ๅŽ†ๅฒ/่ฐƒ็”จๆ—ฅๅฟ—ๅค–่ง‚ - -## ๆไพ›ๅ•†ๆ‰ง่กŒๅ™จ่ฆ†็›–๏ผˆ็ญ–็•ฅๆจกๅผ๏ผ‰ - -ๆฏไธชๆไพ›ๅ•†้ƒฝๆœ‰ไธ€ไธช็ปงๆ‰ฟ่‡ช `BaseExecutor`๏ผˆๅœจ `open-sse/executors/base.ts` ไธญ๏ผ‰็š„ไธ“็”จๆ‰ง่กŒๅ™จ๏ผŒๆไพ› URL ๆž„ๅปบใ€่ฏทๆฑ‚ๅคดๆž„้€ ใ€ๆŒ‡ๆ•ฐ้€€้ฟ้‡่ฏ•ใ€ๅ‡ญ่ฏๅˆทๆ–ฐ้’ฉๅญๅ’Œ `execute()` ็ผ–ๆŽ’ๆ–นๆณ•ใ€‚ - -| ๆ‰ง่กŒๅ™จ | ๆไพ›ๅ•† | ็‰นๆฎŠๅค„็† | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | -| `DefaultExecutor` | OpenAIใ€Claudeใ€Geminiใ€Qwenใ€Qoderใ€OpenRouterใ€GLMใ€Kimiใ€MiniMaxใ€DeepSeekใ€Groqใ€xAIใ€Mistralใ€Perplexityใ€Togetherใ€Fireworksใ€Cerebrasใ€Cohereใ€NVIDIA | ๆฏๆไพ›ๅ•†ๅŠจๆ€ URL/่ฏทๆฑ‚ๅคด้…็ฝฎ | -| `AntigravityExecutor` | Google Antigravity | ่‡ชๅฎšไน‰้กน็›ฎ/ไผš่ฏ ID๏ผŒRetry-After ่งฃๆž | -| `CodexExecutor` | OpenAI Codex | ๆณจๅ…ฅ็ณป็ปŸๆŒ‡ไปค๏ผŒๅผบๅˆถๆŽจ็†ๅŠชๅŠ› | -| `CursorExecutor` | Cursor IDE | ConnectRPC ๅ่ฎฎ๏ผŒProtobuf ็ผ–็ ๏ผŒ้€š่ฟ‡ๆ ก้ชŒๅ’Œ็ญพๅ่ฏทๆฑ‚ | -| `GithubExecutor` | GitHub Copilot | Copilot Token ๅˆทๆ–ฐ๏ผŒๆจกๆ‹Ÿ VSCode ็š„่ฏทๆฑ‚ๅคด | -| `KiroExecutor` | AWS CodeWhisperer/Kiro | AWS EventStream ไบŒ่ฟ›ๅˆถๆ ผๅผ โ†’ SSE ่ฝฌๆข | -| `GeminiCLIExecutor` | Gemini CLI | Google OAuth Token ๅˆทๆ–ฐๅ‘จๆœŸ | - -ๆ‰€ๆœ‰ๅ…ถไป–ๆไพ›ๅ•†๏ผˆๅŒ…ๆ‹ฌ่‡ชๅฎšไน‰ๅ…ผๅฎน่Š‚็‚น๏ผ‰ไฝฟ็”จ `DefaultExecutor`ใ€‚ - -## ๆไพ›ๅ•†ๅ…ผๅฎนๆ€ง็Ÿฉ้˜ต - -| ๆไพ›ๅ•† | ๆ ผๅผ | ่ฎค่ฏ | ๆตๅผไผ ่พ“ | ้žๆตๅผไผ ่พ“ | Token ๅˆทๆ–ฐ | ็”จ้‡ API | -| ---------------- | ---------------- | --------------------- | ---------------- | ---------- | ---------- | ------------------ | -| Claude | claude | API ๅฏ†้’ฅ / OAuth | โœ… | โœ… | โœ… | โš ๏ธ ไป…็ฎก็†ๅ‘˜ | -| Gemini | gemini | API ๅฏ†้’ฅ / OAuth | โœ… | โœ… | โœ… | โš ๏ธ Cloud Console | -| Gemini CLI | gemini-cli | OAuth | โœ… | โœ… | โœ… | โš ๏ธ Cloud Console | -| Antigravity | antigravity | OAuth | โœ… | โœ… | โœ… | โœ… ๅฎŒๆ•ด้…้ข API | -| OpenAI | openai | API ๅฏ†้’ฅ | โœ… | โœ… | โŒ | โŒ | -| Codex | openai-responses | OAuth | โœ… ๅผบๅˆถ | โŒ | โœ… | โœ… ้€Ÿ็Ž‡้™ๅˆถ | -| GitHub Copilot | openai | OAuth + Copilot Token | โœ… | โœ… | โœ… | โœ… ้…้ขๅฟซ็…ง | -| Cursor | cursor | ่‡ชๅฎšไน‰ๆ ก้ชŒๅ’Œ | โœ… | โœ… | โŒ | โŒ | -| Kiro | kiro | AWS SSO OIDC | โœ… (EventStream) | โŒ | โœ… | โœ… ็”จ้‡้™ๅˆถ | -| Qwen | openai | OAuth | โœ… | โœ… | โœ… | โš ๏ธ ๆฏ่ฏทๆฑ‚ | -| Qoder | openai | OAuth (Basic) | โœ… | โœ… | โœ… | โš ๏ธ ๆฏ่ฏทๆฑ‚ | -| OpenRouter | openai | API ๅฏ†้’ฅ | โœ… | โœ… | โŒ | โŒ | -| GLM/Kimi/MiniMax | claude | API ๅฏ†้’ฅ | โœ… | โœ… | โŒ | โŒ | -| DeepSeek | openai | API ๅฏ†้’ฅ | โœ… | โœ… | โŒ | โŒ | -| Groq | openai | API ๅฏ†้’ฅ | โœ… | โœ… | โŒ | โŒ | -| xAI (Grok) | openai | API ๅฏ†้’ฅ | โœ… | โœ… | โŒ | โŒ | -| Mistral | openai | API ๅฏ†้’ฅ | โœ… | โœ… | โŒ | โŒ | -| Perplexity | openai | API ๅฏ†้’ฅ | โœ… | โœ… | โŒ | โŒ | -| Together AI | openai | API ๅฏ†้’ฅ | โœ… | โœ… | โŒ | โŒ | -| Fireworks AI | openai | API ๅฏ†้’ฅ | โœ… | โœ… | โŒ | โŒ | -| Cerebras | openai | API ๅฏ†้’ฅ | โœ… | โœ… | โŒ | โŒ | -| Cohere | openai | API ๅฏ†้’ฅ | โœ… | โœ… | โŒ | โŒ | -| NVIDIA NIM | openai | API ๅฏ†้’ฅ | โœ… | โœ… | โŒ | โŒ | - -## ๆ ผๅผ็ฟป่ฏ‘่ฆ†็›– - -ๆฃ€ๆต‹ๅˆฐ็š„ๆบๆ ผๅผๅŒ…ๆ‹ฌ๏ผš - -- `openai` -- `openai-responses` -- `claude` -- `gemini` - -็›ฎๆ ‡ๆ ผๅผๅŒ…ๆ‹ฌ๏ผš - -- OpenAI ่Šๅคฉ/Responses -- Claude -- Gemini/Gemini-CLI/Antigravity ๅฐ่ฃ… -- Kiro -- Cursor - -็ฟป่ฏ‘ไฝฟ็”จ **OpenAI ไฝœไธบไธญๅฟƒๆ ผๅผ** โ€” ๆ‰€ๆœ‰่ฝฌๆข้ƒฝ้€š่ฟ‡ OpenAI ไฝœไธบไธญไป‹๏ผš - -``` -ๆบๆ ผๅผ โ†’ OpenAI๏ผˆไธญๅฟƒ๏ผ‰โ†’ ็›ฎๆ ‡ๆ ผๅผ -``` - -็ฟป่ฏ‘ๆ นๆฎๆบ่ดŸ่ฝฝๅฝข็Šถๅ’Œๆไพ›ๅ•†็›ฎๆ ‡ๆ ผๅผๅŠจๆ€้€‰ๆ‹ฉใ€‚ - -็ฟป่ฏ‘็ฎก้“ไธญ็š„้ขๅค–ๅค„็†ๅฑ‚๏ผš - -- **ๅ“ๅบ”ๆธ…็†** โ€” ไปŽ OpenAI ๆ ผๅผๅ“ๅบ”๏ผˆๆตๅผๅ’Œ้žๆตๅผ๏ผ‰ไธญๅ‰ฅ็ฆป้žๆ ‡ๅ‡†ๅญ—ๆฎต๏ผŒไปฅ็กฎไฟไธฅๆ ผ็š„ SDK ๅˆ่ง„ๆ€ง -- **่ง’่‰ฒ่ง„่ŒƒๅŒ–** โ€” ไธบ้ž OpenAI ็›ฎๆ ‡ๅฐ† `developer` โ†’ `system`๏ผ›ไธบๆ‹’็ป system ่ง’่‰ฒ็š„ๆจกๅž‹๏ผˆGLMใ€ERNIE๏ผ‰ๅˆๅนถ `system` โ†’ `user` -- **Think ๆ ‡็ญพๆๅ–** โ€” ไปŽๅ†…ๅฎนไธญ่งฃๆž `...` ๅ—ๅˆฐ `reasoning_content` ๅญ—ๆฎต -- **็ป“ๆž„ๅŒ–่พ“ๅ‡บ** โ€” ๅฐ† OpenAI `response_format.json_schema` ่ฝฌๆขไธบ Gemini ็š„ `responseMimeType` + `responseSchema` - -## ๆ”ฏๆŒ็š„ API ็ซฏ็‚น - -| ็ซฏ็‚น | ๆ ผๅผ | ๅค„็†ๅ™จ | -| -------------------------------------------------- | ------------------ | ---------------------------------------------------- | -| `POST /v1/chat/completions` | OpenAI ่Šๅคฉ | `src/sse/handlers/chat.ts` | -| `POST /v1/messages` | Claude Messages | ็›ธๅŒๅค„็†ๅ™จ๏ผˆ่‡ชๅŠจๆฃ€ๆต‹๏ผ‰ | -| `POST /v1/responses` | OpenAI Responses | `open-sse/handlers/responsesHandler.ts` | -| `POST /v1/embeddings` | OpenAI Embeddings | `open-sse/handlers/embeddings.ts` | -| `GET /v1/embeddings` | ๆจกๅž‹ๅˆ—่กจ | API ่ทฏ็”ฑ | -| `POST /v1/images/generations` | OpenAI Images | `open-sse/handlers/imageGeneration.ts` | -| `GET /v1/images/generations` | ๆจกๅž‹ๅˆ—่กจ | API ่ทฏ็”ฑ | -| `POST /v1/providers/{provider}/chat/completions` | OpenAI ่Šๅคฉ | ไธ“็”จ็š„ๆฏๆไพ›ๅ•†๏ผŒๅธฆๆจกๅž‹้ชŒ่ฏ | -| `POST /v1/providers/{provider}/embeddings` | OpenAI Embeddings | ไธ“็”จ็š„ๆฏๆไพ›ๅ•†๏ผŒๅธฆๆจกๅž‹้ชŒ่ฏ | -| `POST /v1/providers/{provider}/images/generations` | OpenAI Images | ไธ“็”จ็š„ๆฏๆไพ›ๅ•†๏ผŒๅธฆๆจกๅž‹้ชŒ่ฏ | -| `POST /v1/messages/count_tokens` | Claude Token ่ฎกๆ•ฐ | API ่ทฏ็”ฑ | -| `GET /v1/models` | OpenAI ๆจกๅž‹ๅˆ—่กจ | API ่ทฏ็”ฑ๏ผˆ่Šๅคฉ + Embedding + ๅ›พๅƒ + ่‡ชๅฎšไน‰ๆจกๅž‹๏ผ‰ | -| `GET /api/models/catalog` | ็›ฎๅฝ• | ๆŒ‰ๆไพ›ๅ•† + ็ฑปๅž‹ๅˆ†็ป„็š„ๆ‰€ๆœ‰ๆจกๅž‹ | -| `POST /v1beta/models/*:streamGenerateContent` | Gemini ๅŽŸ็”Ÿ | API ่ทฏ็”ฑ | -| `GET/PUT/DELETE /api/settings/proxy` | ไปฃ็†้…็ฝฎ | ็ฝ‘็ปœไปฃ็†้…็ฝฎ | -| `POST /api/settings/proxy/test` | ไปฃ็†่ฟžๆŽฅ | ไปฃ็†ๅฅๅบท/่ฟžๆŽฅๆต‹่ฏ•็ซฏ็‚น | -| `GET/POST/DELETE /api/provider-models` | ่‡ชๅฎšไน‰ๆจกๅž‹ | ๆฏๆไพ›ๅ•†็š„่‡ชๅฎšไน‰ๆจกๅž‹็ฎก็† | - -## Bypass ๅค„็†ๅ™จ - -Bypass ๅค„็†ๅ™จ๏ผˆ`open-sse/utils/bypassHandler.ts`๏ผ‰ๆ‹ฆๆˆชๆฅ่‡ช Claude CLI ็š„ๅทฒ็Ÿฅ"ไธขๅผƒ"่ฏทๆฑ‚ โ€” ้ข„็ƒญ pingใ€ๆ ‡้ข˜ๆๅ–ๅ’Œ Token ่ฎกๆ•ฐ โ€” ๅนถ่ฟ”ๅ›ž**ๅ‡ๅ“ๅบ”**่€Œไธๆถˆ่€—ไธŠๆธธๆไพ›ๅ•†็š„ Tokenใ€‚่ฟ™ไป…ๅœจ `User-Agent` ๅŒ…ๅซ `claude-cli` ๆ—ถ่งฆๅ‘ใ€‚ - -## ่ฏทๆฑ‚ๆ—ฅๅฟ—็ฎก้“ - -่ฏทๆฑ‚ๆ—ฅๅฟ—ๅ™จ๏ผˆ`open-sse/utils/requestLogger.ts`๏ผ‰ๆไพ› 7 ้˜ถๆฎต่ฐƒ่ฏ•ๆ—ฅๅฟ—็ฎก้“๏ผŒ้ป˜่ฎค็ฆ็”จ๏ผŒ้€š่ฟ‡ `ENABLE_REQUEST_LOGS=true` ๅฏ็”จ๏ผš - -``` -1_req_client.json โ†’ 2_req_source.json โ†’ 3_req_openai.json โ†’ 4_req_target.json -โ†’ 5_res_provider.txt โ†’ 6_res_openai.txt โ†’ 7_res_client.txt -``` - -ๆ–‡ไปถๅ†™ๅ…ฅๅˆฐ `/logs//`๏ผŒๆฏไธช่ฏทๆฑ‚ไผš่ฏไธ€ไธชใ€‚ - -## ๆ•…้šœๆจกๅผๅ’Œๅผนๆ€ง - -## 1) ่ดฆๆˆท/ๆไพ›ๅ•†ๅฏ็”จๆ€ง - -- ็žฌๆ€/้€Ÿ็Ž‡/่ฎค่ฏ้”™่ฏฏๆ—ถ็š„ๆไพ›ๅ•†่ดฆๆˆทๅ†ทๅด -- ่ฏทๆฑ‚ๅคฑ่ดฅๅ‰็š„่ดฆๆˆทๅŽๅค‡ -- ๅฝ“ๅ‰ๆจกๅž‹/ๆไพ›ๅ•†่ทฏๅพ„่€—ๅฐฝๆ—ถ็š„ Combo ๆจกๅž‹ๅŽๅค‡ - -## 2) Token ่ฟ‡ๆœŸ - -- ๅฏๅˆทๆ–ฐๆไพ›ๅ•†็š„้ข„ๆฃ€ๆŸฅๅ’Œๅธฆ้‡่ฏ•็š„ๅˆทๆ–ฐ -- ๆ ธๅฟƒ่ทฏๅพ„ไธญๅˆทๆ–ฐๅฐ่ฏ•ๅŽ็š„ 401/403 ้‡่ฏ• - -## 3) ๆตๅฎ‰ๅ…จ - -- ๆ–ญๅผ€่ฟžๆŽฅๆ„Ÿ็Ÿฅ็š„ๆตๆŽงๅˆถๅ™จ -- ๅธฆๆต็ป“ๆŸๅˆทๆ–ฐๅ’Œ `[DONE]` ๅค„็†็š„็ฟป่ฏ‘ๆต -- ๆไพ›ๅ•†็”จ้‡ๅ…ƒๆ•ฐๆฎ็ผบๅคฑๆ—ถ็š„็”จ้‡ไผฐ็ฎ—ๅŽๅค‡ - -## 4) ไบ‘ๅŒๆญฅ้™็บง - -- ๅŒๆญฅ้”™่ฏฏไผšๆ˜พ็คบไฝ†ๆœฌๅœฐ่ฟ่กŒๆ—ถ็ปง็ปญ -- ่ฐƒๅบฆๅ™จๆœ‰้‡่ฏ•่ƒฝๅŠ›็š„้€ป่พ‘๏ผŒไฝ†ๅ‘จๆœŸๆ€งๆ‰ง่กŒ็›ฎๅ‰้ป˜่ฎค่ฐƒ็”จๅ•ๆฌกๅฐ่ฏ•ๅŒๆญฅ - -## 5) ๆ•ฐๆฎๅฎŒๆ•ดๆ€ง - -- ๅฏๅŠจๆ—ถ็š„ SQLite ๆจกๅผ่ฟ็งปๅ’Œ่‡ชๅŠจๅ‡็บง้’ฉๅญ -- ๆ—ง็‰ˆ JSON โ†’ SQLite ่ฟ็งปๅ…ผๅฎน่ทฏๅพ„ - -## ๅฏ่ง‚ๆต‹ๆ€งๅ’Œ่ฟ่ฅไฟกๅท - -่ฟ่กŒๆ—ถๅฏ่งๆ€งๆฅๆบ๏ผš - -- ๆฅ่‡ช `src/sse/utils/logger.ts` ็š„ๆŽงๅˆถๅฐๆ—ฅๅฟ— -- SQLite ไธญ็š„ๆฏ่ฏทๆฑ‚็”จ้‡่šๅˆ๏ผˆ`usage_history`ใ€`call_logs`ใ€`proxy_logs`๏ผ‰ -- ๅฝ“ `settings.detailed_logs_enabled=true` ๆ—ถ๏ผŒSQLite ไธญๅ››้˜ถๆฎต็š„่ฏฆ็ป† payload ๆ•่Žท๏ผˆ`request_detail_logs`๏ผ‰ -- `log.txt` ไธญ็š„ๆ–‡ๆœฌ่ฏทๆฑ‚็Šถๆ€ๆ—ฅๅฟ—๏ผˆๅฏ้€‰/ๅ…ผๅฎน๏ผ‰ -- ๅฝ“ `ENABLE_REQUEST_LOGS=true` ๆ—ถ `logs/` ไธ‹็š„ๅฏ้€‰ๆทฑๅบฆ่ฏทๆฑ‚/็ฟป่ฏ‘ๆ—ฅๅฟ— -- Dashboard ็”จ้‡็ซฏ็‚น๏ผˆ`/api/usage/*`๏ผ‰ไพ› UI ๆถˆ่ดน - -่ฏฆ็ป†่ฏทๆฑ‚ payload ๆ•่Žทไผšไธบๆฏๆฌก่ทฏ็”ฑ่ฐƒ็”จๆœ€ๅคšไฟๅญ˜ๅ››ไธช JSON payload ้˜ถๆฎต๏ผš - -- ๅฎขๆˆท็ซฏๅ‘้€็š„ๅŽŸๅง‹่ฏทๆฑ‚ -- ๅฎž้™…ๅ‘้€ๅˆฐไธŠๆธธ็š„ๅทฒ็ฟป่ฏ‘่ฏทๆฑ‚ -- ่ฟ˜ๅŽŸไธบ JSON ็š„ๆไพ›ๅ•†ๅ“ๅบ”๏ผ›ๆตๅผๅ“ๅบ”ไผšๅŽ‹็ผฉไธบๆœ€็ปˆๆ‘˜่ฆๅŠ ๆตๅ…ƒๆ•ฐๆฎ -- OmniRoute ่ฟ”ๅ›ž็ป™ๅฎขๆˆท็ซฏ็š„ๆœ€็ปˆๅ“ๅบ”๏ผ›ๆตๅผๅ“ๅบ”ๅŒๆ ทไปฅ็›ธๅŒ็š„็ดงๅ‡‘ๆ‘˜่ฆๅฝขๅผๅญ˜ๅ‚จ - -## ๅฎ‰ๅ…จๆ•ๆ„Ÿ่พน็•Œ - -- JWT ๅฏ†้’ฅ๏ผˆ`JWT_SECRET`๏ผ‰ไฟๆŠค Dashboard ไผš่ฏ Cookie ้ชŒ่ฏ/็ญพๅ -- ๅˆๅง‹ๅฏ†็ ๅผ•ๅฏผ๏ผˆ`INITIAL_PASSWORD`๏ผ‰ๅบ”ๅœจ้ฆ–ๆฌก่ฟ่กŒ้…็ฝฎๆ—ถๆ˜พๅผ้…็ฝฎ -- API ๅฏ†้’ฅ HMAC ๅฏ†้’ฅ๏ผˆ`API_KEY_SECRET`๏ผ‰ไฟๆŠค็”Ÿๆˆ็š„ๆœฌๅœฐ API ๅฏ†้’ฅๆ ผๅผ -- ๆไพ›ๅ•†ๅฏ†้’ฅ๏ผˆAPI ๅฏ†้’ฅ/Token๏ผ‰ๆŒไน…ๅŒ–ๅœจๆœฌๅœฐๆ•ฐๆฎๅบ“ไธญ๏ผŒๅบ”ๅœจๆ–‡ไปถ็ณป็ปŸ็บงๅˆซไฟๆŠค -- ไบ‘ๅŒๆญฅ็ซฏ็‚นไพ่ต– API ๅฏ†้’ฅ่ฎค่ฏ + ๆœบๅ™จ ID ่ฏญไน‰ - -## ็Žฏๅขƒๅ’Œ่ฟ่กŒๆ—ถ็Ÿฉ้˜ต - -ไปฃ็ ไธญๅฎž้™…ไฝฟ็”จ็š„็Žฏๅขƒๅ˜้‡๏ผš - -- ๅบ”็”จ/่ฎค่ฏ๏ผš`JWT_SECRET`ใ€`INITIAL_PASSWORD` -- ๅญ˜ๅ‚จ๏ผš`DATA_DIR` -- ๅ…ผๅฎน่Š‚็‚น่กŒไธบ๏ผš`ALLOW_MULTI_CONNECTIONS_PER_COMPAT_NODE` -- ๅฏ้€‰ๅญ˜ๅ‚จๅŸบ็ก€่ฆ†็›–๏ผˆๅฝ“ `DATA_DIR` ๆœช่ฎพ็ฝฎๆ—ถ็š„ Linux/macOS๏ผ‰๏ผš`XDG_CONFIG_HOME` -- ๅฎ‰ๅ…จๅ“ˆๅธŒ๏ผš`API_KEY_SECRET`ใ€`MACHINE_ID_SALT` -- ๆ—ฅๅฟ—๏ผš`ENABLE_REQUEST_LOGS` -- ๅŒๆญฅ/ไบ‘ URL๏ผš`NEXT_PUBLIC_BASE_URL`ใ€`NEXT_PUBLIC_CLOUD_URL` -- ๅ‡บ็ซ™ไปฃ็†๏ผš`HTTP_PROXY`ใ€`HTTPS_PROXY`ใ€`ALL_PROXY`ใ€`NO_PROXY` ๅŠๅฐๅ†™ๅ˜ไฝ“ -- SOCKS5 ๅŠŸ่ƒฝๆ ‡ๅฟ—๏ผš`ENABLE_SOCKS5_PROXY`ใ€`NEXT_PUBLIC_ENABLE_SOCKS5_PROXY` -- ๅนณๅฐ/่ฟ่กŒๆ—ถๅŠฉๆ‰‹๏ผˆ้žๅบ”็”จ็‰นๅฎš้…็ฝฎ๏ผ‰๏ผš`APPDATA`ใ€`NODE_ENV`ใ€`PORT`ใ€`HOSTNAME` - -## ๅทฒ็Ÿฅๆžถๆž„่ฏดๆ˜Ž - -1. `usageDb` ๅ’Œ `localDb` ๅ…ฑไบซ็›ธๅŒ็š„ๅŸบ็ก€็›ฎๅฝ•็ญ–็•ฅ๏ผˆ`DATA_DIR` โ†’ `XDG_CONFIG_HOME/omniroute` โ†’ `~/.omniroute`๏ผ‰ๅนถๆ”ฏๆŒๆ—ง็‰ˆๆ–‡ไปถ่ฟ็งปใ€‚ -2. `/api/v1/route.ts` ๅง”ๆ‰˜็ป™ `/api/v1/models`๏ผˆ`src/app/api/v1/models/catalog.ts`๏ผ‰ไฝฟ็”จ็š„็›ธๅŒ็ปŸไธ€็›ฎๅฝ•ๆž„ๅปบๅ™จ๏ผŒไปฅ้ฟๅ…่ฏญไน‰ๆผ‚็งปใ€‚ -3. ่ฏทๆฑ‚ๆ—ฅๅฟ—ๅ™จๅฏ็”จๆ—ถๅ†™ๅ…ฅๅฎŒๆ•ด็š„่ฏทๆฑ‚ๅคด/่ฏทๆฑ‚ไฝ“๏ผ›ๅบ”ๅฐ†ๆ—ฅๅฟ—็›ฎๅฝ•่ง†ไธบๆ•ๆ„Ÿไฟกๆฏใ€‚ -4. ไบ‘่กŒไธบๅ–ๅ†ณไบŽๆญฃ็กฎ็š„ `NEXT_PUBLIC_BASE_URL` ๅ’Œไบ‘็ซฏ็‚นๅฏ่พพๆ€งใ€‚ -5. `open-sse/` ็›ฎๅฝ•ไฝœไธบ `@omniroute/open-sse` **npm ๅทฅไฝœๅŒบๅŒ…**ๅ‘ๅธƒใ€‚ๆบไปฃ็ ้€š่ฟ‡ `@omniroute/open-sse/...` ๅฏผๅ…ฅ๏ผˆ็”ฑ Next.js `transpilePackages` ่งฃๆž๏ผ‰ใ€‚ๆœฌๆ–‡ๆกฃไธญ็š„ๆ–‡ไปถ่ทฏๅพ„ไปไฝฟ็”จ็›ฎๅฝ•ๅ `open-sse/` ไปฅไฟๆŒไธ€่‡ดๆ€งใ€‚ -6. Dashboard ไธญ็š„ๅ›พ่กจไฝฟ็”จ **Recharts**๏ผˆๅŸบไบŽ SVG๏ผ‰ๅฎž็Žฐๅฏ่ฎฟ้—ฎ็š„ไบคไบ’ๅผๅˆ†ๆžๅฏ่ง†ๅŒ–๏ผˆๆจกๅž‹็”จ้‡ๆŸฑ็Šถๅ›พใ€ๅธฆๆˆๅŠŸ็Ž‡็š„ๆไพ›ๅ•†ๅˆ†่งฃ่กจ๏ผ‰ใ€‚ -7. E2E ๆต‹่ฏ•ไฝฟ็”จ **Playwright**๏ผˆ`tests/e2e/`๏ผ‰๏ผŒ้€š่ฟ‡ `npm run test:e2e` ่ฟ่กŒใ€‚ๅ•ๅ…ƒๆต‹่ฏ•ไฝฟ็”จ **Node.js ๆต‹่ฏ•่ฟ่กŒๅ™จ**๏ผˆ`tests/unit/`๏ผ‰๏ผŒ้€š่ฟ‡ `npm run test:unit` ่ฟ่กŒใ€‚`src/` ไธ‹็š„ๆบไปฃ็ ๆ˜ฏ **TypeScript**๏ผˆ`.ts`/`.tsx`๏ผ‰๏ผ›`open-sse/` ๅทฅไฝœๅŒบไฟๆŒ JavaScript๏ผˆ`.js`๏ผ‰ใ€‚ -8. ่ฎพ็ฝฎ้กต้ข็ป„็ป‡ไธบ 5 ไธชๆ ‡็ญพ้กต๏ผšๅฎ‰ๅ…จใ€่ทฏ็”ฑ๏ผˆ6 ็งๅ…จๅฑ€็ญ–็•ฅ๏ผšๅกซๅ……ไผ˜ๅ…ˆใ€่ฝฎ่ฏขใ€p2cใ€้šๆœบใ€ๆœ€ๅฐ‘ไฝฟ็”จใ€ๆˆๆœฌไผ˜ๅŒ–๏ผ‰ใ€ๅผนๆ€ง๏ผˆๅฏ็ผ–่พ‘็š„้€Ÿ็Ž‡้™ๅˆถใ€็†”ๆ–ญๅ™จใ€็ญ–็•ฅ๏ผ‰ใ€AI๏ผˆThinking ้ข„็ฎ—ใ€็ณป็ปŸๆ็คบ่ฏใ€ๆ็คบ่ฏ็ผ“ๅญ˜๏ผ‰ใ€้ซ˜็บง๏ผˆไปฃ็†๏ผ‰ใ€‚ - -## ่ฟ่ฅ้ชŒ่ฏๆธ…ๅ• - -- ไปŽๆบไปฃ็ ๆž„ๅปบ๏ผš`npm run build` -- ๆž„ๅปบ Docker ้•œๅƒ๏ผš`docker build -t omniroute .` -- ๅฏๅŠจๆœๅŠกๅนถ้ชŒ่ฏ๏ผš -- `GET /api/settings` -- `GET /api/v1/models` -- CLI ็›ฎๆ ‡ๅŸบ็ก€ URL ๅบ”ไธบ `http://:20128/v1`๏ผˆๅฝ“ `PORT=20128` ๆ—ถ๏ผ‰ diff --git a/docs/i18n/zh-CN/AUTO-COMBO.md b/docs/i18n/zh-CN/AUTO-COMBO.md deleted file mode 100644 index 84ecc7f8bf..0000000000 --- a/docs/i18n/zh-CN/AUTO-COMBO.md +++ /dev/null @@ -1,67 +0,0 @@ -๐ŸŒ **่ฏญ่จ€:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/AUTO-COMBO.md) - ---- - -# OmniRoute Auto-Combo ๅผ•ๆ“Ž - -> ๅ…ทๆœ‰่‡ช้€‚ๅบ”่ฏ„ๅˆ†็š„่‡ช็ฎก็†ๆจกๅž‹้“พ - -## ๅทฅไฝœๅŽŸ็† - -Auto-Combo ๅผ•ๆ“Žไฝฟ็”จ **6 ๅ› ๅญ่ฏ„ๅˆ†ๅ‡ฝๆ•ฐ** ไธบๆฏไธช่ฏทๆฑ‚ๅŠจๆ€้€‰ๆ‹ฉๆœ€ไฝณๆœๅŠกๅ•†/ๆจกๅž‹๏ผš - -| ๅ› ๅญ | ๆƒ้‡ | ๆ่ฟฐ | -| :--------- | :--- | :--------------------------------------- | -| Quota | 0.20 | ๅ‰ฉไฝ™ๅฎน้‡ [0..1] | -| Health | 0.25 | ็†”ๆ–ญๅ™จ็Šถๆ€๏ผšCLOSED=1.0, HALF=0.5, OPEN=0.0 | -| CostInv | 0.20 | ๆˆๆœฌๅ€’ๆ•ฐ๏ผˆ่ถŠไพฟๅฎœๅพ—ๅˆ†่ถŠ้ซ˜๏ผ‰ | -| LatencyInv | 0.15 | p95 ๅปถ่ฟŸๅ€’ๆ•ฐ๏ผˆ่ถŠๅฟซๅพ—ๅˆ†่ถŠ้ซ˜๏ผ‰ | -| TaskFit | 0.10 | ๆจกๅž‹ ร— ไปปๅŠก็ฑปๅž‹้€‚้…ๅบฆ | -| Stability | 0.10 | ๅปถ่ฟŸ/้”™่ฏฏ็Ž‡็š„ไฝŽๆ–นๅทฎ | - -## ๆจกๅผๅŒ… - -| ๆจกๅผๅŒ… | ไพง้‡็‚น | ๅ…ณ้”ฎๆƒ้‡ | -| :---------------------- | :----- | :--------------- | -| ๐Ÿš€ **Ship Fast** | ้€Ÿๅบฆ | latencyInv: 0.35 | -| ๐Ÿ’ฐ **Cost Saver** | ็ปๆตŽ | costInv: 0.40 | -| ๐ŸŽฏ **Quality First** | ๆœ€ไผ˜ๆจกๅž‹ | taskFit: 0.40 | -| ๐Ÿ“ก **Offline Friendly** | ๅฏ็”จๆ€ง | quota: 0.40 | - -## ่‡ชๆ„ˆ่ƒฝๅŠ› - -- **ไธดๆ—ถๆŽ’้™ค**๏ผš่ฏ„ๅˆ† < 0.2 โ†’ ๆŽ’้™ค 5 ๅˆ†้’Ÿ๏ผˆๆธ่ฟ›้€€้ฟ๏ผŒๆœ€้•ฟ 30 ๅˆ†้’Ÿ๏ผ‰ -- **็†”ๆ–ญๅ™จๆ„Ÿ็Ÿฅ**๏ผšOPEN โ†’ ่‡ชๅŠจๆŽ’้™ค๏ผ›HALF_OPEN โ†’ ๆŽขๆต‹่ฏทๆฑ‚ -- **ไบ‹ๆ•…ๆจกๅผ**๏ผš>50% OPEN โ†’ ็ฆ็”จๆŽข็ดข๏ผŒๆœ€ๅคงๅŒ–็จณๅฎšๆ€ง -- **ๅ†ทๅดๆขๅค**๏ผšๆŽ’้™ค็ป“ๆŸๅŽ๏ผŒ้ฆ–ไธช่ฏทๆฑ‚ไธบ"ๆŽขๆต‹"่ฏทๆฑ‚๏ผŒไฝฟ็”จ็ผฉ็Ÿญ็š„่ถ…ๆ—ถๆ—ถ้—ด - -## Bandit ๆŽข็ดข - -5% ็š„่ฏทๆฑ‚๏ผˆๅฏ้…็ฝฎ๏ผ‰ไผš่ขซ่ทฏ็”ฑๅˆฐ้šๆœบๆœๅŠกๅ•†่ฟ›่กŒๆŽข็ดขใ€‚ๅœจไบ‹ๆ•…ๆจกๅผไธ‹็ฆ็”จใ€‚ - -## API - -```bash -# ๅˆ›ๅปบ auto-combo -curl -X POST http://localhost:20128/api/combos/auto \ - -H "Content-Type: application/json" \ - -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}' - -# ๅˆ—ๅ‡บ auto-combos -curl http://localhost:20128/api/combos/auto -``` - -## ไปปๅŠก้€‚้…ๅบฆ - -30+ ไธชๆจกๅž‹ๅœจ 6 ็งไปปๅŠก็ฑปๅž‹๏ผˆ`coding`ใ€`review`ใ€`planning`ใ€`analysis`ใ€`debugging`ใ€`documentation`๏ผ‰ไธŠ่ฟ›่กŒ่ฏ„ๅˆ†ใ€‚ๆ”ฏๆŒ้€š้…็ฌฆๆจกๅผ๏ผˆไพ‹ๅฆ‚ `*-coder` โ†’ ้ซ˜็ผ–็ ๅพ—ๅˆ†๏ผ‰ใ€‚ - -## ๆ–‡ไปถ - -| ๆ–‡ไปถ | ็”จ้€” | -| :------------------------------------------- | :------------------------ | -| `open-sse/services/autoCombo/scoring.ts` | ่ฏ„ๅˆ†ๅ‡ฝๆ•ฐ & ๆฑ ๅฝ’ไธ€ๅŒ– | -| `open-sse/services/autoCombo/taskFitness.ts` | ๆจกๅž‹ ร— ไปปๅŠก้€‚้…ๅบฆๆŸฅ่ฏข | -| `open-sse/services/autoCombo/engine.ts` | ้€‰ๆ‹ฉ้€ป่พ‘ใ€banditใ€้ข„็ฎ—ไธŠ้™ | -| `open-sse/services/autoCombo/selfHealing.ts` | ๆŽ’้™คใ€ๆŽขๆต‹ใ€ไบ‹ๆ•…ๆจกๅผ | -| `open-sse/services/autoCombo/modePacks.ts` | 4 ็งๆƒ้‡้…็ฝฎ | -| `src/app/api/combos/auto/route.ts` | REST API | diff --git a/docs/i18n/zh-CN/CHANGELOG.md b/docs/i18n/zh-CN/CHANGELOG.md index 2103b0dfbe..9af316a5bc 100644 --- a/docs/i18n/zh-CN/CHANGELOG.md +++ b/docs/i18n/zh-CN/CHANGELOG.md @@ -1,427 +1,451 @@ -# ๆ›ดๆ–ฐๆ—ฅๅฟ— +# Changelog (ไธญๆ–‡๏ผˆ็ฎ€ไฝ“๏ผ‰) -๐ŸŒ **่ฏญ่จ€:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](../pt-BR/CHANGELOG.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](../es/CHANGELOG.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](../fr/CHANGELOG.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](../it/CHANGELOG.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](../ru/CHANGELOG.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](../zh-CN/CHANGELOG.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](../de/CHANGELOG.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](../in/CHANGELOG.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](../th/CHANGELOG.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](../uk-UA/CHANGELOG.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](../ar/CHANGELOG.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](../ja/CHANGELOG.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](../vi/CHANGELOG.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](../bg/CHANGELOG.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](../da/CHANGELOG.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](../fi/CHANGELOG.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](../he/CHANGELOG.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](../hu/CHANGELOG.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](../id/CHANGELOG.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](../ko/CHANGELOG.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](../ms/CHANGELOG.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](../nl/CHANGELOG.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](../no/CHANGELOG.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](../pt/CHANGELOG.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](../ro/CHANGELOG.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](../pl/CHANGELOG.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](../sk/CHANGELOG.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](../sv/CHANGELOG.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](../phi/CHANGELOG.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](../cs/CHANGELOG.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CHANGELOG.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CHANGELOG.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CHANGELOG.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CHANGELOG.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CHANGELOG.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CHANGELOG.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CHANGELOG.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CHANGELOG.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CHANGELOG.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CHANGELOG.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CHANGELOG.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CHANGELOG.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CHANGELOG.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CHANGELOG.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CHANGELOG.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CHANGELOG.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CHANGELOG.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CHANGELOG.md) --- -## [ๆœชๅ‘ๅธƒ] +## [Unreleased] + +### ๐Ÿ› ๏ธ Maintenance + +- **AGENTS.md rewrite:** Condensed from 297โ†’153 lines. Added build/lint/test commands (including single-test execution), code style guidelines (Prettier, TypeScript, ESLint, naming, imports, error handling, security), and trimmed verbose architecture tables for AI agent consumption. + +## [3.4.2] - 2026-04-01 + +### ๐Ÿ› Bug Fixes + +- **CI Stabilization:** Fixed failing analytics/settings Playwright selectors and request assertions so GitHub Actions E2E runs pass reliably across localized UIs and switch-based controls. +- **Deterministic Tests:** Removed date-sensitive quota fixtures from Copilot usage tests and aligned idempotency/model catalog tests with the merged runtime behavior. +- **MCP Type Hardening:** Removed zero-budget explicit `any` regressions from the MCP server tool registration path, restoring the `check:any-budget:t11` workflow gate. + +### ๐Ÿ› ๏ธ Maintenance + +- **Release Branch Integration:** Consolidated the active feature branches into `release/v3.4.2` on top of current `main` and validated the branch with lint, unit, coverage, build, and CI-mode E2E runs. + +## [3.4.1] - 2026-03-31 > [!WARNING] -> **็ ดๅๆ€งๅ˜ๆ›ด๏ผš่ฏทๆฑ‚ๆ—ฅๅฟ—ใ€ไฟ็•™็ญ–็•ฅไปฅๅŠๆ—ฅๅฟ—็Žฏๅขƒๅ˜้‡ๅทฒ็ป้‡ๆ–ฐ่ฎพ่ฎกใ€‚** -> ๅ‡็บงๅŽ็š„้ฆ–ๆฌกๅฏๅŠจๆ—ถ๏ผŒOmniRoute ไผšๅฐ† `DATA_DIR/logs/`ใ€ๆ—ง็‰ˆ `DATA_DIR/call_logs/` ไปฅๅŠ `DATA_DIR/log.txt` ไธญ็š„ๅŽ†ๅฒ่ฏทๆฑ‚ๆ—ฅๅฟ—ๅฝ’ๆกฃๅˆฐ `DATA_DIR/log_archives/*.zip`๏ผŒ้šๅŽ็งป้™คๆ—งๅธƒๅฑ€ๅนถๅˆ‡ๆขๅˆฐ `DATA_DIR/call_logs/` ไธ‹ๆ–ฐ็š„็ปŸไธ€ artifact ๆ ผๅผใ€‚ +> **BREAKING CHANGE: request logging, retention, and logging environment variables have been redesigned.** +> On the first startup after upgrading, OmniRoute archives legacy request logs from `DATA_DIR/logs/`, legacy `DATA_DIR/call_logs/`, and `DATA_DIR/log.txt` into `DATA_DIR/log_archives/*.zip`, then removes the deprecated layout and switches to the new unified artifact format under `DATA_DIR/call_logs/`. -### โœจ ๆ–ฐ็‰นๆ€ง +### โœจ New Features -- **็ปŸไธ€่ฏทๆฑ‚ๆ—ฅๅฟ— Artifact๏ผš** ่ฏทๆฑ‚ๆ—ฅๅฟ—็Žฐๅœจไผšๅœจ `DATA_DIR/call_logs/` ไธ‹ไธบๆฏไธช่ฏทๆฑ‚ไฟๅญ˜ไธ€ๆก SQLite ็ดขๅผ•่ฎฐๅฝ•ๅ’Œไธ€ไธช JSON artifact๏ผŒๅนถๅฏๅฐ†ๅฏ้€‰็š„ๆตๆฐด็บฟๆ•่Žทๅ†…ๅฎนๅตŒๅ…ฅๅŒไธ€ๆ–‡ไปถใ€‚ -- **่ฏญ่จ€๏ผš** ๆ”น่ฟ›ไบ†ไธญๆ–‡็ฟป่ฏ‘๏ผˆ#855๏ผ‰ -- **Opencode-Zen Models๏ผš** ไธบ opencode-zen ๆณจๅ†Œ่กจๆ–ฐๅขžไบ† 4 ไธชๅ…่ดนๆจกๅž‹๏ผˆ#854๏ผ‰ -- **ๆต‹่ฏ•๏ผš** ไธบ่ฎพ็ฝฎๅผ€ๅ…ณๅ’Œ bug ไฟฎๅคๆ–ฐๅขžไบ†ๅ•ๅ…ƒๆต‹่ฏ•ไธŽ E2E ๆต‹่ฏ•๏ผˆ#850๏ผ‰ +- **.ENV Migration Utility:** Included `scripts/migrate-env.mjs` to seamlessly migrate `` ็š„ๆƒ้™ๅŠจๆ€่ฟ‡ๆปคๅ…ถๅˆ—่กจ๏ผˆๅฝ“ๅฏ็”จ่ฎฟ้—ฎ้™ๅˆถๆ—ถ๏ผ‰ (#781) -- **Qoder ้›†ๆˆ๏ผš** ๅŽŸ็”Ÿ้›†ๆˆ Qoder AI๏ผŒๅŽŸ็”Ÿๆ›ฟๆขไผ ็ปŸ็š„ iFlow ๅนณๅฐๆ˜ ๅฐ„ (#660) -- **ๆ็คบ่ฏ็ผ“ๅญ˜่ฟฝ่ธช๏ผš** ๆทปๅŠ ไบ†่ฟฝ่ธชๅŠŸ่ƒฝๅ’Œๅ‰็ซฏๅฏ่ง†ๅŒ–๏ผˆ็ปŸ่ฎกๅก็‰‡๏ผ‰๏ผŒ็”จไบŽไปช่กจ็›˜็•Œ้ขไธญ็š„่ฏญไน‰ๅ’Œๆ็คบ่ฏ็ผ“ๅญ˜ +- **Models API Filtering:** Endpoint `/v1/models` now dynamically filters its list based on the permissions tied to the `Authorization: Bearer ` when restricted access is on (#781) +- **Qoder Integration:** Native integration for Qoder AI natively replacing the legacy iFlow platform mappings (#660) +- **Prompt Cache Tracking:** Added tracking capabilities and frontend visualization (Stats card) for semantic and prompt caching in the Dashboard UI -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **็ผ“ๅญ˜ไปช่กจ็›˜ๅคงๅฐ๏ผš** ๆ”น่ฟ›ไบ†้ซ˜็บง็ผ“ๅญ˜้กต้ข็š„็•Œ้ขๅธƒๅฑ€ๅคงๅฐๅ’ŒไธŠไธ‹ๆ–‡ๆ ‡้ข˜ (#835) -- **่ฐƒ่ฏ•ไพง่พนๆ ๅฏ่งๆ€ง๏ผš** ไฟฎๅคไบ†ไธ€ไธช้—ฎ้ข˜๏ผš่ฐƒ่ฏ•ๅผ€ๅ…ณๆ— ๆณ•ๆญฃ็กฎๆ˜พ็คบ/้š่—ไพง่พนๆ ่ฐƒ่ฏ•่ฏฆๆƒ… (#834) -- **Gemini ๆจกๅž‹ๅ‰็ผ€๏ผš** ไฟฎๆ”นไบ†ๅ‘ฝๅ็ฉบ้—ดๅ›ž้€€๏ผŒไปฅ้€š่ฟ‡ `gemini-cli/` ่€Œไธๆ˜ฏ `gc/` ๆญฃ็กฎ่ทฏ็”ฑ๏ผŒไปŽ่€Œ้ตๅฎˆไธŠๆธธ่ง„่Œƒ (#831) -- **OpenRouter ๅŒๆญฅ๏ผš** ๆ”น่ฟ›ไบ†ๅ…ผๅฎนๆ€งๅŒๆญฅ๏ผŒไปฅๆญฃ็กฎๅœฐ่‡ชๅŠจไปŽ OpenRouter ่Žทๅ–ๅฏ็”จๆจกๅž‹็›ฎๅฝ• (#830) -- **ๆตๅผไผ ่พ“่ดŸ่ฝฝๆ˜ ๅฐ„๏ผš** ๅฝ“่พ“ๅ‡บๆตๅผไผ ่พ“ๅˆฐ่พน็ผ˜่ฎพๅค‡ๆ—ถ๏ผŒๆŽจ็†ๅญ—ๆฎต็š„้‡ๆ–ฐๅบๅˆ—ๅŒ–ๅฏๅŽŸ็”Ÿ่งฃๅ†ณๅ†ฒ็ชๅˆซๅ่ทฏๅพ„ +- **Cache Dashboard Sizing:** Improved the UI layout sizes and context headers for the advanced cache pages (#835) +- **Debug Sidebar Visibility:** Fixed an issue where the debug toggle wouldn't correctly show/hide sidebar debug details (#834) +- **Gemini Model Prefixing:** Modified the namespace fallback to properly route via `gemini-cli/` instead of `gc/` to respect upstream specs (#831) +- **OpenRouter Sync:** Improved compatibility synchronization to automatically ingest the available models catalog correctly from OpenRouter (#830) +- **Streaming Payloads Mapping:** Reserialization of reasoning fields natively resolves conflict alias paths when output is streaming to edge devices --- ## [3.3.7] - 2026-03-30 -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **OpenCode ้…็ฝฎ๏ผš** ้‡ๆž„็”Ÿๆˆ็š„ `opencode.json`๏ผŒไฝฟ็”จ `@ai-sdk/openai-compatible` ๅŸบไบŽ่ฎฐๅฝ•็š„ๆžถๆž„๏ผŒๅฐ† `options` ๅ’Œ `models` ไฝœไธบๅฏน่ฑกๆ˜ ๅฐ„่€Œไธๆ˜ฏๆ‰ๅนณๆ•ฐ็ป„๏ผŒไฟฎๅคไบ†้…็ฝฎ้ชŒ่ฏๅคฑ่ดฅ็š„้—ฎ้ข˜ (#816) -- **i18n ็ผบๅคฑ้”ฎ๏ผš** ๅœจๆ‰€ๆœ‰ 30 ไธช่ฏญ่จ€ๆ–‡ไปถไธญๆทปๅŠ ไบ†็ผบๅคฑ็š„ `cloudflaredUrlNotice` ็ฟป่ฏ‘้”ฎ๏ผŒไปฅ้˜ฒๆญข Endpoint ้กต้ขไธญ็š„ `MISSING_MESSAGE` ๆŽงๅˆถๅฐ้”™่ฏฏ (#823) +- **OpenCode Config:** Restructured generated `opencode.json` to use the `@ai-sdk/openai-compatible` record-based schema with `options` and `models` as object maps instead of flat arrays, fixing config validation failures (#816) +- **i18n Missing Keys:** Added missing `cloudflaredUrlNotice` translation key across all 30 language files to prevent `MISSING_MESSAGE` console errors in the Endpoint page (#823) --- ## [3.3.6] - 2026-03-30 -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **Token ่ฎก่ดน๏ผš** ๅœจๅŽ†ๅฒ็”จ้‡่พ“ๅ…ฅ่ฎก็ฎ—ไธญๅฎ‰ๅ…จๅœฐๅŒ…ๅซไบ†ๆ็คบ่ฏ็ผ“ๅญ˜ token๏ผŒไปฅๅฎž็Žฐๆญฃ็กฎ็š„้…้ขๆ‰ฃ้™ค (PR #822) -- **Combo ๆต‹่ฏ•ๆŽข้’ˆ๏ผš** ้€š่ฟ‡่งฃๆžไป…ๆŽจ็†ๅ“ๅบ”ๅนถ้€š่ฟ‡ Promise.all ๅฎž็Žฐๅคง่ง„ๆจกๅนถ่กŒๅŒ–๏ผŒไฟฎๅคไบ† combo ๆต‹่ฏ•้€ป่พ‘็š„่ฏฏๆŠฅ้—ฎ้ข˜ (PR #828) -- **Docker ๅฟซ้€Ÿ้šง้“๏ผš** ๅœจๅŸบ็ก€่ฟ่กŒๆ—ถๅฎนๅ™จไธญๅตŒๅ…ฅไบ†ๆ‰€้œ€็š„ ca-certificates ไปฅ่งฃๅ†ณ Cloudflared TLS ๅฏๅŠจๅคฑ่ดฅ๏ผŒๅนถๆ˜พ็คบ stdout ็ฝ‘็ปœ้”™่ฏฏไปฅๆ›ฟๆข้€š็”จ้€€ๅ‡บไปฃ็  (PR #829) +- **Token Accounting:** Included prompt cache tokens safely in historical usage inputs calculations for correct quota deductions (PR #822) +- **Combo Test Probes:** Fixed combo testing logic false negatives by resolving parsing for reasoning-only responses and enabled massive parallelization via Promise.all (PR #828) +- **Docker Quick Tunnels:** Embedded required ca-certificates inside the base runtime container to resolve Cloudflared TLS startup failures, and surfaced stdout network errors replacing generic exit codes (PR #829) --- ## [3.3.5] - 2026-03-30 -### โœจ ๆ–ฐ็‰นๆ€ง +### โœจ New Features -- **Gemini ้…้ข่ฟฝ่ธช๏ผš** ้€š่ฟ‡ `retrieveUserQuota` API ๆทปๅŠ ไบ†ๅฎžๆ—ถ Gemini CLI ้…้ข่ฟฝ่ธช (PR #825) -- **็ผ“ๅญ˜ไปช่กจ็›˜๏ผš** ๅขžๅผบไบ†็ผ“ๅญ˜ไปช่กจ็›˜๏ผŒๅฏๆ˜พ็คบๆ็คบ่ฏ็ผ“ๅญ˜ๆŒ‡ๆ ‡ใ€24ๅฐๆ—ถ่ถ‹ๅŠฟๅ’Œ้ข„ไผฐๆˆๆœฌ่Š‚็œ (PR #824) +- **Gemini Quota Tracking:** Added real-time Gemini CLI quota tracking via the `retrieveUserQuota` API (PR #825) +- **Cache Dashboard:** Enhanced the Cache Dashboard to display prompt cache metrics, 24h trends, and estimated cost savings (PR #824) -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **็”จๆˆทไฝ“้ชŒ๏ผš** ็งป้™คไบ†ๅœจ็ฉบ็™ฝๆœๅŠกๅ•†่ฏฆๆƒ…้กต้ขไธŠไพตๅ…ฅๆ€ง็š„่‡ชๅŠจๆ‰“ๅผ€ OAuth ๆจกๆ€ๆก†ๅพช็Žฏ (PR #820) -- **ไพ่ต–ๆ›ดๆ–ฐ๏ผš** ๆ›ดๆ–ฐๅนถ้”ๅฎšไบ†ๅผ€ๅ‘ๅ’Œ็”Ÿไบงไพ่ต–ๆ ‘๏ผŒๅŒ…ๆ‹ฌ Next.js 16.2.1ใ€Recharts ๅ’Œ TailwindCSS 4.2.2 (PR #826, #827) +- **User Experience:** Removed invasive auto-opening OAuth modal loops on barren provider detailed pages (PR #820) +- **Dependency Updates:** Bumped and locked down dependencies for development and production trees including Next.js 16.2.1, Recharts, and TailwindCSS 4.2.2 (PR #826, #827) --- ## [3.3.4] - 2026-03-30 -### โœจ ๆ–ฐ็‰นๆ€ง +### โœจ New Features -- **A2A ๅทฅไฝœๆต๏ผš** ๆทปๅŠ ไบ†็”จไบŽๅคšๆญฅ้ชคไปฃ็†ๅทฅไฝœๆต็š„็กฎๅฎšๆ€ง FSM ็ผ–ๆŽ’ๅ™จ -- **ไผ˜้›…้™็บง๏ผš** ๆทปๅŠ ไบ†ๆ–ฐ็š„ๅคšๅฑ‚ๅ›ž้€€ๆก†ๆžถ๏ผŒไปฅๅœจ้ƒจๅˆ†็ณป็ปŸๆ•…้šœๆœŸ้—ดไฟๆŒๆ ธๅฟƒๅŠŸ่ƒฝ -- **้…็ฝฎๅฎก่ฎก๏ผš** ๆทปๅŠ ไบ†ๅธฆ diff ๆฃ€ๆต‹็š„ๅฎก่ฎก่ฟฝ่ธช๏ผŒไปฅ่ฟฝ่ธชๅ˜ๆ›ดๅนถๅฏ็”จ้…็ฝฎๅ›žๆปš -- **ๆœๅŠกๅ•†ๅฅๅบท็Šถๆ€๏ผš** ๆทปๅŠ ไบ†ๆœๅŠกๅ•†่ฟ‡ๆœŸ่ฟฝ่ธช๏ผŒๅนถไธบๅณๅฐ†่ฟ‡ๆœŸ็š„ API ๅฏ†้’ฅๆไพ›ไธปๅŠจ UI ่ญฆๆŠฅ -- **่‡ช้€‚ๅบ”่ทฏ็”ฑ๏ผš** ๆทปๅŠ ไบ†่‡ช้€‚ๅบ”ๆต้‡ๅ’Œๅคๆ‚ๅบฆๆฃ€ๆต‹ๅ™จ๏ผŒๅฏๆ นๆฎ่ดŸ่ฝฝๅŠจๆ€่ฆ†็›–่ทฏ็”ฑ็ญ–็•ฅ -- **ๆœๅŠกๅ•†ๅคšๆ ทๆ€ง๏ผš** ้€š่ฟ‡้ฆ™ๅ†œ็†ตๅฎž็Žฐไบ†ๆœๅŠกๅ•†ๅคšๆ ทๆ€ง่ฏ„ๅˆ†๏ผŒไปฅๆ”นๅ–„่ดŸ่ฝฝๅˆ†้… -- **่‡ชๅŠจ็ฆ็”จ่พน็•Œ๏ผš** ๅœจๅผนๆ€งไปช่กจ็›˜ไธญๆทปๅŠ ไบ†่‡ชๅŠจ็ฆ็”จ่ขซๅฐ็ฆ่ดฆๆˆท็š„่ฎพ็ฝฎๅผ€ๅ…ณ +- **A2A Workflows:** Added deterministic FSM orchestrator for multi-step agent workflows. +- **Graceful Degradation:** Added a new multi-layer fallback framework to preserve core functionality during partial system outages. +- **Config Audit:** Added an audit trail with diff detection to track changes and enable configuration rollbacks. +- **Provider Health:** Added provider expiration tracking with proactive UI alerts for expiring API keys. +- **Adaptive Routing:** Added an adaptive volume and complexity detector to override routing strategies dynamically based on load. +- **Provider Diversity:** Implemented provider diversity scoring via Shannon entropy to improve load distribution. +- **Auto-Disable Bounds:** Added an Auto-Disable Banned Accounts setting toggle to the Resilience dashboard. -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **Codex ๅ’Œ Claude ๅ…ผๅฎนๆ€ง๏ผš** ไฟฎๅคไบ† UI ๅ›ž้€€๏ผŒไฟฎ่กฅไบ† Codex ้žๆตๅผไผ ่พ“้›†ๆˆ้—ฎ้ข˜๏ผŒๅนถ่งฃๅ†ณไบ† Windows ไธŠ็š„ CLI ่ฟ่กŒๆ—ถๆฃ€ๆต‹้—ฎ้ข˜ -- **ๅ‘ๅธƒ่‡ชๅŠจๅŒ–๏ผš** ๆ‰ฉๅฑ•ไบ† GitHub Actions ไธญ Electron App ๆž„ๅปบๆ‰€้œ€็š„ๆƒ้™ -- **Cloudflare ่ฟ่กŒๆ—ถ๏ผš** ๅค„็†ไบ† Cloudflared ้šง้“็ป„ไปถ็š„ๆญฃ็กฎ่ฟ่กŒๆ—ถ้š”็ฆป้€€ๅ‡บไปฃ็  +- **Codex & Claude Compatibility:** Fixed UI fallbacks, patched Codex non-streaming integration issues, and resolved CLI runtime detection on Windows. +- **Release Automation:** Expanded permissions required for the Electron App build in GitHub Actions. +- **Cloudflare Runtime:** Addressed correct runtime isolation exit codes for Cloudflared tunnel components. -### ๐Ÿงช ๆต‹่ฏ• +### ๐Ÿงช Tests -- **ๆต‹่ฏ•ๅฅ—ไปถๆ›ดๆ–ฐ๏ผš** ๆ‰ฉๅฑ•ไบ†ๆต้‡ๆฃ€ๆต‹ๅ™จใ€ๆœๅŠกๅ•†ๅคšๆ ทๆ€งใ€้…็ฝฎๅฎก่ฎกๅ’Œ FSM ็š„ๆต‹่ฏ•่ฆ†็›–็Ž‡ +- **Test Suite Updates:** Expanded test coverage for volume detectors, provider diversity, configuration audit, and FSM. --- ## [3.3.3] - 2026-03-29 -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **CI/CD ๅฏ้ ๆ€ง๏ผš** ไฟฎ่กฅไบ† GitHub Actions ไฝฟ็”จ็จณๅฎš็š„ไพ่ต–็‰ˆๆœฌ๏ผˆ`actions/checkout@v4`ใ€`actions/upload-artifact@v4`๏ผ‰๏ผŒไปฅ็ผ“่งฃๆœชๅ…ฌๅ‘Š็š„ๆž„ๅปบ็Žฏๅขƒๅผƒ็”จ้—ฎ้ข˜ใ€‚ -- **ๅ›พ็‰‡ๅ›ž้€€๏ผš** ๆ›ฟๆขไบ† `ProviderIcon.tsx` ไธญ็š„ไปปๆ„ๅ›ž้€€้“พ๏ผŒๆ”น็”จๆ˜พๅผ่ต„ๆบ้ชŒ่ฏๆฅ้˜ฒๆญข UI ๅŠ ่ฝฝไธๅญ˜ๅœจๆ–‡ไปถ็š„ `` ็ป„ไปถ๏ผŒไปŽ่€Œๆถˆ้™คไปช่กจ็›˜ๆŽงๅˆถๅฐๆ—ฅๅฟ—ไธญ็š„ `404` ้”™่ฏฏ๏ผˆ#745๏ผ‰ใ€‚ -- **็ฎก็†ๅ‘˜ๆ›ดๆ–ฐๅ™จ๏ผš** ไธบไปช่กจ็›˜ๆ›ดๆ–ฐๅ™จๆทปๅŠ ไบ†ๅŠจๆ€ๆบๅฎ‰่ฃ…ๆฃ€ๆต‹ใ€‚ๅฝ“ OmniRoute ๆ˜ฏๆœฌๅœฐๆž„ๅปบ่€Œ้ž้€š่ฟ‡ npm ๅฎ‰่ฃ…ๆ—ถ๏ผŒๅฎ‰ๅ…จๅœฐ็ฆ็”จ `็ซ‹ๅณๆ›ดๆ–ฐ` ๆŒ‰้’ฎ๏ผŒๅนถๆ็คบไฝฟ็”จ `git pull`๏ผˆ#743๏ผ‰ใ€‚ -- **ๆ›ดๆ–ฐ ERESOLVE ้”™่ฏฏ๏ผš** ๅœจๅ†…้ƒจ่‡ชๅŠจๆ›ดๆ–ฐ่„šๆœฌไธญๆณจๅ…ฅไบ† `package.json` ่ฆ†็›–้…็ฝฎ๏ผˆ็”จไบŽ `react`/`react-dom`๏ผ‰ๅนถๅฏ็”จไบ† `--legacy-peer-deps`๏ผŒไปฅ่งฃๅ†ณไธŽ `@lobehub/ui` ็š„็ ดๅๆ€งไพ่ต–ๆ ‘ๅ†ฒ็ชใ€‚ +- **CI/CD Reliability:** Patched GitHub Actions to stable dependency versions (`actions/checkout@v4`, `actions/upload-artifact@v4`) to mitigate unannounced builder environment deprecations. +- **Image Fallbacks:** Replaced arbitrary fallback chains in `ProviderIcon.tsx` with explicit asset validation to prevent UI loading `` components for files that don't exist, eliminating `404` errors in dashboard console logs (#745). +- **Admin Updater:** Dynamic source-installation detection for the dashboard Updater. Safely disables the `Update Now` button when OmniRoute is built locally rather than through npm, prompting for `git pull` (#743). +- **Update ERESOLVE Error:** Injected `package.json` overrides for `react`/`react-dom` and enabled `--legacy-peer-deps` within the internal automatic updater scripts to resolve breaking dependency tree conflicts with `@lobehub/ui`. --- ## [3.3.2] - 2026-03-29 -### โœจ ๆ–ฐ็‰นๆ€ง +### โœจ New Features -- **Cloudflare Tunnels:** Cloudflare Quick Tunnel ้›†ๆˆ๏ผŒๅธฆๆœ‰ไปช่กจ็›˜ๆŽงๅˆถๅŠŸ่ƒฝ๏ผˆPR #772๏ผ‰ใ€‚ -- **Diagnostics:** ไธบ็ป„ๅˆๅฎžๆ—ถๆต‹่ฏ•ๆทปๅŠ ไบ†่ฏญไน‰็ผ“ๅญ˜็ป•่ฟ‡ๅŠŸ่ƒฝ๏ผˆPR #773๏ผ‰ใ€‚ +- **Cloudflare Tunnels:** Cloudflare Quick Tunnel integration with dashboard controls (PR #772). +- **Diagnostics:** Semantic cache bypass for combo live tests (PR #773). -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **Streaming Stability:** ๅฐ† `FETCH_TIMEOUT_MS` ๅบ”็”จไบŽๆตๅผ่ฏทๆฑ‚็š„ๅˆๅง‹ `fetch()` ่ฐƒ็”จ๏ผŒไปฅ้˜ฒๆญข 300 ็ง’ Node.js TCP ่ถ…ๆ—ถๅฏผ่‡ด็š„้™้ป˜ไปปๅŠกๅคฑ่ดฅ๏ผˆ#769๏ผ‰ใ€‚ -- **i18n:** ๅœจๆ‰€ๆœ‰ 33 ไธช่ฏญ่จ€ๆ–‡ไปถ็š„ `toolDescriptions` ไธญๆทปๅŠ ไบ†็ผบๅคฑ็š„ `windsurf` ๅ’Œ `copilot` ๆก็›ฎ๏ผˆ#748๏ผ‰ใ€‚ -- **GLM Coding Audit:** ๅฎŒๆˆไบ†ๆœๅŠกๅ•†ๅฎก่ฎก๏ผŒไฟฎๅคไบ† ReDoS ๆผๆดžใ€ไธŠไธ‹ๆ–‡็ช—ๅฃๅคงๅฐ๏ผˆ128k/16k๏ผ‰ไปฅๅŠๆจกๅž‹ๆณจๅ†Œ่กจๅŒๆญฅ๏ผˆPR #778๏ผ‰ใ€‚ +- **Streaming Stability:** Apply `FETCH_TIMEOUT_MS` to streaming requests' initial `fetch()` call to prevent 300s Node.js TCP timeout causing silent task failures (#769). +- **i18n:** Add missing `windsurf` and `copilot` entries to `toolDescriptions` across all 33 locale files (#748). +- **GLM Coding Audit:** Complete provider audit fixing ReDoS vulnerabilities, context window sizing (128k/16k), and model registry syncing (PR #778). --- ## [3.3.1] - 2026-03-29 -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **OpenAI Codex:** ไฟฎๅคไบ†ๅ›ž้€€ๅค„็†ไธญ `type: "text"` ๅ…ƒ็ด ๆบๅธฆ null ๆˆ–็ฉบๆ•ฐๆฎ้›†ๅฏผ่‡ด 400 ๆ‹’็ป็š„้—ฎ้ข˜๏ผˆ#742๏ผ‰ใ€‚ -- **Opencode:** ๆ›ดๆ–ฐๆžถๆž„ๅฏน้ฝ๏ผŒไฝฟ็”จๅ•ๆ•ฐ `provider` ไปฅๅŒน้…ๅฎ˜ๆ–น่ง„่Œƒ๏ผˆ#774๏ผ‰ใ€‚ -- **Gemini CLI:** ๆณจๅ…ฅ็ผบๅคฑ็š„็ปˆ็ซฏ็”จๆˆท้…้ขๅคด๏ผŒ้˜ฒๆญข 403 ๆŽˆๆƒ้”ๅฎš๏ผˆ#775๏ผ‰ใ€‚ -- **DB Recovery:** ๅฐ†ๅคš้ƒจๅˆ†่ดŸ่ฝฝๅฏผๅ…ฅ้‡ๆž„ไธบๅŽŸๅง‹ไบŒ่ฟ›ๅˆถ็ผ“ๅ†ฒๆ•ฐ็ป„๏ผŒไปฅ็ป•่ฟ‡ๅๅ‘ไปฃ็†็š„ๆœ€ๅคงๆญฃๆ–‡้™ๅˆถ๏ผˆ#770๏ผ‰ใ€‚ +- **OpenAI Codex:** Fallback processing fix for `type: "text"` elements carrying null or empty datasets that caused 400 rejection (#742). +- **Opencode:** Update schema alignment to singular `provider` to match official spec (#774). +- **Gemini CLI:** Inject missing end-user quota headers preventing 403 authorization lockouts (#775). +- **DB Recovery:** Refactor multipart payload imports into raw binary buffered arrays to bypass reverse proxy max body limits (#770). --- ## [3.3.0] - 2026-03-29 -### โœจ ๅขžๅผบไธŽ้‡ๆž„ +### โœจ Enhancements & Refactoring -- **Release Stabilization** โ€” ๅฎŒๆˆไบ† v3.2.9 ็‰ˆๆœฌๅ‘ๅธƒ๏ผˆ็ป„ๅˆ่ฏŠๆ–ญใ€่ดจ้‡ๆฃ€ๆต‹ใ€Gemini ๅทฅๅ…ทไฟฎๅค๏ผ‰ๅนถๅˆ›ๅปบไบ†็ผบๅคฑ็š„ git ๆ ‡็ญพใ€‚ๅฐ†ๆ‰€ๆœ‰ๆš‚ๅญ˜็š„ๆ›ดๆ”นๆ•ดๅˆๅˆฐๅ•ไธชๅŽŸๅญๅ‘ๅธƒๆไบคไธญใ€‚ +- **Release Stabilization** โ€” Finalized v3.2.9 release (combo diagnostics, quality gates, Gemini tool fix) and created missing git tag. Consolidated all staged changes into a single atomic release commit. -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **Auto-Update Test** โ€” ไฟฎๅคไบ† `buildDockerComposeUpdateScript` ๆต‹่ฏ•ๆ–ญ่จ€๏ผŒไปฅๅŒน้…็”Ÿๆˆ็š„้ƒจ็ฝฒ่„šๆœฌไธญๆœชๅฑ•ๅผ€็š„ shell ๅ˜้‡ๅผ•็”จ๏ผˆ`$TARGET_TAG`ใ€`${TARGET_TAG#v}`๏ผ‰๏ผŒไธŽ v3.2.8 ็š„้‡ๆž„ๆจกๆฟๅฏน้ฝใ€‚ -- **Circuit Breaker Test** โ€” ้€š่ฟ‡ๆณจๅ…ฅ `maxRetries: 0` ๅผบๅŒ–ไบ† `combo-circuit-breaker.test.mjs`๏ผŒไปฅ้˜ฒๆญขๅœจๆ–ญ่ทฏๅ™จ็Šถๆ€่ฝฌๆขๆœŸ้—ด้‡่ฏ•่†จ่ƒ€ๆ‰ญๆ›ฒๅคฑ่ดฅ่ฎกๆ•ฐๆ–ญ่จ€ใ€‚ +- **Auto-Update Test** โ€” Fixed `buildDockerComposeUpdateScript` test assertion to match unexpanded shell variable references (`$TARGET_TAG`, `${TARGET_TAG#v}`) in the generated deploy script, aligning with the refactored template from v3.2.8. +- **Circuit Breaker Test** โ€” Hardened `combo-circuit-breaker.test.mjs` by injecting `maxRetries: 0` to prevent retry inflation from skewing failure count assertions during breaker state transitions. --- ## [3.2.9] - 2026-03-29 -### โœจ ๅขžๅผบไธŽ้‡ๆž„ +### โœจ Enhancements & Refactoring -- **Combo Diagnostics** โ€” ๅผ•ๅ…ฅไบ†ๅฎžๆ—ถๆต‹่ฏ•็ป•่ฟ‡ๆ ‡ๅฟ—๏ผˆ`forceLiveComboTest`๏ผ‰๏ผŒๅ…่ฎธ็ฎก็†ๅ‘˜ๆ‰ง่กŒ็œŸๅฎž็š„ไธŠๆธธๅฅๅบทๆฃ€ๆŸฅ๏ผŒ็ป•่ฟ‡ๆ‰€ๆœ‰ๆœฌๅœฐๆ–ญ่ทฏๅ™จๅ’Œๅ†ทๅด็Šถๆ€ๆœบๅˆถ๏ผŒๅœจๆปšๅŠจไธญๆ–ญๆœŸ้—ดๅฎž็Žฐ็ฒพ็กฎ่ฏŠๆ–ญ๏ผˆPR #759๏ผ‰ -- **Quality Gates** โ€” ๆทปๅŠ ไบ†็ป„ๅˆ็š„่‡ชๅŠจๅ“ๅบ”่ดจ้‡้ชŒ่ฏ๏ผŒๅนถๆญฃๅผๅฐ† `claude-4.6` ๆจกๅž‹ๆ”ฏๆŒ้›†ๆˆๅˆฐๆ ธๅฟƒ่ทฏ็”ฑๆžถๆž„ไธญ๏ผˆPR #762๏ผ‰ +- **Combo Diagnostics** โ€” Introduced a live test bypass flag (`forceLiveComboTest`) allowing administrators to execute real upstream health checks that bypass all local circuit-breaker and cooldown state mechanisms, enabling precise diagnostics during rolling outages (PR #759) +- **Quality Gates** โ€” Added automated response quality validation for combos and officially integrated `claude-4.6` model support into the core routing schemas (PR #762) -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **Tool Definition Validation** โ€” ้€š่ฟ‡ๆ ‡ๅ‡†ๅŒ–ๅทฅๅ…ทๅฎšไน‰ไธญ็š„ๆžšไธพ็ฑปๅž‹ไฟฎๅคไบ† Gemini API ้›†ๆˆ๏ผŒ้˜ฒๆญขไธŠๆธธ HTTP 400 ๅ‚ๆ•ฐ้”™่ฏฏ๏ผˆPR #760๏ผ‰ +- **Tool Definition Validation** โ€” Repaired Gemini API integration by normalizing enum types inside tool definitions, preventing upstream HTTP 400 parameter errors (PR #760) --- ## [3.2.8] - 2026-03-29 -### โœจ ๅขžๅผบไธŽ้‡ๆž„ +### โœจ Enhancements & Refactoring -- **Docker Auto-Update UI** โ€” ้›†ๆˆไบ†ๅŽๅฐ็‹ฌ็ซ‹ๆ›ดๆ–ฐ่ฟ›็จ‹๏ผŒ็”จไบŽ Docker Compose ้ƒจ็ฝฒใ€‚Dashboard UI ็Žฐๅœจๅฏไปฅๆ— ็ผ่ทŸ่ธชๆ›ดๆ–ฐ็”Ÿๅ‘ฝๅ‘จๆœŸไบ‹ไปถ๏ผŒ็ป“ๅˆ JSON REST ๅ“ๅบ”ๅ’Œ SSE ๆตๅผไผ ่พ“่ฟ›ๅบฆ่ฆ†็›–ๅฑ‚๏ผŒๅฎž็Žฐๅผบๅคง็š„่ทจ็Žฏๅขƒๅฏ้ ๆ€งใ€‚ -- **Cache Analytics** โ€” ไฟฎๅคไบ†้›ถๆŒ‡ๆ ‡ๅฏ่ง†ๅŒ–ๆ˜ ๅฐ„้—ฎ้ข˜๏ผŒๅฐ† Semantic Cache ้ฅๆต‹ๆ—ฅๅฟ—็›ดๆŽฅ่ฟ็งปๅˆฐ้›†ไธญ่ฟฝ่ธช SQLite ๆจกๅ—ไธญใ€‚ +- **Docker Auto-Update UI** โ€” Integrated a detached background update process for Docker Compose deployments. The Dashboard UI now seamlessly tracks update lifecycle events combining JSON REST responses with SSE streaming progress overlays for robust cross-environment reliability. +- **Cache Analytics** โ€” Repaired zero-metrics visualization mapping by migrating Semantic Cache telemetry logs directly into the centralized tracking SQLite module. -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **Authentication Logic** โ€” ไฟฎๅคไบ†ๅœจ็ฆ็”จ `requireLogin` ๆ—ถไฟๅญ˜ไปช่กจๆฟ่ฎพ็ฝฎๆˆ–ๆทปๅŠ ๆจกๅž‹ๅคฑ่ดฅๅนถ่ฟ”ๅ›ž 401 Unauthorized ้”™่ฏฏ็š„้—ฎ้ข˜ใ€‚API ็ซฏ็‚น็Žฐๅœจๆญฃ็กฎ่ฏ„ไผฐๅ…จๅฑ€่ฎค่ฏๅผ€ๅ…ณใ€‚้€š่ฟ‡้‡ๆ–ฐๆฟ€ๆดป `src/middleware.ts` ่งฃๅ†ณไบ†ๅ…จๅฑ€้‡ๅฎšๅ‘้—ฎ้ข˜ใ€‚ -- **CLI Tool Detection (Windows)** โ€” ้€š่ฟ‡ๆญฃ็กฎๆ•่Žท `cross-spawn` ENOENT ้”™่ฏฏ๏ผŒ้˜ฒๆญข CLI ็Žฏๅขƒๆฃ€ๆต‹ๆœŸ้—ด็š„่‡ดๅ‘ฝๅˆๅง‹ๅŒ–ๅผ‚ๅธธใ€‚ๆทปๅŠ ไบ† `\AppData\Local\droid\droid.exe` ็š„ๆ˜พๅผๆฃ€ๆต‹่ทฏๅพ„ใ€‚ -- **Codex Native Passthrough** โ€” ่ง„่ŒƒๅŒ–ๆจกๅž‹็ฟป่ฏ‘ๅ‚ๆ•ฐไปฅ้˜ฒๆญขไปฃ็†้€ไผ ๆจกๅผไธ‹็š„ไธŠไธ‹ๆ–‡ๆฑกๆŸ“๏ผŒๅฏนๆ‰€ๆœ‰ Codex ๅ‘่ตท็š„่ฏทๆฑ‚ๆ˜พๅผๅผบๅˆถๆ‰ง่กŒ้€š็”จ็š„ `store: false` ็บฆๆŸใ€‚ -- **SSE Token Reporting** โ€” ่ง„่ŒƒๅŒ–ๆœๅŠกๅ•†ๅทฅๅ…ท่ฐƒ็”จๅ—็š„ `finish_reason` ๆฃ€ๆต‹๏ผŒไฟฎๅคไบ†็ผบๅฐ‘ไธฅๆ ผ `` ๆŒ‡็คบ็ฌฆ็š„็บฏๆตๅผๅ“ๅบ”ๅฏผ่‡ดไฝฟ็”จ็Ž‡ๅˆ†ๆžไธบ 0% ็š„้—ฎ้ข˜ใ€‚ -- **DeepSeek Tags** โ€” ๅœจ `responsesHandler.ts` ไธญๅฎž็Žฐไบ†ๆ˜พๅผ็š„ `` ๆๅ–ๆ˜ ๅฐ„๏ผŒ็กฎไฟ DeepSeek ๆŽจ็†ๆต่ƒฝ็ญ‰ไปทๆ˜ ๅฐ„ๅˆฐๅŽŸ็”Ÿ Anthropic `` ็ป“ๆž„ใ€‚ +- **Authentication Logic** โ€” Fixed a bug where saving dashboard settings or adding models failed with a 401 Unauthorized error when `requireLogin` was disabled. API endpoints now correctly evaluate the global authentication toggle. Resolved global redirection by reactivating `src/middleware.ts`. +- **CLI Tool Detection (Windows)** โ€” Prevented fatal initialization exceptions during CLI environment detection by catching `cross-spawn` ENOENT errors correctly. Adds explicit detection paths for `\AppData\Local\droid\droid.exe`. +- **Codex Native Passthrough** โ€” Normalized model translation parameters preventing context poisoning in proxy pass-through mode, enforcing generic `store: false` constraints explicitly for all Codex-originated requests. +- **SSE Token Reporting** โ€” Normalized provider tool-call chunk `finish_reason` detection, fixing 0% Usage analytics for stream-only responses missing strict `` indicators. +- **DeepSeek Tags** โ€” Implemented an explicit `` extraction mapping inside `responsesHandler.ts`, ensuring DeepSeek reasoning streams map equivalently to native Anthropic `` structures. --- ## [3.2.7] - 2026-03-29 -### ไฟฎๅค +### Fixed -- **Seamless UI Updates**๏ผšDashboard ไธŠ็š„"็ซ‹ๅณๆ›ดๆ–ฐ"ๅŠŸ่ƒฝ็Žฐๅœจไฝฟ็”จ Server-Sent Events (SSE) ๆไพ›ๅฎžๆ—ถ้€ๆ˜Žๅ้ฆˆใ€‚ๅฎƒๅฏ้ ๅœฐๆ‰ง่กŒๅŒ…ๅฎ‰่ฃ…ใ€ๅŽŸ็”Ÿๆจกๅ—้‡ๅปบ๏ผˆbetter-sqlite3๏ผ‰ๅ’Œ PM2 ้‡ๅฏ๏ผŒๅŒๆ—ถๆ˜พ็คบๅฎžๆ—ถๅŠ ่ฝฝๅ™จ่€Œไธๆ˜ฏ้™้ป˜ๆŒ‚่ตทใ€‚ +- **Seamless UI Updates**: The "Update Now" feature on the Dashboard now provides live, transparent feedback using Server-Sent Events (SSE). It performs package installation, native module rebuilds (better-sqlite3), and PM2 restarts reliably while showing real-time loaders instead of silently hanging. --- ## [3.2.6] โ€” 2026-03-29 -### โœจ ๅขžๅผบไธŽ้‡ๆž„ +### โœจ Enhancements & Refactoring -- **API Key Reveal (#740)** โ€” ๅœจ API Manager ไธญๆทปๅŠ ไบ†่Œƒๅ›ด้™ๅฎš็š„ API ๅฏ†้’ฅๅคๅˆถๆต็จ‹๏ผŒๅ— `ALLOW_API_KEY_REVEAL` ็Žฏๅขƒๅ˜้‡ไฟๆŠคใ€‚ -- **Sidebar Visibility Controls (#739)** โ€” ็ฎก็†ๅ‘˜็Žฐๅœจๅฏไปฅ้€š่ฟ‡ๅค–่ง‚่ฎพ็ฝฎ้š่—ไปปไฝ•ไพง่พนๆ ๅฏผ่ˆช้“พๆŽฅ๏ผŒไปฅๅ‡ๅฐ‘่ง†่ง‰ๆ‚ไนฑใ€‚ -- **Strict Combo Testing (#735)** โ€” ๅŠ ๅ›บไบ† combo ๅฅๅบทๆฃ€ๆŸฅ็ซฏ็‚น๏ผŒ่ฆๆฑ‚ๆจกๅž‹่ฟ”ๅ›žๅฎžๆ—ถๆ–‡ๆœฌๅ“ๅบ”๏ผŒ่€Œไธไป…ไป…ๆ˜ฏ่ฝฏๅฏ่พพๆ€งไฟกๅทใ€‚ -- **Streamed Detailed Logs (#734)** โ€” ๅฐ† SSE ๆต็š„่ฏฆ็ป†่ฏทๆฑ‚ๆ—ฅๅฟ—ๅˆ‡ๆขไธบ้‡ๅปบๆœ€็ปˆ่ดŸ่ฝฝ๏ผŒ่Š‚็œไบ†ๅคง้‡ SQLite ๆ•ฐๆฎๅบ“็ฉบ้—ดๅนถๆ˜พ่‘—ๆธ…็†ไบ† UIใ€‚ +- **API Key Reveal (#740)** โ€” Added a scoped API key copy flow in the Api Manager, protected by the `ALLOW_API_KEY_REVEAL` environment variable. +- **Sidebar Visibility Controls (#739)** โ€” Admins can now hide any sidebar navigation link via the Appearance settings to reduce visual clutter. +- **Strict Combo Testing (#735)** โ€” Hardened the combo health check endpoint to require live text responses from models instead of just soft reachability signals. +- **Streamed Detailed Logs (#734)** โ€” Switched detailed request logging for SSE streams to reconstruct the final payload, saving immense amounts of SQLite database size and significantly cleaning up the UI. -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **OpenCode Go MiniMax Auth (#733)** โ€” ไฟฎๆญฃไบ† OpenCode Go ไธญ `minimax` ๆจกๅž‹็š„่ฎค่ฏๅคด้€ป่พ‘๏ผŒๅœจ `/messages` ๅ่ฎฎไธญไฝฟ็”จ `x-api-key` ่€Œไธๆ˜ฏๆ ‡ๅ‡† bearer tokenใ€‚ +- **OpenCode Go MiniMax Auth (#733)** โ€” Corrected the authentication header logic for `minimax` models on OpenCode Go to use `x-api-key` instead of standard bearer tokens across the `/messages` protocol. --- ## [3.2.5] โ€” 2026-03-29 -### โœจ ๅขžๅผบไธŽ้‡ๆž„ +### โœจ Enhancements & Refactoring -- **Void Linux Deployment Support (#732)** โ€” ้›†ๆˆไบ† `xbps-src` ๆ‰“ๅŒ…ๆจกๆฟๅ’Œ่ฏดๆ˜Ž๏ผŒ้€š่ฟ‡ไบคๅ‰็ผ–่ฏ‘็›ฎๆ ‡ๅŽŸ็”Ÿ็ผ–่ฏ‘ๅ’Œๅฎ‰่ฃ…ๅธฆๆœ‰ `better-sqlite3` ็ป‘ๅฎš็š„ OmniRouteใ€‚ +- **Void Linux Deployment Support (#732)** โ€” Integrated `xbps-src` packaging template and instructions to natively compile and install OmniRoute with `better-sqlite3` bindings via cross-compilation target. ## [3.2.4] โ€” 2026-03-29 -### โœจ ๅขžๅผบไธŽ้‡ๆž„ +### โœจ Enhancements & Refactoring -- **Qoder AI Migration (#660)** โ€” ๅฎŒๅ…จๅฐ†ไผ ็ปŸ็š„ `iFlow` ๆ ธๅฟƒๆœๅŠกๅ•†่ฟ็งปๅˆฐ `Qoder AI`๏ผŒไฟๆŒ็จณๅฎš็š„ API ่ทฏ็”ฑ่ƒฝๅŠ›ใ€‚ +- **Qoder AI Migration (#660)** โ€” Completely migrated the legacy `iFlow` core provider onto `Qoder AI` maintaining stable API routing capabilities. -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **Gemini Tools HTTP 400 Payload Invalid Argument (#731)** โ€” ้˜ปๆญขๆ ‡ๅ‡† Gemini `functionCall` ๅบๅˆ—ไธญๆณจๅ…ฅ `thoughtSignature` ๆ•ฐ็ป„๏ผŒไปŽ่€Œ้ฟๅ… agentic routing ๆต็จ‹่ขซ้˜ปๅกžใ€‚ +- **Gemini Tools HTTP 400 Payload Invalid Argument (#731)** โ€” Prevented `thoughtSignature` array injections inside standard Gemini `functionCall` sequences blocking agentic routing flows. --- ## [3.2.3] โ€” 2026-03-29 -### โœจ ๅขžๅผบไธŽ้‡ๆž„ +### โœจ Enhancements & Refactoring -- **Provider Limits Quota UI (#728)** โ€” ็ปŸไธ€ไบ† Limits ็•Œ้ขไธญ็š„้…้ข้™ๅˆถ้€ป่พ‘ๅ’Œๆ•ฐๆฎๆ ‡ๆณจใ€‚ +- **Provider Limits Quota UI (#728)** โ€” Normalized quota limit logic and data labeling inside the Limits interface. -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **Core Routing Schemas & Leaks** โ€” ๆ‰ฉๅฑ•ไบ† `comboStrategySchema`๏ผŒๅŽŸ็”Ÿๆ”ฏๆŒ `fill-first` ๅ’Œ `p2c` ็ญ–็•ฅ๏ผŒ่งฃ้™คๅคๆ‚ combo ็ผ–่พ‘็š„้˜ปๅกžใ€‚ -- **Thinking Tags Extraction (CLI)** โ€” ้‡ๆž„ไบ† CLI token ๅ“ๅบ”ๆธ…็†็š„ๆญฃๅˆ™้€ป่พ‘๏ผŒๅฏๅœจๆตไธญๆญฃ็กฎๆ•่Žทๆจกๅž‹ๆŽจ็†็ป“ๆž„๏ผŒ้ฟๅ…ๆŸๅ็š„ `` ๆๅ–ๅฝฑๅ“ๅ“ๅบ”ๆ–‡ๆœฌ่พ“ๅ‡บๆ ผๅผใ€‚ -- **Strict Format Enforcements** โ€” ๅผบๅŒ–ไบ†ๆตๆฐด็บฟๆธ…็†ๆ‰ง่กŒ้€ป่พ‘๏ผŒไฝฟๅ…ถ่ƒฝๅคŸ็ปŸไธ€ๅบ”็”จๅˆฐ translation mode ็š„็›ฎๆ ‡ๆ ผๅผไธŠใ€‚ +- **Core Routing Schemas & Leaks** โ€” Expanded `comboStrategySchema` to natively support `fill-first` and `p2c` strategies to unblock complex combo editing natively. +- **Thinking Tags Extraction (CLI)** โ€” Restructured CLI token responses sanitizer RegEx capturing model reasoning structures inside streams avoiding broken `` extractions breaking response text output format. +- **Strict Format Enforcements** โ€” Hardened pipeline sanitization execution making it universally apply to translation mode targets. --- ## [3.2.2] โ€” 2026-03-29 -### โœจ ๆ–ฐ็‰นๆ€ง +### โœจ New Features -- **Four-Stage Request Log Pipeline (#705)** โ€” ้‡ๆž„ไบ†ๆ—ฅๅฟ—ๆŒไน…ๅŒ–้€ป่พ‘๏ผŒๅฏๅœจๅ››ไธชไธๅŒๆตๆฐด็บฟ้˜ถๆฎตไฟๅญ˜ๅฎŒๆ•ด่ดŸ่ฝฝ๏ผšClient Requestใ€Translated Provider Requestใ€Provider Response ๅ’Œ Translated Client Responseใ€‚ๅŒๆ—ถๅผ•ๅ…ฅไบ† `streamPayloadCollector`๏ผŒ็”จไบŽๆ›ด็จณๅฅ็š„ SSE ๆตๆˆชๆ–ญๅ’Œ่ดŸ่ฝฝๅบๅˆ—ๅŒ–ใ€‚ +- **Four-Stage Request Log Pipeline (#705)** โ€” Refactored log persistence to save comprehensive payloads at four distinct pipeline stages: Client Request, Translated Provider Request, Provider Response, and Translated Client Response. Introduced `streamPayloadCollector` for robust SSE stream truncation and payload serialization. -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **Mobile UI Fixes (#659)** โ€” ้€š่ฟ‡ไธบ `DashboardLayout` ๆทปๅŠ ๆญฃ็กฎ็š„ๆฐดๅนณๆปšๅŠจๅ’Œๆบขๅ‡บ็บฆๆŸ๏ผŒ้ฟๅ… dashboard ไธญ็š„่กจๆ ผ็ป„ไปถๅœจ็ช„่ง†ๅฃไธ‹็ ดๅๅธƒๅฑ€ใ€‚ -- **Claude Prompt Cache Fixes (#708)** โ€” ็กฎไฟ Claude-to-Claude ๅ›ž้€€ๅพช็Žฏไธญ็š„ `cache_control` ๅ—่ขซๅฎŒๆ•ดไฟ็•™๏ผŒๅนถๅฎ‰ๅ…จๅœฐไผ ๅ›ž Anthropic ๆจกๅž‹ใ€‚ -- **Gemini Tool Definitions (#725)** โ€” ไฟฎๅค Gemini function calling ๅœจๅฃฐๆ˜Ž็ฎ€ๅ• `object` ๅ‚ๆ•ฐ็ฑปๅž‹ๆ—ถๅ‡บ็Žฐ็š„ schema ็ฟป่ฏ‘้”™่ฏฏใ€‚ +- **Mobile UI Fixes (#659)** โ€” Prevented table components on the dashboard from breaking the layout on narrow viewports by adding proper horizontal scrolling and overflow containment to `DashboardLayout`. +- **Claude Prompt Cache Fixes (#708)** โ€” Ensured `cache_control` blocks in Claude-to-Claude fallback loops are faithfully preserved and passed safely back to Anthropic models. +- **Gemini Tool Definitions (#725)** โ€” Fixed schema translation errors when declaring simple `object` parameter types for Gemini function calling. ## [3.2.1] โ€” 2026-03-29 -### โœจ ๆ–ฐ็‰นๆ€ง +### โœจ New Features -- **Global Fallback Provider (#689)** โ€” ๅฝ“ๆ‰€ๆœ‰ combo ๆจกๅž‹้ƒฝๅทฒ่€—ๅฐฝ๏ผˆ502/503๏ผ‰ๆ—ถ๏ผŒOmniRoute ็Žฐๅœจไผšๅœจ่ฟ”ๅ›ž้”™่ฏฏไน‹ๅ‰ๅฐ่ฏ•ไธ€ไธชๅฏ้…็ฝฎ็š„ๅ…จๅฑ€ๅ›ž้€€ๆจกๅž‹ใ€‚ๅฏๅœจ settings ไธญ่ฎพ็ฝฎ `globalFallbackModel` ไปฅๅฏ็”จๆญคๅŠŸ่ƒฝใ€‚ +- **Global Fallback Provider (#689)** โ€” When all combo models are exhausted (502/503), OmniRoute now attempts a configurable global fallback model before returning the error. Set `globalFallbackModel` in settings to enable. -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **Fix #721** โ€” ไฟฎๅค tool-call ๅ“ๅบ”ๆœŸ้—ด็ป•่ฟ‡ context pinning ็š„้—ฎ้ข˜ใ€‚้žๆตๅผๆ ‡่ฎฐไฝฟ็”จไบ†้”™่ฏฏ็š„ JSON ่ทฏๅพ„๏ผˆ`json.messages` โ†’ `json.choices[0].message`๏ผ‰ใ€‚ๆตๅผๆณจๅ…ฅ็Žฐๅœจไผšๅœจไป…ๅŒ…ๅซ tool-call ็š„ๆตไธญ็š„ `finish_reason` chunk ไธŠ่งฆๅ‘ใ€‚`injectModelTag()` ็ŽฐๅœจไนŸไผšไธบ้žๅญ—็ฌฆไธฒๅ†…ๅฎน่ฟฝๅŠ ๅˆๆˆ็š„ pin ๆถˆๆฏใ€‚ -- **Fix #709** โ€” ็กฎ่ฎคๅทฒๅœจ v3.1.9 ไธญไฟฎๅค๏ผš`system-info.mjs` ็Žฐๅœจไผš้€’ๅฝ’ๅˆ›ๅปบ็›ฎๅฝ•ใ€‚้—ฎ้ข˜ๅทฒๅ…ณ้—ญใ€‚ -- **Fix #707** โ€” ็กฎ่ฎคๅทฒๅœจ v3.1.9 ไธญไฟฎๅค๏ผš`chatCore.ts` ไธญ็š„็ฉบๅทฅๅ…ทๅๆธ…็†ใ€‚้—ฎ้ข˜ๅทฒๅ…ณ้—ญใ€‚ +- **Fix #721** โ€” Fixed context pinning bypass during tool-call responses. Non-streaming tagging used wrong JSON path (`json.messages` โ†’ `json.choices[0].message`). Streaming injection now triggers on `finish_reason` chunks for tool-call-only streams. `injectModelTag()` now appends synthetic pin messages for non-string content. +- **Fix #709** โ€” Confirmed already fixed (v3.1.9) โ€” `system-info.mjs` creates directories recursively. Closed. +- **Fix #707** โ€” Confirmed already fixed (v3.1.9) โ€” empty tool name sanitization in `chatCore.ts`. Closed. -### ๐Ÿงช ๆต‹่ฏ• +### ๐Ÿงช Tests -- ๆทปๅŠ ไบ† 6 ไธช unit tests๏ผŒ็”จไบŽ่ฆ†็›–ๅธฆ tool-call ๅ“ๅบ”็š„ context pinning ๅœบๆ™ฏ๏ผˆnull contentใ€array contentใ€roundtripใ€re-injection๏ผ‰ใ€‚ +- Added 6 unit tests for context pinning with tool-call responses (null content, array content, roundtrip, re-injection) ## [3.2.0] โ€” 2026-03-28 -### โœจ ๆ–ฐ็‰นๆ€ง +### โœจ New Features -- **Cache Management UI** โ€” ๅœจ `/dashboard/cache` ๆ–ฐๅขžไธ“็”จ็š„ semantic cache dashboard๏ผŒๆ”ฏๆŒๅฎšๅ‘ API ๅคฑๆ•ˆๅ’Œ 31 ็ง่ฏญ่จ€็š„ i18n๏ผˆPR #701 by @oyi77๏ผ‰ใ€‚ -- **GLM Quota Tracking** โ€” ไธบ GLM Coding๏ผˆZ.AI๏ผ‰ๆไพ›ๅ•†ๆ–ฐๅขžๅฎžๆ—ถ usage ๅ’Œ session ้…้ข่ทŸ่ธช๏ผˆPR #698 by @christopher-s๏ผ‰ใ€‚ -- **Detailed Log Payloads** โ€” ๅฐ†ๅฎŒๆ•ด็š„ๅ››้˜ถๆฎตๆตๆฐด็บฟ่ดŸ่ฝฝๆ•่Žท๏ผˆoriginalใ€translatedใ€provider-responseใ€streamed-deltas๏ผ‰็›ดๆŽฅๆŽฅๅ…ฅ UI๏ผˆPR #705 by @rdself๏ผ‰ใ€‚ +- **Cache Management UI** โ€” Added a dedicated semantic caching dashboard at \`/dashboard/cache\` with targeted API invalidation and 31-language i18n support (PR #701 by @oyi77) +- **GLM Quota Tracking** โ€” Added real-time usage and session quota tracking for the GLM Coding (Z.AI) provider (PR #698 by @christopher-s) +- **Detailed Log Payloads** โ€” Wired full four-stage pipeline payload capturing (original, translated, provider-response, streamed-deltas) directly into the UI (PR #705 by @rdself) -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **Fix #708** โ€” ๅœจ Claude-to-Claude passthrough ่ฟ‡็จ‹ไธญๆญฃ็กฎไฟ็•™ๅŽŸ็”Ÿ `cache_control` ๅคด๏ผŒ้˜ฒๆญข้€š่ฟ‡ OmniRoute ่ทฏ็”ฑ็š„ Claude Code ็”จๆˆทๅ‘็”Ÿ token ๆณ„ๆผ๏ผˆPR #708 by @tombii๏ผ‰ใ€‚ -- **Fix #719** โ€” ไธบ `ModelSyncScheduler` ๅปบ็ซ‹ๅ†…้ƒจ่ฎค่ฏ่พน็•Œ๏ผŒ้˜ฒๆญขๆœช่ฎค่ฏๅฎˆๆŠค่ฟ›็จ‹ๅœจๅฏๅŠจๆ—ถๅคฑ่ดฅ๏ผˆPR #719 by @rdself๏ผ‰ใ€‚ -- **Fix #718** โ€” ้‡ๅปบ Provider Limits UI ไธญ็š„ badge ๆธฒๆŸ“๏ผŒ้ฟๅ…้”™่ฏฏ็š„้…้ข่พน็•Œ้‡ๅ ๏ผˆPR #718 by @rdself๏ผ‰ใ€‚ -- **Fix #704** โ€” ไฟฎๅค Combo Fallbacks ๅœจ HTTP 400 content-policy ้”™่ฏฏไธ‹ๅคฑๆ•ˆใ€ๅฏผ่‡ดๆจกๅž‹่ฝฎ่ฝฌ่ทฏ็”ฑๅกๆญป็š„้—ฎ้ข˜๏ผˆPR #704 by @rdself๏ผ‰ใ€‚ +- **Fix #708** โ€” Prevented token bleeding for Claude Code users routing through OmniRoute by correctly preserving native \`cache_control\` headers during Claude-to-Claude passthrough (PR #708 by @tombii) +- **Fix #719** โ€” Setup internal auth boundaries for \`ModelSyncScheduler\` to prevent unauthenticated daemon failures on startup (PR #719 by @rdself) +- **Fix #718** โ€” Rebuilt badge rendering in Provider Limits UI preventing bad quota boundaries overlap (PR #718 by @rdself) +- **Fix #704** โ€” Fixed Combo Fallbacks breaking on HTTP 400 content-policy errors preventing model-rotation dead-routing (PR #704 by @rdself) -### ๐Ÿ”’ ๅฎ‰ๅ…จไธŽไพ่ต– +### ๐Ÿ”’ Security & Dependencies -- ๅฐ† `path-to-regexp` ๅ‡็บงๅˆฐ `8.4.0`๏ผŒไปฅไฟฎๅค dependabot ๆŠฅๅ‘Š็š„ๆผๆดž๏ผˆPR #715๏ผ‰ใ€‚ +- Bumped \`path-to-regexp\` to \`8.4.0\` resolving dependabot vulnerabilities (PR #715) ## [3.1.10] โ€” 2026-03-28 -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **Fix #706** โ€” ้€š่ฟ‡ๅฏน `.material-symbols-outlined` ๅบ”็”จ `!important`๏ผŒไฟฎๅคไบ†็”ฑ Tailwind V4 `font-sans` ่ฆ†็›–ๅฏผ่‡ด็š„ๅ›พๆ ‡ๅ›ž้€€ๆธฒๆŸ“้—ฎ้ข˜ใ€‚ -- **Fix #703** โ€” ้€š่ฟ‡ไธบไปปไฝ•ไฝฟ็”จ `apiFormat: "responses"` ็š„่‡ชๅฎšไน‰ๆจกๅž‹ๅฏ็”จ `responses` โ†’ `openai` ๆ ผๅผ็ฟป่ฏ‘๏ผŒไฟฎๅค GitHub Copilot ๆตๆŸๅ็š„้—ฎ้ข˜ใ€‚ -- **Fix #702** โ€” ็”จๅ‡†็กฎ็š„ๆ•ฐๆฎๅบ“ๅฎšไปท่ฎก็ฎ—ๆ›ฟๆข flat-rate usage ่ทŸ่ธช๏ผŒ้€‚็”จไบŽๆตๅผๅ’Œ้žๆตๅผๅ“ๅบ”ใ€‚ -- **Fix #716** โ€” ๆธ…็† Claude tool-call ็ฟป่ฏ‘็Šถๆ€๏ผŒๆญฃ็กฎ่งฃๆžๆตๅผๅ‚ๆ•ฐ๏ผŒๅนถ้˜ฒๆญข OpenAI `tool_calls` chunk ้‡ๅค `id` ๅญ—ๆฎตใ€‚ +- **Fix #706** โ€” Fixed icon fallback rendering caused by Tailwind V4 `font-sans` override by applying `!important` to `.material-symbols-outlined`. +- **Fix #703** โ€” Fixed GitHub Copilot broken streams by enabling `responses` to `openai` format translation for any custom models leveraging `apiFormat: "responses"`. +- **Fix #702** โ€” Replaced flat-rate usage tracking with accurate DB pricing calculations for both streaming and non-streaming responses. +- **Fix #716** โ€” Cleaned up Claude tool-call translation state, correctly parsing streaming arguments and preventing OpenAI `tool_calls` chunks from repeating the `id` field. ## [3.1.9] โ€” 2026-03-28 -### โœจ ๆ–ฐ็‰นๆ€ง +### โœจ New Features -- **Schema Coercion** โ€” ่‡ชๅŠจๅฐ†ๅญ—็ฌฆไธฒ็ผ–็ ็š„ๆ•ฐๅญ—ๅž‹ JSON Schema ็บฆๆŸ๏ผˆไพ‹ๅฆ‚ `"minimum": "1"`๏ผ‰ๅผบๅˆถ่ฝฌๆขไธบๆญฃ็กฎ็ฑปๅž‹๏ผŒ้˜ฒๆญข Cursorใ€Cline ็ญ‰ๅฎขๆˆท็ซฏๅ‘้€็•ธๅฝขๅทฅๅ…ท schema ๆ—ถ่งฆๅ‘ 400 ้”™่ฏฏใ€‚ -- **Tool Description Sanitization** โ€” ็กฎไฟๅทฅๅ…ทๆ่ฟฐๅง‹็ปˆไธบๅญ—็ฌฆไธฒ๏ผ›ๅœจๅ‘้€็ป™ๆไพ›ๅ•†ไน‹ๅ‰๏ผŒไผšๆŠŠ `null`ใ€`undefined` ๆˆ–ๆ•ฐๅญ—ๅž‹ๆ่ฟฐ่ฝฌๆขไธบ็ฉบๅญ—็ฌฆไธฒใ€‚ -- **Clear All Models Button** โ€” ไธบ โ€œClear All Modelsโ€ ๆไพ›ๅ•†ๆ“ไฝœ่กฅ้ฝๅ…จ้ƒจ 30 ็ง่ฏญ่จ€็š„ i18n ็ฟป่ฏ‘ใ€‚ -- **Codex Auth Export** โ€” ๆ–ฐๅขž Codex `auth.json` ๅฏผๅ‡บๅ’Œ apply-local ๆŒ‰้’ฎ๏ผŒไปฅๅฎž็Žฐๆ— ็ผ CLI ้›†ๆˆใ€‚ -- **Windsurf BYOK Notes** โ€” ๅœจ Windsurf CLI ๅทฅๅ…ทๅก็‰‡ไธญ่กฅๅ……ๅฎ˜ๆ–น้™ๅˆถ่ฏดๆ˜Ž๏ผŒ่ฎฐๅฝ• BYOK ็บฆๆŸใ€‚ +- **Schema Coercion** โ€” Auto-coerce string-encoded numeric JSON Schema constraints (e.g. `"minimum": "1"`) to proper types, preventing 400 errors from Cursor, Cline, and other clients sending malformed tool schemas. +- **Tool Description Sanitization** โ€” Ensure tool descriptions are always strings; converts `null`, `undefined`, or numeric descriptions to empty strings before sending to providers. +- **Clear All Models Button** โ€” Added i18n translations for the "Clear All Models" provider action across all 30 languages. +- **Codex Auth Export** โ€” Added Codex `auth.json` export and apply-local buttons for seamless CLI integration. +- **Windsurf BYOK Notes** โ€” Added official limitation warnings to the Windsurf CLI tool card documenting BYOK constraints. -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **Fix #709** โ€” `system-info.mjs` ๅœจ่พ“ๅ‡บ็›ฎๅฝ•ไธๅญ˜ๅœจๆ—ถไธๅ†ๅดฉๆบƒ๏ผˆๆ–ฐๅขžๅธฆ recursive ๆ ‡ๅฟ—็š„ `mkdirSync`๏ผ‰ใ€‚ -- **Fix #710** โ€” A2A `TaskManager` ๅ•ไพ‹็Žฐๅœจไฝฟ็”จ `globalThis`๏ผŒไปฅ้˜ฒๆญขๅผ€ๅ‘ๆจกๅผไธ‹ Next.js API ่ทฏ็”ฑ้‡ๆ–ฐ็ผ–่ฏ‘ๆ—ถๅ‘็”Ÿ็Šถๆ€ๆณ„ๆผใ€‚E2E ๆต‹่ฏ•ๅฅ—ไปถไนŸๅทฒๆ›ดๆ–ฐ๏ผŒๅฏไผ˜้›…ๅค„็† 401ใ€‚ -- **Fix #711** โ€” ไธบไธŠๆธธ่ฏทๆฑ‚ๆ–ฐๅขžๆไพ›ๅ•†็บงๅˆซ็š„ `max_tokens` ไธŠ้™ๅผบๅˆถ้™ๅˆถใ€‚ -- **Fix #605 / #592** โ€” ๅœจ้žๆตๅผ Claude ๅ“ๅบ”ไธญๅŽป้™คๅทฅๅ…ทๅ็งฐ็š„ `proxy_` ๅ‰็ผ€๏ผ›ๅŒๆ—ถไฟฎๅค LongCat ้ชŒ่ฏ URLใ€‚ -- **Call Logs Max Cap** โ€” ๅ‡็บง `getMaxCallLogs()`๏ผŒๅขžๅŠ ็ผ“ๅญ˜ๅฑ‚ใ€็Žฏๅขƒๅ˜้‡ๆ”ฏๆŒ๏ผˆ`CALL_LOGS_MAX`๏ผ‰ไปฅๅŠๆ•ฐๆฎๅบ“่ฎพ็ฝฎ้›†ๆˆใ€‚ +- **Fix #709** โ€” `system-info.mjs` no longer crashes when the output directory doesn't exist (added `mkdirSync` with recursive flag). +- **Fix #710** โ€” A2A `TaskManager` singleton now uses `globalThis` to prevent state leakage across Next.js API route recompilations in dev mode. E2E test suite updated to handle 401 gracefully. +- **Fix #711** โ€” Added provider-specific `max_tokens` cap enforcement for upstream requests. +- **Fix #605 / #592** โ€” Strip `proxy_` prefix from tool names in non-streaming Claude responses; fixed LongCat validation URL. +- **Call Logs Max Cap** โ€” Upgraded `getMaxCallLogs()` with caching layer, env var support (`CALL_LOGS_MAX`), and DB settings integration. -### ๐Ÿงช ๆต‹่ฏ• +### ๐Ÿงช Tests -- ๆต‹่ฏ•ๅฅ—ไปถไปŽ 964 ๆ‰ฉๅฑ•ๅˆฐ 1027 ไธชๆต‹่ฏ•๏ผˆๆ–ฐๅขž 63 ไธช๏ผ‰ใ€‚ -- ๆทปๅŠ ไบ† `schema-coercion.test.mjs` โ€”โ€” 9 ไธชๆต‹่ฏ•๏ผŒ็”จไบŽ้ชŒ่ฏๆ•ฐๅญ—ๅญ—ๆฎตๅผบๅˆถ่ฝฌๆขๅ’Œๅทฅๅ…ทๆ่ฟฐๆธ…็†ใ€‚ -- ๆทปๅŠ ไบ† `t40-opencode-cli-tools-integration.test.mjs` โ€”โ€” OpenCode/Windsurf CLI ้›†ๆˆๆต‹่ฏ•ใ€‚ -- ไฝฟ็”จๅ…จ้ข็š„่ฆ†็›–็Ž‡ๅทฅๅ…ทๅขžๅผบไบ† feature-tests ๅˆ†ๆ”ฏใ€‚ +- Test suite expanded from 964 โ†’ 1027 tests (63 new tests) +- Added `schema-coercion.test.mjs` โ€” 9 tests for numeric field coercion and tool description sanitization +- Added `t40-opencode-cli-tools-integration.test.mjs` โ€” OpenCode/Windsurf CLI integration tests +- Enhanced feature-tests branch with comprehensive coverage tooling -### ๐Ÿ“ ๆ–ฐๅขžๆ–‡ไปถ +### ๐Ÿ“ New Files -| ๆ–‡ไปถ | ็›ฎ็š„ | -| -------------------------------------------------------- | ----------------------------------------------------- | -| `open-sse/translator/helpers/schemaCoercion.ts` | Schema coercion ๅ’Œ tool description sanitization ๅทฅๅ…ท | -| `tests/unit/schema-coercion.test.mjs` | ็”จไบŽ schema coercion ็š„ๅ•ๅ…ƒๆต‹่ฏ• | -| `tests/unit/t40-opencode-cli-tools-integration.test.mjs` | CLI ๅทฅๅ…ท้›†ๆˆๆต‹่ฏ• | -| `COVERAGE_PLAN.md` | ๆต‹่ฏ•่ฆ†็›–็Ž‡่ง„ๅˆ’ๆ–‡ๆกฃ | +| File | Purpose | +| -------------------------------------------------------- | ----------------------------------------------------------- | +| `open-sse/translator/helpers/schemaCoercion.ts` | Schema coercion and tool description sanitization utilities | +| `tests/unit/schema-coercion.test.mjs` | Unit tests for schema coercion | +| `tests/unit/t40-opencode-cli-tools-integration.test.mjs` | CLI tool integration tests | +| `COVERAGE_PLAN.md` | Test coverage planning document | -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **Claude Prompt Caching Passthrough** โ€” ไฟฎๅคไบ† Claude passthrough ๆจกๅผ๏ผˆClaude โ†’ OmniRoute โ†’ Claude๏ผ‰ไธ‹ `cache_control` ๆ ‡่ฎฐ่ขซ็งป้™ค็š„้—ฎ้ข˜๏ผ›ๆญคๅ‰่ฟ™ไผšๅฏผ่‡ด Claude Code ็”จๆˆทๆฏ”็›ด่ฟžๆ›ดๅฟซๅœฐ่€—ๅฐฝ Anthropic API ้…้ข๏ผŒ้€Ÿๅบฆ้ซ˜ๅ‡บ 5-10 ๅ€ใ€‚็Žฐๅœจ๏ผŒๅฝ“ `sourceFormat` ๅ’Œ `targetFormat` ้ƒฝๆ˜ฏ Claude ๆ—ถ๏ผŒOmniRoute ไผšไฟ็•™ๅฎขๆˆท็ซฏ็š„ `cache_control` ๆ ‡่ฎฐ๏ผŒ็กฎไฟ prompt caching ๆญฃๅธธๅทฅไฝœ๏ผŒๅนถๆ˜พ่‘—้™ไฝŽ token ๆถˆ่€—ใ€‚ +- **Claude Prompt Caching Passthrough** โ€” Fixed cache_control markers being stripped in Claude passthrough mode (Claude โ†’ OmniRoute โ†’ Claude), which caused Claude Code users to deplete their Anthropic API quota 5-10x faster than direct connections. OmniRoute now preserves client's cache_control markers when sourceFormat and targetFormat are both Claude, ensuring prompt caching works correctly and dramatically reducing token consumption. ## [3.1.8] - 2026-03-27 -### ๐Ÿ› Bug ไฟฎๅคไธŽๆ–ฐ็‰นๆ€ง +### ๐Ÿ› Bug Fixes & Features -- **Platform Core:** ไธบ Hidden Models ๅ’Œ Combos ๅฎž็Žฐๅ…จๅฑ€็Šถๆ€ๅค„็†๏ผŒ้˜ฒๆญขๅฎƒไปฌๆฑกๆŸ“็›ฎๅฝ•ๆˆ–ๆณ„ๆผๅˆฐๅทฒ่ฟžๆŽฅ็š„ MCP agents ไธญ๏ผˆ#681๏ผ‰ใ€‚ -- **Stability:** ไฟฎ่กฅไบ†ไธŽๅŽŸ็”Ÿ Antigravity ๆไพ›ๅ•†้›†ๆˆ็›ธๅ…ณ็š„ๆตๅผๅดฉๆบƒ้—ฎ้ข˜๏ผŒๅ…ถๆ นๅ› ๆ˜ฏๆœชๅค„็†็š„ undefined ็Šถๆ€ๆ•ฐ็ป„๏ผˆ#684๏ผ‰ใ€‚ -- **Localization Sync:** ้ƒจ็ฝฒไบ†ๅ…จๆ–ฐ้‡ๆž„็š„ `i18n` ๅŒๆญฅๅ™จ๏ผŒๅฏๆฃ€ๆต‹็ผบๅคฑ็š„ๅตŒๅฅ— JSON ๅฑžๆ€ง๏ผŒๅนถๆŒ‰้กบๅบไธบ 30 ไธช locale ๅ›žๅกซๅ†…ๅฎน๏ผˆ#685๏ผ‰ใ€‚ +- **Platform Core:** Implemented global state handling for Hidden Models & Combos preventing them from cluttering the catalog or leaking into connected MCP agents (#681). +- **Stability:** Patched streaming crashes related to the native Antigravity provider integration failing due to unhandled undefined state arrays (#684). +- **Localization Sync:** Deployed a fully overhauled `i18n` synchronizer detecting missing nested JSON properties and retro-fitting 30 locales sequentially (#685).## [3.1.7] - 2026-03-27 -## [3.1.7] - 2026-03-27 +### ๐Ÿ› Bug Fixes -### ๐Ÿ› Bug ไฟฎๅค - -- **Streaming Stability:** ไฟฎๅคไบ† `hasValuableContent` ๅœจ SSE ๆตไธญ็š„็ฉบ chunk ไธŠ่ฟ”ๅ›ž `undefined` ็š„้—ฎ้ข˜๏ผˆ#676๏ผ‰ใ€‚ -- **Tool Calling:** ไฟฎๅค `sseParser.ts` ไธญ็š„ไธ€ไธช้—ฎ้ข˜๏ผš้žๆตๅผ Claude ๅ“ๅบ”ๅœจๅŒ…ๅซๅคšไธชๅทฅๅ…ท่ฐƒ็”จๆ—ถ๏ผŒไผšๅ› ้”™่ฏฏ็š„ๅŸบไบŽ็ดขๅผ•ๅŽป้‡่€ŒไธขๅคฑๅŽ็ปญๅทฅๅ…ท่ฐƒ็”จ็š„ `id`๏ผˆ#671๏ผ‰ใ€‚ +- **Streaming Stability:** Fixed `hasValuableContent` returning `undefined` for empty chunks in SSE streams (#676). +- **Tool Calling:** Fixed an issue in `sseParser.ts` where non-streaming Claude responses with multiple tool calls dropped the `id` of subsequent tool calls due to incorrect index-based deduplication (#671). --- ## [3.1.6] โ€” 2026-03-27 -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **Claude Native Tool Name Restoration** โ€” ๅƒ `TodoWrite` ่ฟ™ๆ ท็š„ๅทฅๅ…ทๅ็งฐๅœจ Claude passthrough ๅ“ๅบ”ไธญไธๅ†่ขซๅŠ ไธŠ `proxy_` ๅ‰็ผ€๏ผˆ้€‚็”จไบŽๆตๅผๅ’Œ้žๆตๅผ๏ผ‰ใ€‚ๅŒ…ๅซๅฏนๅบ”็š„ๅ•ๅ…ƒๆต‹่ฏ•่ฆ†็›–๏ผˆPR #663 by @coobabm๏ผ‰ใ€‚ -- **Clear All Models Alias Cleanup** โ€” โ€œClear All Modelsโ€ ๆŒ‰้’ฎ็ŽฐๅœจไนŸไผš็งป้™คๅ…ณ่”็š„ๆจกๅž‹ alias๏ผŒ้˜ฒๆญข UI ไธญๅ‡บ็Žฐๅนฝ็ตๆจกๅž‹๏ผˆPR #664 by @rdself๏ผ‰ใ€‚ +- **Claude Native Tool Name Restoration** โ€” Tool names like `TodoWrite` are no longer prefixed with `proxy_` in Claude passthrough responses (both streaming and non-streaming). Includes unit test coverage (PR #663 by @coobabm) +- **Clear All Models Alias Cleanup** โ€” "Clear All Models" button now also removes associated model aliases, preventing ghost models in the UI (PR #664 by @rdself) --- ## [3.1.5] โ€” 2026-03-27 -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **Backoff Auto-Decay** โ€” ๅฝ“ๅ†ทๅด็ช—ๅฃๅˆฐๆœŸๆ—ถ๏ผŒๅ—้€Ÿ็Ž‡้™ๅˆถ็š„่ดฆๆˆท็Žฐๅœจไผš่‡ชๅŠจๆขๅค๏ผŒไฟฎๅคไบ†้ซ˜ `backoffLevel` ไผšๆฐธไน…้™ไฝŽ่ดฆๆˆทไผ˜ๅ…ˆ็บง็š„ๆญป้”้—ฎ้ข˜๏ผˆPR #657 by @brendandebeasi๏ผ‰ใ€‚ +- **Backoff Auto-Decay** โ€” Rate-limited accounts now auto-recover when their cooldown window expires, fixing a deadlock where high `backoffLevel` permanently deprioritized accounts (PR #657 by @brendandebeasi) ### ๐ŸŒ i18n -- **Chinese translation overhaul** โ€” ๅฏน `zh-CN.json` ่ฟ›่กŒไบ†ๅ…จ้ข้‡ๅ†™๏ผŒๆ้ซ˜ไบ†็ฟป่ฏ‘ๅ‡†็กฎๆ€ง๏ผˆPR #658 by @only4copilot๏ผ‰ใ€‚ +- **Chinese translation overhaul** โ€” Comprehensive rewrite of `zh-CN.json` with improved accuracy (PR #658 by @only4copilot) --- ## [3.1.4] โ€” 2026-03-27 -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **Streaming Override Fix** โ€” ่ฏทๆฑ‚ไฝ“ไธญ็š„ๆ˜พๅผ `stream: true` ็Žฐๅœจไผ˜ๅ…ˆไบŽ `Accept: application/json` ่ฏทๆฑ‚ๅคดใ€‚ไธค่€…ๅŒๆ—ถๅ‘้€ๆ—ถ๏ผŒๅฎขๆˆท็ซฏๅฐ†ๆญฃ็กฎๆ”ถๅˆฐ SSE ๆตๅผๅ“ๅบ”๏ผˆ#656๏ผ‰ใ€‚ +- **Streaming Override Fix** โ€” Explicit `stream: true` in request body now takes priority over `Accept: application/json` header. Clients sending both will correctly receive SSE streaming responses (#656) ### ๐ŸŒ i18n -- **Czech string improvements** โ€” ็ฒพ็‚ผไบ† `cs.json` ไธญ็š„ๆœฏ่ฏญ็”จๆณ•๏ผˆPR #655 by @zen0bit๏ผ‰ใ€‚ +- **Czech string improvements** โ€” Refined terminology across `cs.json` (PR #655 by @zen0bit) --- @@ -429,20 +453,20 @@ ### ๐ŸŒ i18n & Community -- **~70 missing translation keys** โ€” ๅ‘ `en.json` ๅ’Œ 12 ็ง่ฏญ่จ€ไธญ่กฅๅ……ไบ†็บฆ 70 ไธช็ผบๅคฑ็š„็ฟป่ฏ‘้”ฎ๏ผˆPR #652 by @zen0bit๏ผ‰ใ€‚ -- **Czech documentation updated** โ€” ๆ›ดๆ–ฐไบ† CLI-TOOLSใ€API_REFERENCEใ€VM_DEPLOYMENT ๆŒ‡ๅ—็š„ๆทๅ…‹่ฏญๆ–‡ๆกฃ๏ผˆPR #652๏ผ‰ใ€‚ -- **Translation ้ชŒ่ฏ scripts** โ€” ๆ–ฐๅขž `check_translations.py` ๅ’Œ `validate_translation.py`๏ผŒ็”จไบŽ CI/QA๏ผˆPR #651 by @zen0bit๏ผ‰ใ€‚ +- **~70 missing translation keys** added to `en.json` and 12 languages (PR #652 by @zen0bit) +- **Czech documentation updated** โ€” CLI-TOOLS, API_REFERENCE, VM_DEPLOYMENT guides (PR #652) +- **Translation validation scripts** โ€” `check_translations.py` and `validate_translation.py` for CI/QA (PR #651 by @zen0bit) --- ## [3.1.2] โ€” 2026-03-26 -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **Critical: Tool Calling Regression** โ€” ้€š่ฟ‡ๅœจ Claude passthrough ่ทฏๅพ„ไธญ็ฆ็”จ `proxy_` ๅทฅๅ…ทๅๅ‰็ผ€๏ผŒไฟฎๅคไบ† `proxy_Bash` ้”™่ฏฏใ€‚ๆญคๅ‰ `Bash`ใ€`Read`ใ€`Write` ็ญ‰ๅทฅๅ…ทไผš่ขซ้‡ๅ‘ฝๅไธบ `proxy_Bash`ใ€`proxy_Read` ็ญ‰๏ผŒๅฏผ่‡ด Claude ๆ‹’็ป่ฟ™ไบ›ๅทฅๅ…ท๏ผˆ#618๏ผ‰ใ€‚ -- **Kiro Account Ban Documentation** โ€” ๅฐ†ๅ…ถ่ฎฐๅฝ•ไธบไธŠๆธธ AWS ๅๆฌบ่ฏˆ่ฏฏๅˆค๏ผŒ่€Œไธๆ˜ฏ OmniRoute ๆœฌ่บซ็š„้—ฎ้ข˜๏ผˆ#649๏ผ‰ใ€‚ +- **Critical: Tool Calling Regression** โ€” Fixed `proxy_Bash` errors by disabling the `proxy_` tool name prefix in the Claude passthrough path. Tools like `Bash`, `Read`, `Write` were being renamed to `proxy_Bash`, `proxy_Read`, etc., causing Claude to reject them (#618) +- **Kiro Account Ban Documentation** โ€” Documented as upstream AWS anti-fraud false positive, not an OmniRoute issue (#649) -### ๐Ÿงช ๆต‹่ฏ• +### ๐Ÿงช Tests - **936 tests, 0 failures** @@ -450,17 +474,17 @@ ## [3.1.1] โ€” 2026-03-26 -### โœจ ๆ–ฐ็‰นๆ€ง +### โœจ New Features -- **Vision Capability Metadata**๏ผšไธบๆ”ฏๆŒ่ง†่ง‰็š„ๆจกๅž‹๏ผŒๅœจ `/v1/models` ๆก็›ฎไธญๆ–ฐๅขž `capabilities.vision`ใ€`input_modalities` ๅ’Œ `output_modalities`๏ผˆPR #646๏ผ‰ใ€‚ -- **Gemini 3.1 Models**๏ผšไธบ Antigravity ๆไพ›ๅ•†ๆ–ฐๅขž `gemini-3.1-pro-preview` ๅ’Œ `gemini-3.1-flash-lite-preview`๏ผˆ#645๏ผ‰ใ€‚ +- **Vision Capability Metadata**: Added `capabilities.vision`, `input_modalities`, and `output_modalities` to `/v1/models` entries for vision-capable models (PR #646) +- **Gemini 3.1 Models**: Added `gemini-3.1-pro-preview` and `gemini-3.1-flash-lite-preview` to the Antigravity provider (#645) -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **Ollama Cloud 401 Error**๏ผšไฟฎๅค้”™่ฏฏ็š„ API base URL โ€”โ€” ๅทฒไปŽ `api.ollama.com` ๆ”นไธบๅฎ˜ๆ–น `ollama.com/v1/chat/completions`๏ผˆ#643๏ผ‰ใ€‚ -- **Expired Token Retry**๏ผšไธบ่ฟ‡ๆœŸ็š„ OAuth ่ฟžๆŽฅๆ–ฐๅขžๅธฆๆŒ‡ๆ•ฐ้€€้ฟ๏ผˆ5โ†’10โ†’20 ๅˆ†้’Ÿ๏ผ‰็š„ๆœ‰็•Œ้‡่ฏ•๏ผŒ่€Œไธๆ˜ฏๆฐธไน…่ทณ่ฟ‡ๅฎƒไปฌ๏ผˆPR #647๏ผ‰ใ€‚ +- **Ollama Cloud 401 Error**: Fixed incorrect API base URL โ€” changed from `api.ollama.com` to official `ollama.com/v1/chat/completions` (#643) +- **Expired Token Retry**: Added bounded retry with exponential backoff (5โ†’10โ†’20 min) for expired OAuth connections instead of permanently skipping them (PR #647) -### ๐Ÿงช ๆต‹่ฏ• +### ๐Ÿงช Tests - **936 tests, 0 failures** @@ -468,20 +492,20 @@ ## [3.1.0] โ€” 2026-03-26 -### โœจ ๆ–ฐ็‰นๆ€ง +### โœจ New Features -- **GitHub Issue Templates**๏ผšๆ–ฐๅขžๆ ‡ๅ‡†ๅŒ–็š„ bug reportใ€feature request ๅ’Œ config/proxy issue ๆจกๆฟ๏ผˆ#641๏ผ‰ใ€‚ -- **Clear All Models**๏ผšๅœจๆไพ›ๅ•†่ฏฆๆƒ…้กตๆ–ฐๅขž โ€œClear All Modelsโ€ ๆŒ‰้’ฎ๏ผŒๅนถไธบ 29 ็ง่ฏญ่จ€ๆไพ› i18n ๆ”ฏๆŒ๏ผˆ#634๏ผ‰ใ€‚ +- **GitHub Issue Templates**: Added standardized bug report, feature request, and config/proxy issue templates (#641) +- **Clear All Models**: Added a "Clear All Models" button to the provider detail page with i18n support in 29 languages (#634) -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **Locale Conflict (`in.json`)**๏ผšๅฐ†ๅฐๅœฐ่ฏญ locale ๆ–‡ไปถไปŽ `in.json`๏ผˆๅฎž้™…ๆ˜ฏๅฐๅฐผ่ฏญ ISO code๏ผ‰้‡ๅ‘ฝๅไธบ `hi.json`๏ผŒไปฅไฟฎๅค Weblate ไธญ็š„็ฟป่ฏ‘ๅ†ฒ็ช๏ผˆ#642๏ผ‰ใ€‚ -- **Codex Empty Tool Names**๏ผšๅฐ†ๅทฅๅ…ทๅๆธ…็†้€ป่พ‘ๆๅ‰ๅˆฐๅŽŸ็”Ÿ Codex passthrough ไน‹ๅ‰๏ผŒไฟฎๅคๅฝ“ๅทฅๅ…ทๅไธบ็ฉบๆ—ถไธŠๆธธๆไพ›ๅ•†่ฟ”ๅ›ž 400 ้”™่ฏฏ็š„้—ฎ้ข˜๏ผˆ#637๏ผ‰ใ€‚ -- **Streaming Newline Artifacts**๏ผšๅœจๅ“ๅบ”ๆธ…็†ๅ™จไธญๆ–ฐๅขž `collapseExcessiveNewlines`๏ผŒๆŠŠ thinking ๆจกๅž‹ไบง็”Ÿ็š„่ฟž็ปญ 3 ไธชๅŠไปฅไธŠๆข่กŒๆŠ˜ๅ ไธบๆ ‡ๅ‡†ๅŒๆข่กŒ๏ผˆ#638๏ผ‰ใ€‚ -- **Claude Reasoning Effort**๏ผšๅฐ† OpenAI ็š„ `reasoning_effort` ๅ‚ๆ•ฐ่ฝฌๆขไธบ Claude ๅŽŸ็”Ÿ็š„ `thinking` budget block๏ผŒๅนถๅœจๆ‰€ๆœ‰่ฏทๆฑ‚่ทฏๅพ„ไธญ่‡ชๅŠจ่ฐƒๆ•ด `max_tokens`๏ผˆ#627๏ผ‰ใ€‚ -- **Qwen Token Refresh**๏ผšๅฎž็Žฐไบ†่ฟ‡ๆœŸๅ‰ไธปๅŠจๅˆทๆ–ฐ OAuth token๏ผˆ5 ๅˆ†้’Ÿ็ผ“ๅ†ฒ๏ผ‰๏ผŒ้˜ฒๆญขไฝฟ็”จ็Ÿญ็”Ÿๅ‘ฝๅ‘จๆœŸ token ๆ—ถ่ฏทๆฑ‚ๅคฑ่ดฅ๏ผˆ#631๏ผ‰ใ€‚ +- **Locale Conflict (`in.json`)**: Renamed the Hindi locale file from `in.json` (Indonesian ISO code) to `hi.json` to fix translation conflicts in Weblate (#642) +- **Codex Empty Tool Names**: Moved tool name sanitization before the native Codex passthrough, fixing 400 errors from upstream providers when tools had empty names (#637) +- **Streaming Newline Artifacts**: Added `collapseExcessiveNewlines` to the response sanitizer, collapsing runs of 3+ consecutive newlines from thinking models into a standard double newline (#638) +- **Claude Reasoning Effort**: Converted OpenAI `reasoning_effort` param to Claude's native `thinking` budget block across all request paths, including automatic `max_tokens` adjustment (#627) +- **Qwen Token Refresh**: Implemented proactive pre-expiry OAuth token refreshes (5-minute buffer) to prevent requests from failing when using short-lived tokens (#631) -### ๐Ÿงช ๆต‹่ฏ• +### ๐Ÿงช Tests - **936 tests, 0 failures** (+10 tests since 3.0.9) @@ -489,452 +513,452 @@ ## [3.0.9] โ€” 2026-03-26 -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **Claude Code / ๅฎขๆˆท็ซฏๅ“ๅบ”ไธญ็š„ NaN tokens๏ผˆ#617๏ผ‰:** - - `sanitizeUsage()` ็Žฐๅœจไผšๅœจ็™ฝๅๅ•่ฟ‡ๆปคไน‹ๅ‰ไบคๅ‰ๆ˜ ๅฐ„ `input_tokens`โ†’`prompt_tokens` ๅ’Œ `output_tokens`โ†’`completion_tokens`๏ผŒไฟฎๅคๅฝ“ๆไพ›ๅ•†่ฟ”ๅ›ž Claude ้ฃŽๆ ผ usage ๅญ—ๆฎตๆ—ถ๏ผŒๅ“ๅบ”ไธญ token ่ฎกๆ•ฐๆ˜พ็คบไธบ NaN/0 ็š„้—ฎ้ข˜ใ€‚ +- **NaN tokens in Claude Code / client responses (#617):** + - `sanitizeUsage()` now cross-maps `input_tokens`โ†’`prompt_tokens` and `output_tokens`โ†’`completion_tokens` before the whitelist filter, fixing responses showing NaN/0 token counts when providers return Claude-style usage field names -### ๐Ÿ”’ ๅฎ‰ๅ…จ +### ๅฎ‰ๅ…จ -- ๆ›ดๆ–ฐ `yaml` ๅŒ…ไปฅไฟฎๅคๆ ˆๆบขๅ‡บๆผๆดž๏ผˆGHSA-48c2-rrv3-qjmp๏ผ‰ใ€‚ +- Updated `yaml` package to fix stack overflow vulnerability (GHSA-48c2-rrv3-qjmp) -### ๐Ÿ“‹ Issue ๅˆ†ๆต +### ๐Ÿ“‹ Issue Triage -- ๅ…ณ้—ญ #613๏ผˆCodestral โ€”โ€” ๅทฒ้€š่ฟ‡ Custom Provider workaround ่งฃๅ†ณ๏ผ‰ -- ๅœจ #615 ไธญๅ›žๅค๏ผˆOpenCode dual-endpoint โ€”โ€” ๅทฒๆไพ› workaround๏ผŒๅนถไฝœไธบ feature request ่ทŸ่ธช๏ผ‰ -- ๅœจ #618 ไธญๅ›žๅค๏ผˆtool call visibility โ€”โ€” ่ฏทๆฑ‚็”จๆˆทๆต‹่ฏ• v3.0.9๏ผ‰ -- ๅœจ #627 ไธญๅ›žๅค๏ผˆeffort level โ€”โ€” ๅทฒ็ปๆ”ฏๆŒ๏ผ‰ +- Closed #613 (Codestral โ€” resolved with Custom Provider workaround) +- Commented on #615 (OpenCode dual-endpoint โ€” workaround provided, tracked as feature request) +- Commented on #618 (tool call visibility โ€” requesting v3.0.9 test) +- Commented on #627 (effort level โ€” already supported) --- ## [3.0.8] โ€” 2026-03-25 -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **Claude CLI ไธญ OpenAI-format Providers ็š„็ฟป่ฏ‘ๅคฑ่ดฅ๏ผˆ#632๏ผ‰:** - - ๅค„็†ๆฅ่‡ช StepFun/OpenRouter ็š„ `reasoning_details[]` ๆ•ฐ็ป„ๆ ผๅผ๏ผŒๅนถ่ฝฌๆขไธบ `reasoning_content` - - ๅค„็†ๆŸไบ›ๆไพ›ๅ•†่ฟ”ๅ›ž็š„ `reasoning` ๅญ—ๆฎตๅˆซๅ๏ผŒๅนถ่ง„่ŒƒๅŒ–ไธบ `reasoning_content` - - ๅœจ `filterUsageForFormat` ไธญไบคๅ‰ๆ˜ ๅฐ„ usage ๅญ—ๆฎตๅ๏ผš`input_tokens`โ†”`prompt_tokens`ใ€`output_tokens`โ†”`completion_tokens` - - ไฟฎๅค `extractUsage`๏ผŒไฝฟๅ…ถๅŒๆ—ถๆŽฅๅ— `input_tokens`/`output_tokens` ๅ’Œ `prompt_tokens`/`completion_tokens` ไฝœไธบๅˆๆณ• usage ๅญ—ๆฎต - - ๅŒๆ—ถๅบ”็”จไบŽๆตๅผ่ทฏๅพ„๏ผˆ`sanitizeStreamingChunk`ใ€`openai-to-claude.ts` translator๏ผ‰ๅ’Œ้žๆตๅผ่ทฏๅพ„๏ผˆ`sanitizeMessage`๏ผ‰ +- **Translation Failures for OpenAI-format Providers in Claude CLI (#632):** + - Handle `reasoning_details[]` array format from StepFun/OpenRouter โ€” converts to `reasoning_content` + - Handle `reasoning` field alias from some providers โ†’ normalized to `reasoning_content` + - Cross-map usage field names: `input_tokens`โ†”`prompt_tokens`, `output_tokens`โ†”`completion_tokens` in `filterUsageForFormat` + - Fix `extractUsage` to accept both `input_tokens`/`output_tokens` and `prompt_tokens`/`completion_tokens` as valid usage fields + - Applied to both streaming (`sanitizeStreamingChunk`, `openai-to-claude.ts` translator) and non-streaming (`sanitizeMessage`) paths --- ## [3.0.7] โ€” 2026-03-25 -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **Antigravity Token Refresh:** ไฟฎๅคไบ† npm ๅฎ‰่ฃ…็”จๆˆท้‡ๅˆฐ็š„ `client_secret is missing` ้”™่ฏฏ๏ผ›ๆญคๅ‰ `providerRegistry` ไธญ็š„ `clientSecretDefault` ไธบ็ฉบ๏ผŒๅฏผ่‡ด Google ๆ‹’็ป token ๅˆทๆ–ฐ่ฏทๆฑ‚๏ผˆ#588๏ผ‰ใ€‚ -- **OpenCode Zen Models:** ไธบ OpenCode Zen ็š„ registry ๆก็›ฎๆ–ฐๅขž `modelsUrl`๏ผŒไฝฟ โ€œImport from /modelsโ€ ่ƒฝๆญฃ็กฎๅทฅไฝœ๏ผˆ#612๏ผ‰ใ€‚ -- **Streaming Artifacts:** ไฟฎๅคไบ†็งป้™ค thinking-tag ็ญพๅๅŽๅ“ๅบ”ไธญๆฎ‹็•™่ฟ‡ๅคšๆข่กŒ็š„้—ฎ้ข˜๏ผˆ#626๏ผ‰ใ€‚ -- **Proxy Fallback:** ๅฝ“ SOCKS5 relay ๅคฑ่ดฅๆ—ถ๏ผŒๆ–ฐๅขž่‡ชๅŠจ้‡่ฏ•ไธ”ไธ่ตฐไปฃ็†็š„ๅ›ž้€€้€ป่พ‘ใ€‚ -- **Proxy Test:** Test ็ซฏ็‚น็Žฐๅœจไผš้€š่ฟ‡ `proxyId` ไปŽๆ•ฐๆฎๅบ“ไธญ่งฃๆž็œŸๅฎžๅ‡ญ่ฏใ€‚ +- **Antigravity Token Refresh:** Fixed `client_secret is missing` error for npm-installed users โ€” the `clientSecretDefault` was empty in providerRegistry, causing Google to reject token refresh requests (#588) +- **OpenCode Zen Models:** Added `modelsUrl` to the OpenCode Zen registry entry so "Import from /models" works correctly (#612) +- **Streaming Artifacts:** Fixed excessive newlines left in responses after thinking-tag signature stripping (#626) +- **Proxy Fallback:** Added automatic retry without proxy when SOCKS5 relay fails +- **Proxy Test:** Test endpoint now resolves real credentials from DB via proxyId -### โœจ ๆ–ฐ็‰นๆ€ง +### โœจ New Features -- **Playground Account/Key Selector:** ๆ–ฐๅขžไธ€ไธชๅธธ้ฉปไธ”ๅง‹็ปˆๅฏ่ง็š„ไธ‹ๆ‹‰ๆก†๏ผŒๅฏๅœจๆต‹่ฏ•ๆ—ถ้€‰ๆ‹ฉ็‰นๅฎš็š„ๆไพ›ๅ•†่ดฆๆˆท/ๅฏ†้’ฅ๏ผ›ๅฏๅŠจๆ—ถไผšๆŠ“ๅ–ๆ‰€ๆœ‰่ฟžๆŽฅ๏ผŒๅนถๆŒ‰ๆ‰€้€‰ๆไพ›ๅ•†่ฟ‡ๆปคใ€‚ -- **CLI Tools Dynamic Models:** ๆจกๅž‹้€‰ๆ‹ฉ็ŽฐๅœจไผšๅŠจๆ€ไปŽ `/v1/models` API ่Žทๅ–๏ผ›ๅƒ Kiro ่ฟ™ๆ ท็š„ๆไพ›ๅ•†ไผšๆ˜พ็คบๅฎŒๆ•ดๆจกๅž‹็›ฎๅฝ•ใ€‚ -- **Antigravity Model List:** ๆ›ดๆ–ฐไธบๅŒ…ๅซ Claude Sonnet 4.5ใ€Claude Sonnet 4ใ€GPT 5ใ€GPT 5 Mini๏ผ›ๅนถๅฏ็”จ `passthroughModels` ไปฅๆ”ฏๆŒๅŠจๆ€ๆจกๅž‹่ฎฟ้—ฎ๏ผˆ#628๏ผ‰ใ€‚ +- **Playground Account/Key Selector:** Persistent, always-visible dropdown to select specific provider accounts/keys for testing โ€” fetches all connections at startup and filters by selected provider +- **CLI Tools Dynamic Models:** Model selection now dynamically fetches from `/v1/models` API โ€” providers like Kiro now show their full model catalog +- **Antigravity Model List:** Updated with Claude Sonnet 4.5, Claude Sonnet 4, GPT 5, GPT 5 Mini; enabled `passthroughModels` for dynamic model access (#628) -### ๐Ÿ”ง ็ปดๆŠค +### ๐Ÿ”ง Maintenance -- ๅˆๅนถ PR #625 โ€”โ€” ไฟฎๅค Provider Limits ๅœจๆต…่‰ฒๆจกๅผไธ‹็š„่ƒŒๆ™ฏ้—ฎ้ข˜ +- Merged PR #625 โ€” Provider Limits light mode background fix --- ## [3.0.6] โ€” 2026-03-25 -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **Limits/Proxy:** ไฟฎๅคไบ†ไฝไบŽ SOCKS5 ไปฃ็†ๅŽ็š„่ดฆๆˆทๆ— ๆณ•่Žทๅ– Codex ้™้ข็š„้—ฎ้ข˜๏ผ›token ๅˆทๆ–ฐ็Žฐๅœจไผšๅœจไปฃ็†ไธŠไธ‹ๆ–‡ไธญ่ฟ่กŒใ€‚ -- **CI:** ไฟฎๅคๅœจๆฒกๆœ‰ๆไพ›ๅ•†่ฟžๆŽฅ็š„ CI ็Žฏๅขƒไธญ๏ผŒ้›†ๆˆๆต‹่ฏ• `v1/models` ็š„ๆ–ญ่จ€ๅคฑ่ดฅ้—ฎ้ข˜ใ€‚ -- **Settings:** Proxy test ๆŒ‰้’ฎ็Žฐๅœจไผš็ซ‹ๅณๆ˜พ็คบๆˆๅŠŸ/ๅคฑ่ดฅ็ป“ๆžœ๏ผŒไธๅ†้š่—ๅœจๅฅๅบทๆ•ฐๆฎไน‹ๅŽใ€‚ +- **Limits/Proxy:** Fixed Codex limit fetching for accounts behind SOCKS5 proxies โ€” token refresh now runs inside proxy context +- **CI:** Fixed integration test `v1/models` assertion failure in CI environments without provider connections +- **Settings:** Proxy test button now shows success/failure results immediately (previously hidden behind health data) -### โœจ ๆ–ฐ็‰นๆ€ง +### โœจ New Features -- **Playground:** ๆ–ฐๅขž Account selector ไธ‹ๆ‹‰ๆก†๏ผ›ๅฝ“ๆŸไธชๆไพ›ๅ•†ๆœ‰ๅคšไธช่ดฆๆˆทๆ—ถ๏ผŒๅฏๅˆ†ๅˆซๆต‹่ฏ•็‰นๅฎš่ฟžๆŽฅใ€‚ +- **Playground:** Added Account selector dropdown โ€” test specific connections individually when a provider has multiple accounts -### ๐Ÿ”ง ็ปดๆŠค +### ๐Ÿ”ง Maintenance -- ๅˆๅนถ PR #623 โ€”โ€” ไฟฎๆญฃ LongCat API base URL ่ทฏๅพ„ +- Merged PR #623 โ€” LongCat API base URL path correction --- ## [3.0.5] โ€” 2026-03-25 -### โœจ ๆ–ฐ็‰นๆ€ง +### โœจ New Features -- **Limits UI:** ๅœจ connections dashboard ไธญๆ–ฐๅขžๆ ‡็ญพๅˆ†็ป„ๅŠŸ่ƒฝ๏ผŒไปฅๆ”นๅ–„ๅธฆ่‡ชๅฎšไน‰ๆ ‡็ญพ่ดฆๆˆท็š„่ง†่ง‰็ป„็ป‡ๆ–นๅผใ€‚ +- **Limits UI:** Added tag grouping feature to the connections dashboard to improve visual organization for accounts with custom tags. --- ## [3.0.4] โ€” 2026-03-25 -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **Streaming:** ไฟฎๅค combo `sanitize` TransformStream ไธญ `TextDecoder` ็Šถๆ€ๆŸๅ็š„้—ฎ้ข˜๏ผ›ๆญคๅ‰ๅฎƒไผšๅœจ้‡ๅˆฐๅคšๅญ—่Š‚ๅญ—็ฌฆๆ—ถๅฏผ่‡ด SSE ่พ“ๅ‡บไนฑ็ ๏ผˆPR #614๏ผ‰ใ€‚ -- **Providers UI:** ไฝฟ็”จ `dangerouslySetInnerHTML`๏ผŒๅฎ‰ๅ…จๅœฐๅœจๆไพ›ๅ•†่ฟžๆŽฅ้”™่ฏฏๆ็คบไธญๆธฒๆŸ“ HTML ๆ ‡็ญพใ€‚ -- **Proxy Settings:** ่กฅๅ……็ผบๅคฑ็š„ `username` ๅ’Œ `password` ่ฏทๆฑ‚ไฝ“ๅญ—ๆฎต๏ผŒไฝฟ่ฎค่ฏไปฃ็†ๅฏไปฅไปŽ Dashboard ๆญฃๅธธ้ชŒ่ฏใ€‚ -- **Provider API:** ๅฐ†่ฝฏๅผ‚ๅธธ่ฟ”ๅ›ž็ป‘ๅฎšๅˆฐ `getCodexUsage`๏ผŒ้˜ฒๆญข token ่Žทๅ–ๅคฑ่ดฅๆ—ถ API ่งฆๅ‘ HTTP 500ใ€‚ +- **Streaming:** Fixed `TextDecoder` state corruption inside combo `sanitize` TransformStream which caused SSE garbled output matching multibyte characters (PR #614) +- **Providers UI:** Safely render HTML tags inside provider connection error tooltips using `dangerouslySetInnerHTML` +- **Proxy Settings:** Added missing `username` and `password` payload body properties allowing authenticated proxies to be successfully verified from the Dashboard. +- **Provider API:** Bound soft exception returns to `getCodexUsage` preventing API HTTP 500 failures when token fetch fails --- ## [3.0.3] โ€” 2026-03-25 -### โœจ ๆ–ฐ็‰นๆ€ง +### โœจ New Features -- **Auto-Sync Models:** ๆ–ฐๅขž UI ๅผ€ๅ…ณๅ’Œ `sync-models` ็ซฏ็‚น๏ผŒๅฏ้€š่ฟ‡ๅฎšๆ—ถ่ฐƒๅบฆๅ™จๆŒ‰ๆไพ›ๅ•†่‡ชๅŠจๅŒๆญฅๆจกๅž‹ๅˆ—่กจ๏ผˆPR #597๏ผ‰ใ€‚ +- **Auto-Sync Models:** Added a UI toggle and `sync-models` endpoint to automatically synchronise model lists per provider using a scheduled interval scheduler (PR #597) -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **Timeouts:** ๅฐ†้ป˜่ฎคไปฃ็†็š„ `FETCH_TIMEOUT_MS` ๅ’Œ `STREAM_IDLE_TIMEOUT_MS` ๆๅ‡ๅˆฐ 10 ๅˆ†้’Ÿ๏ผŒไปฅไพฟๆญฃ็กฎๆ”ฏๆŒๅƒ o1 ่ฟ™ๆ ท็š„ๆทฑๅบฆๆŽจ็†ๆจกๅž‹๏ผŒ่€Œไธไผšไธญ้€”็ปˆๆญข่ฏทๆฑ‚๏ผˆFixes #609๏ผ‰ใ€‚ -- **CLI Tool Detection:** ๆ”น่ฟ›่ทจๅนณๅฐๆฃ€ๆต‹้€ป่พ‘๏ผŒๆ”ฏๆŒ NVM ่ทฏๅพ„ใ€Windows `PATHEXT`๏ผˆ้˜ฒๆญข `.cmd` ๅŒ…่ฃ…ๅ™จ้—ฎ้ข˜๏ผ‰ไปฅๅŠ่‡ชๅฎšไน‰ NPM ๅ‰็ผ€๏ผˆPR #598๏ผ‰ใ€‚ -- **Streaming Logs:** ๅœจๆตๅผๅ“ๅบ”ๆ—ฅๅฟ—ไธญๅฎž็Žฐ `tool_calls` delta ็ดฏ็งฏ๏ผŒไฝฟๅ‡ฝๆ•ฐ่ฐƒ็”จ่ƒฝๅœจๆ•ฐๆฎๅบ“ไธญ่ขซๅ‡†็กฎ่ทŸ่ธชๅ’ŒๆŒไน…ๅŒ–๏ผˆPR #603๏ผ‰ใ€‚ -- **Model Catalog:** ็งป้™ค auth exemption๏ผ›ๅฝ“ๆฒกๆœ‰ๆ˜พๅผ้…็ฝฎๆไพ›ๅ•†ๆ—ถ๏ผŒ่ƒฝๆญฃ็กฎ้š่— `comfyui` ๅ’Œ `sdwebui` ๆจกๅž‹๏ผˆPR #599๏ผ‰ใ€‚ +- **Timeouts:** Elevated default proxies `FETCH_TIMEOUT_MS` and `STREAM_IDLE_TIMEOUT_MS` to 10 minutes to properly support deep reasoning models (like o1) without aborting requests (Fixes #609) +- **CLI Tool Detection:** Improved cross-platform detection handling NVM paths, Windows `PATHEXT` (preventing `.cmd` wrappers issue), and custom NPM prefixes (PR #598) +- **Streaming Logs:** Implemented `tool_calls` delta accumulation in streaming response logs so function calls are tracked and persisted accurately in DB (PR #603) +- **Model Catalog:** Removed auth exemption, properly hiding `comfyui` and `sdwebui` models when no provider is explicitly configured (PR #599) -### ๐ŸŒ ็ฟป่ฏ‘ +### ๐ŸŒ Translations -- **cs:** ๆ”น่ฟ›ไบ†ๆ•ดไธชๅบ”็”จไธญ็š„ๆทๅ…‹่ฏญ็ฟป่ฏ‘ๅญ—็ฌฆไธฒ๏ผˆPR #601๏ผ‰ใ€‚ +- **cs:** Improved Czech translation strings across the app (PR #601) ## [3.0.2] โ€” 2026-03-25 -### ๐Ÿš€ ๅขžๅผบไธŽ็‰นๆ€ง +### ๐Ÿš€ Enhancements & Features #### feat(ui): Connection Tag Grouping -- ๅœจ `EditConnectionModal` ไธญๆ–ฐๅขž Tag/Group ๅญ—ๆฎต๏ผˆๅญ˜ๅ‚จไบŽ `providerSpecificData.tag`๏ผ‰๏ผŒไธ”ๆ— ้œ€ๆ•ฐๆฎๅบ“ schema migrationใ€‚ -- ๆไพ›ๅ•†่ง†ๅ›พไธญ็š„่ฟžๆŽฅ็ŽฐๅœจไผšๆŒ‰ๆ ‡็ญพๅŠจๆ€ๅˆ†็ป„๏ผŒๅนถๅธฆๆœ‰ๅฏ่ง†ๅŒ–ๅˆ†้š”็บฟใ€‚ -- ๆœชๆ‰“ๆ ‡็ญพ็š„่ฟžๆŽฅไผšไผ˜ๅ…ˆๆ˜พ็คบไธ”ไธๅธฆๆ ‡้ข˜๏ผŒๅ…ถๅŽๆ˜ฏๆŒ‰ๅญ—ๆฏ้กบๅบๆŽ’ๅˆ—็š„ๅทฒๆ‰“ๆ ‡็ญพๅˆ†็ป„ใ€‚ -- ่ฏฅๆ ‡็ญพๅˆ†็ป„ไผš่‡ชๅŠจๅบ”็”จๅˆฐ Codex/Copilot/Antigravity Limits ๅŒบๅŸŸ๏ผŒๅ› ไธบ็›ธๅ…ณๅผ€ๅ…ณไฝไบŽ่ฟžๆŽฅ่กŒๅ†…้ƒจใ€‚ +- Added a Tag/Group field to `EditConnectionModal` (stored in `providerSpecificData.tag`) without requiring DB schema migrations. +- Connections in the provider view now dynamically group by tag with visual dividers. +- Untagged connections appear first without a header, followed by tagged groups in alphabetical order. +- The tag grouping automatically applies to the Codex/Copilot/Antigravity Limits section since toggles exist inside connection rows. -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes #### fix(ui): Proxy Management UI Stabilization -- **่ฟžๆŽฅๅก็‰‡็ผบๅฐ‘ๅพฝ็ซ ๏ผš** ๆ”นไธบไฝฟ็”จ `resolveProxyForConnection()`๏ผŒ่€Œไธๆ˜ฏ้™ๆ€ๆ˜ ๅฐ„ใ€‚ -- **ไฟๅญ˜ๆจกๅผไธ‹ Test Connection ่ขซ็ฆ็”จ๏ผš** ้€š่ฟ‡ไปŽๅทฒไฟๅญ˜ๅˆ—่กจไธญ่งฃๆž proxy ้…็ฝฎ๏ผŒ้‡ๆ–ฐๅฏ็”จ Test ๆŒ‰้’ฎใ€‚ -- **Config Modal ๅกๆญป๏ผš** ๅœจไฟๅญ˜/ๆธ…้™คๅŽ่ฐƒ็”จ `onClose()`๏ผŒ้˜ฒๆญข UI ๅกๆญปใ€‚ -- **ไฝฟ็”จ้‡้‡ๅค็ปŸ่ฎก๏ผš** `ProxyRegistryManager` ็ŽฐๅœจไผšๅœจๆŒ‚่ฝฝๆ—ถไธปๅŠจๅŠ ่ฝฝ usage๏ผŒๅนถๆŒ‰ `scope` + `scopeId` ๅŽป้‡ใ€‚ๅŽŸๆฅ็š„ usage ่ฎกๆ•ฐๅทฒๆ›ฟๆขไธบไธ€ไธชๅ†…่”ๆ˜พ็คบ IP/ๅปถ่ฟŸ็š„ Test ๆŒ‰้’ฎใ€‚ +- **Missing badges on connection cards:** Fixed by using `resolveProxyForConnection()` rather than static mapping. +- **Test Connection disabled in saved mode:** Enabled the Test button by resolving proxy config from the saved list. +- **Config Modal freezing:** Added `onClose()` calls after save/clear to prevent the UI from freezing. +- **Double usage counting:** `ProxyRegistryManager` now loads usage eagerly on mount with deduplication by `scope` + `scopeId`. Usage counts were replaced with a Test button displaying IP/latency inline. #### fix(translator): `function_call` prefix stripping -- ไฟฎๅคไบ† PR #607 ไธญไธ€ไธชไธๅฎŒๆ•ด็š„้—ฎ้ข˜๏ผšๆญคๅ‰ๅชๆœ‰ `tool_use` ๅ—ไผš็งป้™ค Claude ็š„ `proxy_` ๅทฅๅ…ทๅ‰็ผ€ใ€‚็Žฐๅœจ๏ผŒไฝฟ็”จ OpenAI Responses API ๆ ผๅผ็š„ๅฎขๆˆท็ซฏไนŸ่ƒฝๆญฃ็กฎๆ”ถๅˆฐไธๅธฆ `proxy_` ๅ‰็ผ€็š„ๅทฅๅ…ทๅ็งฐใ€‚ +- Repaired an incomplete fix from PR #607 where only `tool_use` blocks stripped Claude's `proxy_` tool prefix. Now, clients using the OpenAI Responses API format will also correctly receive tool tools without the `proxy_` prefix. --- ## [3.0.1] โ€” 2026-03-25 -### ๐Ÿ”ง ็ƒญไฟฎๅค่กฅไธ โ€” ๅ…ณ้”ฎ Bug ไฟฎๅค +### ๐Ÿ”ง Hotfix Patch โ€” Critical Bug Fixes -v3.0.0 ๅ‘ๅธƒๅŽ๏ผŒ็”จๆˆทๆŠฅๅ‘Š็š„ 3 ไธชๅ…ณ้”ฎๅ›žๅฝ’้—ฎ้ข˜็Žฐๅทฒๅ…จ้ƒจไฟฎๅคใ€‚ +Three critical regressions reported by users after the v3.0.0 launch have been resolved. -#### fix(translator): ๅœจ้žๆตๅผ Claude ๅ“ๅบ”ไธญๅŽป้™ค `proxy_` ๅ‰็ผ€๏ผˆ#605๏ผ‰ +#### fix(translator): strip `proxy_` prefix in non-streaming Claude responses (#605) -Claude OAuth ๆทปๅŠ ็š„ `proxy_` ๅ‰็ผ€ๆญคๅ‰ๅชไผšๅœจ**ๆตๅผ**ๅ“ๅบ”ไธญ่ขซๅŽป้™คใ€‚ๅœจ**้žๆตๅผ**ๆจกๅผไธ‹๏ผŒ`translateNonStreamingResponse` ๆ— ๆณ•่ฎฟ้—ฎ `toolNameMap`๏ผŒๅฏผ่‡ดๅฎขๆˆท็ซฏๆ”ถๅˆฐ่ขซ็ ดๅ็š„ๅทฅๅ…ทๅ๏ผŒไพ‹ๅฆ‚ `proxy_read_file`๏ผŒ่€Œไธๆ˜ฏ `read_file`ใ€‚ +The `proxy_` prefix added by Claude OAuth was only stripped from **streaming** responses. In **non-streaming** mode, `translateNonStreamingResponse` had no access to the `toolNameMap`, causing clients to receive mangled tool names like `proxy_read_file` instead of `read_file`. -**ไฟฎๅคๆ–นๅผ๏ผš** ไธบ `translateNonStreamingResponse` ๆ–ฐๅขžๅฏ้€‰็š„ `toolNameMap` ๅ‚ๆ•ฐ๏ผŒๅนถๅœจ Claude `tool_use` ๅ—ๅค„็†ๅ™จไธญๅบ”็”จๅ‰็ผ€ๅŽป้™ค้€ป่พ‘ใ€‚`chatCore.ts` ็ŽฐๅœจไนŸไผšๆŠŠ่ฏฅๆ˜ ๅฐ„็ปง็ปญไผ ้€’ไธ‹ๅŽปใ€‚ +**Fix:** Added optional `toolNameMap` parameter to `translateNonStreamingResponse` and applied prefix stripping in the Claude `tool_use` block handler. `chatCore.ts` now passes the map through. -#### fix(validation): ไธบ LongCat ๆทปๅŠ ไธ“็”จ้ชŒ่ฏๅ™จไปฅ่ทณ่ฟ‡ `/models` ๆŽขๆต‹๏ผˆ#592๏ผ‰ +#### fix(validation): add LongCat specialty validator to skip /models probe (#592) -LongCat AI ไธๆไพ› `GET /v1/models`ใ€‚้€š็”จ็š„ `validateOpenAICompatibleProvider` ้ชŒ่ฏๅ™จๅชๆœ‰ๅœจ่ฎพ็ฝฎไบ† `validationModelId` ๆ—ถๆ‰ไผšๅ›ž้€€ๅˆฐ chat-completions๏ผŒ่€Œ LongCat ๅนถๆœช้…็ฝฎ่ฏฅๅญ—ๆฎตใ€‚่ฟ™ไผšๅฏผ่‡ดๅœจๆ–ฐๅขž/ไฟๅญ˜ๆ—ถ๏ผŒๆไพ›ๅ•†้ชŒ่ฏไปฅ่ฏฏๅฏผๆ€ง็š„้”™่ฏฏไฟกๆฏๅคฑ่ดฅใ€‚ +LongCat AI does not expose `GET /v1/models`. The generic `validateOpenAICompatibleProvider` validator fell through to a chat-completions fallback only if `validationModelId` was set, which LongCat doesn't configure. This caused provider validation to fail with a misleading error on add/save. -**ไฟฎๅคๆ–นๅผ๏ผš** ๅœจไธ“็”จ้ชŒ่ฏๅ™จๆ˜ ๅฐ„ไธญๆ–ฐๅขž `longcat`๏ผŒ็›ดๆŽฅๆŽขๆต‹ `/chat/completions`๏ผŒๅนถๅฐ†ไปปไฝ•้ž่ฎค่ฏ้”™่ฏฏ็š„ๅ“ๅบ”่ง†ไธบ้€š่ฟ‡ใ€‚ +**Fix:** Added `longcat` to the specialty validators map, probing `/chat/completions` directly and treating any non-auth response as a pass. -#### fix(translator): ไธบ Anthropic ่ง„่ŒƒๅŒ– object ๅทฅๅ…ท schema๏ผˆ#595๏ผ‰ +#### fix(translator): normalize object tool schemas for Anthropic (#595) -MCP ๅทฅๅ…ท๏ผˆไพ‹ๅฆ‚ `pencil`ใ€`computer_use`๏ผ‰่ฝฌๅ‘็š„ๅทฅๅ…ทๅฎšไน‰ไธญไผšๅ‡บ็Žฐ `{type:"object"}`๏ผŒไฝ†ๆฒกๆœ‰ `properties` ๅญ—ๆฎตใ€‚Anthropic API ไผšๅ› ๆญคๆ‹’็ป่ฏทๆฑ‚๏ผŒๅนถๆŠฅ้”™๏ผš`object schema missing properties`ใ€‚ +MCP tools (e.g. `pencil`, `computer_use`) forward tool definitions with `{type:"object"}` but without a `properties` field. Anthropic's API rejects these with: `object schema missing properties`. -**ไฟฎๅคๆ–นๅผ๏ผš** ๅœจ `openai-to-claude.ts` ไธญ๏ผŒๅฝ“ `type` ไธบ `"object"` ไธ”็ผบๅฐ‘ `properties` ๆ—ถ๏ผŒๆณจๅ…ฅๅฎ‰ๅ…จ้ป˜่ฎคๅ€ผ `properties: {}`ใ€‚ +**Fix:** In `openai-to-claude.ts`, inject `properties: {}` as a safe default when `type` is `"object"` and `properties` is absent. --- -### ๐Ÿ”€ ๅทฒๅˆๅนถ็š„็คพๅŒบ PR๏ผˆ2๏ผ‰ +### ๐Ÿ”€ Community PRs Merged (2) -| PR | ไฝœ่€… | ๆ‘˜่ฆ | -| -------- | ------- | ---------------------------------------------------------- | -| **#589** | @flobo3 | docs(i18n): ไฟฎๅค Playground ๅ’Œ Testbed ็š„ไฟ„่ฏญ็ฟป่ฏ‘ | -| **#591** | @rdself | fix(ui): ๆ”นๅ–„ Provider Limits ๆต…่‰ฒๆจกๅผๅฏนๆฏ”ๅบฆๅ’Œ่ฎกๅˆ’ๅฑ‚็บงๆ˜พ็คบ | +| PR | Author | Summary | +| -------- | ------- | -------------------------------------------------------------------------- | +| **#589** | @flobo3 | docs(i18n): fix Russian translation for Playground and Testbed | +| **#591** | @rdself | fix(ui): improve Provider Limits light mode contrast and plan tier display | --- -### โœ… ๅทฒ่งฃๅ†ณ้—ฎ้ข˜ +### โœ… Issues Resolved `#592` `#595` `#605` --- -### ๐Ÿงช ๆต‹่ฏ• +### ๐Ÿงช Tests -- **926 ไธชๆต‹่ฏ•๏ผŒ0 ๅคฑ่ดฅ**๏ผˆไธŽ v3.0.0 ๆŒๅนณ๏ผ‰ +- **926 tests, 0 failures** (unchanged from v3.0.0) --- ## [3.0.0] โ€” 2026-03-24 -### ๐ŸŽ‰ OmniRoute v3.0.0 โ€” ๅ…่ดน AI ็ฝ‘ๅ…ณ๏ผŒ็Žฐๅทฒๆ”ฏๆŒ 67+ ไธชๆไพ›ๅ•† +### ๐ŸŽ‰ OmniRoute v3.0.0 โ€” The Free AI Gateway, Now with 67+ Providers -> **ๅฒไธŠๆœ€ๅคง็‰ˆๆœฌใ€‚** ไปŽ v2.9.5 ็š„ 36 ไธชๆไพ›ๅ•†ๆ‰ฉๅฑ•ๅˆฐ v3.0.0 ็š„ **67+ ไธชๆไพ›ๅ•†**๏ผŒๅนถๅธฆๆฅ MCP Serverใ€A2A Protocolใ€auto-combo engineใ€Provider Iconsใ€Registered Keys APIใ€926 ไธชๆต‹่ฏ•๏ผŒไปฅๅŠๆฅ่‡ช **12 ไฝ็คพๅŒบๆˆๅ‘˜** ็š„ **10 ไธชๅทฒๅˆๅนถ PR** ่ดก็Œฎใ€‚ +> **The biggest release ever.** From 36 providers in v2.9.5 to **67+ providers** in v3.0.0 โ€” with MCP Server, A2A Protocol, auto-combo engine, Provider Icons, Registered Keys API, 926 tests, and contributions from **12 community members** across **10 merged PRs**. > -> ๆ•ดๅˆ่‡ช v3.0.0-rc.1 ๅˆฐ rc.17๏ผˆ3 ๅคฉ้ซ˜ๅผบๅบฆๅผ€ๅ‘ไธญ็š„ 17 ไธชๅ‘ๅธƒๅ€™้€‰็‰ˆๆœฌ๏ผ‰ใ€‚ +> Consolidated from v3.0.0-rc.1 through rc.17 (17 release candidates over 3 days of intense development). --- -### ๐Ÿ†• ๆ–ฐๆไพ›ๅ•†๏ผˆ่พƒ v2.9.5 ๅขžๅŠ  31 ไธช๏ผ‰ +### ๐Ÿ†• New Providers (+31 since v2.9.5) -| ๆไพ›ๅ•† | ๅˆซๅ | ๅฑ‚็บง | ่ฏดๆ˜Ž | -| ----------------------------- | --------------- | ------ | ------------------------------------------------------------------------- | -| **OpenCode Zen** | `opencode-zen` | ๅ…่ดน | ้€š่ฟ‡ `opencode.ai/zen/v1` ๆไพ› 3 ไธชๆจกๅž‹๏ผˆPR #530 by @kang-heewon๏ผ‰ | -| **OpenCode Go** | `opencode-go` | ไป˜่ดน | ้€š่ฟ‡ `opencode.ai/zen/go/v1` ๆไพ› 4 ไธชๆจกๅž‹๏ผˆPR #530 by @kang-heewon๏ผ‰ | -| **LongCat AI** | `lc` | ๅ…่ดน | ๅ…ฌๆต‹ๆœŸ้—ดๆฏๅคฉ 5000 ไธ‡ tokens๏ผˆFlash-Lite๏ผ‰+ 50 ไธ‡/ๅคฉ๏ผˆChat/Thinking๏ผ‰ | -| **Pollinations AI** | `pol` | ๅ…่ดน | ๆ— ้œ€ API key โ€”โ€” GPT-5ใ€Claudeใ€Geminiใ€DeepSeek V3ใ€Llama 4๏ผˆ1 ๆฌก/15 ็ง’๏ผ‰ | -| **Cloudflare Workers AI** | `cf` | ๅ…่ดน | ๆฏๅคฉ 10K Neurons โ€”โ€” ็บฆ 150 ๆฌก LLM ๅ“ๅบ”ๆˆ– 500 ็ง’ Whisper ้Ÿณ้ข‘๏ผŒ่พน็ผ˜ๆŽจ็† | -| **Scaleway AI** | `scw` | ๅ…่ดน | ๆ–ฐ่ดฆๆˆทๆไพ› 100 ไธ‡ๅ…่ดน tokens โ€”โ€” ็ฌฆๅˆ EU/GDPR๏ผˆๅทด้ปŽ๏ผ‰ | -| **AI/ML API** | `aiml` | ๅ…่ดน | ๆฏๅคฉ $0.025 ๅ…่ดน้ขๅบฆ โ€”โ€” ้€š่ฟ‡ๅ•ไธ€็ซฏ็‚น่ฎฟ้—ฎ 200+ ไธชๆจกๅž‹ | -| **Puter AI** | `pu` | ๅ…่ดน | 500+ ไธชๆจกๅž‹๏ผˆGPT-5ใ€Claude Opus 4ใ€Gemini 3 Proใ€Grok 4ใ€DeepSeek V3๏ผ‰ | -| **Alibaba Cloud (DashScope)** | `ali` | ไป˜่ดน | ้€š่ฟ‡ `alicode`/`alicode-intl` ๆไพ›ๅ›ฝ้™…ไธŽไธญๅ›ฝ็ซฏ็‚น | -| **Alibaba Coding Plan** | `bcp` | ไป˜่ดน | Alibaba Model Studio๏ผŒๆไพ› Anthropic-compatible API | -| **Kimi Coding (API Key)** | `kmca` | ไป˜่ดน | ๅŸบไบŽ API key ็š„็‹ฌ็ซ‹ Kimi ๆŽฅๅ…ฅ๏ผˆไธŽ OAuth ๅˆ†็ฆป๏ผ‰ | -| **MiniMax Coding** | `minimax` | ไป˜่ดน | ๅ›ฝ้™…็ซฏ็‚น | -| **MiniMax (China)** | `minimax-cn` | ไป˜่ดน | ไธญๅ›ฝๅŒบ็ซฏ็‚น | -| **Z.AI (GLM-5)** | `zai` | ไป˜่ดน | ๆ™บ่ฐฑ AI ๆ–ฐไธ€ไปฃ GLM ๆจกๅž‹ | -| **Vertex AI** | `vertex` | ไป˜่ดน | Google Cloud โ€”โ€” Service Account JSON ๆˆ– OAuth access_token | -| **Ollama Cloud** | `ollamacloud` | ไป˜่ดน | Ollama ๆ‰˜็ฎก API ๆœๅŠก | -| **Synthetic** | `synthetic` | ไป˜่ดน | Passthrough ๆจกๅž‹็ฝ‘ๅ…ณ | -| **Kilo Gateway** | `kg` | ไป˜่ดน | Passthrough ๆจกๅž‹็ฝ‘ๅ…ณ | -| **Perplexity Search** | `pplx-search` | ไป˜่ดน | ไธ“็”จๆœ็ดขๅขžๅผบ็ซฏ็‚น | -| **Serper Search** | `serper-search` | ไป˜่ดน | Web search API ้›†ๆˆ | -| **Brave Search** | `brave-search` | ไป˜่ดน | Brave Search API ้›†ๆˆ | -| **Exa Search** | `exa-search` | ไป˜่ดน | Neural search API ้›†ๆˆ | -| **Tavily Search** | `tavily-search` | ไป˜่ดน | AI search API ้›†ๆˆ | -| **NanoBanana** | `nb` | ไป˜่ดน | ๅ›พๅƒ็”Ÿๆˆ API | -| **ElevenLabs** | `el` | ไป˜่ดน | ๆ–‡ๆœฌ่ฝฌ่ฏญ้Ÿณ่ฏญ้Ÿณๅˆๆˆ | -| **Cartesia** | `cartesia` | ไป˜่ดน | ่ถ…้ซ˜้€Ÿ TTS ่ฏญ้Ÿณๅˆๆˆ | -| **PlayHT** | `playht` | ไป˜่ดน | ่ฏญ้Ÿณๅ…‹้š†ไธŽ TTS | -| **Inworld** | `inworld` | ไป˜่ดน | AI ่ง’่‰ฒ่ฏญ้Ÿณ่Šๅคฉ | -| **SD WebUI** | `sdwebui` | ่‡ชๆ‰˜็ฎก | Stable Diffusion ๆœฌๅœฐๅ›พๅƒ็”Ÿๆˆ | -| **ComfyUI** | `comfyui` | ่‡ชๆ‰˜็ฎก | ComfyUI ๆœฌๅœฐๅทฅไฝœๆต่Š‚็‚นๅผ็”Ÿๆˆ | -| **GLM Coding** | `glm` | ไป˜่ดน | BigModel/Zhipu ไธ“็”จ็ผ–็ ็ซฏ็‚น | +| Provider | Alias | Tier | Notes | +| ----------------------------- | --------------- | ----------- | --------------------------------------------------------------------------- | +| **OpenCode Zen** | `opencode-zen` | Free | 3 models via `opencode.ai/zen/v1` (PR #530 by @kang-heewon) | +| **OpenCode Go** | `opencode-go` | Paid | 4 models via `opencode.ai/zen/go/v1` (PR #530 by @kang-heewon) | +| **LongCat AI** | `lc` | Free | 50M tokens/day (Flash-Lite) + 500K/day (Chat/Thinking) during public beta | +| **Pollinations AI** | `pol` | Free | No API key needed โ€” GPT-5, Claude, Gemini, DeepSeek V3, Llama 4 (1 req/15s) | +| **Cloudflare Workers AI** | `cf` | Free | 10K Neurons/day โ€” ~150 LLM responses or 500s Whisper audio, edge inference | +| **Scaleway AI** | `scw` | Free | 1M free tokens for new accounts โ€” EU/GDPR compliant (Paris) | +| **AI/ML API** | `aiml` | Free | $0.025/day free credits โ€” 200+ models via single endpoint | +| **Puter AI** | `pu` | Free | 500+ models (GPT-5, Claude Opus 4, Gemini 3 Pro, Grok 4, DeepSeek V3) | +| **Alibaba Cloud (DashScope)** | `ali` | Paid | International + China endpoints via `alicode`/`alicode-intl` | +| **Alibaba Coding Plan** | `bcp` | Paid | Alibaba Model Studio with Anthropic-compatible API | +| **Kimi Coding (API Key)** | `kmca` | Paid | Dedicated API-key-based Kimi access (separate from OAuth) | +| **MiniMax Coding** | `minimax` | Paid | International endpoint | +| **MiniMax (China)** | `minimax-cn` | Paid | China-specific endpoint | +| **Z.AI (GLM-5)** | `zai` | Paid | Zhipu AI next-gen GLM models | +| **Vertex AI** | `vertex` | Paid | Google Cloud โ€” Service Account JSON or OAuth access_token | +| **Ollama Cloud** | `ollamacloud` | Paid | Ollama's hosted API service | +| **Synthetic** | `synthetic` | Paid | Passthrough models gateway | +| **Kilo Gateway** | `kg` | Paid | Passthrough models gateway | +| **Perplexity Search** | `pplx-search` | Paid | Dedicated search-grounded endpoint | +| **Serper Search** | `serper-search` | Paid | Web search API integration | +| **Brave Search** | `brave-search` | Paid | Brave Search API integration | +| **Exa Search** | `exa-search` | Paid | Neural search API integration | +| **Tavily Search** | `tavily-search` | Paid | AI search API integration | +| **NanoBanana** | `nb` | Paid | Image generation API | +| **ElevenLabs** | `el` | Paid | Text-to-speech voice synthesis | +| **Cartesia** | `cartesia` | Paid | Ultra-fast TTS voice synthesis | +| **PlayHT** | `playht` | Paid | Voice cloning and TTS | +| **Inworld** | `inworld` | Paid | AI character voice chat | +| **SD WebUI** | `sdwebui` | Self-hosted | Stable Diffusion local image generation | +| **ComfyUI** | `comfyui` | Self-hosted | ComfyUI local workflow node-based generation | +| **GLM Coding** | `glm` | Paid | BigModel/Zhipu coding-specific endpoint | -**ๆ€ป่ฎก๏ผš67+ ไธชๆไพ›ๅ•†**๏ผˆ4 ไธชๅ…่ดนใ€8 ไธช OAuthใ€55 ไธช API Key๏ผ‰+ ๆ— ้™ๆ•ฐ้‡็š„ OpenAI/Anthropic-Compatible ่‡ชๅฎšไน‰ๆไพ›ๅ•†ใ€‚ +**Total: 67+ providers** (4 Free, 8 OAuth, 55 API Key) + unlimited OpenAI/Anthropic-Compatible custom providers. --- -### โœจ ไธป่ฆๅŠŸ่ƒฝ +### โœจ Major Features #### ๐Ÿ”‘ Registered Keys Provisioning API (#464) -ๅฏ้€š่ฟ‡็ผ–็จ‹ๆ–นๅผ่‡ชๅŠจ็”Ÿๆˆๅนถ็ญพๅ‘ OmniRoute API key๏ผŒๆ”ฏๆŒๆŒ‰ๆไพ›ๅ•†ๅ’Œ่ดฆๆˆท่ฟ›่กŒ้…้ข้™ๅˆถใ€‚ +Auto-generate and issue OmniRoute API keys programmatically with per-provider and per-account quota enforcement. -| ็ซฏ็‚น | ๆ–นๆณ• | ่ฏดๆ˜Ž | -| ------------------------------- | ------------ | ------------------------------------- | -| `/api/v1/registered-keys` | `POST` | ็ญพๅ‘ๆ–ฐ key โ€”โ€” ๅŽŸๅง‹ key **ๅช่ฟ”ๅ›žไธ€ๆฌก** | -| `/api/v1/registered-keys` | `GET` | ๅˆ—ๅ‡บๅทฒๆณจๅ†Œ key๏ผˆ่„ฑๆ•๏ผ‰ | -| `/api/v1/registered-keys/{id}` | `GET/DELETE` | ่Žทๅ–ๅ…ƒๆ•ฐๆฎ / ๅŠ้”€ | -| `/api/v1/quotas/check` | `GET` | ็ญพๅ‘ๅ‰้ข„ๆฃ€้…้ข | -| `/api/v1/providers/{id}/limits` | `GET/PUT` | ้…็ฝฎๆŒ‰ๆไพ›ๅ•†็š„็ญพๅ‘้™ๅˆถ | -| `/api/v1/accounts/{id}/limits` | `GET/PUT` | ้…็ฝฎๆŒ‰่ดฆๆˆท็š„็ญพๅ‘้™ๅˆถ | -| `/api/v1/issues/report` | `POST` | ๅ‘ GitHub Issues ๆŠฅๅ‘Š้…้ขไบ‹ไปถ | +| Endpoint | Method | Description | +| ------------------------------- | ------------ | ------------------------------------------------ | +| `/api/v1/registered-keys` | `POST` | Issue a new key โ€” raw key returned **once only** | +| `/api/v1/registered-keys` | `GET` | List registered keys (masked) | +| `/api/v1/registered-keys/{id}` | `GET/DELETE` | Get metadata / Revoke | +| `/api/v1/quotas/check` | `GET` | Pre-validate quota before issuing | +| `/api/v1/providers/{id}/limits` | `GET/PUT` | Configure per-provider issuance limits | +| `/api/v1/accounts/{id}/limits` | `GET/PUT` | Configure per-account issuance limits | +| `/api/v1/issues/report` | `POST` | Report quota events to GitHub Issues | -**ๅฎ‰ๅ…จๆ€ง๏ผš** key ไปฅ SHA-256 ๅ“ˆๅธŒๅญ˜ๅ‚จใ€‚ๅŽŸๅง‹ key ๅชๅœจๅˆ›ๅปบๆ—ถๅฑ•็คบไธ€ๆฌก๏ผŒไน‹ๅŽไธๅฏๅ†ๅ–ๅ›žใ€‚ +**Security:** Keys stored as SHA-256 hashes. Raw key shown once on creation, never retrievable again. #### ๐ŸŽจ Provider Icons via @lobehub/icons (#529) -130+ ไธชๆไพ›ๅ•† Logo ็Žฐไฝฟ็”จ `@lobehub/icons` React ็ป„ไปถ๏ผˆSVG๏ผ‰ใ€‚ๅ›ž้€€้“พไธบ๏ผš**Lobehub SVG โ†’ ็Žฐๆœ‰ PNG โ†’ ้€š็”จๅ›พๆ ‡**ใ€‚ๅทฒ็ปŸไธ€ๅบ”็”จๅˆฐ Dashboardใ€Providers ๅ’Œ Agents ้กต้ข๏ผŒไฝฟ็”จๆ ‡ๅ‡†ๅŒ–็š„ `ProviderIcon` ็ป„ไปถใ€‚ +130+ provider logos using `@lobehub/icons` React components (SVG). Fallback chain: **Lobehub SVG โ†’ existing PNG โ†’ generic icon**. Applied across Dashboard, Providers, and Agents pages with standardized `ProviderIcon` component. #### ๐Ÿ”„ Model Auto-Sync Scheduler (#488) -ๆฏ **24 ๅฐๆ—ถ**่‡ชๅŠจๅˆทๆ–ฐๅทฒ่ฟžๆŽฅๆไพ›ๅ•†็š„ๆจกๅž‹ๅˆ—่กจใ€‚ไผšๅœจๆœๅŠกๅ™จๅฏๅŠจๆ—ถ่ฟ่กŒ๏ผŒๅนถๅฏ้€š่ฟ‡ `MODEL_SYNC_INTERVAL_HOURS` ้…็ฝฎใ€‚ +Auto-refreshes model lists for connected providers every **24 hours**. Runs on server startup. Configurable via `MODEL_SYNC_INTERVAL_HOURS`. #### ๐Ÿ”€ Per-Model Combo Routing (#563) -ๅฏๅฐ†ๆจกๅž‹ๅ็งฐๆจกๅผ๏ผˆglob๏ผ‰ๆ˜ ๅฐ„ๅˆฐ็‰นๅฎš combo๏ผŒๅฎž็Žฐ่‡ชๅŠจ่ทฏ็”ฑ๏ผš +Map model name patterns (glob) to specific combos for automatic routing: -- `claude-sonnet*` โ†’ code-combo๏ผŒ`gpt-4o*` โ†’ openai-combo๏ผŒ`gemini-*` โ†’ google-combo -- ๆ–ฐๅขž `model_combo_mappings` ่กจ๏ผŒๆ”ฏๆŒ glob ่ฝฌ regex ๅŒน้… -- Dashboard UI ๆ–ฐๅขž โ€œModel Routing Rulesโ€ ๅŒบๅŸŸ๏ผŒๆ”ฏๆŒๅ†…่”ๆ–ฐๅขž/็ผ–่พ‘/ๅผ€ๅ…ณ/ๅˆ ้™ค +- `claude-sonnet*` โ†’ code-combo, `gpt-4o*` โ†’ openai-combo, `gemini-*` โ†’ google-combo +- New `model_combo_mappings` table with glob-to-regex matching +- Dashboard UI section: "Model Routing Rules" with inline add/edit/toggle/delete #### ๐Ÿงญ API Endpoints Dashboard -ไบคไบ’ๅผ็›ฎๅฝ•ใ€webhooks ็ฎก็†ไธŽ OpenAPI ๆŸฅ็œ‹ๅ™จ๏ผŒๅ…จ้ƒจ้›†ไธญๅœจ `/dashboard/endpoint` ็š„ๅ•ไธ€ๆ ‡็ญพ้กต้กต้ขไธญใ€‚ +Interactive catalog, webhooks management, OpenAPI viewer โ€” all in one tabbed page at `/dashboard/endpoint`. #### ๐Ÿ” Web Search Providers -ๆ–ฐๅขž 5 ไธชๆœ็ดขๆไพ›ๅ•†้›†ๆˆ๏ผš**Perplexity Search**ใ€**Serper**ใ€**Brave Search**ใ€**Exa**ใ€**Tavily**๏ผŒ่ฎฉ AI ๅ“ๅบ”ๅฏ็ป“ๅˆๅฎžๆ—ถ Web ๆ•ฐๆฎ่ฟ›่กŒ grounded ๅ›ž็ญ”ใ€‚ +5 new search provider integrations: **Perplexity Search**, **Serper**, **Brave Search**, **Exa**, **Tavily** โ€” enabling grounded AI responses with real-time web data. #### ๐Ÿ“Š Search Analytics -`/dashboard/analytics` ไธญๆ–ฐๅขžๆ ‡็ญพ้กต๏ผŒๅฑ•็คบๆไพ›ๅ•†ๆ‹†ๅˆ†ใ€็ผ“ๅญ˜ๅ‘ฝไธญ็Ž‡ๅ’Œๆˆๆœฌ่ทŸ่ธชใ€‚API๏ผš`GET /api/v1/search/analytics`ใ€‚ +New tab in `/dashboard/analytics` โ€” provider breakdown, cache hit rate, cost tracking. API: `GET /api/v1/search/analytics`. #### ๐Ÿ›ก๏ธ Per-API-Key Rate Limits (#452) -ๆ–ฐๅขž `max_requests_per_day` ๅ’Œ `max_requests_per_minute` ๅญ—ๆฎต๏ผŒๅนถ้€š่ฟ‡ๅ†…ๅญ˜ๆป‘ๅŠจ็ช—ๅฃๅผบๅˆถ้™ๅˆถ๏ผŒ่ฟ”ๅ›ž HTTP 429ใ€‚ +`max_requests_per_day` and `max_requests_per_minute` columns with in-memory sliding-window enforcement returning HTTP 429. #### ๐ŸŽต Media Playground -`/dashboard/media` ๆไพ›ๅฎŒๆ•ด็š„ๅคšๅช’ไฝ“็”Ÿๆˆ playground๏ผšๅ›พๅƒ็”Ÿๆˆใ€่ง†้ข‘ใ€้Ÿณไนใ€้Ÿณ้ข‘่ฝฌๅฝ•๏ผˆ2GB ไธŠไผ ้™ๅˆถ๏ผ‰ๅ’Œๆ–‡ๆœฌ่ฝฌ่ฏญ้Ÿณใ€‚ +Full media generation playground at `/dashboard/media`: Image Generation, Video, Music, Audio Transcription (2GB upload limit), and Text-to-Speech. --- -### ๐Ÿ”’ ๅฎ‰ๅ…จไธŽ CI/CD +### ๐Ÿ”’ Security & CI/CD -- **CodeQL remediation** โ€”โ€” ไฟฎๅค 10+ ไธช่ญฆๆŠฅ๏ผš6 ไธช polynomial-redosใ€1 ไธช insecure-randomness๏ผˆ`Math.random()` โ†’ `crypto.randomUUID()`๏ผ‰ใ€1 ไธช shell-command-injection -- **Route validation** โ€”โ€” ไธบ **176/176 ไธช API ่ทฏ็”ฑ**ๅŠ ๅ…ฅ Zod schema + `validateBody()`๏ผŒๅนถ็”ฑ CI ๅผบๅˆถๆ‰ง่กŒ -- **CVE fix** โ€”โ€” ้€š่ฟ‡ npm overrides ไฟฎๅค dompurify XSS ๆผๆดž๏ผˆGHSA-v2wj-7wpq-c8vv๏ผ‰ -- **Flatted** โ€”โ€” ไปŽ 3.3.3 ๅ‡็บงๅˆฐ 3.4.2๏ผˆCWE-1321 prototype pollution๏ผ‰ -- **Docker** โ€”โ€” ๅฐ† `docker/setup-buildx-action` ไปŽ v3 ๅ‡็บงๅˆฐ v4 +- **CodeQL remediation** โ€” Fixed 10+ alerts: 6 polynomial-redos, 1 insecure-randomness (`Math.random()` โ†’ `crypto.randomUUID()`), 1 shell-command-injection +- **Route validation** โ€” Zod schemas + `validateBody()` on **176/176 API routes** โ€” CI enforced +- **CVE fix** โ€” dompurify XSS vulnerability (GHSA-v2wj-7wpq-c8vv) resolved via npm overrides +- **Flatted** โ€” Bumped 3.3.3 โ†’ 3.4.2 (CWE-1321 prototype pollution) +- **Docker** โ€” Upgraded `docker/setup-buildx-action` v3 โ†’ v4 --- -### ๐Ÿ› Bug ไฟฎๅค๏ผˆ40+๏ผ‰ +### ๐Ÿ› Bug Fixes (40+) -#### OAuth ไธŽ่ฎค่ฏ +#### OAuth & Auth -- **#537** โ€”โ€” ๅœจ Docker ไธญ็ผบๅฐ‘ `GEMINI_OAUTH_CLIENT_SECRET` ๆ—ถ๏ผŒGemini CLI OAuth ็Žฐๅœจไผš็ป™ๅ‡บๆธ…ๆ™ฐไธ”ๅฏๆ“ไฝœ็š„้”™่ฏฏๆ็คบ -- **#549** โ€”โ€” CLI ่ฎพ็ฝฎ่ทฏ็”ฑ็ŽฐๅœจไผšไปŽ `keyId` ่งฃๆž็œŸๅฎž API key๏ผˆ่€Œไธๆ˜ฏ่„ฑๆ•ๅญ—็ฌฆไธฒ๏ผ‰ -- **#574** โ€”โ€” ่ทณ่ฟ‡ๅ‘ๅฏผๅฏ†็ ่ฎพ็ฝฎๅŽ๏ผŒ็™ปๅฝ•ไธๅ†ๅกๆญป -- **#506** โ€”โ€” ้‡ๅ†™่ทจๅนณๅฐ `machineId` ้€ป่พ‘๏ผˆWindows REG.exe โ†’ macOS ioreg โ†’ Linux โ†’ hostname ๅ›ž้€€๏ผ‰ +- **#537** โ€” Gemini CLI OAuth: clear actionable error when `GEMINI_OAUTH_CLIENT_SECRET` missing in Docker +- **#549** โ€” CLI settings routes now resolve real API key from `keyId` (not masked strings) +- **#574** โ€” Login no longer freezes after skipping wizard password setup +- **#506** โ€” Cross-platform `machineId` rewritten (Windows REG.exe โ†’ macOS ioreg โ†’ Linux โ†’ hostname fallback) -#### ๆไพ›ๅ•†ไธŽ่ทฏ็”ฑ +#### Providers & Routing -- **#536** โ€”โ€” ไฟฎๅค LongCat AI ็š„ `baseUrl` ๅ’Œ `authHeader` -- **#535** โ€”โ€” ไฟฎๅคๅ›บๅฎšๆจกๅž‹่ฆ†็›–๏ผš`body.model` ็Žฐๅœจไผšๆญฃ็กฎ่ฎพ็ฝฎไธบ `pinnedModel` -- **#570** โ€”โ€” ๆœชๅธฆๅ‰็ผ€็š„ Claude ๆจกๅž‹็Žฐๅœจไผšๆญฃ็กฎ่งฃๆžๅˆฐ Anthropic ๆไพ›ๅ•† -- **#585** โ€”โ€” `` ๅ†…้ƒจๆ ‡็ญพไธๅ†ๆณ„้œฒๅˆฐ SSE ๆตๅผๅฎขๆˆท็ซฏ -- **#493** โ€”โ€” ่‡ชๅฎšไน‰ๆไพ›ๅ•†ๆจกๅž‹ๅ‘ฝๅไธๅ†่ขซๅ‰็ผ€ๅ‰ฅ็ฆป็ ดๅ -- **#490** โ€”โ€” ้€š่ฟ‡ `TransformStream` ๆณจๅ…ฅๅฎž็Žฐๆตๅผ + context cache protection -- **#511** โ€”โ€” `` ๆ ‡็ญพ็Žฐๅœจไผšๆณจๅ…ฅๅˆฐ้ฆ–ไธชๅ†…ๅฎน chunk ไธญ๏ผˆ่€Œไธๆ˜ฏ `[DONE]` ไน‹ๅŽ๏ผ‰ +- **#536** โ€” LongCat AI: fixed `baseUrl` and `authHeader` +- **#535** โ€” Pinned model override: `body.model` correctly set to `pinnedModel` +- **#570** โ€” Unprefixed Claude models now resolve to Anthropic provider +- **#585** โ€” `` internal tags no longer leak to clients in SSE streaming +- **#493** โ€” Custom provider model naming no longer mangled by prefix stripping +- **#490** โ€” Streaming + context cache protection via `TransformStream` injection +- **#511** โ€” `` tag injected into first content chunk (not after `[DONE]`) -#### CLI ไธŽๅทฅๅ…ท +#### CLI & Tools -- **#527** โ€”โ€” Claude Code + Codex ๅพช็Žฏ้—ฎ้ข˜๏ผš`tool_result` ๅ—็Žฐๅœจไผš่ขซ่ฝฌๆขไธบๆ–‡ๆœฌ -- **#524** โ€”โ€” OpenCode ้…็ฝฎๅฏๆญฃ็กฎไฟๅญ˜๏ผˆXDG_CONFIG_HOMEใ€TOML ๆ ผๅผ๏ผ‰ -- **#522** โ€”โ€” API Manager ็งป้™คๅ…ทๆœ‰่ฏฏๅฏผๆ€ง็š„ โ€œCopy masked keyโ€ ๆŒ‰้’ฎ -- **#546** โ€”โ€” ไฟฎๅค Windows ไธŠ `--version` ่ฟ”ๅ›ž `unknown` ็š„้—ฎ้ข˜๏ผˆPR by @k0valik๏ผ‰ -- **#544** โ€”โ€” ้€š่ฟ‡ๅทฒ็Ÿฅๅฎ‰่ฃ…่ทฏๅพ„ๅฎž็Žฐๅฎ‰ๅ…จ็š„ CLI ๅทฅๅ…ทๆฃ€ๆต‹๏ผˆPR by @k0valik๏ผ‰ -- **#510** โ€”โ€” Windows MSYS2/Git-Bash ่ทฏๅพ„็Žฐๅœจไผš่‡ชๅŠจ่ง„่ŒƒๅŒ– -- **#492** โ€”โ€” ๅฝ“ `app/server.js` ็ผบๅคฑๆ—ถ๏ผŒCLI ๅฏๆฃ€ๆต‹็”ฑ `mise`/`nvm` ็ฎก็†็š„ Node +- **#527** โ€” Claude Code + Codex loop: `tool_result` blocks now converted to text +- **#524** โ€” OpenCode config saved correctly (XDG_CONFIG_HOME, TOML format) +- **#522** โ€” API Manager: removed misleading "Copy masked key" button +- **#546** โ€” `--version` returning `unknown` on Windows (PR by @k0valik) +- **#544** โ€” Secure CLI tool detection via known installation paths (PR by @k0valik) +- **#510** โ€” Windows MSYS2/Git-Bash paths normalized automatically +- **#492** โ€” CLI detects `mise`/`nvm`-managed Node when `app/server.js` missing -#### Streaming ไธŽ SSE +#### Streaming & SSE -- **PR #587** โ€”โ€” ๅ›žๆปš responsesTransformer ไธญๅฏน `resolveDataDir` ็š„ๅฏผๅ…ฅ๏ผŒไปฅๅ…ผๅฎน Cloudflare Workers๏ผˆ@k0valik๏ผ‰ -- **PR #495** โ€”โ€” ไฟฎๅค Bottleneck 429 ๆ— ้™็ญ‰ๅพ…๏ผšๅœจ้™ๆตๆ—ถไธขๅผƒ็ญ‰ๅพ…ไธญ็š„ไปปๅŠก๏ผˆ@xandr0s๏ผ‰ -- **#483** โ€”โ€” ๅœจ `[DONE]` ไฟกๅทๅŽๅœๆญข้™„ๅŠ  `data: null` -- **#473** โ€”โ€” Zombie SSE ๆต่ถ…ๆ—ถไปŽ 300 ็ง’้™ๅˆฐ 120 ็ง’๏ผŒไปฅๅฎž็Žฐๆ›ดๅฟซๅ›ž้€€ +- **PR #587** โ€” Revert `resolveDataDir` import in responsesTransformer for Cloudflare Workers compat (@k0valik) +- **PR #495** โ€” Bottleneck 429 infinite wait: drop waiting jobs on rate limit (@xandr0s) +- **#483** โ€” Stop trailing `data: null` after `[DONE]` signal +- **#473** โ€” Zombie SSE streams: timeout reduced 300s โ†’ 120s for faster fallback -#### ๅช’ไฝ“ไธŽ่ฝฌๅฝ• +#### Media & Transcription -- **Transcription** โ€”โ€” Deepgram `video/mp4` โ†’ `audio/mp4` MIME ๆ˜ ๅฐ„๏ผŒ่‡ชๅŠจ่ฏญ่จ€ๆฃ€ๆต‹ๅ’Œๆ ‡็‚น -- **TTS** โ€”โ€” ไฟฎๅค ElevenLabs ้ฃŽๆ ผๅตŒๅฅ—้”™่ฏฏไธญ็š„ `[object Object]` ๆ˜พ็คบ้—ฎ้ข˜ -- **Upload limits** โ€”โ€” ๅช’ไฝ“่ฝฌๅฝ•ไธŠ้™ๆๅ‡ๅˆฐ 2GB๏ผˆnginx `client_max_body_size 2g` + `maxDuration=300`๏ผ‰ +- **Transcription** โ€” Deepgram `video/mp4` โ†’ `audio/mp4` MIME mapping, auto language detection, punctuation +- **TTS** โ€” `[object Object]` error display fixed for ElevenLabs-style nested errors +- **Upload limits** โ€” Media transcription increased to 2GB (nginx `client_max_body_size 2g` + `maxDuration=300`) --- -### ๐Ÿ”ง ๅŸบ็ก€่ฎพๆ–ฝไธŽๆ”น่ฟ› +### ๐Ÿ”ง Infrastructure & Improvements -#### Sub2api Gap Analysis๏ผˆT01โ€“T15 + T23โ€“T42๏ผ‰ +#### Sub2api Gap Analysis (T01โ€“T15 + T23โ€“T42) -- **T01** โ€”โ€” ๅœจ call logs ไธญๆ–ฐๅขž `requested_model` ๅˆ—๏ผˆmigration 009๏ผ‰ -- **T02** โ€”โ€” ไปŽๅตŒๅฅ—็š„ `tool_result.content` ไธญๅ‰ฅ็ฆป็ฉบๆ–‡ๆœฌๅ— -- **T03** โ€”โ€” ่งฃๆž `x-codex-5h-*` / `x-codex-7d-*` ้…้ขๅคด -- **T04** โ€”โ€” ไธบๅค–้ƒจ็ฒ˜ๆ€ง่ทฏ็”ฑๅขžๅŠ  `X-Session-Id` ่ฏทๆฑ‚ๅคด -- **T05** โ€”โ€” ้€š่ฟ‡ไธ“็”จ API ๆŒไน…ๅŒ– rate-limit ๆ•ฐๆฎ -- **T06** โ€”โ€” ่ดฆๆˆทๅœ็”จ โ†’ ๆฐธไน…ๅฐ้”๏ผˆ1 ๅนดๅ†ทๅด๏ผ‰ -- **T07** โ€”โ€” `X-Forwarded-For` IP ๆ ก้ชŒ๏ผˆ`extractClientIp()`๏ผ‰ -- **T08** โ€”โ€” ๅŸบไบŽๆป‘ๅŠจ็ช—ๅฃ็š„ Per-API-key ไผš่ฏ้™ๅˆถ -- **T09** โ€”โ€” Codex ไธŽ Spark ็š„้™ๆต่Œƒๅ›ดๅˆ†็ฆป๏ผˆ็‹ฌ็ซ‹ๆฑ ๏ผ‰ -- **T10** โ€”โ€” ็งฏๅˆ†่€—ๅฐฝ โ†’ ็‹ฌ็ซ‹็š„ 1 ๅฐๆ—ถๅ†ทๅดๅ›ž้€€ -- **T11** โ€”โ€” `max` reasoning effort โ†’ 131072 budget tokens -- **T12** โ€”โ€” ๆ–ฐๅขž MiniMax M2.7 ๅฎšไปทๆก็›ฎ -- **T13** โ€”โ€” ไฟฎๅค่ฟ‡ๆœŸ้…้ขๆ˜พ็คบ๏ผˆๆ„Ÿ็Ÿฅ้‡็ฝฎ็ช—ๅฃ๏ผ‰ -- **T14** โ€”โ€” ไปฃ็†ๅฟซ้€Ÿๅคฑ่ดฅ TCP ๆฃ€ๆŸฅ๏ผˆโ‰ค2 ็ง’๏ผŒ็ผ“ๅญ˜ 30 ็ง’๏ผ‰ -- **T15** โ€”โ€” ไธบ Anthropic ่ง„่ŒƒๅŒ–ๆ•ฐ็ป„ๅ†…ๅฎน -- **T23** โ€”โ€” ๆ™บ่ƒฝ้…้ข้‡็ฝฎๅ›ž้€€๏ผˆไปŽ header ๆๅ–๏ผ‰ -- **T24** โ€”โ€” `503` ๅ†ทๅด + `406` ๆ˜ ๅฐ„ -- **T25** โ€”โ€” Provider ้ชŒ่ฏๅ›ž้€€ -- **T29** โ€”โ€” Vertex AI Service Account JWT ่ฎค่ฏ -- **T33** โ€”โ€” Thinking level ๅˆฐ budget ็š„่ฝฌๆข -- **T36** โ€”โ€” `403` ไธŽ `429` ้”™่ฏฏๅˆ†็ฑป -- **T38** โ€”โ€” ้›†ไธญๅŒ–ๆจกๅž‹่ง„ๆ ผๅฎšไน‰๏ผˆ`modelSpecs.ts`๏ผ‰ -- **T39** โ€”โ€” `fetchAvailableModels` ็š„็ซฏ็‚นๅ›ž้€€ -- **T41** โ€”โ€” ๅŽๅฐไปปๅŠก่‡ชๅŠจ้‡ๅฎšๅ‘ๅˆฐ flash ๆจกๅž‹ -- **T42** โ€”โ€” ๅ›พๅƒ็”Ÿๆˆ้•ฟๅฎฝๆฏ”ๆ˜ ๅฐ„ +- **T01** โ€” `requested_model` column in call logs (migration 009) +- **T02** โ€” Strip empty text blocks from nested `tool_result.content` +- **T03** โ€” Parse `x-codex-5h-*` / `x-codex-7d-*` quota headers +- **T04** โ€” `X-Session-Id` header for external sticky routing +- **T05** โ€” Rate-limit DB persistence with dedicated API +- **T06** โ€” Account deactivated โ†’ permanent block (1-year cooldown) +- **T07** โ€” X-Forwarded-For IP validation (`extractClientIp()`) +- **T08** โ€” Per-API-key session limits with sliding-window enforcement +- **T09** โ€” Codex vs Spark rate-limit scopes (separate pools) +- **T10** โ€” Credits exhausted โ†’ distinct 1h cooldown fallback +- **T11** โ€” `max` reasoning effort โ†’ 131072 budget tokens +- **T12** โ€” MiniMax M2.7 pricing entries +- **T13** โ€” Stale quota display fix (reset window awareness) +- **T14** โ€” Proxy fast-fail TCP check (โ‰ค2s, cached 30s) +- **T15** โ€” Array content normalization for Anthropic +- **T23** โ€” Intelligent quota reset fallback (header extraction) +- **T24** โ€” `503` cooldown + `406` mapping +- **T25** โ€” Provider validation fallback +- **T29** โ€” Vertex AI Service Account JWT auth +- **T33** โ€” Thinking level to budget conversion +- **T36** โ€” `403` vs `429` error classification +- **T38** โ€” Centralized model specifications (`modelSpecs.ts`) +- **T39** โ€” Endpoint fallback for `fetchAvailableModels` +- **T41** โ€” Background task auto-redirect to flash models +- **T42** โ€” Image generation aspect ratio mapping -#### ๅ…ถไป–ๆ”น่ฟ› +#### Other Improvements -- **Per-model upstream custom headers** โ€”โ€” ้€š่ฟ‡้…็ฝฎ UI ่ฎพ็ฝฎ๏ผˆPR #575 by @zhangqiang8vip๏ผ‰ -- **Model context length** โ€”โ€” ๅฏๅœจๆจกๅž‹ๅ…ƒๆ•ฐๆฎไธญ้…็ฝฎ๏ผˆPR #578 by @hijak๏ผ‰ -- **Model prefix stripping** โ€”โ€” ๅฏ้€‰็งป้™คๆจกๅž‹ๅ็งฐไธญ็š„ๆไพ›ๅ•†ๅ‰็ผ€๏ผˆPR #582 by @jay77721๏ผ‰ -- **Gemini CLI deprecation** โ€”โ€” ๅ›  Google OAuth ้™ๅˆถ่ญฆๅ‘Š่€Œๆ ‡่ฎฐไธบ deprecated -- **YAML parser** โ€”โ€” ็”จ `js-yaml` ๆ›ฟๆข่‡ชๅฎšไน‰่งฃๆžๅ™จ๏ผŒไปฅๆญฃ็กฎ่งฃๆž OpenAPI spec -- **ZWS v5** โ€”โ€” HMR ๆณ„ๆผไฟฎๅค๏ผˆๆ•ฐๆฎๅบ“่ฟžๆŽฅ 485 โ†’ 1๏ผŒๅ†…ๅญ˜ 2.4GB โ†’ 195MB๏ผ‰ -- **Log export** โ€”โ€” Dashboard ๆ–ฐๅขžๅธฆๆ—ถ้—ด่Œƒๅ›ดไธ‹ๆ‹‰ๆก†็š„ JSON ๅฏผๅ‡บๆŒ‰้’ฎ -- **Update notification banner** โ€”โ€” Dashboard ้ฆ–้กต็Žฐๅœจไผšๆ˜พ็คบๆ–ฐ็‰ˆๆœฌๅฏ็”จๆ้†’ +- **Per-model upstream custom headers** โ€” via configuration UI (PR #575 by @zhangqiang8vip) +- **Model context length** โ€” configurable in model metadata (PR #578 by @hijak) +- **Model prefix stripping** โ€” option to remove provider prefix from model names (PR #582 by @jay77721) +- **Gemini CLI deprecation** โ€” marked deprecated with Google OAuth restriction warning +- **YAML parser** โ€” replaced custom parser with `js-yaml` for correct OpenAPI spec parsing +- **ZWS v5** โ€” HMR leak fix (485 DB connections โ†’ 1, memory 2.4GB โ†’ 195MB) +- **Log export** โ€” New JSON export button on dashboard with time range dropdown +- **Update notification banner** โ€” dashboard homepage shows when new versions are available --- -### ๐ŸŒ i18n ไธŽๆ–‡ๆกฃ +### ๐ŸŒ i18n & Documentation -- **30 ็ง่ฏญ่จ€** ่พพๅˆฐ 100% ๅŒๆญฅ โ€”โ€” ๅทฒ่กฅ้ฝ 2,788 ไธช็ผบๅคฑ้”ฎ -- **Czech** โ€”โ€” ๅฎŒๆ•ด็ฟป่ฏ‘๏ผš22 ไปฝๆ–‡ๆกฃ๏ผŒ2,606 ๆก UI ๅญ—็ฌฆไธฒ๏ผˆPR by @zen0bit๏ผ‰ -- **Chinese (zh-CN)** โ€”โ€” ๅฎŒๆ•ด้‡่ฏ‘๏ผˆPR by @only4copilot๏ผ‰ -- **VM Deployment Guide** โ€”โ€” ๅทฒ็ฟป่ฏ‘ไธบ่‹ฑๆ–‡ๆบๆ–‡ๆกฃ -- **API Reference** โ€”โ€” ๆ–ฐๅขž `/v1/embeddings` ๅ’Œ `/v1/audio/speech` ็ซฏ็‚น -- **Provider count** โ€”โ€” ๅฐ† README ๅ’Œๅ…จ้ƒจ 30 ไปฝ i18n README ไธญ็š„ๆไพ›ๅ•†ๆ•ฐ้‡ไปŽ 36+/40+/44+ ๆ›ดๆ–ฐไธบ **67+** +- **30 languages** at 100% parity โ€” 2,788 missing keys synced +- **Czech** โ€” Full translation: 22 docs, 2,606 UI strings (PR by @zen0bit) +- **Chinese (zh-CN)** โ€” Complete retranslation (PR by @only4copilot) +- **VM Deployment Guide** โ€” Translated to English as source document +- **API Reference** โ€” Added `/v1/embeddings` and `/v1/audio/speech` endpoints +- **Provider count** โ€” Updated from 36+/40+/44+ to **67+** across README and all 30 i18n READMEs --- -### ๐Ÿ”€ ๅทฒๅˆๅนถ็š„็คพๅŒบ PR๏ผˆ10๏ผ‰ +### ๐Ÿ”€ Community PRs Merged (10) -| PR | ไฝœ่€… | ๆ‘˜่ฆ | -| -------- | --------------- | ------------------------------------------------------------- | -| **#587** | @k0valik | fix(sse): ๅ›žๆปš `resolveDataDir` ๅฏผๅ…ฅไปฅๅ…ผๅฎน Cloudflare Workers | -| **#582** | @jay77721 | feat(proxy): ๆจกๅž‹ๅๅ‰็ผ€ๅ‰ฅ็ฆป้€‰้กน | -| **#581** | @jay77721 | fix(npm): ๅฐ† electron-release ๆŽฅๅ…ฅ npm-publish ๅทฅไฝœๆต | -| **#578** | @hijak | feat: ๅฏ้…็ฝฎ็š„ๆจกๅž‹ไธŠไธ‹ๆ–‡้•ฟๅบฆๅ…ƒๆ•ฐๆฎ | -| **#575** | @zhangqiang8vip | feat: ๆŒ‰ๆจกๅž‹่ฎพ็ฝฎไธŠๆธธ่ฏทๆฑ‚ๅคดใ€compat PATCHใ€chat ๅฏน้ฝ | -| **#562** | @coobabm | fix: MCP ไผš่ฏ็ฎก็†ใ€Claude passthroughใ€detectFormat | -| **#561** | @zen0bit | fix(i18n): ๆทๅ…‹่ฏญ็ฟป่ฏ‘ไฟฎๆญฃ | -| **#555** | @k0valik | fix(sse): ้›†ไธญๅŒ– `resolveDataDir()` ็”จไบŽ่ทฏๅพ„่งฃๆž | -| **#546** | @k0valik | fix(cli): Windows ไธŠ `--version` ่ฟ”ๅ›ž `unknown` | -| **#544** | @k0valik | fix(cli): ๅŸบไบŽๅฎ‰่ฃ…่ทฏๅพ„็š„ๅฎ‰ๅ…จ CLI ๅทฅๅ…ทๆฃ€ๆต‹ | -| **#542** | @rdself | fix(ui): ๆต…่‰ฒๆจกๅผๅฏนๆฏ”ๅบฆ CSS ไธป้ข˜ๅ˜้‡ | -| **#530** | @kang-heewon | feat: ไฝฟ็”จ `OpencodeExecutor` ็š„ OpenCode Zen + Go ๆไพ›ๅ•† | -| **#512** | @zhangqiang8vip | feat: ๆŒ‰ๅ่ฎฎๅฎšไน‰ๆจกๅž‹ๅ…ผๅฎนๆ€ง๏ผˆ`compatByProtocol`๏ผ‰ | -| **#497** | @zhangqiang8vip | fix: ๅผ€ๅ‘ๆจกๅผ HMR ่ต„ๆบๆณ„ๆผ๏ผˆZWS v5๏ผ‰ | -| **#495** | @xandr0s | fix: Bottleneck 429 ๆ— ้™็ญ‰ๅพ…๏ผˆไธขๅผƒ็ญ‰ๅพ…ไธญ็š„ไปปๅŠก๏ผ‰ | -| **#494** | @zhangqiang8vip | feat: MiniMax developerโ†’system ่ง’่‰ฒไฟฎๅค | -| **#480** | @prakersh | fix: ๆตๅผ flush usage ๆๅ– | -| **#479** | @prakersh | feat: Codex 5.3/5.4 ๅ’Œ Anthropic ๅฎšไปทๆก็›ฎ | -| **#475** | @only4copilot | feat(i18n): ๆ”น่ฟ›ไธญๆ–‡็ฟป่ฏ‘ | +| PR | Author | Summary | +| -------- | --------------- | -------------------------------------------------------------------- | +| **#587** | @k0valik | fix(sse): revert resolveDataDir import for Cloudflare Workers compat | +| **#582** | @jay77721 | feat(proxy): model name prefix stripping option | +| **#581** | @jay77721 | fix(npm): link electron-release to npm-publish workflow | +| **#578** | @hijak | feat: configurable context length in model metadata | +| **#575** | @zhangqiang8vip | feat: per-model upstream headers, compat PATCH, chat alignment | +| **#562** | @coobabm | fix: MCP session management, Claude passthrough, detectFormat | +| **#561** | @zen0bit | fix(i18n): Czech translation corrections | +| **#555** | @k0valik | fix(sse): centralized `resolveDataDir()` for path resolution | +| **#546** | @k0valik | fix(cli): `--version` returning `unknown` on Windows | +| **#544** | @k0valik | fix(cli): secure CLI tool detection via installation paths | +| **#542** | @rdself | fix(ui): light mode contrast CSS theme variables | +| **#530** | @kang-heewon | feat: OpenCode Zen + Go providers with `OpencodeExecutor` | +| **#512** | @zhangqiang8vip | feat: per-protocol model compatibility (`compatByProtocol`) | +| **#497** | @zhangqiang8vip | fix: dev-mode HMR resource leaks (ZWS v5) | +| **#495** | @xandr0s | fix: Bottleneck 429 infinite wait (drop waiting jobs) | +| **#494** | @zhangqiang8vip | feat: MiniMax developerโ†’system role fix | +| **#480** | @prakersh | fix: stream flush usage extraction | +| **#479** | @prakersh | feat: Codex 5.3/5.4 and Anthropic pricing entries | +| **#475** | @only4copilot | feat(i18n): improved Chinese translation | -**ๆ„Ÿ่ฐขๆ‰€ๆœ‰่ดก็Œฎ่€…๏ผ** +**Thank you to all contributors!** ๐Ÿ™ --- -### ๐Ÿ“‹ ๅทฒ่งฃๅ†ณ้—ฎ้ข˜๏ผˆ50+๏ผ‰ +### ๐Ÿ“‹ Issues Resolved (50+) `#452` `#458` `#462` `#464` `#466` `#473` `#474` `#481` `#483` `#487` `#488` `#489` `#490` `#491` `#492` `#493` `#506` `#508` `#509` `#510` `#511` `#513` `#520` `#521` `#522` `#524` `#525` `#527` `#529` `#531` `#532` `#535` `#536` `#537` `#541` `#546` `#549` `#563` `#570` `#574` `#585` --- -### ๐Ÿงช ๆต‹่ฏ• +### ๐Ÿงช Tests -- **926 ไธชๆต‹่ฏ•๏ผŒ0 ๅคฑ่ดฅ**๏ผˆ็›ธๆฏ” v2.9.5 ็š„ 821 ไธชๆœ‰ๆ‰€ๅขžๅŠ ๏ผ‰ -- ๆ–ฐๅขž 105 ไธชๆต‹่ฏ•๏ผŒ่ฆ†็›– model-combo mappingsใ€registered keysใ€OpencodeExecutorใ€Bailian ๆไพ›ๅ•†ใ€route validationใ€error classificationใ€aspect ratio mapping ็ญ‰ๅ†…ๅฎน +- **926 tests, 0 failures** (up from 821 in v2.9.5) +- +105 new tests covering: model-combo mappings, registered keys, OpencodeExecutor, Bailian provider, route validation, error classification, aspect ratio mapping, and more --- -### ๐Ÿ“ฆ ๆ•ฐๆฎๅบ“่ฟ็งป +### ๐Ÿ“ฆ Database Migrations -| ่ฟ็งป็ผ–ๅท | ่ฏดๆ˜Ž | -| -------- | ----------------------------------------------------------------- | -| **008** | `registered_keys`ใ€`provider_key_limits`ใ€`account_key_limits` ่กจ | -| **009** | `call_logs` ไธญๆ–ฐๅขž `requested_model` ๅˆ— | -| **010** | ็”จไบŽๆŒ‰ๆจกๅž‹ combo ่ทฏ็”ฑ็š„ `model_combo_mappings` ่กจ | +| Migration | Description | +| --------- | --------------------------------------------------------------------- | +| **008** | `registered_keys`, `provider_key_limits`, `account_key_limits` tables | +| **009** | `requested_model` column in `call_logs` | +| **010** | `model_combo_mappings` table for per-model combo routing | --- -### โฌ†๏ธ ไปŽ v2.9.5 ๅ‡็บง +### โฌ†๏ธ Upgrading from v2.9.5 ```bash # npm @@ -943,379 +967,379 @@ npm install -g omniroute@3.0.0 # Docker docker pull diegosouzapw/omniroute:3.0.0 -# ้ฆ–ๆฌกๅฏๅŠจๆ—ถไผš่‡ชๅŠจ่ฟ่กŒ่ฟ็งป +# Migrations run automatically on first startup ``` -> **็ ดๅๆ€งๅ˜ๆ›ด๏ผš** ๆ— ใ€‚ๆ‰€ๆœ‰็Žฐๆœ‰้…็ฝฎใ€combo ๅ’Œ API key ้ƒฝไผš่ขซไฟ็•™ใ€‚ -> ๆ•ฐๆฎๅบ“่ฟ็งป 008-010 ไผšๅœจๅฏๅŠจๆ—ถ่‡ชๅŠจ่ฟ่กŒใ€‚ +> **Breaking changes:** None. All existing configurations, combos, and API keys are preserved. +> Database migrations 008-010 run automatically on startup. --- ## [3.0.0-rc.17] โ€” 2026-03-24 -### ๐Ÿ”’ ๅฎ‰ๅ…จไธŽ CI/CD +### ๐Ÿ”’ Security & CI/CD -- **CodeQL remediation** โ€”โ€” ไฟฎๅค 10+ ไธช่ญฆๆŠฅ๏ผš - - `provider.ts` / `chatCore.ts` ไธญ็š„ 6 ไธช polynomial-redos๏ผˆๅฐ† `(?:^|/)` ไบคๆ›ฟๆจกๅผๆ›ฟๆขไธบๅŸบไบŽ็‰‡ๆฎต็š„ๅŒน้…๏ผ‰ - - `acp/manager.ts` ไธญ็š„ 1 ไธช insecure-randomness๏ผˆ`Math.random()` โ†’ `crypto.randomUUID()`๏ผ‰ - - `prepublish.mjs` ไธญ็š„ 1 ไธช shell-command-injection๏ผˆ`JSON.stringify()` ่ทฏๅพ„่ฝฌไน‰๏ผ‰ -- **Route validation** โ€”โ€” ไธบ 5 ไธช็ผบๅฐ‘้ชŒ่ฏ็š„่ทฏ็”ฑๆ–ฐๅขž Zod schema + `validateBody()`๏ผš - - `model-combo-mappings`๏ผˆPOSTใ€PUT๏ผ‰ใ€`webhooks`๏ผˆPOSTใ€PUT๏ผ‰ใ€`openapi/try`๏ผˆPOST๏ผ‰ - - CI `check:route-validation:t06` ็Žฐๅทฒ้€š่ฟ‡๏ผš**176/176 ไธช่ทฏ็”ฑๅ…จ้ƒจๅฎŒๆˆ้ชŒ่ฏ** +- **CodeQL remediation** โ€” Fixed 10+ alerts: + - 6 polynomial-redos in `provider.ts` / `chatCore.ts` (replaced `(?:^|/)` alternation patterns with segment-based matching) + - 1 insecure-randomness in `acp/manager.ts` (`Math.random()` โ†’ `crypto.randomUUID()`) + - 1 shell-command-injection in `prepublish.mjs` (`JSON.stringify()` path escaping) +- **Route validation** โ€” Added Zod schemas + `validateBody()` to 5 routes missing validation: + - `model-combo-mappings` (POST, PUT), `webhooks` (POST, PUT), `openapi/try` (POST) + - CI `check:route-validation:t06` now passes: **176/176 routes validated** -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **#585** โ€”โ€” `` ๅ†…้ƒจๆ ‡็ญพไธๅ†ๆณ„้œฒ็ป™ SSE ๅฎขๆˆท็ซฏๅ“ๅบ”ใ€‚ๅทฒๅœจ `combo.ts` ไธญๆทปๅŠ ๅ‡บ็ซ™ๆธ…็† `TransformStream` +- **#585** โ€” `` internal tags no longer leak to clients in SSE responses. Added outbound sanitization `TransformStream` in `combo.ts` -### โš™๏ธ ๅŸบ็ก€่ฎพๆ–ฝ +### โš™๏ธ Infrastructure -- **Docker** โ€”โ€” ๅฐ† `docker/setup-buildx-action` ไปŽ v3 ๅ‡็บงๅˆฐ v4๏ผˆไฟฎๅค Node.js 20 ๅผƒ็”จ้—ฎ้ข˜๏ผ‰ -- **CI cleanup** โ€”โ€” ๅˆ ้™ค 150+ ไธชๅคฑ่ดฅ/ๅทฒๅ–ๆถˆ็š„ workflow ่ฟ่กŒ +- **Docker** โ€” Upgraded `docker/setup-buildx-action` from v3 โ†’ v4 (Node.js 20 deprecation fix) +- **CI cleanup** โ€” Deleted 150+ failed/cancelled workflow runs -### ๐Ÿงช ๆต‹่ฏ• +### ๐Ÿงช Tests -- ๆต‹่ฏ•ๅฅ—ไปถ๏ผš**926 ไธชๆต‹่ฏ•๏ผŒ0 ๅคฑ่ดฅ**๏ผˆๆ–ฐๅขž 3 ไธช๏ผ‰ +- Test suite: **926 tests, 0 failures** (+3 new) --- ## [3.0.0-rc.16] โ€” 2026-03-24 -### โœจ ๆ–ฐ็‰นๆ€ง +### โœจ New Features -- ๆ้ซ˜ไบ†ๅช’ไฝ“่ฝฌๅฝ•้™ๅˆถ -- ไธบ registry metadata ๆทปๅŠ ไบ†ๆจกๅž‹ไธŠไธ‹ๆ–‡้•ฟๅบฆ -- ้€š่ฟ‡้…็ฝฎ UI ๆทปๅŠ ไบ†ๆฏๆจกๅž‹ไธŠๆธธ่‡ชๅฎšไน‰่ฏทๆฑ‚ๅคด -- ไฟฎๅคไบ†ๅคšไธช bug๏ผŒไฝฟ็”จ Zod ้ชŒ่ฏ่ฟ›่กŒ่กฅไธ๏ผŒๅนถ่งฃๅ†ณไบ†ๅ„็ง็คพๅŒบ้—ฎ้ข˜ +- Increased media transcription limits +- Added Model Context Length to registry metadata +- Added per-model upstream custom headers via configuration UI +- Fixed multiple bugs, Zod valiadation for patches, and resolved various community issues. ## [3.0.0-rc.15] โ€” 2026-03-24 -### โœจ ๆ–ฐ็‰นๆ€ง +### โœจ New Features -- **#563** โ€” ๆฏๆจกๅž‹ Combo ่ทฏ็”ฑ๏ผšๅฐ†ๆจกๅž‹ๅ็งฐๆจกๅผ๏ผˆglob๏ผ‰ๆ˜ ๅฐ„ๅˆฐ็‰นๅฎš combo๏ผŒๅฎž็Žฐ่‡ชๅŠจ่ทฏ็”ฑ - - ๆ–ฐๅขž `model_combo_mappings` ่กจ๏ผˆmigration 010๏ผ‰๏ผŒๅŒ…ๅซ patternใ€combo_idใ€priorityใ€enabled ๅญ—ๆฎต - - `resolveComboForModel()` ๆ•ฐๆฎๅบ“ๅ‡ฝๆ•ฐ๏ผŒไฝฟ็”จ glob ๅˆฐๆญฃๅˆ™ๅŒน้…๏ผˆไธๅŒบๅˆ†ๅคงๅฐๅ†™๏ผŒๆ”ฏๆŒ `*` ๅ’Œ `?` ้€š้…็ฌฆ๏ผ‰ - - `getComboForModel()` ๅœจ `model.ts` ไธญ๏ผšๅขžๅผบ `getCombo()`๏ผŒไฝฟ็”จๆจกๅž‹ๆจกๅผๅ›ž้€€ - - `chat.ts`๏ผš่ทฏ็”ฑๅ†ณ็ญ–็Žฐๅœจๅœจๅค„็†ๅ•ๆจกๅž‹ไน‹ๅ‰ๆฃ€ๆŸฅๆจกๅž‹-combo ๆ˜ ๅฐ„ - - API๏ผš`GET/POST /api/model-combo-mappings`ใ€`GET/PUT/DELETE /api/model-combo-mappings/:id` - - ไปช่กจ็›˜๏ผšๅœจ Combos ้กต้ขๆ–ฐๅขž "Model Routing Rules" ๅŒบๅŸŸ๏ผŒๆ”ฏๆŒๅ†…่”ๆ–ฐๅขž/็ผ–่พ‘/ๅผ€ๅ…ณ/ๅˆ ้™ค - - ็คบไพ‹๏ผš`claude-sonnet*` โ†’ code-comboใ€`gpt-4o*` โ†’ openai-comboใ€`gemini-*` โ†’ google-combo +- **#563** โ€” Per-model Combo Routing: map model name patterns (glob) to specific combos for automatic routing + - New `model_combo_mappings` table (migration 010) with pattern, combo_id, priority, enabled + - `resolveComboForModel()` DB function with glob-to-regex matching (case-insensitive, `*` and `?` wildcards) + - `getComboForModel()` in `model.ts`: augments `getCombo()` with model-pattern fallback + - `chat.ts`: routing decision now checks model-combo mappings before single-model handling + - API: `GET/POST /api/model-combo-mappings`, `GET/PUT/DELETE /api/model-combo-mappings/:id` + - Dashboard: "Model Routing Rules" section added to Combos page with inline add/edit/toggle/delete + - Examples: `claude-sonnet*` โ†’ code-combo, `gpt-4o*` โ†’ openai-combo, `gemini-*` โ†’ google-combo ### ๐ŸŒ i18n -- **ๅฎŒๆ•ด i18n ๅŒๆญฅ**๏ผšๅœจ 30 ไธช่ฏญ่จ€ๆ–‡ไปถไธญๆ–ฐๅขž 2,788 ไธช็ผบๅคฑ้”ฎ โ€” ๆ‰€ๆœ‰่ฏญ่จ€็ŽฐๅœจไธŽ `en.json` ่พพๅˆฐ 100% ไธ€่‡ด -- **ไปฃ็†้กต้ข i18n**๏ผšOpenCode ้›†ๆˆ้ƒจๅˆ†ๅฎŒๅ…จๅ›ฝ้™…ๅŒ–๏ผˆๆ ‡้ข˜ใ€ๆ่ฟฐใ€ๆ‰ซๆใ€ไธ‹่ฝฝๆ ‡็ญพ๏ผ‰ -- **ๆ–ฐๅขž 6 ไธช้”ฎ**ๅˆฐ `agents` ๅ‘ฝๅ็ฉบ้—ด๏ผŒ็”จไบŽ OpenCode ้ƒจๅˆ† +- **Full i18n Sync**: 2,788 missing keys added across 30 language files โ€” all languages now at 100% parity with `en.json` +- **Agents page i18n**: OpenCode Integration section fully internationalized (title, description, scanning, download labels) +- **6 new keys** added to `agents` namespace for OpenCode section -### ๐ŸŽจ ็•Œ้ข/ไฝ“้ชŒ +### ๐ŸŽจ UI/UX -- **ๆไพ›ๅ•†ๅ›พๆ ‡**๏ผšๆ–ฐๅขž 16 ไธช็ผบๅคฑ็š„ๆไพ›ๅ•†ๅ›พๆ ‡๏ผˆ3 ไธชๅคๅˆถใ€2 ไธชไธ‹่ฝฝใ€11 ไธช SVG ๅˆ›ๅปบ๏ผ‰ -- **SVG ๅ›ž้€€**๏ผš`ProviderIcon` ็ป„ไปถๆ›ดๆ–ฐไธบ 4 ๅฑ‚็ญ–็•ฅ๏ผšLobehub โ†’ PNG โ†’ SVG โ†’ ้€š็”จๅ›พๆ ‡ -- **ไปฃ็†ๆŒ‡็บน่ฏ†ๅˆซ**๏ผšไธŽ CLI ๅทฅๅ…ทๅŒๆญฅ โ€” ๅฐ† droidใ€openclawใ€copilotใ€opencode ๆทปๅŠ ๅˆฐๆŒ‡็บนๅˆ—่กจ๏ผˆๅ…ฑ 14 ไธช๏ผ‰ +- **Provider Icons**: 16 missing provider icons added (3 copied, 2 downloaded, 11 SVG created) +- **SVG fallback**: `ProviderIcon` component updated with 4-tier strategy: Lobehub โ†’ PNG โ†’ SVG โ†’ Generic icon +- **Agents fingerprinting**: Synced with CLI tools โ€” added droid, openclaw, copilot, opencode to fingerprint list (14 total) -### ๐Ÿ”’ ๅฎ‰ๅ…จ +### ๅฎ‰ๅ…จ -- **CVE ไฟฎๅค**๏ผš้€š่ฟ‡ npm ๅผบๅˆถไฝฟ็”จ `dompurify@^3.3.2` ่งฃๅ†ณไบ† dompurify XSS ๆผๆดž๏ผˆGHSA-v2wj-7wpq-c8vv๏ผ‰ -- `npm audit` ็ŽฐๅœจๆŠฅๅ‘Š **0 ไธชๆผๆดž** +- **CVE fix**: Resolved dompurify XSS vulnerability (GHSA-v2wj-7wpq-c8vv) via npm overrides forcing `dompurify@^3.3.2` +- `npm audit` now reports **0 vulnerabilities** -### ๐Ÿงช ๆต‹่ฏ• +### ๐Ÿงช Tests -- ๆต‹่ฏ•ๅฅ—ไปถ๏ผš**923 ไธชๆต‹่ฏ•๏ผŒ0 ๅคฑ่ดฅ**๏ผˆๆ–ฐๅขž 15 ไธชๆจกๅž‹-combo ๆ˜ ๅฐ„ๆต‹่ฏ•๏ผ‰ +- Test suite: **923 tests, 0 failures** (+15 new model-combo mapping tests) --- ## [3.0.0-rc.14] โ€” 2026-03-23 -### ๐Ÿ”€ ๅทฒๅˆๅนถ็š„็คพๅŒบ PR +### ๐Ÿ”€ Community PRs Merged -| PR | ไฝœ่€… | ๆ‘˜่ฆ | -| -------- | -------- | -------------------------------------------------------------------- | -| **#562** | @coobabm | fix(ux): MCP ไผš่ฏ็ฎก็†ใ€Claude ้€ไผ ่ง„่ŒƒๅŒ–ใ€OAuth ๆจกๆ€ๆก†ใ€detectFormat | -| **#561** | @zen0bit | fix(i18n): ๆทๅ…‹่ฏญ็ฟป่ฏ‘ไฟฎๆญฃ โ€” HTTP ๆ–นๆณ•ๅ็งฐๅ’Œๆ–‡ๆกฃๆ›ดๆ–ฐ | +| PR | Author | Summary | +| -------- | -------- | -------------------------------------------------------------------------------------------- | +| **#562** | @coobabm | fix(ux): MCP session management, Claude passthrough normalization, OAuth modal, detectFormat | +| **#561** | @zen0bit | fix(i18n): Czech translation corrections โ€” HTTP method names and documentation updates | -### ๐Ÿงช ๆต‹่ฏ• +### ๐Ÿงช Tests -- ๆต‹่ฏ•ๅฅ—ไปถ๏ผš**908 ไธชๆต‹่ฏ•๏ผŒ0 ๅคฑ่ดฅ** +- Test suite: **908 tests, 0 failures** --- ## [3.0.0-rc.13] โ€” 2026-03-23 -### ๐Ÿ”ง Bug ไฟฎๅค +### ๐Ÿ”ง Bug Fixes -- **config:** ๅœจ CLI ่ฎพ็ฝฎ่ทฏ็”ฑ๏ผˆ`codex-settings`ใ€`droid-settings`ใ€`kilo-settings`๏ผ‰ไธญไปŽ `keyId` ่งฃๆž็œŸๅฎž API key๏ผŒ้˜ฒๆญขๅ†™ๅ…ฅ่„ฑๆ•ๅญ—็ฌฆไธฒ (#549) +- **config:** resolve real API key from `keyId` in CLI settings routes (`codex-settings`, `droid-settings`, `kilo-settings`) to prevent writing masked strings (#549) --- ## [3.0.0-rc.12] โ€” 2026-03-23 -### ๐Ÿ”€ ๅทฒๅˆๅนถ็š„็คพๅŒบ PR +### ๐Ÿ”€ Community PRs Merged -| PR | ไฝœ่€… | ๆ‘˜่ฆ | -| -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- | -| **#546** | @k0valik | fix(cli): Windows ไธŠ `--version` ่ฟ”ๅ›ž `unknown` โ€” ไฝฟ็”จ `JSON.parse(readFileSync)` ๆ›ฟไปฃ ESM import | -| **#555** | @k0valik | fix(sse): ้›†ไธญๅŒ– `resolveDataDir()` ็”จไบŽ่ทฏๅพ„่งฃๆž๏ผŒๅŒ…ๆ‹ฌ credentialsใ€autoComboใ€ๅ“ๅบ” logger ๅ’Œ่ฏทๆฑ‚ logger | -| **#544** | @k0valik | fix(cli): ้€š่ฟ‡ๅทฒ็Ÿฅๅฎ‰่ฃ…่ทฏๅพ„๏ผˆ8 ไธชๅทฅๅ…ท๏ผ‰่ฟ›่กŒๅฎ‰ๅ…จ็š„ CLI ๅทฅๅ…ทๆฃ€ๆต‹๏ผŒๅŒ…ๆ‹ฌ็ฌฆๅท้“พๆŽฅ้ชŒ่ฏใ€ๆ–‡ไปถ็ฑปๅž‹ๆฃ€ๆŸฅใ€ๅคงๅฐ่พน็•Œใ€ๅฅๅบทๆฃ€ๆŸฅไธญ็š„ๆœ€ๅฐ็Žฏๅขƒๆฃ€ๆต‹ | -| **#542** | @rdself | fix(ui): ๆ”นๅ–„ๆต…่‰ฒๆจกๅผๅฏนๆฏ”ๅบฆ โ€” ๆทปๅŠ ็ผบๅคฑ็š„ CSS ไธป้ข˜ๅ˜้‡๏ผˆ`bg-primary`ใ€`bg-subtle`ใ€`text-primary`๏ผ‰ๅนถไฟฎๅคๆ—ฅๅฟ—่ฏฆๆƒ…ไธญไป…ๆš—่‰ฒ็š„้ขœ่‰ฒ | +| PR | Author | Summary | +| -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **#546** | @k0valik | fix(cli): `--version` returning `unknown` on Windows โ€” use `JSON.parse(readFileSync)` instead of ESM import | +| **#555** | @k0valik | fix(sse): centralized `resolveDataDir()` for path resolution in credentials, autoCombo, responses logger, and request logger | +| **#544** | @k0valik | fix(cli): secure CLI tool detection via known installation paths (8 tools) with symlink validation, file-type checks, size bounds, minimal env in healthcheck | +| **#542** | @rdself | fix(ui): improve light mode contrast โ€” add missing CSS theme variables (`bg-primary`, `bg-subtle`, `text-primary`) and fix dark-only colors in log detail | -### ๐Ÿ”ง Bug ไฟฎๅค +### ๐Ÿ”ง Bug Fixes -- **TDZ ไฟฎๅค๏ผˆ`cliRuntime.ts`๏ผ‰** โ€” `validateEnvPath` ๅœจๆจกๅ—ๅฏๅŠจๆ—ถ่ขซ `getExpectedParentPaths()` ไฝฟ็”จๅ‰ๆœชๅˆๅง‹ๅŒ–ใ€‚้‡ๆ–ฐๆŽ’ๅบๅฃฐๆ˜Žไปฅไฟฎๅค `ReferenceError`ใ€‚ -- **ๆž„ๅปบไฟฎๅค** โ€” ๅฐ† `pino` ๅ’Œ `pino-pretty` ๆทปๅŠ ๅˆฐ `serverExternalPackages` ไปฅ้˜ฒๆญข Turbopack ็ ดๅ Pino ็š„ๅ†…้ƒจ worker ๅŠ ่ฝฝใ€‚ +- **TDZ fix in `cliRuntime.ts`** โ€” `validateEnvPath` was used before initialization at module startup by `getExpectedParentPaths()`. Reordered declarations to fix `ReferenceError`. +- **Build fixes** โ€” Added `pino` and `pino-pretty` to `serverExternalPackages` to prevent Turbopack from breaking Pino's internal worker loading. -### ๐Ÿงช ๆต‹่ฏ• +### ๐Ÿงช Tests -- ๆต‹่ฏ•ๅฅ—ไปถ๏ผš**905 ไธชๆต‹่ฏ•๏ผŒ0 ๅคฑ่ดฅ** +- Test suite: **905 tests, 0 failures** --- ## [3.0.0-rc.10] โ€” 2026-03-23 -### ๐Ÿ”ง Bug ไฟฎๅค +### ๐Ÿ”ง Bug Fixes -- **#509 / #508** โ€” Electron ๆž„ๅปบๅ›žๅฝ’๏ผšๅฐ† Next.js ไปŽ `16.1.x` ้™็บงๅˆฐ `16.0.10` ไปฅๆถˆ้™ค Turbopack ๆจกๅ—ๅ“ˆๅธŒไธ็จณๅฎš้—ฎ้ข˜๏ผŒ่ฏฅ้—ฎ้ข˜ๅฏผ่‡ด Electron ๆกŒ้ขๅŒ…ๅ‡บ็Žฐ็™ฝๅฑใ€‚ -- **ๅ•ๅ…ƒๆต‹่ฏ•ไฟฎๅค** โ€” ไฟฎๆญฃไบ†ไธคไธช่ฟ‡ๆ—ถ็š„ๆต‹่ฏ•ๆ–ญ่จ€๏ผˆ`nanobanana-image-handler` ๅฎฝ้ซ˜ๆฏ”/ๅˆ†่พจ็Ž‡ใ€`thinking-budget` Gemini `thinkingConfig` ๅญ—ๆฎตๆ˜ ๅฐ„๏ผ‰๏ผŒ่ฟ™ไบ›ๅœจๆœ€่ฟ‘็š„ๅฎž็Žฐๅ˜ๆ›ดๅŽๅทฒๅ็ฆปใ€‚ -- **#541** โ€” ๅ›žๅคไบ†็”จๆˆทๅ…ณไบŽๅฎ‰่ฃ…ๅคๆ‚ๅบฆ็š„ๅ้ฆˆ๏ผ›ๆ— ้œ€ไปฃ็ ๅ˜ๆ›ดใ€‚ +- **#509 / #508** โ€” Electron build regression: downgraded Next.js from `16.1.x` to `16.0.10` to eliminate Turbopack module-hashing instability that caused blank screens in the Electron desktop bundle. +- **Unit test fixes** โ€” Corrected two stale test assertions (`nanobanana-image-handler` aspect ratio/resolution, `thinking-budget` Gemini `thinkingConfig` field mapping) that had drifted after recent implementation changes. +- **#541** โ€” Responded to user feedback about installation complexity; no code changes required. --- ## [3.0.0-rc.9] โ€” 2026-03-23 -### โœจ ๆ–ฐ็‰นๆ€ง +### โœจ New Features -- **T29** โ€” Vertex AI ๆœๅŠก่ดฆๆˆท JSON ๆ‰ง่กŒๅ™จ๏ผšไฝฟ็”จ `jose` ๅบ“ๅค„็† JWT/ๆœๅŠก่ดฆๆˆท่ฎค่ฏ๏ผŒไปฅๅŠ UI ไธญๅฏ้…็ฝฎ็š„ๅŒบๅŸŸๅ’Œ่‡ชๅŠจไผ™ไผดๆจกๅž‹ URL ๆž„ๅปบใ€‚ -- **T42** โ€” ๅ›พๅƒ็”Ÿๆˆ้•ฟๅฎฝๆฏ”ๆ˜ ๅฐ„๏ผšไธบ้€š็”จ OpenAI ๆ ผๅผ๏ผˆ`size`๏ผ‰ๅˆ›ๅปบไบ† `sizeMapper` ้€ป่พ‘๏ผŒๆทปๅŠ ไบ†ๅŽŸ็”Ÿ `imagen3` ๅค„็†๏ผŒๅนถๆ›ดๆ–ฐ NanoBanana ็ซฏ็‚นไปฅ่‡ชๅŠจไฝฟ็”จๆ˜ ๅฐ„็š„้•ฟๅฎฝๆฏ”ใ€‚ -- **T38** โ€” ้›†ไธญๅŒ–ๆจกๅž‹่ง„ๆ ผๅฎšไน‰๏ผšๅˆ›ๅปบ `modelSpecs.ts` ็”จไบŽๆฏไธชๆจกๅž‹็š„้™้ขๅ’Œๅ‚ๆ•ฐใ€‚ +- **T29** โ€” Vertex AI SA JSON Executor: implemented using the `jose` library to handle JWT/Service Account auth, along with configurable regions in the UI and automatic partner model URL building. +- **T42** โ€” Image generation aspect ratio mapping: created `sizeMapper` logic for generic OpenAI formats (`size`), added native `imagen3` handling, and updated NanoBanana endpoints to utilize mapped aspect ratios automatically. +- **T38** โ€” Centralized model specifications: `modelSpecs.ts` created for limits and parameters per model. -### ๐Ÿ”ง ๆ”น่ฟ› +### ๐Ÿ”ง Improvements -- **T40** โ€” OpenCode CLI ๅทฅๅ…ท้›†ๆˆ๏ผšๅœจไน‹ๅ‰็š„ PR ไธญๅทฒๅฎŒๆˆๅŽŸ็”Ÿ `opencode-zen` ๅ’Œ `opencode-go` ้›†ๆˆใ€‚ +- **T40** โ€” OpenCode CLI tools integration: native `opencode-zen` and `opencode-go` integration completed in earlier PR. --- ## [3.0.0-rc.8] โ€” 2026-03-23 -### ๐Ÿ”ง Bug ไฟฎๅคไธŽๆ”น่ฟ›๏ผˆๅ›ž้€€ใ€้…้ขไธŽ้ข„็ฎ—๏ผ‰ +### ๐Ÿ”ง Bug Fixes & Improvements (Fallback, Quota & Budget) -- **T24** โ€” `503` ๅ†ทๅด็ญ‰ๅพ…ไฟฎๅค + `406` ๆ˜ ๅฐ„๏ผšๅฐ† `406 Not Acceptable` ๆ˜ ๅฐ„ไธบ `503 Service Unavailable`๏ผŒๅนถ่ฎพ็ฝฎ้€‚ๅฝ“็š„ๅ†ทๅด้—ด้š”ใ€‚ -- **T25** โ€” ๆไพ›ๅ•†้ชŒ่ฏๅ›ž้€€๏ผšๅฝ“ไธๅญ˜ๅœจ็‰นๅฎš็š„ `validationModelId` ๆ—ถ๏ผŒไผ˜้›…ๅ›ž้€€ๅˆฐๆ ‡ๅ‡†้ชŒ่ฏๆจกๅž‹ใ€‚ -- **T36** โ€” `403` ไธŽ `429` ๆไพ›ๅ•†ๅค„็†ไผ˜ๅŒ–๏ผšๆๅ–ๅˆฐ `errorClassifier.ts` ไปฅๆญฃ็กฎ้š”็ฆป็กฌๆ€งๆƒ้™ๅคฑ่ดฅ๏ผˆ`403`๏ผ‰ๅ’Œ้€Ÿ็Ž‡้™ๅˆถ๏ผˆ`429`๏ผ‰ใ€‚ -- **T39** โ€” `fetchAvailableModels` ็ซฏ็‚นๅ›ž้€€๏ผšๅฎž็Žฐไบ†ไธ‰ๅฑ‚ๆœบๅˆถ๏ผˆ`/models` โ†’ `/v1/models` โ†’ ๆœฌๅœฐ้€š็”จ็›ฎๅฝ•๏ผ‰+ ๆ›ดๆ–ฐ `list_models_catalog` MCP ๅทฅๅ…ทไปฅๅๆ˜  `source` ๅ’Œ `warning`ใ€‚ -- **T33** โ€” Thinking ็บงๅˆซๅˆฐ้ข„็ฎ—่ฝฌๆข๏ผšๅฐ†ๅฎšๆ€ง thinking ็บงๅˆซ่ฝฌๆขไธบ็ฒพ็กฎ็š„้ข„็ฎ—ๅˆ†้…ใ€‚ -- **T41** โ€” ๅŽๅฐไปปๅŠก่‡ชๅŠจ้‡ๅฎšๅ‘๏ผš่‡ชๅŠจๅฐ†ๆฒ‰้‡็š„ๅŽๅฐ่ฏ„ไผฐไปปๅŠก่ทฏ็”ฑๅˆฐๅฟซ้€Ÿ/้ซ˜ๆ•ˆๆจกๅž‹ใ€‚ -- **T23** โ€” ๆ™บ่ƒฝ้…้ข้‡็ฝฎๅ›ž้€€๏ผšๅ‡†็กฎๆๅ– `x-ratelimit-reset` / `retry-after` ่ฏทๆฑ‚ๅคดๅ€ผๆˆ–ๆ˜ ๅฐ„้™ๆ€ๅ†ทๅดๆ—ถ้—ดใ€‚ +- **T24** โ€” `503` cooldown await fix + `406` mapping: mapped `406 Not Acceptable` to `503 Service Unavailable` with proper cooldown intervals. +- **T25** โ€” Provider validation fallback: graceful fallback to standard validation models when a specific `validationModelId` is not present. +- **T36** โ€” `403` vs `429` provider handling refinement: extracted into `errorClassifier.ts` to properly segregate hard permissions failures (`403`) from rate limits (`429`). +- **T39** โ€” Endpoint Fallback for `fetchAvailableModels`: implemented a tri-tier mechanism (`/models` -> `/v1/models` -> local generic catalog) + `list_models_catalog` MCP tool updates to reflect `source` and `warning`. +- **T33** โ€” Thinking level to budget conversion: translates qualitative thinking levels into precise budget allocations. +- **T41** โ€” Background task auto redirect: routes heavy background evaluation tasks to flash/efficient models automatically. +- **T23** โ€” Intelligent quota reset fallback: accurately extracts `x-ratelimit-reset` / `retry-after` header values or maps static cooldowns. --- -## [3.0.0-rc.7] โ€” 2026-03-23 _๏ผˆ็›ธๆฏ” v2.9.5 ็š„ๆ–ฐๅขžๅ†…ๅฎน โ€” ๅฐ†ไฝœไธบ v3.0.0 ๅ‘ๅธƒ๏ผ‰_ +## [3.0.0-rc.7] โ€” 2026-03-23 _(What's New vs v2.9.5 โ€” will be released as v3.0.0)_ -> **ไปŽ v2.9.5 ๅ‡็บง๏ผš** 16 ไธช้—ฎ้ข˜ๅทฒ่งฃๅ†ณ ยท 2 ไธช็คพๅŒบ PR ๅทฒๅˆๅนถ ยท 2 ไธชๆ–ฐๆไพ›ๅ•† ยท 7 ไธชๆ–ฐ API ็ซฏ็‚น ยท 3 ไธชๆ–ฐๅŠŸ่ƒฝ ยท ๆ•ฐๆฎๅบ“่ฟ็งป 008+009 ยท 832 ไธชๆต‹่ฏ•้€š่ฟ‡ ยท 15 ้กน sub2api ๅทฎ่ทๆ”น่ฟ›๏ผˆT01โ€“T15 ๅฎŒๆˆ๏ผ‰ใ€‚ +> **Upgrade from v2.9.5:** 16 issues resolved ยท 2 community PRs merged ยท 2 new providers ยท 7 new API endpoints ยท 3 new features ยท DB migration 008+009 ยท 832 tests passing ยท 15 sub2api gap improvements (T01โ€“T15 complete). -### ๐Ÿ†• ๆ–ฐๆไพ›ๅ•† +### ๐Ÿ†• New Providers -| ๆไพ›ๅ•† | ๅˆซๅ | ๅฑ‚็บง | ่ฏดๆ˜Ž | -| ---------------- | -------------- | ---- | --------------------------------------------------------------------- | -| **OpenCode Zen** | `opencode-zen` | ๅ…่ดน | ้€š่ฟ‡ `opencode.ai/zen/v1` ๆไพ› 3 ไธชๆจกๅž‹๏ผˆPR #530 by @kang-heewon๏ผ‰ | -| **OpenCode Go** | `opencode-go` | ไป˜่ดน | ้€š่ฟ‡ `opencode.ai/zen/go/v1` ๆไพ› 4 ไธชๆจกๅž‹๏ผˆPR #530 by @kang-heewon๏ผ‰ | +| Provider | Alias | Tier | Notes | +| ---------------- | -------------- | ---- | -------------------------------------------------------------- | +| **OpenCode Zen** | `opencode-zen` | Free | 3 models via `opencode.ai/zen/v1` (PR #530 by @kang-heewon) | +| **OpenCode Go** | `opencode-go` | Paid | 4 models via `opencode.ai/zen/go/v1` (PR #530 by @kang-heewon) | -ไธคไธชๆไพ›ๅ•†้ƒฝไฝฟ็”จๆ–ฐ็š„ `OpencodeExecutor`๏ผŒๆ”ฏๆŒๅคšๆ ผๅผ่ทฏ็”ฑ๏ผˆ`/chat/completions`ใ€`/messages`ใ€`/responses`ใ€`/models/{model}:generateContent`๏ผ‰ใ€‚ +Both providers use the new `OpencodeExecutor` with multi-format routing (`/chat/completions`, `/messages`, `/responses`, `/models/{model}:generateContent`). --- -### โœจ ๆ–ฐ็‰นๆ€ง +### โœจ New Features #### ๐Ÿ”‘ Registered Keys Provisioning API (#464) -ๅฏ้€š่ฟ‡็ผ–็จ‹ๆ–นๅผ่‡ชๅŠจ็”Ÿๆˆๅนถ็ญพๅ‘ OmniRoute API key๏ผŒๆ”ฏๆŒๆŒ‰ๆไพ›ๅ•†ๅ’Œ่ดฆๆˆท่ฟ›่กŒ้…้ข้™ๅˆถใ€‚ +Auto-generate and issue OmniRoute API keys programmatically with per-provider and per-account quota enforcement. -| ็ซฏ็‚น | ๆ–นๆณ• | ่ฏดๆ˜Ž | -| ------------------------------------- | --------- | ------------------------------------- | -| `/api/v1/registered-keys` | `POST` | ็ญพๅ‘ๆ–ฐ key โ€”โ€” ๅŽŸๅง‹ key **ๅช่ฟ”ๅ›žไธ€ๆฌก** | -| `/api/v1/registered-keys` | `GET` | ๅˆ—ๅ‡บๅทฒๆณจๅ†Œ key๏ผˆ่„ฑๆ•๏ผ‰ | -| `/api/v1/registered-keys/{id}` | `GET` | ่Žทๅ–ๅ…ƒๆ•ฐๆฎ | -| `/api/v1/registered-keys/{id}` | `DELETE` | ๅŠ้”€ key | -| `/api/v1/registered-keys/{id}/revoke` | `POST` | ๅŠ้”€๏ผˆ้€‚็”จไบŽไธๆ”ฏๆŒ DELETE ็š„ๅฎขๆˆท็ซฏ๏ผ‰ | -| `/api/v1/quotas/check` | `GET` | ็ญพๅ‘ๅ‰้ข„ๆฃ€้…้ข | -| `/api/v1/providers/{id}/limits` | `GET/PUT` | ้…็ฝฎๆŒ‰ๆไพ›ๅ•†็š„็ญพๅ‘้™ๅˆถ | -| `/api/v1/accounts/{id}/limits` | `GET/PUT` | ้…็ฝฎๆŒ‰่ดฆๆˆท็š„็ญพๅ‘้™ๅˆถ | -| `/api/v1/issues/report` | `POST` | ๅ‘ GitHub Issues ๆŠฅๅ‘Š้…้ขไบ‹ไปถ | +| Endpoint | Method | Description | +| ------------------------------------- | --------- | ------------------------------------------------ | +| `/api/v1/registered-keys` | `POST` | Issue a new key โ€” raw key returned **once only** | +| `/api/v1/registered-keys` | `GET` | List registered keys (masked) | +| `/api/v1/registered-keys/{id}` | `GET` | Get key metadata | +| `/api/v1/registered-keys/{id}` | `DELETE` | Revoke a key | +| `/api/v1/registered-keys/{id}/revoke` | `POST` | Revoke (for clients without DELETE support) | +| `/api/v1/quotas/check` | `GET` | Pre-validate quota before issuing | +| `/api/v1/providers/{id}/limits` | `GET/PUT` | Configure per-provider issuance limits | +| `/api/v1/accounts/{id}/limits` | `GET/PUT` | Configure per-account issuance limits | +| `/api/v1/issues/report` | `POST` | Report quota events to GitHub Issues | -**ๆ•ฐๆฎๅบ“ โ€” ่ฟ็งป 008๏ผš** ไธ‰ไธชๆ–ฐ่กจ๏ผš`registered_keys`ใ€`provider_key_limits`ใ€`account_key_limits`ใ€‚ -**ๅฎ‰ๅ…จๆ€ง๏ผš** key ไปฅ SHA-256 ๅ“ˆๅธŒๅญ˜ๅ‚จใ€‚ๅŽŸๅง‹ key ๅชๅœจๅˆ›ๅปบๆ—ถๅฑ•็คบไธ€ๆฌก๏ผŒไน‹ๅŽไธๅฏๅ†ๅ–ๅ›žใ€‚ -**้…้ข็ฑปๅž‹๏ผš** ๆฏไธชๆไพ›ๅ•†ๅ’Œ่ดฆๆˆท็š„ `maxActiveKeys`ใ€`dailyIssueLimit`ใ€`hourlyIssueLimit`ใ€‚ -**ๅน‚็ญ‰ๆ€ง๏ผš** `idempotency_key` ๅญ—ๆฎต้˜ฒๆญข้‡ๅค็ญพๅ‘ใ€‚ๅฆ‚ๆžœ key ๅทฒ่ขซไฝฟ็”จ๏ผŒ่ฟ”ๅ›ž `409 IDEMPOTENCY_CONFLICT`ใ€‚ -**ๆฏไธช key ็š„้ข„็ฎ—๏ผš** `dailyBudget` / `hourlyBudget` โ€”โ€” ้™ๅˆถๆฏไธชๆ—ถ้—ด็ช—ๅฃๅ†… key ๅฏ่ทฏ็”ฑ็š„่ฏทๆฑ‚ๆ•ฐใ€‚ -**GitHub ๆŠฅๅ‘Š๏ผš** ๅฏ้€‰ใ€‚่ฎพ็ฝฎ `GITHUB_ISSUES_REPO` + `GITHUB_ISSUES_TOKEN` ๅฏๅœจ้…้ข่ถ…ๅ‡บๆˆ–็ญพๅ‘ๅคฑ่ดฅๆ—ถ่‡ชๅŠจๅˆ›ๅปบ GitHub issueใ€‚ +**DB โ€” Migration 008:** Three new tables: `registered_keys`, `provider_key_limits`, `account_key_limits`. +**Security:** Keys stored as SHA-256 hashes. Raw key shown once on creation, never retrievable again. +**Quota types:** `maxActiveKeys`, `dailyIssueLimit`, `hourlyIssueLimit` per provider and per account. +**Idempotency:** `idempotency_key` field prevents duplicate issuance. Returns `409 IDEMPOTENCY_CONFLICT` if key was already used. +**Budget per key:** `dailyBudget` / `hourlyBudget` โ€” limits how many requests a key can route per window. +**GitHub reporting:** Optional. Set `GITHUB_ISSUES_REPO` + `GITHUB_ISSUES_TOKEN` to auto-create GitHub issues on quota exceeded or issuance failures. -#### ๐ŸŽจ ๆไพ›ๅ•†ๅ›พๆ ‡ โ€” @lobehub/icons (#529) +#### ๐ŸŽจ Provider Icons โ€” @lobehub/icons (#529) -ไปช่กจ็›˜ไธญๆ‰€ๆœ‰ๆไพ›ๅ•†ๅ›พๆ ‡็Žฐๅœจไฝฟ็”จ `@lobehub/icons` React ็ป„ไปถ๏ผˆ130+ ไธชๆไพ›ๅ•†๏ผŒSVG ๆ ผๅผ๏ผ‰ใ€‚ -ๅ›ž้€€้“พ๏ผš**Lobehub SVG โ†’ ็Žฐๆœ‰ `/providers/{id}.png` โ†’ ้€š็”จๅ›พๆ ‡**ใ€‚ไฝฟ็”จๆ ‡ๅ‡†็š„ React `ErrorBoundary` ๆจกๅผใ€‚ +All provider icons in the dashboard now use `@lobehub/icons` React components (130+ providers with SVG). +Fallback chain: **Lobehub SVG โ†’ existing `/providers/{id}.png` โ†’ generic icon**. Uses a proper React `ErrorBoundary` pattern. -#### ๐Ÿ”„ ๆจกๅž‹่‡ชๅŠจๅŒๆญฅ่ฐƒๅบฆๅ™จ (#488) +#### ๐Ÿ”„ Model Auto-Sync Scheduler (#488) -OmniRoute ็Žฐๅœจๆฏ **24 ๅฐๆ—ถ**่‡ชๅŠจๅˆทๆ–ฐๅทฒ่ฟžๆŽฅๆไพ›ๅ•†็š„ๆจกๅž‹ๅˆ—่กจใ€‚ +OmniRoute now automatically refreshes model lists for connected providers every **24 hours**. -- ้€š่ฟ‡็Žฐๆœ‰็š„ `/api/sync/initialize` ้’ฉๅญๅœจๆœๅŠกๅ™จๅฏๅŠจๆ—ถ่ฟ่กŒ -- ๅฏ้€š่ฟ‡ `MODEL_SYNC_INTERVAL_HOURS` ็Žฏๅขƒๅ˜้‡้…็ฝฎ -- ่ฆ†็›– 16 ไธชไธป่ฆๆไพ›ๅ•† -- ๅœจ่ฎพ็ฝฎๆ•ฐๆฎๅบ“ไธญ่ฎฐๅฝ•ๆœ€ๅŽๅŒๆญฅๆ—ถ้—ด +- Runs on server startup via the existing `/api/sync/initialize` hook +- Configurable via `MODEL_SYNC_INTERVAL_HOURS` environment variable +- Covers 16 major providers +- Records last sync time in the settings database --- -### ๐Ÿ”ง Bug ไฟฎๅค +### ๐Ÿ”ง Bug Fixes -#### OAuth ไธŽ่ฎค่ฏ +#### OAuth & Auth -- **#537 โ€” Gemini CLI OAuth๏ผš** ๅœจ Docker/่‡ชๆ‰˜็ฎก้ƒจ็ฝฒไธญ็ผบๅฐ‘ `GEMINI_OAUTH_CLIENT_SECRET` ๆ—ถ๏ผŒ็Žฐๅœจไผš็ป™ๅ‡บๆธ…ๆ™ฐไธ”ๅฏๆ“ไฝœ็š„้”™่ฏฏๆ็คบใ€‚ๆญคๅ‰ไผšๆ˜พ็คบๆฅ่‡ช Google ็š„็ฅž็ง˜ `client_secret is missing` ้”™่ฏฏใ€‚็Žฐๅœจๆไพ›ๅ…ทไฝ“็š„ `docker-compose.yml` ๅ’Œ `~/.omniroute/.env` ้…็ฝฎ่ฏดๆ˜Žใ€‚ +- **#537 โ€” Gemini CLI OAuth:** Clear actionable error when `GEMINI_OAUTH_CLIENT_SECRET` is missing in Docker/self-hosted deployments. Previously showed cryptic `client_secret is missing` from Google. Now provides specific `docker-compose.yml` and `~/.omniroute/.env` instructions. -#### ๆไพ›ๅ•†ไธŽ่ทฏ็”ฑ +#### Providers & Routing -- **#536 โ€” LongCat AI๏ผš** ไฟฎๅคไบ† `baseUrl`๏ผˆ`api.longcat.chat/openai`๏ผ‰ๅ’Œ `authHeader`๏ผˆ`Authorization: Bearer`๏ผ‰ใ€‚ -- **#535 โ€” ๅ›บๅฎšๆจกๅž‹่ฆ†็›–๏ผš** ๅฝ“ context-cache ไฟๆŠคๆฟ€ๆดปๆ—ถ๏ผŒ`body.model` ็Žฐๅœจไผšๆญฃ็กฎ่ฎพ็ฝฎไธบ `pinnedModel`ใ€‚ -- **#532 โ€” OpenCode Go key ้ชŒ่ฏ๏ผš** ็Žฐๅœจไฝฟ็”จ `zen/v1` ๆต‹่ฏ•็ซฏ็‚น๏ผˆ`testKeyBaseUrl`๏ผ‰โ€”โ€” ๅŒไธ€ไธช key ้€‚็”จไบŽไธคไธชๅฑ‚็บงใ€‚ +- **#536 โ€” LongCat AI:** Fixed `baseUrl` (`api.longcat.chat/openai`) and `authHeader` (`Authorization: Bearer`). +- **#535 โ€” Pinned model override:** `body.model` is now correctly set to `pinnedModel` when context-cache protection is active. +- **#532 โ€” OpenCode Go key validation:** Now uses the `zen/v1` test endpoint (`testKeyBaseUrl`) โ€” same key works for both tiers. -#### CLI ไธŽๅทฅๅ…ท +#### CLI & Tools -- **#527 โ€” Claude Code + Codex ๅพช็Žฏ๏ผš** `tool_result` ๅ—็Žฐๅœจไผš่ขซ่ฝฌๆขไธบๆ–‡ๆœฌ่€Œไธๆ˜ฏ่ขซไธขๅผƒ๏ผŒไปŽ่€Œ้˜ปๆญขๆ— ้™ๅทฅๅ…ท็ป“ๆžœๅพช็Žฏใ€‚ -- **#524 โ€” OpenCode ้…็ฝฎไฟๅญ˜๏ผš** ๆทปๅŠ ไบ† `saveOpenCodeConfig()` ๅค„็†ๅ™จ๏ผˆXDG_CONFIG_HOME ๆ„Ÿ็Ÿฅ๏ผŒๅ†™ๅ…ฅ TOML ๆ ผๅผ๏ผ‰ใ€‚ -- **#521 โ€” ็™ปๅฝ•ๅกๆญป๏ผš** ่ทณ่ฟ‡ๅฏ†็ ่ฎพ็ฝฎๅŽ็™ปๅฝ•ไธๅ†ๅกๆญป โ€”โ€” ็Žฐๅœจๆญฃ็กฎ้‡ๅฎšๅ‘ๅˆฐๅผ•ๅฏผ้กต้ขใ€‚ -- **#522 โ€” API Manager๏ผš** ็งป้™คไบ†ๅ…ทๆœ‰่ฏฏๅฏผๆ€ง็š„ "Copy masked key" ๆŒ‰้’ฎ๏ผˆๆ›ฟๆขไธบ้”ๅ›พๆ ‡ๆ็คบ๏ผ‰ใ€‚ -- **#532 โ€” OpenCode Go ้…็ฝฎ๏ผš** ๅผ•ๅฏผ่ฎพ็ฝฎๅค„็†ๅ™จ็Žฐๅœจๅค„็† `opencode` toolIdใ€‚ +- **#527 โ€” Claude Code + Codex loop:** `tool_result` blocks are now converted to text instead of dropped, stopping infinite tool-result loops. +- **#524 โ€” OpenCode config save:** Added `saveOpenCodeConfig()` handler (XDG_CONFIG_HOME aware, writes TOML). +- **#521 โ€” Login stuck:** Login no longer freezes after skipping password setup โ€” redirects correctly to onboarding. +- **#522 โ€” API Manager:** Removed misleading "Copy masked key" button (replaced with a lock icon tooltip). +- **#532 โ€” OpenCode Go config:** Guide settings handler now handles `opencode` toolId. -#### ๅผ€ๅ‘่€…ไฝ“้ชŒ +#### Developer Experience -- **#489 โ€” Antigravity๏ผš** ็ผบๅฐ‘ `googleProjectId` ๆ—ถ่ฟ”ๅ›ž็ป“ๆž„ๅŒ–็š„ 422 ้”™่ฏฏ๏ผŒ้™„ๅธฆ้‡ๆ–ฐ่ฟžๆŽฅๆŒ‡ๅฏผ๏ผŒ่€Œไธๆ˜ฏ็ฅž็ง˜ๅดฉๆบƒใ€‚ -- **#510 โ€” Windows ่ทฏๅพ„๏ผš** MSYS2/Git-Bash ่ทฏๅพ„๏ผˆ`/c/Program Files/...`๏ผ‰็Žฐๅœจไผš่‡ชๅŠจ่ง„่ŒƒๅŒ–ไธบ `C:\\Program Files\\...`ใ€‚ -- **#492 โ€” CLI ๅฏๅŠจ๏ผš** ๅฝ“ `app/server.js` ็ผบๅคฑๆ—ถ๏ผŒ`omniroute` CLI ็Žฐๅœจ่ƒฝๆฃ€ๆต‹็”ฑ `mise`/`nvm` ็ฎก็†็š„ Node๏ผŒๅนถๆ˜พ็คบ้’ˆๅฏนๆ€ง็š„ไฟฎๅค่ฏดๆ˜Žใ€‚ +- **#489 โ€” Antigravity:** Missing `googleProjectId` returns a structured 422 error with reconnect guidance instead of a cryptic crash. +- **#510 โ€” Windows paths:** MSYS2/Git-Bash paths (`/c/Program Files/...`) are now normalized to `C:\\Program Files\\...` automatically. +- **#492 โ€” CLI startup:** `omniroute` CLI now detects `mise`/`nvm`-managed Node when `app/server.js` is missing and shows targeted fix instructions. --- -### ๐Ÿ“– ๆ–‡ๆกฃๆ›ดๆ–ฐ +### ๐Ÿ“– Documentation Updates -- **#513** โ€”โ€” Docker ๅฏ†็ ้‡็ฝฎ๏ผš่ฎฐๅฝ•ไบ† `INITIAL_PASSWORD` ็Žฏๅขƒๅ˜้‡่งฃๅ†ณๆ–นๆกˆ -- **#520** โ€”โ€” pnpm๏ผš่ฎฐๅฝ•ไบ† `pnpm approve-builds better-sqlite3` ๆญฅ้ชค +- **#513** โ€” Docker password reset: `INITIAL_PASSWORD` env var workaround documented +- **#520** โ€” pnpm: `pnpm approve-builds better-sqlite3` step documented --- -### โœ… ๅœจ v3.0.0 ไธญ่งฃๅ†ณ็š„้—ฎ้ข˜ +### โœ… Issues Resolved in v3.0.0 `#464` `#488` `#489` `#492` `#510` `#513` `#520` `#521` `#522` `#524` `#527` `#529` `#532` `#535` `#536` `#537` --- -### ๐Ÿ”€ ๅทฒๅˆๅนถ็š„็คพๅŒบ PR +### ๐Ÿ”€ Community PRs Merged -| PR | ไฝœ่€… | ๆ‘˜่ฆ | -| -------- | ------------ | --------------------------------------------------------------- | -| **#530** | @kang-heewon | ไฝฟ็”จ `OpencodeExecutor` ็š„ OpenCode Zen + Go ๆไพ›ๅ•†๏ผŒๆ”น่ฟ›ไบ†ๆต‹่ฏ• | +| PR | Author | Summary | +| -------- | ------------ | ---------------------------------------------------------------------- | +| **#530** | @kang-heewon | OpenCode Zen + Go providers with `OpencodeExecutor` and improved tests | --- ## [3.0.0-rc.7] - 2026-03-23 -### ๐Ÿ”ง ๆ”น่ฟ›๏ผˆsub2api ๅทฎ่ทๅˆ†ๆž โ€” T05, T08, T09, T13, T14๏ผ‰ +### ๐Ÿ”ง Improvements (sub2api Gap Analysis โ€” T05, T08, T09, T13, T14) -- **T05** โ€” ้™ๆตๆ•ฐๆฎๅบ“ๆŒไน…ๅŒ–๏ผš`setConnectionRateLimitUntil()`ใ€`isConnectionRateLimited()`ใ€`getRateLimitedConnections()` ๅœจ `providers.ts` ไธญใ€‚็Žฐๆœ‰็š„ `rate_limited_until` ๅˆ—็Žฐๅœจไฝœไธบไธ“็”จ API ๅ…ฌๅผ€ โ€” OAuth token ๅˆทๆ–ฐ็ปไธ่ƒฝ่งฆ็ขฐๆญคๅญ—ๆฎต๏ผŒไปฅ้˜ฒๆญข้™ๆตๅพช็Žฏใ€‚ -- **T08** โ€” ๆฏ API key ไผš่ฏ้™ๅˆถ๏ผš้€š่ฟ‡่‡ชๅŠจ่ฟ็งปๅœจ `api_keys` ไธญๆ–ฐๅขž `max_sessions INTEGER DEFAULT 0`ใ€‚`sessionManager.ts` ๆ–ฐๅขž `registerKeySession()`ใ€`unregisterKeySession()`ใ€`checkSessionLimit()` ๅ’Œ `getActiveSessionCountForKey()`ใ€‚`chatCore.js` ไธญ็š„่ฐƒ็”จๆ–นๅฏไปฅๅผบๅˆถๆ‰ง่กŒ่ฏฅ้™ๅˆถๅนถๅœจ `req.close` ๆ—ถ้€’ๅ‡ใ€‚ -- **T09** โ€” Codex ไธŽ Spark ้™ๆต่Œƒๅ›ดๅˆ†็ฆป๏ผš`codex.ts` ไธญ็š„ `getCodexModelScope()` ๅ’Œ `getCodexRateLimitKey()`ใ€‚ๆ ‡ๅ‡†ๆจกๅž‹๏ผˆ`gpt-5.x-codex`ใ€`codex-mini`๏ผ‰่Žทๅพ—่Œƒๅ›ด `"codex"`๏ผ›spark ๆจกๅž‹๏ผˆ`codex-spark*`๏ผ‰่Žทๅพ—่Œƒๅ›ด `"spark"`ใ€‚้™ๆต key ๅบ”ไธบ `${accountId}:${scope}`๏ผŒ่ฟ™ๆ ท่€—ๅฐฝไธ€ไธชๆฑ ไธไผš้˜ปๅกžๅฆไธ€ไธชใ€‚ -- **T13** โ€” ่ฟ‡ๆœŸ้…้ขๆ˜พ็คบไฟฎๅค๏ผšๅฝ“้‡็ฝฎ็ช—ๅฃๅทฒ่ฟ‡ๆ—ถ๏ผŒ`getEffectiveQuotaUsage(used, resetAt)` ่ฟ”ๅ›ž `0`๏ผ›`formatResetCountdown(resetAt)` ่ฟ”ๅ›žไบบ็ฑปๅฏ่ฏป็š„ๅ€’่ฎกๆ—ถๅญ—็ฌฆไธฒ๏ผˆไพ‹ๅฆ‚ `"2h 35m"`๏ผ‰ใ€‚ไธค่€…้ƒฝไปŽ `providers.ts` + `localDb.ts` ๅฏผๅ‡บ๏ผŒไพ›ไปช่กจ็›˜ไฝฟ็”จใ€‚ -- **T14** โ€” ไปฃ็†ๅฟซ้€Ÿๅคฑ่ดฅ๏ผšๆ–ฐๅขž `src/lib/proxyHealth.ts`๏ผŒๅŒ…ๅซ `isProxyReachable(proxyUrl, timeoutMs=2000)`๏ผˆTCP ๆฃ€ๆŸฅ๏ผŒโ‰ค2 ็ง’่€Œ้ž 30 ็ง’่ถ…ๆ—ถ๏ผ‰ใ€`getCachedProxyHealth()`ใ€`invalidateProxyHealth()` ๅ’Œ `getAllProxyHealthStatuses()`ใ€‚็ป“ๆžœ้ป˜่ฎค็ผ“ๅญ˜ 30 ็ง’๏ผ›ๅฏ้€š่ฟ‡ `PROXY_FAST_FAIL_TIMEOUT_MS` / `PROXY_HEALTH_CACHE_TTL_MS` ้…็ฝฎใ€‚ +- **T05** โ€” Rate-limit DB persistence: `setConnectionRateLimitUntil()`, `isConnectionRateLimited()`, `getRateLimitedConnections()` in `providers.ts`. The existing `rate_limited_until` column is now exposed as a dedicated API โ€” OAuth token refresh must NOT touch this field to prevent rate-limit loops. +- **T08** โ€” Per-API-key session limit: `max_sessions INTEGER DEFAULT 0` added to `api_keys` via auto-migration. `sessionManager.ts` gains `registerKeySession()`, `unregisterKeySession()`, `checkSessionLimit()`, and `getActiveSessionCountForKey()`. Callers in `chatCore.js` can enforce the limit and decrement on `req.close`. +- **T09** โ€” Codex vs Spark rate-limit scopes: `getCodexModelScope()` and `getCodexRateLimitKey()` in `codex.ts`. Standard models (`gpt-5.x-codex`, `codex-mini`) get scope `"codex"`; spark models (`codex-spark*`) get scope `"spark"`. Rate-limit keys should be `${accountId}:${scope}` so exhausting one pool doesn't block the other. +- **T13** โ€” Stale quota display fix: `getEffectiveQuotaUsage(used, resetAt)` returns `0` when the reset window has passed; `formatResetCountdown(resetAt)` returns a human-readable countdown string (e.g. `"2h 35m"`). Both exported from `providers.ts` + `localDb.ts` for dashboard consumption. +- **T14** โ€” Proxy fast-fail: new `src/lib/proxyHealth.ts` with `isProxyReachable(proxyUrl, timeoutMs=2000)` (TCP check, โ‰ค2s instead of 30s timeout), `getCachedProxyHealth()`, `invalidateProxyHealth()`, and `getAllProxyHealthStatuses()`. Results cached 30s by default; configurable via `PROXY_FAST_FAIL_TIMEOUT_MS` / `PROXY_HEALTH_CACHE_TTL_MS`. -### ๐Ÿงช ๆต‹่ฏ• +### ๐Ÿงช Tests -- ๆต‹่ฏ•ๅฅ—ไปถ๏ผš**832 ไธชๆต‹่ฏ•๏ผŒ0 ๅคฑ่ดฅ** +- Test suite: **832 tests, 0 failures** --- ## [3.0.0-rc.6] - 2026-03-23 -### ๐Ÿ”ง Bug ไฟฎๅคไธŽๆ”น่ฟ›๏ผˆsub2api ๅทฎ่ทๅˆ†ๆž โ€” T01โ€“T15๏ผ‰ +### ๐Ÿ”ง Bug Fixes & Improvements (sub2api Gap Analysis โ€” T01โ€“T15) -- **T01** โ€” `call_logs` ไธญ็š„ `requested_model` ๅˆ—๏ผˆ่ฟ็งป 009๏ผ‰๏ผš่ทŸ่ธชๅฎขๆˆท็ซฏๆœ€ๅˆ่ฏทๆฑ‚็š„ๆจกๅž‹ไธŽๅฎž้™…่ทฏ็”ฑ็š„ๆจกๅž‹ใ€‚ๅฏ็”จๅ›ž้€€้€Ÿ็Ž‡ๅˆ†ๆžใ€‚ -- **T02** โ€” ไปŽๅตŒๅฅ—็š„ `tool_result.content` ไธญๅ‰ฅ็ฆป็ฉบๆ–‡ๆœฌๅ—๏ผš้˜ฒๆญข Claude Code ้“พๅผๅทฅๅ…ท็ป“ๆžœๆ—ถๅ‡บ็Žฐ Anthropic 400 ้”™่ฏฏ๏ผˆ`text content blocks must be non-empty`๏ผ‰ใ€‚ -- **T03** โ€” ่งฃๆž `x-codex-5h-*` / `x-codex-7d-*` ่ฏทๆฑ‚ๅคด๏ผš`parseCodexQuotaHeaders()` + `getCodexResetTime()` ๆๅ– Codex ้…้ข็ช—ๅฃ๏ผŒ็”จไบŽ็ฒพ็กฎๅ†ทๅด่ฐƒๅบฆ๏ผŒ่€Œ้ž้€š็”จ็š„ 5 ๅˆ†้’Ÿๅ›ž้€€ใ€‚ -- **T04** โ€” ็”จไบŽๅค–้ƒจ็ฒ˜ๆ€ง่ทฏ็”ฑ็š„ `X-Session-Id` ่ฏทๆฑ‚ๅคด๏ผš`sessionManager.ts` ไธญ็š„ `extractExternalSessionId()` ่ฏปๅ– `x-session-id` / `x-omniroute-session` ่ฏทๆฑ‚ๅคด๏ผŒไฝฟ็”จ `ext:` ๅ‰็ผ€ไปฅ้ฟๅ…ไธŽๅ†…้ƒจ SHA-256 ไผš่ฏ ID ๅ†ฒ็ชใ€‚ๅ…ผๅฎน Nginx๏ผˆ่ฟžๅญ—็ฌฆ่ฏทๆฑ‚ๅคด๏ผ‰ใ€‚ -- **T06** โ€” ่ดฆๆˆทๅœ็”จ โ†’ ๆฐธไน…ๅฐ้”๏ผš`accountFallback.ts` ไธญ็š„ `isAccountDeactivated()` ๆฃ€ๆต‹ 401 ๅœ็”จไฟกๅทๅนถๅบ”็”จ 1 ๅนดๅ†ทๅด๏ผŒไปฅ้˜ฒๆญข้‡่ฏ•ๆฐธไน…ๅคฑๆ•ˆ็š„่ดฆๆˆทใ€‚ -- **T07** โ€” X-Forwarded-For IP ้ชŒ่ฏ๏ผšๆ–ฐๅขž `src/lib/ipUtils.ts`๏ผŒๅŒ…ๅซ `extractClientIp()` ๅ’Œ `getClientIpFromRequest()` โ€” ่ทณ่ฟ‡ `X-Forwarded-For` ้“พไธญ็š„ `unknown`/้ž IP ๆก็›ฎ๏ผˆNginx/ไปฃ็†่ฝฌๅ‘็š„่ฏทๆฑ‚๏ผ‰ใ€‚ -- **T10** โ€” ็งฏๅˆ†่€—ๅฐฝ โ†’ ็‹ฌ็ซ‹็š„ๅ›ž้€€๏ผš`accountFallback.ts` ไธญ็š„ `isCreditsExhausted()` ่ฟ”ๅ›ž 1 ๅฐๆ—ถๅ†ทๅด๏ผŒๅธฆๆœ‰ `creditsExhausted` ๆ ‡ๅฟ—๏ผŒๅŒบๅˆซไบŽ้€š็”จ็š„ 429 ้™ๆตใ€‚ -- **T11** โ€” `max` ๆŽจ็†ๅŠชๅŠ› โ†’ 131072 ้ข„็ฎ— token๏ผšๆ›ดๆ–ฐไบ† `EFFORT_BUDGETS` ๅ’Œ `THINKING_LEVEL_MAP`๏ผ›ๅๅ‘ๆ˜ ๅฐ„็Žฐๅœจไธบๅ…จ้ข„็ฎ—ๅ“ๅบ”่ฟ”ๅ›ž `"max"`ใ€‚ๅ•ๅ…ƒๆต‹่ฏ•ๅทฒๆ›ดๆ–ฐใ€‚ -- **T12** โ€” ๆ–ฐๅขž MiniMax M2.7 ๅฎšไปทๆก็›ฎ๏ผš`minimax-m2.7`ใ€`MiniMax-M2.7`ใ€`minimax-m2.7-highspeed` ๅทฒๆทปๅŠ ๅˆฐๅฎšไปท่กจ๏ผˆsub2api PR #1120๏ผ‰ใ€‚M2.5/GLM-4.7/GLM-5/Kimi ๅฎšไปทๅทฒๅญ˜ๅœจใ€‚ -- **T15** โ€” ๆ•ฐ็ป„ๅ†…ๅฎน่ง„่ŒƒๅŒ–๏ผš`openai-to-claude.ts` ไธญ็š„ `normalizeContentToString()` ่พ…ๅŠฉๅ‡ฝๆ•ฐๆญฃ็กฎๅœฐๅฐ†ๆ•ฐ็ป„ๆ ผๅผๅŒ–็š„็ณป็ปŸ/ๅทฅๅ…ทๆถˆๆฏๆŠ˜ๅ ไธบๅญ—็ฌฆไธฒ๏ผŒ็„ถๅŽๅ†ๅ‘้€็ป™ Anthropicใ€‚ +- **T01** โ€” `requested_model` column in `call_logs` (migration 009): track which model the client originally requested vs the actual routed model. Enables fallback rate analytics. +- **T02** โ€” Strip empty text blocks from nested `tool_result.content`: prevents Anthropic 400 errors (`text content blocks must be non-empty`) when Claude Code chains tool results. +- **T03** โ€” Parse `x-codex-5h-*` / `x-codex-7d-*` headers: `parseCodexQuotaHeaders()` + `getCodexResetTime()` extract Codex quota windows for precise cooldown scheduling instead of generic 5-min fallback. +- **T04** โ€” `X-Session-Id` header for external sticky routing: `extractExternalSessionId()` in `sessionManager.ts` reads `x-session-id` / `x-omniroute-session` headers with `ext:` prefix to avoid collision with internal SHA-256 session IDs. Nginx-compatible (hyphenated header). +- **T06** โ€” Account deactivated โ†’ permanent block: `isAccountDeactivated()` in `accountFallback.ts` detects 401 deactivation signals and applies a 1-year cooldown to prevent retrying permanently dead accounts. +- **T07** โ€” X-Forwarded-For IP validation: new `src/lib/ipUtils.ts` with `extractClientIp()` and `getClientIpFromRequest()` โ€” skips `unknown`/non-IP entries in `X-Forwarded-For` chains (Nginx/proxy-forwarded requests). +- **T10** โ€” Credits exhausted โ†’ distinct fallback: `isCreditsExhausted()` in `accountFallback.ts` returns 1h cooldown with `creditsExhausted` flag, distinct from generic 429 rate limiting. +- **T11** โ€” `max` reasoning effort โ†’ 131072 budget tokens: `EFFORT_BUDGETS` and `THINKING_LEVEL_MAP` updated; reverse mapping now returns `"max"` for full-budget responses. Unit test updated. +- **T12** โ€” MiniMax M2.7 pricing entries added: `minimax-m2.7`, `MiniMax-M2.7`, `minimax-m2.7-highspeed` added to pricing table (sub2api PR #1120). M2.5/GLM-4.7/GLM-5/Kimi pricing already existed. +- **T15** โ€” Array content normalization: `normalizeContentToString()` helper in `openai-to-claude.ts` correctly collapses array-formatted system/tool messages to string before sending to Anthropic. -### ๐Ÿงช ๆต‹่ฏ• +### ๐Ÿงช Tests -- ๆต‹่ฏ•ๅฅ—ไปถ๏ผš**832 ไธชๆต‹่ฏ•๏ผŒ0 ๅคฑ่ดฅ**๏ผˆไธŽ rc.5 ๆŒๅนณ๏ผ‰ +- Test suite: **832 tests, 0 failures** (unchanged from rc.5) --- ## [3.0.0-rc.5] - 2026-03-22 -### โœจ ๆ–ฐ็‰นๆ€ง +### โœจ New Features -- **#464** โ€” Registered Keys Provisioning API๏ผš่‡ชๅŠจ็ญพๅ‘ API key๏ผŒๆ”ฏๆŒๆŒ‰ๆไพ›ๅ•†ๅ’Œ่ดฆๆˆท่ฟ›่กŒ้…้ข้™ๅˆถ - - `POST /api/v1/registered-keys` โ€” ็ญพๅ‘ key๏ผŒๆ”ฏๆŒๅน‚็ญ‰ๆ€ง - - `GET /api/v1/registered-keys` โ€” ๅˆ—ๅ‡บๅทฒๆณจๅ†Œ key๏ผˆ่„ฑๆ•๏ผ‰ - - `GET /api/v1/registered-keys/{id}` โ€” ่Žทๅ– key ๅ…ƒๆ•ฐๆฎ - - `DELETE /api/v1/registered-keys/{id}` / `POST ../{id}/revoke` โ€” ๅŠ้”€ key - - `GET /api/v1/quotas/check` โ€” ็ญพๅ‘ๅ‰้ข„ๆฃ€ - - `PUT /api/v1/providers/{id}/limits` โ€” ่ฎพ็ฝฎๆไพ›ๅ•†็ญพๅ‘้™ๅˆถ - - `PUT /api/v1/accounts/{id}/limits` โ€” ่ฎพ็ฝฎ่ดฆๆˆท็ญพๅ‘้™ๅˆถ - - `POST /api/v1/issues/report` โ€” ๅฏ้€‰็š„ GitHub issue ๆŠฅๅ‘Š - - ๆ•ฐๆฎๅบ“่ฟ็งป 008๏ผš`registered_keys`ใ€`provider_key_limits`ใ€`account_key_limits` ่กจ +- **#464** โ€” Registered Keys Provisioning API: auto-issue API keys with per-provider & per-account quota enforcement + - `POST /api/v1/registered-keys` โ€” issue keys with idempotency support + - `GET /api/v1/registered-keys` โ€” list (masked) registered keys + - `GET /api/v1/registered-keys/{id}` โ€” get key metadata + - `DELETE /api/v1/registered-keys/{id}` / `POST ../{id}/revoke` โ€” revoke keys + - `GET /api/v1/quotas/check` โ€” pre-validate before issuing + - `PUT /api/v1/providers/{id}/limits` โ€” set provider issuance limits + - `PUT /api/v1/accounts/{id}/limits` โ€” set account issuance limits + - `POST /api/v1/issues/report` โ€” optional GitHub issue reporting + - DB migration 008: `registered_keys`, `provider_key_limits`, `account_key_limits` tables --- ## [3.0.0-rc.4] - 2026-03-22 -### โœจ ๆ–ฐ็‰นๆ€ง +### โœจ New Features -- **#530 (PR)** โ€” ๆ–ฐๅขž OpenCode Zen ๅ’Œ OpenCode Go ๆไพ›ๅ•†๏ผˆby @kang-heewon๏ผ‰ - - ๆ–ฐ็š„ `OpencodeExecutor`๏ผŒๆ”ฏๆŒๅคšๆ ผๅผ่ทฏ็”ฑ๏ผˆ`/chat/completions`ใ€`/messages`ใ€`/responses`๏ผ‰ - - ไธคไธชๅฑ‚็บงๅ…ฑ 7 ไธชๆจกๅž‹ +- **#530 (PR)** โ€” OpenCode Zen and OpenCode Go providers added (by @kang-heewon) + - New `OpencodeExecutor` with multi-format routing (`/chat/completions`, `/messages`, `/responses`) + - 7 models across both tiers --- ## [3.0.0-rc.3] - 2026-03-22 -### โœจ ๆ–ฐ็‰นๆ€ง +### โœจ New Features -- **#529** โ€” ๆไพ›ๅ•†ๅ›พๆ ‡็Žฐๅœจไฝฟ็”จ [@lobehub/icons](https://github.com/lobehub/lobe-icons)๏ผŒๆ”ฏๆŒไผ˜้›…็š„ PNG ๅ›ž้€€ๅ’Œ `ProviderIcon` ็ป„ไปถ๏ผˆๆ”ฏๆŒ 130+ ไธชๆไพ›ๅ•†๏ผ‰ -- **#488** โ€” ๆฏ 24 ๅฐๆ—ถ้€š่ฟ‡ `modelSyncScheduler` ่‡ชๅŠจๆ›ดๆ–ฐๆจกๅž‹ๅˆ—่กจ๏ผˆๅฏ้€š่ฟ‡ `MODEL_SYNC_INTERVAL_HOURS` ้…็ฝฎ๏ผ‰ +- **#529** โ€” Provider icons now use [@lobehub/icons](https://github.com/lobehub/lobe-icons) with graceful PNG fallback and a `ProviderIcon` component (130+ providers supported) +- **#488** โ€” Auto-update model lists every 24h via `modelSyncScheduler` (configurable via `MODEL_SYNC_INTERVAL_HOURS`) -### ๐Ÿ”ง Bug ไฟฎๅค +### ๐Ÿ”ง Bug Fixes -- **#537** โ€” Gemini CLI OAuth๏ผšๅœจ Docker/่‡ชๆ‰˜็ฎก้ƒจ็ฝฒไธญ็ผบๅฐ‘ `GEMINI_OAUTH_CLIENT_SECRET` ๆ—ถ๏ผŒ็Žฐๅœจไผšๆ˜พ็คบๆธ…ๆ™ฐไธ”ๅฏๆ“ไฝœ็š„้”™่ฏฏๆ็คบ +- **#537** โ€” Gemini CLI OAuth: now shows clear actionable error when `GEMINI_OAUTH_CLIENT_SECRET` is missing in Docker/self-hosted deployments --- ## [3.0.0-rc.2] - 2026-03-22 -### ๐Ÿ”ง Bug ไฟฎๅค +### ๐Ÿ”ง Bug Fixes -- **#536** โ€” LongCat AI key ้ชŒ่ฏ๏ผšไฟฎๅคไบ† baseUrl๏ผˆ`api.longcat.chat/openai`๏ผ‰ๅ’Œ authHeader๏ผˆ`Authorization: Bearer`๏ผ‰ -- **#535** โ€” ๅ›บๅฎšๆจกๅž‹่ฆ†็›–๏ผšๅฝ“ context-cache ไฟๆŠคๆฃ€ๆต‹ๅˆฐๅ›บๅฎšๆจกๅž‹ๆ—ถ๏ผŒ`body.model` ็Žฐๅœจ่ฎพ็ฝฎไธบ `pinnedModel` -- **#524** โ€” OpenCode ้…็ฝฎ็Žฐๅœจๆญฃ็กฎไฟๅญ˜๏ผšๆทปๅŠ ไบ† `saveOpenCodeConfig()` ๅค„็†ๅ™จ๏ผˆXDG_CONFIG_HOME ๆ„Ÿ็Ÿฅ๏ผŒๅ†™ๅ…ฅ TOML ๆ ผๅผ๏ผ‰ +- **#536** โ€” LongCat AI key validation: fixed baseUrl (`api.longcat.chat/openai`) and authHeader (`Authorization: Bearer`) +- **#535** โ€” Pinned model override: `body.model` is now set to `pinnedModel` when context-cache protection detects a pinned model +- **#524** โ€” OpenCode config now saved correctly: added `saveOpenCodeConfig()` handler (XDG_CONFIG_HOME aware, writes TOML) --- ## [3.0.0-rc.1] - 2026-03-22 -### ๐Ÿ”ง Bug ไฟฎๅค +### ๐Ÿ”ง Bug Fixes -- **#521** โ€” ่ทณ่ฟ‡ๅฏ†็ ่ฎพ็ฝฎๅŽ็™ปๅฝ•ไธๅ†ๅกๆญป๏ผˆ้‡ๅฎšๅ‘ๅˆฐๅผ•ๅฏผ้กต้ข๏ผ‰ -- **#522** โ€” API Manager๏ผš็งป้™คไบ†ๅ…ทๆœ‰่ฏฏๅฏผๆ€ง็š„ "Copy masked key" ๆŒ‰้’ฎ๏ผˆๆ›ฟๆขไธบ้”ๅ›พๆ ‡ๆ็คบ๏ผ‰ -- **#527** โ€” Claude Code + Codex ่ถ…็บง่ƒฝๅŠ›ๅพช็Žฏ๏ผš`tool_result` ๅ—็Žฐๅœจ่ฝฌๆขไธบๆ–‡ๆœฌ่€Œไธๆ˜ฏ่ขซไธขๅผƒ -- **#532** โ€” OpenCode GO API key ้ชŒ่ฏ็Žฐๅœจไฝฟ็”จๆญฃ็กฎ็š„ `zen/v1` ็ซฏ็‚น๏ผˆ`testKeyBaseUrl`๏ผ‰ -- **#489** โ€” Antigravity๏ผš็ผบๅฐ‘ `googleProjectId` ๆ—ถ่ฟ”ๅ›ž็ป“ๆž„ๅŒ–็š„ 422 ้”™่ฏฏ๏ผŒ้™„ๅธฆ้‡ๆ–ฐ่ฟžๆŽฅๆŒ‡ๅฏผ -- **#510** โ€” Windows๏ผšMSYS2/Git-Bash ่ทฏๅพ„๏ผˆ`/c/Program Files/...`๏ผ‰็Žฐๅœจ่‡ชๅŠจ่ง„่ŒƒๅŒ–ไธบ `C:\\Program Files\\...` -- **#492** โ€” `omniroute` CLI ็Žฐๅœจๅœจ `app/server.js` ็ผบๅคฑๆ—ถ่ƒฝๆฃ€ๆต‹ `mise`/`nvm`๏ผŒๅนถๆ˜พ็คบ้’ˆๅฏนๆ€ง็š„ไฟฎๅค่ฏดๆ˜Ž +- **#521** โ€” Login no longer gets stuck after skipping password setup (redirects to onboarding) +- **#522** โ€” API Manager: Removed misleading "Copy masked key" button (replaced with lock icon tooltip) +- **#527** โ€” Claude Code + Codex superpowers loop: `tool_result` blocks now converted to text instead of dropped +- **#532** โ€” OpenCode GO API key validation now uses the correct `zen/v1` endpoint (`testKeyBaseUrl`) +- **#489** โ€” Antigravity: missing `googleProjectId` returns structured 422 error with reconnect guidance +- **#510** โ€” Windows: MSYS2/Git-Bash paths (`/c/Program Files/...`) are now normalized to `C:\\Program Files\\...` +- **#492** โ€” `omniroute` CLI now detects `mise`/`nvm` when `app/server.js` is missing and shows targeted fix -### ๐Ÿ“– ๆ–‡ๆกฃ +### ๆ–‡ๆกฃ -- **#513** โ€”โ€” Docker ๅฏ†็ ้‡็ฝฎ๏ผš่ฎฐๅฝ•ไบ† `INITIAL_PASSWORD` ็Žฏๅขƒๅ˜้‡่งฃๅ†ณๆ–นๆกˆ -- **#520** โ€”โ€” pnpm๏ผš่ฎฐๅฝ•ไบ† `pnpm approve-builds better-sqlite3` ๆญฅ้ชค +- **#513** โ€” Docker password reset: `INITIAL_PASSWORD` env var workaround documented +- **#520** โ€” pnpm: `pnpm approve-builds better-sqlite3` documented -### โœ… ๅทฒๅ…ณ้—ญ็š„้—ฎ้ข˜ +### โœ… Closed Issues #489, #492, #510, #513, #520, #521, #522, #525, #527, #532 @@ -1323,665 +1347,665 @@ OmniRoute ็Žฐๅœจๆฏ **24 ๅฐๆ—ถ**่‡ชๅŠจๅˆทๆ–ฐๅทฒ่ฟžๆŽฅๆไพ›ๅ•†็š„ๆจกๅž‹ๅˆ—่กจ ## [2.9.5] โ€” 2026-03-22 -> Sprint๏ผšๆ–ฐๅขž OpenCode ๆไพ›ๅ•†ใ€embedding ๅ‡ญ่ฏไฟฎๅคใ€CLI ่„ฑๆ• key bugใ€CACHE_TAG_PATTERN ไฟฎๅคใ€‚ +> Sprint: New OpenCode providers, embedding credentials fix, CLI masked key bug, CACHE_TAG_PATTERN fix. -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **CLI ๅทฅๅ…ทๅฐ†่„ฑๆ• API key ไฟๅญ˜ๅˆฐ้…็ฝฎๆ–‡ไปถ** โ€” `claude-settings`ใ€`cline-settings` ๅ’Œ `openclaw-settings` POST ่ทฏ็”ฑ็ŽฐๅœจๆŽฅๅ— `keyId` ๅ‚ๆ•ฐ๏ผŒๅนถๅœจๅ†™ๅ…ฅ็ฃ็›˜ๅ‰ไปŽๆ•ฐๆฎๅบ“่งฃๆž็œŸๅฎž API keyใ€‚`ClaudeToolCard` ๆ›ดๆ–ฐไธบๅ‘้€ `keyId` ่€Œไธๆ˜ฏ่„ฑๆ•ๆ˜พ็คบๅญ—็ฌฆไธฒใ€‚ไฟฎๅค #523ใ€#526ใ€‚ -- **่‡ชๅฎšไน‰ embedding ๆไพ›ๅ•†๏ผš`No credentials` ้”™่ฏฏ** โ€” `/v1/embeddings` ็Žฐๅœจๅฐ† `credentialsProviderId` ไธŽ่ทฏ็”ฑๅ‰็ผ€ๅˆ†ๅผ€่ทŸ่ธช๏ผŒๅ› ๆญคๅ‡ญ่ฏไปŽๅŒน้…็š„ๆไพ›ๅ•†่Š‚็‚น ID ่Žทๅ–๏ผŒ่€Œไธๆ˜ฏไปŽๅ…ฌๅผ€ๅ‰็ผ€ๅญ—็ฌฆไธฒ่Žทๅ–ใ€‚ไฟฎๅคไบ†ไธ€ไธชๅ›žๅฝ’้—ฎ้ข˜๏ผš`google/gemini-embedding-001` ๅ’Œ็ฑปไผผ็š„่‡ชๅฎšไน‰ๆไพ›ๅ•†ๆจกๅž‹ๆ€ปๆ˜ฏไผšๅ› ๅ‡ญ่ฏ้”™่ฏฏ่€Œๅคฑ่ดฅใ€‚ไฟฎๅค #532 ็›ธๅ…ณ้—ฎ้ข˜ใ€‚๏ผˆPR #528 by @jacob2826๏ผ‰ -- **Context ็ผ“ๅญ˜ไฟๆŠคๆญฃๅˆ™่กจ่พพๅผ้—ๆผ `\n` ๅ‰็ผ€** โ€” `comboAgentMiddleware.ts` ไธญ็š„ `CACHE_TAG_PATTERN` ๆ›ดๆ–ฐไธบๅŒๆ—ถๅŒน้…ๅญ—้ข้‡ `\n`๏ผˆๅๆ–œๆ -n๏ผ‰ๅ’Œๅฎž้™…็š„ๆข่กŒ็ฌฆ U+000A๏ผŒ`combo.ts` ๆตๅผไผ ่พ“ๅœจไฟฎๅค #515 ๅŽไผšๅœจ `` ๆ ‡็ญพๅ‘จๅ›ดๆณจๅ…ฅ่ฟ™ไบ›ๅญ—็ฌฆใ€‚ไฟฎๅค #531ใ€‚ +- **CLI tools save masked API key to config files** โ€” `claude-settings`, `cline-settings`, and `openclaw-settings` POST routes now accept a `keyId` param and resolve the real API key from DB before writing to disk. `ClaudeToolCard` updated to send `keyId` instead of the masked display string. Fixes #523, #526. +- **Custom embedding providers: `No credentials` error** โ€” `/v1/embeddings` now tracks `credentialsProviderId` separately from the routing prefix, so credentials are fetched from the matching provider node ID rather than the public prefix string. Fixes a regression where `google/gemini-embedding-001` and similar custom-provider models would always fail with a credentials error. Fixes #532-related. (PR #528 by @jacob2826) +- **Context cache protection regex misses `\n` prefix** โ€” `CACHE_TAG_PATTERN` in `comboAgentMiddleware.ts` updated to match both literal `\n` (backslash-n) and actual newline U+000A that `combo.ts` streaming injects around the `` tag after fix #515. Fixes #531. -### โœจ ๆ–ฐๆไพ›ๅ•† +### โœจ New Providers -- **OpenCode Zen** โ€” ๅ…่ดนๅฑ‚็ฝ‘ๅ…ณไฝไบŽ `opencode.ai/zen/v1`๏ผŒๆไพ› 3 ไธชๆจกๅž‹๏ผš`minimax-m2.5-free`ใ€`big-pickle`ใ€`gpt-5-nano` -- **OpenCode Go** โ€” ่ฎข้˜…ๆœๅŠกไฝไบŽ `opencode.ai/zen/go/v1`๏ผŒๆไพ› 4 ไธชๆจกๅž‹๏ผš`glm-5`ใ€`kimi-k2.5`ใ€`minimax-m2.7`๏ผˆClaude ๆ ผๅผ๏ผ‰ใ€`minimax-m2.5`๏ผˆClaude ๆ ผๅผ๏ผ‰ -- ไธคไธชๆไพ›ๅ•†้ƒฝไฝฟ็”จๆ–ฐ็š„ `OpencodeExecutor`๏ผŒๆ นๆฎ่ฏทๆฑ‚็š„ๆจกๅž‹ๅŠจๆ€่ทฏ็”ฑๅˆฐ `/chat/completions`ใ€`/messages`ใ€`/responses` ๆˆ– `/models/{model}:generateContent`ใ€‚๏ผˆPR #530 by @kang-heewon๏ผ‰ +- **OpenCode Zen** โ€” Free tier gateway at `opencode.ai/zen/v1` with 3 models: `minimax-m2.5-free`, `big-pickle`, `gpt-5-nano` +- **OpenCode Go** โ€” Subscription service at `opencode.ai/zen/go/v1` with 4 models: `glm-5`, `kimi-k2.5`, `minimax-m2.7` (Claude format), `minimax-m2.5` (Claude format) +- Both providers use the new `OpencodeExecutor` which routes dynamically to `/chat/completions`, `/messages`, `/responses`, or `/models/{model}:generateContent` based on the requested model. (PR #530 by @kang-heewon) --- ## [2.9.4] โ€” 2026-03-21 -> Sprint๏ผšBug ไฟฎๅค โ€” ไฟ็•™ Codex prompt ็ผ“ๅญ˜ keyใ€ไฟฎๅค tagContent JSON ่ฝฌไน‰ใ€ๅฐ†่ฟ‡ๆœŸ token ็Šถๆ€ๅŒๆญฅๅ›žๆ•ฐๆฎๅบ“ใ€‚ +> Sprint: Bug fixes โ€” preserve Codex prompt cache key, fix tagContent JSON escaping, sync expired token status to DB. -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **fix(translator)**๏ผšๅœจ Responses API โ†’ Chat Completions ็ฟป่ฏ‘ไธญไฟ็•™ `prompt_cache_key`๏ผˆ#517๏ผ‰ - โ€” ่ฏฅๅญ—ๆฎตๆ˜ฏ Codex ไฝฟ็”จ็š„็ผ“ๅญ˜ไบฒๅ’Œๆ€งไฟกๅท๏ผ›ๅ‰ฅ็ฆปๅฎƒไผš้˜ปๆญข prompt ็ผ“ๅญ˜ๅ‘ฝไธญใ€‚ - ๅœจ `openai-responses.ts` ๅ’Œ `responsesApiHelper.ts` ไธญไฟฎๅคใ€‚ +- **fix(translator)**: Preserve `prompt_cache_key` in Responses API โ†’ Chat Completions translation (#517) + โ€” The field is a cache-affinity signal used by Codex; stripping it was preventing prompt cache hits. + Fixed in `openai-responses.ts` and `responsesApiHelper.ts`. -- **fix(combo)**๏ผš่ฝฌไน‰ `tagContent` ไธญ็š„ `\n`๏ผŒไฝฟๆณจๅ…ฅ็š„ JSON ๅญ—็ฌฆไธฒๆœ‰ๆ•ˆ๏ผˆ#515๏ผ‰ - โ€” ๆจกๆฟๅญ—้ข้‡ๆข่กŒ็ฌฆ๏ผˆU+000A๏ผ‰ไธๅ…่ฎธๅœจ JSON ๅญ—็ฌฆไธฒๅ€ผไธญไธ่ฝฌไน‰ไฝฟ็”จใ€‚ - ๅœจ `open-sse/services/combo.ts` ไธญๆ›ฟๆขไธบ `\\n` ๅญ—้ข้‡ๅบๅˆ—ใ€‚ +- **fix(combo)**: Escape `\n` in `tagContent` so injected JSON string is valid (#515) + โ€” Template literal newlines (U+000A) are not allowed unescaped inside JSON string values. + Replaced with `\\n` literal sequences in `open-sse/services/combo.ts`. -- **fix(usage)**๏ผšๅœจๅฎžๆ—ถ่ฎค่ฏๅคฑ่ดฅๆ—ถๅฐ†่ฟ‡ๆœŸ token ็Šถๆ€ๅŒๆญฅๅ›žๆ•ฐๆฎๅบ“๏ผˆ#491๏ผ‰ - โ€” ๅฝ“ Limits & Quotas ๅฎžๆ—ถๆฃ€ๆŸฅ่ฟ”ๅ›ž 401/403 ๆ—ถ๏ผŒ่ฟžๆŽฅ็š„ `testStatus` ็Žฐๅœจไผšๆ›ดๆ–ฐ - ไธบๆ•ฐๆฎๅบ“ไธญ็š„ `"expired"`๏ผŒไปฅไพฟๆไพ›ๅ•†้กต้ขๅๆ˜ ็›ธๅŒ็š„้™็บง็Šถๆ€ใ€‚ - ๅœจ `src/app/api/usage/[connectionId]/route.ts` ไธญไฟฎๅคใ€‚ +- **fix(usage)**: Sync expired token status back to DB on live auth failure (#491) + โ€” When the Limits & Quotas live check returns 401/403, the connection `testStatus` is now updated + to `"expired"` in the database so the Providers page reflects the same degraded state. + Fixed in `src/app/api/usage/[connectionId]/route.ts`. --- ## [2.9.3] โ€” 2026-03-21 -> Sprint๏ผšๆ–ฐๅขž 5 ไธชๅ…่ดน AI ๆไพ›ๅ•† โ€” LongCatใ€Pollinationsใ€Cloudflare AIใ€Scalewayใ€AI/ML APIใ€‚ +> Sprint: Add 5 new free AI providers โ€” LongCat, Pollinations, Cloudflare AI, Scaleway, AI/ML API. -### โœจ ๆ–ฐๆไพ›ๅ•† +### โœจ New Providers -- **feat(providers/longcat)**๏ผšๆ–ฐๅขž LongCat AI๏ผˆ`lc/`๏ผ‰โ€” ๅ…ฌๆต‹ๆœŸ้—ดๆฏๅคฉ 5000 ไธ‡ tokens ๅ…่ดน๏ผˆFlash-Lite๏ผ‰+ 50 ไธ‡/ๅคฉ๏ผˆChat/Thinking๏ผ‰ใ€‚OpenAI ๅ…ผๅฎน๏ผŒๆ ‡ๅ‡† Bearer ่ฎค่ฏใ€‚ -- **feat(providers/pollinations)**๏ผšๆ–ฐๅขž Pollinations AI๏ผˆ`pol/`๏ผ‰โ€” ๆ— ้œ€ API keyใ€‚ไปฃ็† GPT-5ใ€Claudeใ€Geminiใ€DeepSeek V3ใ€Llama 4๏ผˆ1 ๆฌก/15 ็ง’ๅ…่ดน๏ผ‰ใ€‚่‡ชๅฎšไน‰ๆ‰ง่กŒๅ™จๅค„็†ๅฏ้€‰่ฎค่ฏใ€‚ -- **feat(providers/cloudflare-ai)**๏ผšๆ–ฐๅขž Cloudflare Workers AI๏ผˆ`cf/`๏ผ‰โ€” ๆฏๅคฉ 10K Neurons ๅ…่ดน๏ผˆ็บฆ 150 ๆฌก LLM ๅ“ๅบ”ๆˆ– 500 ็ง’ Whisper ้Ÿณ้ข‘๏ผ‰ใ€‚ๅ…จ็ƒ่พน็ผ˜ 50+ ๆจกๅž‹ใ€‚่‡ชๅฎšไน‰ๆ‰ง่กŒๅ™จไปŽๅ‡ญ่ฏไธญๆž„ๅปบๅธฆ `accountId` ็š„ๅŠจๆ€ URLใ€‚ -- **feat(providers/scaleway)**๏ผšๆ–ฐๅขž Scaleway ็”Ÿๆˆๅผ API๏ผˆ`scw/`๏ผ‰โ€” ๆ–ฐ่ดฆๆˆท 100 ไธ‡ๅ…่ดน tokensใ€‚็ฌฆๅˆ EU/GDPR๏ผˆๅทด้ปŽ๏ผ‰ใ€‚Qwen3 235Bใ€Llama 3.1 70Bใ€Mistral Small 3.2ใ€‚ -- **feat(providers/aimlapi)**๏ผšๆ–ฐๅขž AI/ML API๏ผˆ`aiml/`๏ผ‰โ€” ๆฏๅคฉ $0.025 ๅ…่ดน้ขๅบฆ๏ผŒ200+ ๆจกๅž‹๏ผˆGPT-4oใ€Claudeใ€Geminiใ€Llama๏ผ‰๏ผŒ้€š่ฟ‡ๅ•ไธ€่šๅˆ็ซฏ็‚นใ€‚ +- **feat(providers/longcat)**: Add LongCat AI (`lc/`) โ€” 50M tokens/day free (Flash-Lite) + 500K/day (Chat/Thinking) during public beta. OpenAI-compatible, standard Bearer auth. +- **feat(providers/pollinations)**: Add Pollinations AI (`pol/`) โ€” no API key required. Proxies GPT-5, Claude, Gemini, DeepSeek V3, Llama 4 (1 req/15s free). Custom executor handles optional auth. +- **feat(providers/cloudflare-ai)**: Add Cloudflare Workers AI (`cf/`) โ€” 10K Neurons/day free (~150 LLM responses or 500s Whisper audio). 50+ models on global edge. Custom executor builds dynamic URL with `accountId` from credentials. +- **feat(providers/scaleway)**: Add Scaleway Generative APIs (`scw/`) โ€” 1M free tokens for new accounts. EU/GDPR compliant (Paris). Qwen3 235B, Llama 3.1 70B, Mistral Small 3.2. +- **feat(providers/aimlapi)**: Add AI/ML API (`aiml/`) โ€” $0.025/day free credit, 200+ models (GPT-4o, Claude, Gemini, Llama) via single aggregator endpoint. -### ๐Ÿ”„ ๆไพ›ๅ•†ๆ›ดๆ–ฐ +### ๐Ÿ”„ Provider Updates -- **feat(providers/together)**๏ผšๆ–ฐๅขž `hasFree: true` + 3 ไธชๆฐธไน…ๅ…่ดนๆจกๅž‹ ID๏ผš`Llama-3.3-70B-Instruct-Turbo-Free`ใ€`Llama-Vision-Free`ใ€`DeepSeek-R1-Distill-Llama-70B-Free` -- **feat(providers/gemini)**๏ผšๆ–ฐๅขž `hasFree: true` + `freeNote`๏ผˆๆฏๅคฉ 1500 ๆฌก่ฏทๆฑ‚๏ผŒๆ— ้œ€ไฟก็”จๅก๏ผŒaistudio.google.com๏ผ‰ -- **chore(providers/gemini)**๏ผšๅฐ†ๆ˜พ็คบๅ็งฐ้‡ๅ‘ฝๅไธบ `Gemini (Google AI Studio)` ไปฅๆ้ซ˜ๆธ…ๆ™ฐๅบฆ +- **feat(providers/together)**: Add `hasFree: true` + 3 permanently free model IDs: `Llama-3.3-70B-Instruct-Turbo-Free`, `Llama-Vision-Free`, `DeepSeek-R1-Distill-Llama-70B-Free` +- **feat(providers/gemini)**: Add `hasFree: true` + `freeNote` (1,500 req/day, no credit card needed, aistudio.google.com) +- **chore(providers/gemini)**: Rename display name to `Gemini (Google AI Studio)` for clarity -### โš™๏ธ ๅŸบ็ก€่ฎพๆ–ฝ +### โš™๏ธ Infrastructure -- **feat(executors/pollinations)**๏ผšๆ–ฐๅขž `PollinationsExecutor` โ€” ๆœชๆไพ› API key ๆ—ถ็œ็•ฅ `Authorization` ่ฏทๆฑ‚ๅคด -- **feat(executors/cloudflare-ai)**๏ผšๆ–ฐๅขž `CloudflareAIExecutor` โ€” ๅŠจๆ€ URL ๆž„ๅปบ้œ€่ฆๆไพ›ๅ•†ๅ‡ญ่ฏไธญ็š„ `accountId` -- **feat(executors)**๏ผšๆณจๅ†Œ `pollinations`ใ€`pol`ใ€`cloudflare-ai`ใ€`cf` ๆ‰ง่กŒๅ™จๆ˜ ๅฐ„ +- **feat(executors/pollinations)**: New `PollinationsExecutor` โ€” omits `Authorization` header when no API key provided +- **feat(executors/cloudflare-ai)**: New `CloudflareAIExecutor` โ€” dynamic URL construction requires `accountId` in provider credentials +- **feat(executors)**: Register `pollinations`, `pol`, `cloudflare-ai`, `cf` executor mappings -### ๐Ÿ“ ๆ–‡ๆกฃ +### ๆ–‡ๆกฃ -- **docs(readme)**๏ผšๅฐ†ๅ…่ดน combo ๆ ˆๆ‰ฉๅฑ•ๅˆฐ 11 ไธชๆไพ›ๅ•†๏ผˆๆฐธไน… $0๏ผ‰ -- **docs(readme)**๏ผšๆ–ฐๅขž 4 ไธชๅ…่ดนๆไพ›ๅ•†้ƒจๅˆ†๏ผˆLongCatใ€Pollinationsใ€Cloudflare AIใ€Scaleway๏ผ‰๏ผŒ้™„ๅธฆๆจกๅž‹่กจ -- **docs(readme)**๏ผšๆ›ดๆ–ฐๅฎšไปท่กจ๏ผŒๆ–ฐๅขž 4 ไธชๅ…่ดนๅฑ‚่กŒ -- **docs(i18n/pt-BR)**๏ผšๆ›ดๆ–ฐๅฎšไปท่กจ + ๆ–ฐๅขž่‘ก่„็‰™่ฏญ็š„ LongCat/Pollinations/Cloudflare AI/Scaleway ้ƒจๅˆ† -- **docs(new-features/ai)**๏ผš10 ไธชไปปๅŠก่ง„่Œƒๆ–‡ไปถ + ไธปๅฎž็Žฐ่ฎกๅˆ’๏ผŒไฝไบŽ `docs/new-features/ai/` +- **docs(readme)**: Expanded free combo stack to 11 providers ($0 forever) +- **docs(readme)**: Added 4 new free provider sections (LongCat, Pollinations, Cloudflare AI, Scaleway) with model tables +- **docs(readme)**: Updated pricing table with 4 new free tier rows +- **docs(i18n/pt-BR)**: Updated pricing table + added LongCat/Pollinations/Cloudflare AI/Scaleway sections in Portuguese +- **docs(new-features/ai)**: 10 task spec files + master implementation plan in `docs/new-features/ai/` -### ๐Ÿงช ๆต‹่ฏ• +### ๐Ÿงช Tests -- ๆต‹่ฏ•ๅฅ—ไปถ๏ผš**821 ไธชๆต‹่ฏ•๏ผŒ0 ๅคฑ่ดฅ**๏ผˆไธๅ˜๏ผ‰ +- Test suite: **821 tests, 0 failures** (unchanged) --- ## [2.9.2] โ€” 2026-03-21 -> Sprint๏ผšไฟฎๅคๅช’ไฝ“่ฝฌๅฝ•๏ผˆDeepgram/HuggingFace Content-Typeใ€่ฏญ่จ€ๆฃ€ๆต‹๏ผ‰ๅ’Œ TTS ้”™่ฏฏๆ˜พ็คบใ€‚ +> Sprint: Fix media transcription (Deepgram/HuggingFace Content-Type, language detection) and TTS error display. -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **fix(transcription)**๏ผšDeepgram ๅ’Œ HuggingFace ้Ÿณ้ข‘่ฝฌๅฝ•็Žฐๅœจ้€š่ฟ‡ๆ–ฐ็š„ `resolveAudioContentType()` ่พ…ๅŠฉๅ‡ฝๆ•ฐๆญฃ็กฎๆ˜ ๅฐ„ `video/mp4` โ†’ `audio/mp4` ๅŠๅ…ถไป–ๅช’ไฝ“ MIME ็ฑปๅž‹ใ€‚ๆญคๅ‰ไธŠไผ  `.mp4` ๆ–‡ไปถๅง‹็ปˆ่ฟ”ๅ›ž "No speech detected"๏ผŒๅ› ไธบ Deepgram ๆ”ถๅˆฐ็š„ๆ˜ฏ `Content-Type: video/mp4`ใ€‚ -- **fix(transcription)**๏ผšๅ‘ Deepgram ่ฏทๆฑ‚ๆทปๅŠ ไบ† `detect_language=true` โ€”โ€” ่‡ชๅŠจๆฃ€ๆต‹้Ÿณ้ข‘่ฏญ่จ€๏ผˆ่‘ก่„็‰™่ฏญใ€่ฅฟ็ญ็‰™่ฏญ็ญ‰๏ผ‰๏ผŒ่€Œไธๆ˜ฏ้ป˜่ฎคไฝฟ็”จ่‹ฑ่ฏญใ€‚ไฟฎๅคไบ†้ž่‹ฑ่ฏญ่ฝฌๅฝ•่ฟ”ๅ›ž็ฉบๆˆ–ๅžƒๅœพ็ป“ๆžœ็š„้—ฎ้ข˜ใ€‚ -- **fix(transcription)**๏ผšๅ‘ Deepgram ่ฏทๆฑ‚ๆทปๅŠ ไบ† `punctuate=true`๏ผŒ็”จไบŽๆ›ด้ซ˜่ดจ้‡็š„่ฝฌๅฝ•่พ“ๅ‡บ๏ผŒๅธฆๆœ‰ๆญฃ็กฎ็š„ๆ ‡็‚น็ฌฆๅทใ€‚ -- **fix(tts)**๏ผšไฟฎๅคไบ† `audioSpeech.ts` ๅ’Œ `audioTranscription.ts` ไธญ Text-to-Speech ๅ“ๅบ”็š„ `[object Object]` ้”™่ฏฏๆ˜พ็คบใ€‚`upstreamErrorResponse()` ๅ‡ฝๆ•ฐ็Žฐๅœจๆญฃ็กฎๅœฐไปŽ ElevenLabs ็ญ‰ๆไพ›ๅ•†่ฟ”ๅ›ž็š„ๅตŒๅฅ—้”™่ฏฏๆถˆๆฏ๏ผˆๅฆ‚ `{ error: { message: "...", status_code: 401 } }`๏ผ‰ไธญๆๅ–ๅญ—็ฌฆไธฒๆถˆๆฏ๏ผŒ่€Œไธๆ˜ฏๆ‰ๅนณ้”™่ฏฏๅญ—็ฌฆไธฒใ€‚ +- **fix(transcription)**: Deepgram and HuggingFace audio transcription now correctly map `video/mp4` โ†’ `audio/mp4` and other media MIME types via new `resolveAudioContentType()` helper. Previously, uploading `.mp4` files consistently returned "No speech detected" because Deepgram was receiving `Content-Type: video/mp4`. +- **fix(transcription)**: Added `detect_language=true` to Deepgram requests โ€” auto-detects audio language (Portuguese, Spanish, etc.) instead of defaulting to English. Fixes non-English transcriptions returning empty or garbage results. +- **fix(transcription)**: Added `punctuate=true` to Deepgram requests for higher-quality transcription output with correct punctuation. +- **fix(tts)**: `[object Object]` error display in Text-to-Speech responses fixed in both `audioSpeech.ts` and `audioTranscription.ts`. The `upstreamErrorResponse()` function now correctly extracts nested string messages from providers like ElevenLabs that return `{ error: { message: "...", status_code: 401 } }` instead of a flat error string. -### ๐Ÿงช ๆต‹่ฏ• +### ๐Ÿงช Tests -- ๆต‹่ฏ•ๅฅ—ไปถ๏ผš**821 ไธชๆต‹่ฏ•๏ผŒ0 ๅคฑ่ดฅ**๏ผˆไธๅ˜๏ผ‰ +- Test suite: **821 tests, 0 failures** (unchanged) -### ้—ฎ้ข˜ๅˆ†็ฑป +### Triaged Issues -- **#508** โ€” ๅทฅๅ…ท่ฐƒ็”จๆ ผๅผๅ›žๅฝ’๏ผš่ฏทๆฑ‚ไปฃ็†ๆ—ฅๅฟ—ๅ’Œๆไพ›ๅ•†้“พไฟกๆฏ๏ผˆ`needs-info`๏ผ‰ -- **#510** โ€” Windows CLI ๅฅๅบทๆฃ€ๆŸฅ่ทฏๅพ„๏ผš่ฏทๆฑ‚ shell/Node ็‰ˆๆœฌไฟกๆฏ๏ผˆ`needs-info`๏ผ‰ -- **#485** โ€” Kiro MCP ๅทฅๅ…ท่ฐƒ็”จ๏ผšไฝœไธบๅค–้ƒจ Kiro ้—ฎ้ข˜ๅ…ณ้—ญ๏ผˆ้ž OmniRoute๏ผ‰ -- **#442** โ€” Baseten /models ็ซฏ็‚น๏ผšๅทฒๅ…ณ้—ญ๏ผˆ่ฎฐๅฝ•ไบ†ๆ‰‹ๅŠจ่งฃๅ†ณๆ–นๆกˆ๏ผ‰ -- **#464** โ€” Key provisioning API๏ผš็กฎ่ฎคไธบ่ทฏ็บฟๅ›พ้กน็›ฎ +- **#508** โ€” Tool call format regression: requested proxy logs and provider chain info (`needs-info`) +- **#510** โ€” Windows CLI healthcheck path: requested shell/Node version info (`needs-info`) +- **#485** โ€” Kiro MCP tool calls: closed as external Kiro issue (not OmniRoute) +- **#442** โ€” Baseten /models endpoint: closed (documented manual workaround) +- **#464** โ€” Key provisioning API: acknowledged as roadmap item --- ## [2.9.1] โ€” 2026-03-21 -> Sprint๏ผšไฟฎๅค SSE omniModel ๆ•ฐๆฎไธขๅคฑ๏ผŒๅˆๅนถๆฏๅ่ฎฎๆจกๅž‹ๅ…ผๅฎนๆ€งใ€‚ +> Sprint: Fix SSE omniModel data loss, merge per-protocol model compatibility. -### Bug ไฟฎๅค +### Bug Fixes -- **#511** โ€” ๅ…ณ้”ฎ้—ฎ้ข˜๏ผš`` ๆ ‡็ญพๅœจ SSE ๆตไธญๅœจ `finish_reason:stop` ไน‹ๅŽๅ‘้€๏ผŒๅฏผ่‡ดๆ•ฐๆฎไธขๅคฑใ€‚็Žฐๅœจๆ ‡็ญพไผšๆณจๅ…ฅๅˆฐ้ฆ–ไธช้ž็ฉบๅ†…ๅฎน chunk ไธญ๏ผŒ็กฎไฟๅœจ SDK ๅ…ณ้—ญ่ฟžๆŽฅไน‹ๅ‰ๅฎŒๆˆไบคไป˜ใ€‚ +- **#511** โ€” Critical: `` tag was sent after `finish_reason:stop` in SSE streams, causing data loss. Tag is now injected into the first non-empty content chunk, guaranteeing delivery before SDKs close the connection. -### ๅทฒๅˆๅนถ็š„ PR +### Merged PRs -- **PR #512**๏ผˆ@zhangqiang8vip๏ผ‰๏ผšๆฏๅ่ฎฎๆจกๅž‹ๅ…ผๅฎนๆ€ง โ€” `normalizeToolCallId` ๅ’Œ `preserveOpenAIDeveloperRole` ็ŽฐๅœจๅฏไปฅๆŒ‰ๅฎขๆˆท็ซฏๅ่ฎฎ๏ผˆOpenAIใ€Claudeใ€Responses API๏ผ‰้…็ฝฎใ€‚ๆจกๅž‹้…็ฝฎไธญๆ–ฐๅขž `compatByProtocol` ๅญ—ๆฎต๏ผŒๅธฆ Zod ้ชŒ่ฏใ€‚ +- **PR #512** (@zhangqiang8vip): Per-protocol model compatibility โ€” `normalizeToolCallId` and `preserveOpenAIDeveloperRole` can now be configured per client protocol (OpenAI, Claude, Responses API). New `compatByProtocol` field in model config with Zod validation. -### ้—ฎ้ข˜ๅˆ†็ฑป +### Triaged Issues -- **#510** โ€” Windows CLI healthcheck_failed๏ผš่ฏทๆฑ‚ PATH/version ไฟกๆฏ -- **#509** โ€” Turbopack Electron ๅ›žๅฝ’๏ผšไธŠๆธธ Next.js bug๏ผŒๅทฒ่ฎฐๅฝ•่งฃๅ†ณๆ–นๆกˆ -- **#508** โ€” macOS ้ป‘ๅฑ๏ผšๅปบ่ฎฎ `--disable-gpu` ่งฃๅ†ณๆ–นๆกˆ +- **#510** โ€” Windows CLI healthcheck_failed: requested PATH/version info +- **#509** โ€” Turbopack Electron regression: upstream Next.js bug, documented workarounds +- **#508** โ€” macOS black screen: suggested `--disable-gpu` workaround --- ## [2.9.0] โ€” 2026-03-20 -> Sprint๏ผš่ทจๅนณๅฐ machineId ไฟฎๅคใ€ๆฏ API key ้™ๆตใ€ๆตๅผ context ็ผ“ๅญ˜ใ€Alibaba DashScopeใ€ๆœ็ดขๅˆ†ๆžใ€ZWS v5 ไปฅๅŠ 8 ไธช้—ฎ้ข˜ๅทฒๅ…ณ้—ญใ€‚ +> Sprint: Cross-platform machineId fix, per-API-key rate limits, streaming context cache, Alibaba DashScope, search analytics, ZWS v5, and 8 issues closed. -### โœจ ๆ–ฐ็‰นๆ€ง +### โœจ New Features -- **feat(search)**๏ผš`/dashboard/analytics` ไธญ็š„ๆœ็ดขๅˆ†ๆžๆ ‡็ญพ้กต โ€”โ€” ๆไพ›ๅ•†ๆ‹†ๅˆ†ใ€็ผ“ๅญ˜ๅ‘ฝไธญ็Ž‡ใ€ๆˆๆœฌ่ทŸ่ธชใ€‚ๆ–ฐ API๏ผš`GET /api/v1/search/analytics`๏ผˆ#feat/search-provider-routing๏ผ‰ -- **feat(provider)**๏ผšๆ–ฐๅขž Alibaba Cloud DashScope๏ผŒๅธฆ่‡ชๅฎšไน‰็ซฏ็‚น่ทฏๅพ„้ชŒ่ฏ โ€”โ€” ๆฏไธช่Š‚็‚นๅฏ้…็ฝฎ `chatPath` ๅ’Œ `modelsPath`๏ผˆ#feat/custom-endpoint-paths๏ผ‰ -- **feat(api)**๏ผšๆฏ API key ่ฏทๆฑ‚ๆ•ฐ้™ๅˆถ โ€”โ€” `max_requests_per_day` ๅ’Œ `max_requests_per_minute` ๅˆ—๏ผŒ้€š่ฟ‡ๅ†…ๅญ˜ๆป‘ๅŠจ็ช—ๅฃๅผบๅˆถๆ‰ง่กŒ๏ผŒ่ฟ”ๅ›ž HTTP 429๏ผˆ#452๏ผ‰ -- **feat(dev)**๏ผšZWS v5 โ€”โ€” HMR ๆณ„ๆผไฟฎๅค๏ผˆ485 ไธชๆ•ฐๆฎๅบ“่ฟžๆŽฅ โ†’ 1๏ผ‰๏ผŒๅ†…ๅญ˜ 2.4GB โ†’ 195MB๏ผŒ`globalThis` ๅ•ไพ‹๏ผŒEdge Runtime ่ญฆๅ‘Šไฟฎๅค๏ผˆ@zhangqiang8vip๏ผ‰ +- **feat(search)**: Search Analytics tab in `/dashboard/analytics` โ€” provider breakdown, cache hit rate, cost tracking. New API: `GET /api/v1/search/analytics` (#feat/search-provider-routing) +- **feat(provider)**: Alibaba Cloud DashScope added with custom endpoint path validation โ€” configurable `chatPath` and `modelsPath` per node (#feat/custom-endpoint-paths) +- **feat(api)**: Per-API-key request-count limits โ€” `max_requests_per_day` and `max_requests_per_minute` columns with in-memory sliding-window enforcement returning HTTP 429 (#452) +- **feat(dev)**: ZWS v5 โ€” HMR leak fix (485 DB connections โ†’ 1), memory 2.4GB โ†’ 195MB, `globalThis` singletons, Edge Runtime warning fix (@zhangqiang8vip) -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **fix(#506)**๏ผš่ทจๅนณๅฐ `machineId` โ€”โ€” `getMachineIdRaw()` ไฝฟ็”จ try/catch ็€‘ๅธƒ้‡ๅ†™๏ผˆWindows REG.exe โ†’ macOS ioreg โ†’ Linux ๆ–‡ไปถ่ฏปๅ– โ†’ hostname โ†’ `os.hostname()`๏ผ‰ใ€‚ๆถˆ้™คไบ† Next.js ๆ‰“ๅŒ…ๅ™จๆญปไปฃ็ ๆถˆ้™ค็š„ `process.platform` ๅˆ†ๆ”ฏ๏ผŒไฟฎๅคไบ† Windows ไธŠ็š„ `'head' is not recognized` ้—ฎ้ข˜ใ€‚ๅŒๆ—ถไฟฎๅค #466ใ€‚ -- **fix(#493)**๏ผš่‡ชๅฎšไน‰ๆไพ›ๅ•†ๆจกๅž‹ๅ‘ฝๅ โ€”โ€” ็งป้™คไบ† `DefaultExecutor.transformRequest()` ไธญไธๆญฃ็กฎ็š„ๅ‰็ผ€ๅ‰ฅ็ฆป๏ผŒ่ฏฅ้—ฎ้ข˜็ ดๅไบ† `zai-org/GLM-5-FP8` ็ญ‰็ป„็ป‡่Œƒๅ›ด็š„ๆจกๅž‹ IDใ€‚ -- **fix(#490)**๏ผšๆตๅผ + context ็ผ“ๅญ˜ไฟๆŠค โ€”โ€” `TransformStream` ๆ‹ฆๆˆช SSE ไปฅๅœจ `[DONE]` ๆ ‡่ฎฐไน‹ๅ‰ๆณจๅ…ฅ `` ๆ ‡็ญพ๏ผŒๅฎž็Žฐๆตๅผๅ“ๅบ”็š„ context ็ผ“ๅญ˜ไฟๆŠคใ€‚ -- **fix(#458)**๏ผšCombo schema ้ชŒ่ฏ โ€”โ€” `system_message`ใ€`tool_filter_regex`ใ€`context_cache_protection` ๅญ—ๆฎต็Žฐๅœจๅœจไฟๅญ˜ๆ—ถ้€š่ฟ‡ Zod ้ชŒ่ฏใ€‚ -- **fix(#487)**๏ผšKIRO MITM ๅก็‰‡ๆธ…็† โ€”โ€” ็งป้™ค ZWS_README๏ผŒๅฐ† `AntigravityToolCard` ๆณ›ๅŒ–ไปฅไฝฟ็”จๅŠจๆ€ๅทฅๅ…ทๅ…ƒๆ•ฐๆฎใ€‚ +- **fix(#506)**: Cross-platform `machineId` โ€” `getMachineIdRaw()` rewritten with try/catch waterfall (Windows REG.exe โ†’ macOS ioreg โ†’ Linux file read โ†’ hostname โ†’ `os.hostname()`). Eliminates `process.platform` branching that Next.js bundler dead-code-eliminated, fixing `'head' is not recognized` on Windows. Also fixes #466. +- **fix(#493)**: Custom provider model naming โ€” removed incorrect prefix stripping in `DefaultExecutor.transformRequest()` that mangled org-scoped model IDs like `zai-org/GLM-5-FP8`. +- **fix(#490)**: Streaming + context cache protection โ€” `TransformStream` intercepts SSE to inject `` tag before `[DONE]` marker, enabling context cache protection for streaming responses. +- **fix(#458)**: Combo schema validation โ€” `system_message`, `tool_filter_regex`, `context_cache_protection` fields now pass Zod validation on save. +- **fix(#487)**: KIRO MITM card cleanup โ€” removed ZWS_README, generified `AntigravityToolCard` to use dynamic tool metadata. -### ๐Ÿงช ๆต‹่ฏ• +### ๐Ÿงช Tests -- ๆทปๅŠ ไบ† Anthropic ๆ ผๅผๅทฅๅ…ท่ฟ‡ๆปคๅ™จๅ•ๅ…ƒๆต‹่ฏ•๏ผˆPR #397๏ผ‰โ€”โ€” 8 ไธชๅ›žๅฝ’ๆต‹่ฏ•๏ผŒ็”จไบŽไธๅธฆ `.function` ๅŒ…่ฃ…็š„ `tool.name` -- ๆต‹่ฏ•ๅฅ—ไปถ๏ผš**821 ไธชๆต‹่ฏ•๏ผŒ0 ๅคฑ่ดฅ**๏ผˆไปŽ 813 ๅขžๅŠ ๏ผ‰ +- Added Anthropic-format tools filter unit tests (PR #397) โ€” 8 regression tests for `tool.name` without `.function` wrapper +- Test suite: **821 tests, 0 failures** (up from 813) -### ๐Ÿ“‹ ๅทฒๅ…ณ้—ญ็š„้—ฎ้ข˜๏ผˆ8 ไธช๏ผ‰ +### ๐Ÿ“‹ Issues Closed (8) -- **#506** โ€”โ€” Windows machineId `head` ๆ— ๆณ•่ฏ†ๅˆซ๏ผˆๅทฒไฟฎๅค๏ผ‰ -- **#493** โ€”โ€” ่‡ชๅฎšไน‰ๆไพ›ๅ•†ๆจกๅž‹ๅ‘ฝๅ๏ผˆๅทฒไฟฎๅค๏ผ‰ -- **#490** โ€”โ€” ๆตๅผ context ็ผ“ๅญ˜๏ผˆๅทฒไฟฎๅค๏ผ‰ -- **#452** โ€”โ€” ๆฏ API key ่ฏทๆฑ‚้™ๅˆถ๏ผˆๅทฒๅฎž็Žฐ๏ผ‰ -- **#466** โ€”โ€” Windows ็™ปๅฝ•ๅคฑ่ดฅ๏ผˆไธŽ #506 ็›ธๅŒๆ นๅ› ๏ผ‰ -- **#504** โ€”โ€” MITM ๆœชๆฟ€ๆดป๏ผˆ้ข„ๆœŸ่กŒไธบ๏ผ‰ -- **#462** โ€”โ€” Gemini CLI PSA๏ผˆๅทฒ่งฃๅ†ณ๏ผ‰ -- **#434** โ€”โ€” Electron ๅบ”็”จๅดฉๆบƒ๏ผˆ#402 ็š„้‡ๅค๏ผ‰ +- **#506** โ€” Windows machineId `head` not recognized (fixed) +- **#493** โ€” Custom provider model naming (fixed) +- **#490** โ€” Streaming context cache (fixed) +- **#452** โ€” Per-API-key request limits (implemented) +- **#466** โ€” Windows login failure (same root cause as #506) +- **#504** โ€” MITM inactive (expected behavior) +- **#462** โ€” Gemini CLI PSA (resolved) +- **#434** โ€” Electron app crash (duplicate of #402) ## [2.8.9] โ€” 2026-03-20 -> Sprint๏ผšๅˆๅนถ็คพๅŒบ PRใ€ไฟฎๅค KIRO MITM ๅก็‰‡ใ€ไพ่ต–ๆ›ดๆ–ฐใ€‚ +> Sprint: Merge community PRs, fix KIRO MITM card, dependency updates. -### ๅทฒๅˆๅนถ็š„ PR +### Merged PRs -- **PR #498**๏ผˆ@Sajid11194๏ผ‰๏ผšไฟฎๅค Windows ๆœบๅ™จ ID ๅดฉๆบƒ๏ผˆ`undefined\REG.exe`๏ผ‰ใ€‚ไฝฟ็”จๅŽŸ็”Ÿ OS ๆณจๅ†Œ่กจๆŸฅ่ฏขๆ›ฟๆข `node-machine-id`ใ€‚**ๅ…ณ้—ญ #486ใ€‚** -- **PR #497**๏ผˆ@zhangqiang8vip๏ผ‰๏ผšไฟฎๅคๅผ€ๅ‘ๆจกๅผ HMR ่ต„ๆบๆณ„ๆผ โ€”โ€” 485 ไธชๆณ„ๆผ็š„ๆ•ฐๆฎๅบ“่ฟžๆŽฅ โ†’ 1๏ผŒๅ†…ๅญ˜ 2.4GB โ†’ 195MBใ€‚`globalThis` ๅ•ไพ‹ใ€Edge Runtime ่ญฆๅ‘Šไฟฎๅคใ€Windows ๆต‹่ฏ•็จณๅฎšๆ€งใ€‚๏ผˆ22 ไธชๆ–‡ไปถ๏ผŒ+1168/-338๏ผ‰ -- **PR #499-503**๏ผˆDependabot๏ผ‰๏ผšGitHub Actions ๆ›ดๆ–ฐ โ€”โ€” `docker/build-push-action@7`ใ€`actions/checkout@6`ใ€`peter-evans/dockerhub-description@5`ใ€`docker/setup-qemu-action@4`ใ€`docker/login-action@4`ใ€‚ +- **PR #498** (@Sajid11194): Fix Windows machine ID crash (`undefined\REG.exe`). Replaces `node-machine-id` with native OS registry queries. **Closes #486.** +- **PR #497** (@zhangqiang8vip): Fix dev-mode HMR resource leaks โ€” 485 leaked DB connections โ†’ 1, memory 2.4GB โ†’ 195MB. `globalThis` singletons, Edge Runtime warning fix, Windows test stability. (+1168/-338 across 22 files) +- **PRs #499-503** (Dependabot): GitHub Actions updates โ€” `docker/build-push-action@7`, `actions/checkout@6`, `peter-evans/dockerhub-description@5`, `docker/setup-qemu-action@4`, `docker/login-action@4`. -### Bug ไฟฎๅค +### Bug Fixes -- **#505** โ€”โ€” KIRO MITM ๅก็‰‡็Žฐๅœจๆ˜พ็คบ็‰นๅฎšๅทฅๅ…ท็š„่ฏดๆ˜Ž๏ผˆ`api.anthropic.com`๏ผ‰๏ผŒ่€Œไธๆ˜ฏ Antigravity ็‰นๅฎš็š„ๆ–‡ๆœฌใ€‚ -- **#504** โ€”โ€” ๅ›žๅคไบ† UX ๆพ„ๆธ…่ฏดๆ˜Ž๏ผˆๅฝ“ไปฃ็†ๆœช่ฟ่กŒๆ—ถ๏ผŒMITM "Inactive" ๆ˜ฏ้ข„ๆœŸ่กŒไธบ๏ผ‰ใ€‚ +- **#505** โ€” KIRO MITM card now displays tool-specific instructions (`api.anthropic.com`) instead of Antigravity-specific text. +- **#504** โ€” Responded with UX clarification (MITM "Inactive" is expected behavior when proxy is not running). --- ## [2.8.8] โ€” 2026-03-20 -> Sprint๏ผšไฟฎๅค OAuth ๆ‰น้‡ๆต‹่ฏ•ๅดฉๆบƒ๏ผŒไธบๅ„ไธชๆไพ›ๅ•†้กต้ขๆทปๅŠ  "Test All" ๆŒ‰้’ฎใ€‚ +> Sprint: Fix OAuth batch test crash, add "Test All" button to individual provider pages. -### Bug ไฟฎๅค +### Bug Fixes -- **OAuth ๆ‰น้‡ๆต‹่ฏ•ๅดฉๆบƒ**๏ผˆERR_CONNECTION_REFUSED๏ผ‰๏ผšๅฐ†้กบๅบ for-loop ๆ›ฟๆขไธบ 5 ่ฟžๆŽฅๅนถๅ‘้™ๅˆถ + ๆฏไธช่ฟžๆŽฅ 30 ็ง’่ถ…ๆ—ถ๏ผŒ้€š่ฟ‡ `Promise.race()` + `Promise.allSettled()` ๅฎž็Žฐใ€‚้˜ฒๆญขๅœจๆต‹่ฏ•ๅคงๅž‹ OAuth ๆไพ›ๅ•†็ป„๏ผˆ็บฆ 30+ ่ฟžๆŽฅ๏ผ‰ๆ—ถๆœๅŠกๅ™จๅดฉๆบƒใ€‚ +- **OAuth batch test crash** (ERR_CONNECTION_REFUSED): Replaced sequential for-loop with 5-connection concurrency limit + 30s per-connection timeout via `Promise.race()` + `Promise.allSettled()`. Prevents server crash when testing large OAuth provider groups (~30+ connections). -### ๆ–ฐ็‰นๆ€ง +### ๅŠŸ่ƒฝ็‰น็‚น -- **ๅ„ๆไพ›ๅ•†้กต้ข็š„ "Test All" ๆŒ‰้’ฎ**๏ผšๅ„ไธชๆไพ›ๅ•†้กต้ข๏ผˆๅฆ‚ `/providers/codex`๏ผ‰็Žฐๅœจๆœ‰ 2+ ่ฟžๆŽฅๆ—ถไผšๅœจ Connections ๆ ‡้ข˜ๅค„ๆ˜พ็คบ "Test All" ๆŒ‰้’ฎใ€‚ไฝฟ็”จ `POST /api/providers/test-batch` ๅ’Œ `{mode: "provider", providerId}`ใ€‚็ป“ๆžœๅœจๆจกๆ€ๆก†ไธญๆ˜พ็คบ๏ผŒๅŒ…ๅซ้€š่ฟ‡/ๅคฑ่ดฅๆ‘˜่ฆๅ’Œๆฏไธช่ฟžๆŽฅ็š„่ฏŠๆ–ญไฟกๆฏใ€‚ +- **"Test All" button on provider pages**: Individual provider pages (e.g., `/providers/codex`) now show a "Test All" button in the Connections header when there are 2+ connections. Uses `POST /api/providers/test-batch` with `{mode: "provider", providerId}`. Results displayed in a modal with pass/fail summary and per-connection diagnosis. --- ## [2.8.7] โ€” 2026-03-20 -> Sprint๏ผšๅˆๅนถ PR #495๏ผˆBottleneck 429 ไธขๅผƒ๏ผ‰ใ€ไฟฎๅค #496๏ผˆ่‡ชๅฎšไน‰ embedding ๆไพ›ๅ•†๏ผ‰ใ€ๅˆ†็ฑปๅŠŸ่ƒฝใ€‚ +> Sprint: Merge PR #495 (Bottleneck 429 drop), fix #496 (custom embedding providers), triage features. -### Bug ไฟฎๅค +### Bug Fixes -- **Bottleneck 429 ๆ— ้™็ญ‰ๅพ…**๏ผˆPR #495 by @xandr0s๏ผ‰๏ผšๆ”ถๅˆฐ 429 ๆ—ถ๏ผŒ`limiter.stop({ dropWaitingJobs: true })` ็ซ‹ๅณไฝฟๆ‰€ๆœ‰ๆŽ’้˜Ÿ็š„่ฏทๆฑ‚ๅคฑ่ดฅ๏ผŒไปฅไพฟไธŠๆธธ่ฐƒ็”จๆ–นๅฏไปฅ่งฆๅ‘ๅ›ž้€€ใ€‚Limiter ไปŽ Map ไธญๅˆ ้™ค๏ผŒไปฅไพฟไธ‹ไธ€ไธช่ฏทๆฑ‚ๅˆ›ๅปบๆ–ฐๅฎžไพ‹ใ€‚ -- **่‡ชๅฎšไน‰ embedding ๆจกๅž‹ๆ— ๆณ•่งฃๆž**๏ผˆ#496๏ผ‰๏ผš`POST /v1/embeddings` ็ŽฐๅœจไปŽๆ‰€ๆœ‰ๆไพ›ๅ•†่Š‚็‚น่งฃๆž่‡ชๅฎšไน‰ embedding ๆจกๅž‹๏ผˆ่€Œไธไป…ไป…ๆ˜ฏ localhost๏ผ‰ใ€‚ๆ”ฏๆŒ้€š่ฟ‡ไปช่กจ็›˜ๆทปๅŠ ็š„ `google/gemini-embedding-001` ็ญ‰ๆจกๅž‹ใ€‚ +- **Bottleneck 429 infinite wait** (PR #495 by @xandr0s): On 429, `limiter.stop({ dropWaitingJobs: true })` immediately fails all queued requests so upstream callers can trigger fallback. Limiter is deleted from Map so next request creates a fresh instance. +- **Custom embedding models unresolvable** (#496): `POST /v1/embeddings` now resolves custom embedding models from ALL provider_nodes (not just localhost). Enables models like `google/gemini-embedding-001` added via dashboard. -### ๅทฒๅ›žๅค็š„้—ฎ้ข˜ +### Issues Responded -- **#452** โ€”โ€” ๆฏ API key ่ฏทๆฑ‚ๆ•ฐ้™ๅˆถ๏ผˆๅทฒ็กฎ่ฎค๏ผŒๅœจ่ทฏ็บฟๅ›พไธญ๏ผ‰ -- **#464** โ€”โ€” ่‡ชๅŠจ็ญพๅ‘ API key๏ผŒๅธฆๆไพ›ๅ•†/่ดฆๆˆท้™ๅˆถ๏ผˆ้œ€่ฆๆ›ดๅคš็ป†่Š‚๏ผ‰ -- **#488** โ€”โ€” ่‡ชๅŠจๆ›ดๆ–ฐๆจกๅž‹ๅˆ—่กจ๏ผˆๅทฒ็กฎ่ฎค๏ผŒๅœจ่ทฏ็บฟๅ›พไธญ๏ผ‰ -- **#496** โ€”โ€” ่‡ชๅฎšไน‰ embedding ๆไพ›ๅ•†่งฃๆž๏ผˆๅทฒไฟฎๅค๏ผ‰ +- **#452** โ€” Per-API-key request-count limits (acknowledged, on roadmap) +- **#464** โ€” Auto-issue API keys with provider/account limits (needs more detail) +- **#488** โ€” Auto-update model lists (acknowledged, on roadmap) +- **#496** โ€” Custom embedding provider resolution (fixed) --- ## [2.8.6] โ€” 2026-03-20 -> Sprint๏ผšๅˆๅนถ PR #494๏ผˆMiniMax ่ง’่‰ฒไฟฎๅค๏ผ‰ใ€ไฟฎๅค KIRO MITM ไปช่กจ็›˜ใ€ๅˆ†็ฑป 8 ไธช้—ฎ้ข˜ใ€‚ +> Sprint: Merge PR #494 (MiniMax role fix), fix KIRO MITM dashboard, triage 8 issues. -### ๆ–ฐ็‰นๆ€ง +### ๅŠŸ่ƒฝ็‰น็‚น -- **MiniMax developerโ†’system ่ง’่‰ฒไฟฎๅค**๏ผˆPR #494 by @zhangqiang8vip๏ผ‰๏ผšๆฏๆจกๅž‹ `preserveDeveloperRole` ๅผ€ๅ…ณใ€‚ๅœจๆไพ›ๅ•†้กต้ขๆ–ฐๅขž "Compatibility" UIใ€‚ไฟฎๅค MiniMax ๅ’Œ็ฑปไผผ็ฝ‘ๅ…ณ็š„ 422 "role param error"ใ€‚ -- **roleNormalizer**๏ผš`normalizeDeveloperRole()` ็ŽฐๅœจๆŽฅๅ— `preserveDeveloperRole` ๅ‚ๆ•ฐ๏ผŒๆ”ฏๆŒไธ‰ๆ€่กŒไธบ๏ผˆundefined=ไฟๆŒใ€true=ไฟๆŒใ€false=่ฝฌๆข๏ผ‰ใ€‚ -- **ๆ•ฐๆฎๅบ“**๏ผšๅœจ `models.ts` ไธญๆ–ฐๅขž `getModelPreserveOpenAIDeveloperRole()` ๅ’Œ `mergeModelCompatOverride()`ใ€‚ +- **MiniMax developerโ†’system role fix** (PR #494 by @zhangqiang8vip): Per-model `preserveDeveloperRole` toggle. Adds "Compatibility" UI in providers page. Fixes 422 "role param error" for MiniMax and similar gateways. +- **roleNormalizer**: `normalizeDeveloperRole()` now accepts `preserveDeveloperRole` parameter with tri-state behavior (undefined=keep, true=keep, false=convert). +- **DB**: New `getModelPreserveOpenAIDeveloperRole()` and `mergeModelCompatOverride()` in `models.ts`. -### Bug ไฟฎๅค +### Bug Fixes -- **KIRO MITM ไปช่กจ็›˜**๏ผˆ#481/#487๏ผ‰๏ผš`CLIToolsPageClient` ็Žฐๅœจๅฐ†ไปปไฝ• `configType: "mitm"` ๅทฅๅ…ท่ทฏ็”ฑๅˆฐ `AntigravityToolCard`๏ผˆMITM ๅผ€ๅง‹/ๅœๆญขๆŽงๅˆถ๏ผ‰ใ€‚ๆญคๅ‰ๅชๆœ‰ Antigravity ๆ˜ฏ็กฌ็ผ–็ ็š„ใ€‚ -- **AntigravityToolCard ๆณ›ๅŒ–**๏ผšไฝฟ็”จ `tool.image`ใ€`tool.description`ใ€`tool.id` ่€Œไธๆ˜ฏ็กฌ็ผ–็ ็š„ Antigravity ๅ€ผใ€‚้˜ฒๆญข็ผบๅฐ‘ `defaultModels` ๆ—ถๅ‡บ้”™ใ€‚ +- **KIRO MITM dashboard** (#481/#487): `CLIToolsPageClient` now routes any `configType: "mitm"` tool to `AntigravityToolCard` (MITM Start/Stop controls). Previously only Antigravity was hardcoded. +- **AntigravityToolCard generic**: Uses `tool.image`, `tool.description`, `tool.id` instead of hardcoded Antigravity values. Guards against missing `defaultModels`. -### ๆธ…็† +### Cleanup -- ็งป้™คไบ† `ZWS_README_V2.md`๏ผˆPR #494 ไธญ็š„ไป…ๅผ€ๅ‘ๆ–‡ๆกฃ๏ผ‰ใ€‚ +- Removed `ZWS_README_V2.md` (development-only docs from PR #494). -### ๅทฒๅˆ†็ฑป็š„้—ฎ้ข˜๏ผˆ8 ไธช๏ผ‰ +### Issues Triaged (8) -- **#487** โ€”โ€” ๅทฒๅ…ณ้—ญ๏ผˆKIRO MITM ๅœจๆญค็‰ˆๆœฌไธญไฟฎๅค๏ผ‰ -- **#486** โ€”โ€” ้œ€่ฆไฟกๆฏ๏ผˆWindows REG.exe PATH ้—ฎ้ข˜๏ผ‰ -- **#489** โ€”โ€” ้œ€่ฆไฟกๆฏ๏ผˆAntigravity projectId ็ผบๅคฑ๏ผŒ้œ€่ฆ OAuth ้‡ๆ–ฐ่ฟžๆŽฅ๏ผ‰ -- **#492** โ€”โ€” ้œ€่ฆไฟกๆฏ๏ผˆ็ผบๅฐ‘ app/server.js๏ผŒๅœจ mise ็ฎก็†็š„ Node ไธญ๏ผ‰ -- **#490** โ€”โ€” ๅทฒ็กฎ่ฎค๏ผˆๆตๅผ + context ็ผ“ๅญ˜้˜ปๅกž๏ผŒ่ฎกๅˆ’ไฟฎๅค๏ผ‰ -- **#491** โ€”โ€” ๅทฒ็กฎ่ฎค๏ผˆCodex ่ฎค่ฏ็Šถๆ€ไธไธ€่‡ด๏ผ‰ -- **#493** โ€”โ€” ๅทฒ็กฎ่ฎค๏ผˆๆจกๆ€ๆก†ๆไพ›ๅ•†ๆจกๅž‹ๅ็งฐๅ‰็ผ€๏ผŒๅทฒๆไพ›่งฃๅ†ณๆ–นๆกˆ๏ผ‰ -- **#488** โ€”โ€” ๅŠŸ่ƒฝ่ฏทๆฑ‚ๅพ…ๅŠž๏ผˆ่‡ชๅŠจๆ›ดๆ–ฐๆจกๅž‹ๅˆ—่กจ๏ผ‰ +- **#487** โ€” Closed (KIRO MITM fixed in this release) +- **#486** โ€” needs-info (Windows REG.exe PATH issue) +- **#489** โ€” needs-info (Antigravity projectId missing, OAuth reconnect needed) +- **#492** โ€” needs-info (missing app/server.js on mise-managed Node) +- **#490** โ€” Acknowledged (streaming + context cache blocking, fix planned) +- **#491** โ€” Acknowledged (Codex auth state inconsistency) +- **#493** โ€” Acknowledged (Modal provider model name prefix, workaround provided) +- **#488** โ€” Feature request backlog (auto-update model lists) --- ## [2.8.5] โ€” 2026-03-19 -> Sprint๏ผšไฟฎๅคๅƒตๅฐธ SSE ๆตใ€context ็ผ“ๅญ˜้ฆ–่ฝฎใ€KIRO MITM ไปฅๅŠๅˆ†็ฑป 5 ไธชๅค–้ƒจ้—ฎ้ข˜ใ€‚ +> Sprint: Fix zombie SSE streams, context cache first-turn, KIRO MITM, and triage 5 external issues. -### Bug ไฟฎๅค +### Bug Fixes -- **ๅƒตๅฐธ SSE ๆต**๏ผˆ#473๏ผ‰๏ผšๅฐ† `STREAM_IDLE_TIMEOUT_MS` ไปŽ 300 ็ง’้™ไฝŽๅˆฐ 120 ็ง’๏ผŒไปฅไพฟๅœจๆไพ›ๅ•†ไธญ้€”ๆŒ‚่ตทๆ—ถๆ›ดๅฟซๅ›ž้€€ใ€‚ๅฏ้€š่ฟ‡็Žฏๅขƒๅ˜้‡้…็ฝฎใ€‚ -- **Context ็ผ“ๅญ˜ๆ ‡็ญพ**๏ผˆ#474๏ผ‰๏ผšไฟฎๅค `injectModelTag()` ไปฅๅค„็†้ฆ–่ฝฎ่ฏทๆฑ‚๏ผˆๆ— ๅŠฉๆ‰‹ๆถˆๆฏ๏ผ‰โ€”โ€” context ็ผ“ๅญ˜ไฟๆŠค็ŽฐๅœจไปŽ็ฌฌไธ€ไธชๅ“ๅบ”ๅผ€ๅง‹ๅฐฑ็”Ÿๆ•ˆใ€‚ -- **KIRO MITM**๏ผˆ#481๏ผ‰๏ผšๅฐ† KIRO `configType` ไปŽ `guide` ๆ”นไธบ `mitm`๏ผŒไปฅไพฟไปช่กจ็›˜ๆธฒๆŸ“ MITM ๅผ€ๅง‹/ๅœๆญขๆŽงๅˆถใ€‚ -- **E2E ๆต‹่ฏ•**๏ผˆCI๏ผ‰๏ผšไฟฎๅค `providers-bailian-coding-plan.spec.ts` โ€”โ€” ๅœจ็‚นๅ‡ปๆทปๅŠ  API Key ๆŒ‰้’ฎไน‹ๅ‰ๅ…ณ้—ญ้ข„ๅ…ˆๅญ˜ๅœจ็š„ๆจกๆ€ๆก†่ฆ†็›–ๅฑ‚ใ€‚ +- **Zombie SSE Streams** (#473): Reduce `STREAM_IDLE_TIMEOUT_MS` from 300s โ†’ 120s for faster combo fallback when providers hang mid-stream. Configurable via env var. +- **Context Cache Tag** (#474): Fix `injectModelTag()` to handle first-turn requests (no assistant messages) โ€” context cache protection now works from the very first response. +- **KIRO MITM** (#481): Change KIRO `configType` from `guide` โ†’ `mitm` so the dashboard renders MITM Start/Stop controls. +- **E2E Test** (CI): Fix `providers-bailian-coding-plan.spec.ts` โ€” dismiss pre-existing modal overlay before clicking Add API Key button. -### ๅทฒๅ…ณ้—ญ็š„้—ฎ้ข˜ +### Closed Issues -- #473 โ€”โ€” ๅƒตๅฐธ SSE ๆต็ป•่ฟ‡ combo ๅ›ž้€€ -- #474 โ€”โ€” Context ็ผ“ๅญ˜ `` ๆ ‡็ญพๅœจ้ฆ–่ฝฎ็ผบๅคฑ -- #481 โ€”โ€” KIRO ็š„ MITM ๆ— ๆณ•ไปŽไปช่กจ็›˜ๆฟ€ๆดป -- #468 โ€”โ€” Gemini CLI ่ฟœ็จ‹ๆœๅŠกๅ™จ๏ผˆๅทฒ่ขซ #462 ๅผƒ็”จๅ–ไปฃ๏ผ‰ -- #438 โ€”โ€” Claude ๆ— ๆณ•ๅ†™ๅ…ฅๆ–‡ไปถ๏ผˆๅค–้ƒจ CLI ้—ฎ้ข˜๏ผ‰ -- #439 โ€”โ€” AppImage ๆ— ๆณ•ๅทฅไฝœ๏ผˆๅทฒ่ฎฐๅฝ• libfuse2 ่งฃๅ†ณๆ–นๆกˆ๏ผ‰ -- #402 โ€”โ€” ARM64 DMG "ๆŸๅ"๏ผˆๅทฒ่ฎฐๅฝ• xattr -cr ่งฃๅ†ณๆ–นๆกˆ๏ผ‰ -- #460 โ€”โ€” CLI ๅœจ Windows ไธŠๆ— ๆณ•่ฟ่กŒ๏ผˆๅทฒ่ฎฐๅฝ• PATH ไฟฎๅคๆ–นๆกˆ๏ผ‰ +- #473 โ€” Zombie SSE streams bypass combo fallback +- #474 โ€” Context cache `` tag missing on first turn +- #481 โ€” MITM for KIRO not activatable from dashboard +- #468 โ€” Gemini CLI remote server (superseded by #462 deprecation) +- #438 โ€” Claude unable to write files (external CLI issue) +- #439 โ€” AppImage doesn't work (documented libfuse2 workaround) +- #402 โ€” ARM64 DMG "damaged" (documented xattr -cr workaround) +- #460 โ€” CLI not runnable on Windows (documented PATH fix) --- ## [2.8.4] โ€” 2026-03-19 -> Sprint๏ผšGemini CLI ๅผƒ็”จใ€VM ๆŒ‡ๅ— i18n ไฟฎๅคใ€dependabot ๅฎ‰ๅ…จไฟฎๅคใ€ๆไพ›ๅ•† schema ๆ‰ฉๅฑ•ใ€‚ +> Sprint: Gemini CLI deprecation, VM guide i18n fix, dependabot security fix, provider schema expansion. -### ๆ–ฐ็‰นๆ€ง +### ๅŠŸ่ƒฝ็‰น็‚น -- **Gemini CLI ๅผƒ็”จ**๏ผˆ#462๏ผ‰๏ผšๅฐ† `gemini-cli` ๆไพ›ๅ•†ๆ ‡่ฎฐไธบๅทฒๅผƒ็”จ๏ผŒ้™„ๅธฆ่ญฆๅ‘Š โ€”โ€” Google ไปŽ 2026 ๅนด 3 ๆœˆ่ตท้™ๅˆถ็ฌฌไธ‰ๆ–น OAuth ไฝฟ็”จ -- **ๆไพ›ๅ•† Schema**๏ผˆ#462๏ผ‰๏ผšๆ‰ฉๅฑ• Zod ้ชŒ่ฏ๏ผŒๆ–ฐๅขž `deprecated`ใ€`deprecationReason`ใ€`hasFree`ใ€`freeNote`ใ€`authHint`ใ€`apiHint` ๅฏ้€‰ๅญ—ๆฎต +- **Gemini CLI Deprecation** (#462): Mark `gemini-cli` provider as deprecated with warning โ€” Google restricts third-party OAuth usage from March 2026 +- **Provider Schema** (#462): Expand Zod validation with `deprecated`, `deprecationReason`, `hasFree`, `freeNote`, `authHint`, `apiHint` optional fields -### Bug ไฟฎๅค +### Bug Fixes -- **VM ๆŒ‡ๅ— i18n**๏ผˆ#471๏ผ‰๏ผšๅฐ† `VM_DEPLOYMENT_GUIDE.md` ๆทปๅŠ ๅˆฐ i18n ็ฟป่ฏ‘ๆตๆฐด็บฟ๏ผŒไปŽ่‹ฑๆ–‡ๆบ้‡ๆ–ฐ็”Ÿๆˆๆ‰€ๆœ‰ 30 ไธช่ฏญ่จ€็š„็ฟป่ฏ‘๏ผˆๆญคๅ‰ๅกๅœจ่‘ก่„็‰™่ฏญ็‰ˆๆœฌ๏ผ‰ +- **VM Guide i18n** (#471): Add `VM_DEPLOYMENT_GUIDE.md` to i18n translation pipeline, regenerate all 30 locale translations from English source (were stuck in Portuguese) ### ๅฎ‰ๅ…จ -- **deps**๏ผšๅฐ† `flatted` ไปŽ 3.3.3 ๅ‡็บงๅˆฐ 3.4.2 โ€”โ€” ไฟฎๅค CWE-1321 ๅŽŸๅž‹ๆฑกๆŸ“๏ผˆ#484๏ผŒ@dependabot๏ผ‰ +- **deps**: Bump `flatted` 3.3.3 โ†’ 3.4.2 โ€” fixes CWE-1321 prototype pollution (#484, @dependabot) -### ๅทฒๅ…ณ้—ญ็š„้—ฎ้ข˜ +### Closed Issues -- #472 โ€”โ€” Model Aliases ๅ›žๅฝ’๏ผˆๅทฒๅœจ v2.8.2 ไฟฎๅค๏ผ‰ -- #471 โ€”โ€” VM ๆŒ‡ๅ—็ฟป่ฏ‘ๆŸๅ -- #483 โ€”โ€” `[DONE]` ๅŽๅฐพ้š `data: null`๏ผˆๅทฒๅœจ v2.8.3 ไฟฎๅค๏ผ‰ +- #472 โ€” Model Aliases regression (fixed in v2.8.2) +- #471 โ€” VM guide translations broken +- #483 โ€” Trailing `data: null` after `[DONE]` (fixed in v2.8.3) -### ๅทฒๅˆๅนถ็š„ PR +### Merged PRs -- #484 โ€”โ€” deps: ๅฐ† flatted ไปŽ 3.3.3 ๅ‡็บงๅˆฐ 3.4.2๏ผˆ@dependabot๏ผ‰ +- #484 โ€” deps: bump flatted from 3.3.3 to 3.4.2 (@dependabot) --- ## [2.8.3] โ€” 2026-03-19 -> Sprint๏ผšๆทๅ…‹่ฏญ i18nใ€SSE ๅ่ฎฎไฟฎๅคใ€VM ๆŒ‡ๅ—็ฟป่ฏ‘ใ€‚ +> Sprint: Czech i18n, SSE protocol fix, VM guide translation. -### ๆ–ฐ็‰นๆ€ง +### ๅŠŸ่ƒฝ็‰น็‚น -- **ๆทๅ…‹่ฏญ**๏ผˆ#482๏ผ‰๏ผšๅฎŒๆ•ดๆทๅ…‹่ฏญ๏ผˆcs๏ผ‰i18n โ€”โ€” 22 ไปฝๆ–‡ๆกฃ๏ผŒ2606 ๆก UI ๅญ—็ฌฆไธฒ๏ผŒ่ฏญ่จ€ๅˆ‡ๆขๅ™จๆ›ดๆ–ฐ๏ผˆ@zen0bit๏ผ‰ -- **VM ้ƒจ็ฝฒๆŒ‡ๅ—**๏ผšไปŽ่‘ก่„็‰™่ฏญ็ฟป่ฏ‘ไธบ่‹ฑๆ–‡ไฝœไธบๆบๆ–‡ๆกฃ๏ผˆ@zen0bit๏ผ‰ +- **Czech Language** (#482): Full Czech (cs) i18n โ€” 22 docs, 2606 UI strings, language switcher updates (@zen0bit) +- **VM Deployment Guide**: Translated from Portuguese to English as the source document (@zen0bit) -### Bug ไฟฎๅค +### Bug Fixes -- **SSE ๅ่ฎฎ**๏ผˆ#483๏ผ‰๏ผšๅœๆญขๅœจ `[DONE]` ไฟกๅทๅŽๅ‘้€ๅฐพ้š็š„ `data: null` โ€”โ€” ไฟฎๅคไธฅๆ ผ AI SDK ๅฎขๆˆท็ซฏ๏ผˆๅŸบไบŽ Zod ็š„้ชŒ่ฏๅ™จ๏ผ‰ไธญ็š„ `AI_TypeValidationError` +- **SSE Protocol** (#483): Stop sending trailing `data: null` after `[DONE]` signal โ€” fixes `AI_TypeValidationError` in strict AI SDK clients (Zod-based validators) -### ๅทฒๅˆๅนถ็š„ PR +### Merged PRs -- #482 โ€”โ€” ๆ–ฐๅขžๆทๅ…‹่ฏญ + ไฟฎๅค VM_DEPLOYMENT_GUIDE.md ่‹ฑๆ–‡ๆบ๏ผˆ@zen0bit๏ผ‰ +- #482 โ€” Add Czech language + Fix VM_DEPLOYMENT_GUIDE.md English source (@zen0bit) --- ## [2.8.2] โ€” 2026-03-19 -> Sprint๏ผš2 ไธชๅทฒๅˆๅนถ PRใ€ๆจกๅž‹ aliases ่ทฏ็”ฑไฟฎๅคใ€ๆ—ฅๅฟ—ๅฏผๅ‡บๅ’Œ้—ฎ้ข˜ๅˆ†็ฑปใ€‚ +> Sprint: 2 merged PRs, model aliases routing fix, log export, and issue triage. -### ๆ–ฐ็‰นๆ€ง +### ๅŠŸ่ƒฝ็‰น็‚น -- **ๆ—ฅๅฟ—ๅฏผๅ‡บ**๏ผš`/dashboard/logs` ไธญๆ–ฐๅขžๅฏผๅ‡บๆŒ‰้’ฎ๏ผŒๅธฆๆ—ถ้—ด่Œƒๅ›ดไธ‹ๆ‹‰๏ผˆ1hใ€6hใ€12hใ€24h๏ผ‰ใ€‚้€š่ฟ‡ `/api/logs/export` API ไธ‹่ฝฝ่ฏทๆฑ‚/ไปฃ็†/call ๆ—ฅๅฟ—็š„ JSON๏ผˆ#user-request๏ผ‰ +- **Log Export**: New Export button on `/dashboard/logs` with time range dropdown (1h, 6h, 12h, 24h). Downloads JSON of request/proxy/call logs via `/api/logs/export` API (#user-request) -### Bug ไฟฎๅค +### Bug Fixes -- **Model Aliases ่ทฏ็”ฑ**๏ผˆ#472๏ผ‰๏ผš่ฎพ็ฝฎ โ†’ Model Aliases ็Žฐๅœจๆญฃ็กฎๅฝฑๅ“ๆไพ›ๅ•†่ทฏ็”ฑ๏ผŒ่€Œไธไป…ไป…ๆ˜ฏๆ ผๅผๆฃ€ๆต‹ใ€‚ๆญคๅ‰ `resolveModelAlias()` ็š„่พ“ๅ‡บไป…็”จไบŽ `getModelTargetFormat()`๏ผŒไฝ†ๅŽŸๅง‹ๆจกๅž‹ ID ่ขซๅ‘้€็ป™ๆไพ›ๅ•† -- **Stream Flush ็”จ้‡**๏ผˆ#480๏ผ‰๏ผš็ผ“ๅ†ฒๅŒบไธญๆœ€ๅŽไธ€ไธช SSE ไบ‹ไปถ็š„็”จ้‡ๆ•ฐๆฎ็Žฐๅœจๅœจๆตๅˆทๆ–ฐๆœŸ้—ดๆญฃ็กฎๆๅ–๏ผˆๅˆๅนถ่‡ช @prakersh๏ผ‰ +- **Model Aliases Routing** (#472): Settings โ†’ Model Aliases now correctly affect provider routing, not just format detection. Previously `resolveModelAlias()` output was only used for `getModelTargetFormat()` but the original model ID was sent to the provider +- **Stream Flush Usage** (#480): Usage data from the last SSE event in the buffer is now correctly extracted during stream flush (merged from @prakersh) -### ๅทฒๅˆๅนถ็š„ PR +### Merged PRs -- #480 โ€”โ€” ๅœจ flush handler ไธญไปŽๅ‰ฉไฝ™็ผ“ๅ†ฒๅŒบๆๅ–็”จ้‡๏ผˆ@prakersh๏ผ‰ -- #479 โ€”โ€” ๆทปๅŠ ็ผบๅคฑ็š„ Codex 5.3/5.4 ๅ’Œ Anthropic ๆจกๅž‹ ID ๅฎšไปทๆก็›ฎ๏ผˆ@prakersh๏ผ‰ +- #480 โ€” Extract usage from remaining buffer in flush handler (@prakersh) +- #479 โ€” Add missing Codex 5.3/5.4 and Anthropic model ID pricing entries (@prakersh) --- ## [2.8.1] โ€” 2026-03-19 -> Sprint๏ผš5 ไธช็คพๅŒบ PR โ€”โ€” ๆตๅผ call log ไฟฎๅคใ€Kiro ๅ…ผๅฎนๆ€งใ€็ผ“ๅญ˜ token ๅˆ†ๆžใ€ไธญๆ–‡็ฟป่ฏ‘ๅ’Œๅฏ้…็ฝฎๅทฅๅ…ท่ฐƒ็”จ IDใ€‚ +> Sprint: Five community PRs โ€” streaming call log fixes, Kiro compatibility, cache token analytics, Chinese translation, and configurable tool call IDs. -### โœจ ๆ–ฐ็‰นๆ€ง +### ๅŠŸ่ƒฝ็‰น็‚น -- **feat(logs)**๏ผšCall log ๅ“ๅบ”ๅ†…ๅฎน็Žฐๅœจๅœจ็ฟป่ฏ‘ๅ‰ๆญฃ็กฎไปŽๅŽŸๅง‹ๆไพ›ๅ•† chunk๏ผˆOpenAI/Claude/Gemini๏ผ‰็ดฏ็งฏ๏ผŒไฟฎๅคๆตๅผๆจกๅผไธ‹็ฉบๅ“ๅบ”่ดŸ่ฝฝ็š„้—ฎ้ข˜๏ผˆ#470๏ผŒ@zhangqiang8vip๏ผ‰ -- **feat(providers)**๏ผšๆฏๆจกๅž‹ๅฏ้…็ฝฎ็š„ 9 ๅญ—็ฌฆๅทฅๅ…ท่ฐƒ็”จ ID ่ง„่ŒƒๅŒ–๏ผˆMistral ้ฃŽๆ ผ๏ผ‰โ€”โ€” ๅชๆœ‰ๅฏ็”จ่ฏฅ้€‰้กน็š„ๆจกๅž‹ๆ‰ไผš่Žทๅพ—ๆˆชๆ–ญ ID๏ผˆ#470๏ผ‰ -- **feat(api)**๏ผšKey PATCH API ๆ‰ฉๅฑ•ไปฅๆ”ฏๆŒ `allowedConnections`ใ€`name`ใ€`autoResolve`ใ€`isActive` ๅ’Œ `accessSchedule` ๅญ—ๆฎต๏ผˆ#470๏ผ‰ -- **feat(dashboard)**๏ผš่ฏทๆฑ‚ๆ—ฅๅฟ—่ฏฆๆƒ… UI ้‡‡็”จๅ“ๅบ”ไผ˜ๅ…ˆๅธƒๅฑ€๏ผˆ#470๏ผ‰ -- **feat(i18n)**๏ผšๆ”น่ฟ›ไบ†ไธญๆ–‡๏ผˆzh-CN๏ผ‰็ฟป่ฏ‘ โ€”โ€” ๅฎŒๆ•ด้‡่ฏ‘๏ผˆ#475๏ผŒ@only4copilot๏ผ‰ +- **feat(logs)**: Call log response content now correctly accumulated from raw provider chunks (OpenAI/Claude/Gemini) before translation, fixing empty response payloads in streaming mode (#470, @zhangqiang8vip) +- **feat(providers)**: Per-model configurable 9-char tool call ID normalization (Mistral-style) โ€” only models with the option enabled get truncated IDs (#470) +- **feat(api)**: Key PATCH API expanded to support `allowedConnections`, `name`, `autoResolve`, `isActive`, and `accessSchedule` fields (#470) +- **feat(dashboard)**: Response-first layout in request log detail UI (#470) +- **feat(i18n)**: Improved Chinese (zh-CN) translation โ€” complete retranslation (#475, @only4copilot) -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **fix(kiro)**๏ผšไปŽ่ฏทๆฑ‚ไฝ“ไธญๅ‰ฅ็ฆปๆณจๅ…ฅ็š„ `model` ๅญ—ๆฎต โ€”โ€” Kiro API ๆ‹’็ปๆœช็Ÿฅ็š„้กถ็บงๅญ—ๆฎต๏ผˆ#478๏ผŒ@prakersh๏ผ‰ -- **fix(usage)**๏ผšๅœจ็”จ้‡ๅŽ†ๅฒ่พ“ๅ…ฅๆ€ป่ฎกไธญๅŒ…ๅซ็ผ“ๅญ˜่ฏปๅ– + ็ผ“ๅญ˜ๅˆ›ๅปบ token๏ผŒ็”จไบŽๅ‡†็กฎ็š„ๅˆ†ๆž๏ผˆ#477๏ผŒ@prakersh๏ผ‰ -- **fix(callLogs)**๏ผšๆ”ฏๆŒ Claude ๆ ผๅผ็”จ้‡ๅญ—ๆฎต๏ผˆ`input_tokens`/`output_tokens`๏ผ‰ไปฅๅŠ OpenAI ๆ ผๅผ๏ผŒๅŒ…ๅซๆ‰€ๆœ‰็ผ“ๅญ˜ token ๅ˜ไฝ“๏ผˆ#476๏ผŒ@prakersh๏ผ‰ +- **fix(kiro)**: Strip injected `model` field from request body โ€” Kiro API rejects unknown top-level fields (#478, @prakersh) +- **fix(usage)**: Include cache read + cache creation tokens in usage history input totals for accurate analytics (#477, @prakersh) +- **fix(callLogs)**: Support Claude format usage fields (`input_tokens`/`output_tokens`) alongside OpenAI format, include all cache token variants (#476, @prakersh) --- ## [2.8.0] โ€” 2026-03-19 -> Sprint๏ผšBailian Coding Plan ๆไพ›ๅ•†๏ผŒๅธฆๅฏ็ผ–่พ‘ๅŸบ็ก€ URL๏ผŒไปฅๅŠ Alibaba Cloud ๅ’Œ Kimi Coding ็š„็คพๅŒบ่ดก็Œฎใ€‚ +> Sprint: Bailian Coding Plan provider with editable base URLs, plus community contributions for Alibaba Cloud and Kimi Coding. -### โœจ ๆ–ฐ็‰นๆ€ง +### ๅŠŸ่ƒฝ็‰น็‚น -- **feat(providers)**๏ผšๆ–ฐๅขž Bailian Coding Plan๏ผˆ`bailian-coding-plan`๏ผ‰โ€”โ€” Alibaba Model Studio๏ผŒไฝฟ็”จ Anthropic ๅ…ผๅฎน APIใ€‚8 ไธชๆจกๅž‹็š„้™ๆ€็›ฎๅฝ•๏ผŒๅŒ…ๆ‹ฌ Qwen3.5 Plusใ€Qwen3 Coderใ€MiniMax M2.5ใ€GLM 5 ๅ’Œ Kimi K2.5ใ€‚ๅŒ…ๅซ่‡ชๅฎšไน‰่ฎค่ฏ้ชŒ่ฏ๏ผˆ400=ๆœ‰ๆ•ˆ๏ผŒ401/403=ๆ— ๆ•ˆ๏ผ‰๏ผˆ#467๏ผŒ@Mind-Dragon๏ผ‰ -- **feat(admin)**๏ผšๆไพ›ๅ•†็ฎก็†ๅ‘˜ๅˆ›ๅปบ/็ผ–่พ‘ๆต็จ‹ไธญๅฏ็ผ–่พ‘็š„้ป˜่ฎค URL โ€”โ€” ็”จๆˆทๅฏไปฅไธบๆฏไธช่ฟžๆŽฅ้…็ฝฎ่‡ชๅฎšไน‰ๅŸบ็ก€ URLใ€‚ๆŒไน…ๅŒ–ๅˆฐ `providerSpecificData.baseUrl`๏ผŒไฝฟ็”จ Zod schema ้ชŒ่ฏๆ‹’็ป้ž http(s) ๆ–นๆกˆ๏ผˆ#467๏ผ‰ +- **feat(providers)**: Added Bailian Coding Plan (`bailian-coding-plan`) โ€” Alibaba Model Studio with Anthropic-compatible API. Static catalog of 8 models including Qwen3.5 Plus, Qwen3 Coder, MiniMax M2.5, GLM 5, and Kimi K2.5. Includes custom auth validation (400=valid, 401/403=invalid) (#467, @Mind-Dragon) +- **feat(admin)**: Editable default URL in Provider Admin create/edit flows โ€” users can configure custom base URLs per connection. Persisted in `providerSpecificData.baseUrl` with Zod schema validation rejecting non-http(s) schemes (#467) -### ๐Ÿงช ๆต‹่ฏ• +### ๐Ÿงช Tests -- ไธบ Bailian Coding Plan ๆไพ›ๅ•†ๆทปๅŠ ไบ† 30+ ๅ•ๅ…ƒๆต‹่ฏ•ๅ’Œ 2 ไธช e2e ๅœบๆ™ฏ๏ผŒ่ฆ†็›–่ฎค่ฏ้ชŒ่ฏใ€schema ๅผบๅŒ–ใ€่ทฏ็”ฑ็บง่กŒไธบๅ’Œ่ทจๅฑ‚้›†ๆˆ +- Added 30+ unit tests and 2 e2e scenarios for Bailian Coding Plan provider covering auth validation, schema hardening, route-level behavior, and cross-layer integration --- ## [2.7.10] โ€” 2026-03-19 -> Sprint๏ผšไธคไธช็คพๅŒบ่ดก็Œฎ็š„ๆไพ›ๅ•†๏ผˆAlibaba Cloud Codingใ€Kimi Coding API-key๏ผ‰ๅ’Œ Docker pino ไฟฎๅคใ€‚ +> Sprint: Two new community-contributed providers (Alibaba Cloud Coding, Kimi Coding API-key) and Docker pino fix. -### โœจ ๆ–ฐ็‰นๆ€ง +### ๅŠŸ่ƒฝ็‰น็‚น -- **feat(providers)**๏ผšๆ–ฐๅขž Alibaba Cloud Coding Plan ๆ”ฏๆŒ๏ผŒไฝฟ็”จไธคไธช OpenAI ๅ…ผๅฎน็ซฏ็‚น โ€”โ€” `alicode`๏ผˆไธญๅ›ฝ๏ผ‰ๅ’Œ `alicode-intl`๏ผˆๅ›ฝ้™…๏ผ‰๏ผŒๆฏไธช็ซฏ็‚น 8 ไธชๆจกๅž‹๏ผˆ#465๏ผŒ@dtk1985๏ผ‰ -- **feat(providers)**๏ผšๆ–ฐๅขžไธ“็”จ็š„ `kimi-coding-apikey` ๆไพ›ๅ•†่ทฏๅพ„ โ€”โ€” ๅŸบไบŽ API key ็š„ Kimi Coding ่ฎฟ้—ฎไธๅ†ๅผบๅˆถ้€š่ฟ‡ไป… OAuth ็š„ `kimi-coding` ่ทฏ็”ฑใ€‚ๅŒ…ๆ‹ฌๆณจๅ†Œ่กจใ€ๅธธ้‡ใ€ๆจกๅž‹ APIใ€้…็ฝฎๅ’Œ้ชŒ่ฏๆต‹่ฏ•๏ผˆ#463๏ผŒ@Mind-Dragon๏ผ‰ +- **feat(providers)**: Added Alibaba Cloud Coding Plan support with two OpenAI-compatible endpoints โ€” `alicode` (China) and `alicode-intl` (International), each with 8 models (#465, @dtk1985) +- **feat(providers)**: Added dedicated `kimi-coding-apikey` provider path โ€” API-key-based Kimi Coding access is no longer forced through OAuth-only `kimi-coding` route. Includes registry, constants, models API, config, and validation test (#463, @Mind-Dragon) -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **fix(docker)**๏ผšไธบ Docker ้•œๅƒๆทปๅŠ ไบ†็ผบๅคฑ็š„ `split2` ไพ่ต– โ€”โ€” `pino-abstract-transport` ๅœจ่ฟ่กŒๆ—ถ้œ€่ฆๅฎƒ๏ผŒไฝ†ๆœช่ขซๅคๅˆถๅˆฐ็‹ฌ็ซ‹ๅฎนๅ™จไธญ๏ผŒๅฏผ่‡ด `Cannot find module 'split2'` ๅดฉๆบƒ๏ผˆ#459๏ผ‰ +- **fix(docker)**: Added missing `split2` dependency to Docker image โ€” `pino-abstract-transport` requires it at runtime but it was not being copied into the standalone container, causing `Cannot find module 'split2'` crashes (#459) --- ## [2.7.9] โ€” 2026-03-18 -> Sprint๏ผšCodex ๅ“ๅบ”ๅญ่ทฏๅพ„้€ไผ ๅŽŸ็”Ÿๆ”ฏๆŒใ€Windows MITM ๅดฉๆบƒไฟฎๅคๅ’Œ Combos agent schema ่ฐƒๆ•ดใ€‚ +> Sprint: Codex responses subpath passthrough natively supported, Windows MITM crash fixed, and Combos agent schemas adjusted. -### โœจ ๆ–ฐ็‰นๆ€ง +### ๅŠŸ่ƒฝ็‰น็‚น -- **feat(codex)**๏ผšCodex ๅŽŸ็”Ÿๅ“ๅบ”ๅญ่ทฏๅพ„้€ไผ  โ€”โ€” ๅŽŸ็”Ÿๅฐ† `POST /v1/responses/compact` ่ทฏ็”ฑๅˆฐ Codex ไธŠๆธธ๏ผŒๅœจไธๅ‰ฅ็ฆป `/compact` ๅŽ็ผ€็š„ๆƒ…ๅ†ตไธ‹ไฟๆŒ Claude Code ๅ…ผๅฎนๆ€ง๏ผˆ#457๏ผ‰ +- **feat(codex)**: Native responses subpath passthrough for Codex โ€” natively routes `POST /v1/responses/compact` to Codex upstream, maintaining Claude Code compatibility without stripping the `/compact` suffix (#457) -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **fix(combos)**๏ผšZod schema๏ผˆ`updateComboSchema` ๅ’Œ `createComboSchema`๏ผ‰็ŽฐๅœจๅŒ…ๅซ `system_message`ใ€`tool_filter_regex` ๅ’Œ `context_cache_protection`ใ€‚ไฟฎๅคไบ†้€š่ฟ‡ไปช่กจ็›˜ๅˆ›ๅปบ็š„ไปฃ็†็‰นๅฎš่ฎพ็ฝฎ่ขซๅŽ็ซฏ้ชŒ่ฏๅฑ‚้™้ป˜ไธขๅผƒ็š„ bug๏ผˆ#458๏ผ‰ -- **fix(mitm)**๏ผšไฟฎๅค Windows ไธŠ Kiro MITM ้…็ฝฎๅดฉๆบƒ โ€”โ€” `node-machine-id` ๅ› ็ผบๅฐ‘ `REG.exe` ็Žฏๅขƒๅคฑ่ดฅ๏ผŒไธ”ๅ›ž้€€ๆŠ›ๅ‡บไบ†่‡ดๅ‘ฝ็š„ `crypto is not defined` ้”™่ฏฏใ€‚ๅ›ž้€€็Žฐๅœจๅฎ‰ๅ…จๆญฃ็กฎๅœฐๅฏผๅ…ฅ crypto๏ผˆ#456๏ผ‰ +- **fix(combos)**: Zod schemas (`updateComboSchema` and `createComboSchema`) now include `system_message`, `tool_filter_regex`, and `context_cache_protection`. Fixes bug where agent-specific settings created via the dashboard were silently discarded by the backend validation layer (#458) +- **fix(mitm)**: Kiro MITM profile crash on Windows fixed โ€” `node-machine-id` failed due to missing `REG.exe` env, and the fallback threw a fatal `crypto is not defined` error. Fallback now safely and correctly imports crypto (#456) --- ## [2.7.8] โ€” 2026-03-18 -> Sprint๏ผš้ข„็ฎ—ไฟๅญ˜ bug + combo agent ๅŠŸ่ƒฝ UI + omniModel ๆ ‡็ญพๅฎ‰ๅ…จไฟฎๅคใ€‚ +> Sprint: Budget save bug + combo agent features UI + omniModel tag security fix. -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **fix(budget)**๏ผš"Save Limits" ไธๅ†่ฟ”ๅ›ž 422 โ€”โ€” `warningThreshold` ็Žฐๅœจๆญฃ็กฎไฝœไธบๅˆ†ๆ•ฐ๏ผˆ0โ€“1๏ผ‰ๅ‘้€๏ผŒ่€Œไธๆ˜ฏ็™พๅˆ†ๆฏ”๏ผˆ0โ€“100๏ผ‰๏ผˆ#451๏ผ‰ -- **fix(combos)**๏ผš`` ๅ†…้ƒจ็ผ“ๅญ˜ๆ ‡็ญพ็Žฐๅœจๅœจ่ฝฌๅ‘่ฏทๆฑ‚็ป™ๆไพ›ๅ•†ไน‹ๅ‰่ขซๅ‰ฅ็ฆป๏ผŒ้˜ฒๆญข็ผ“ๅญ˜ไผš่ฏไธญๆ–ญ๏ผˆ#454๏ผ‰ +- **fix(budget)**: "Save Limits" no longer returns 422 โ€” `warningThreshold` is now correctly sent as fraction (0โ€“1) instead of percentage (0โ€“100) (#451) +- **fix(combos)**: `` internal cache tag is now stripped before forwarding requests to providers, preventing cache session breaks (#454) -### โœจ ๆ–ฐ็‰นๆ€ง +### ๅŠŸ่ƒฝ็‰น็‚น -- **feat(combos)**๏ผšๅœจ combo ๅˆ›ๅปบ/็ผ–่พ‘ๆจกๆ€ๆก†ไธญๆ–ฐๅขž Agent Features ้ƒจๅˆ† โ€”โ€” ็›ดๆŽฅไปŽไปช่กจ็›˜ๆšด้œฒ `system_message` ่ฆ†็›–ใ€`tool_filter_regex` ๅ’Œ `context_cache_protection`๏ผˆ#454๏ผ‰ +- **feat(combos)**: Agent Features section added to combo create/edit modal โ€” expose `system_message` override, `tool_filter_regex`, and `context_cache_protection` directly from the dashboard (#454) --- ## [2.7.7] โ€” 2026-03-18 -> Sprint๏ผšDocker pino ๅดฉๆบƒใ€Codex CLI ๅ“ๅบ” worker ไฟฎๅคใ€package-lock ๅŒๆญฅใ€‚ +> Sprint: Docker pino crash, Codex CLI responses worker fix, package-lock sync. -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **fix(docker)**๏ผš`pino-abstract-transport` ๅ’Œ `pino-pretty` ็Žฐๅœจๅœจ Docker runner ้˜ถๆฎตๆ˜พๅผๅคๅˆถ โ€”โ€” Next.js ็‹ฌ็ซ‹่ทŸ่ธช้—ๆผ่ฟ™ไบ›ๅฏน็ญ‰ไพ่ต–๏ผŒๅฏผ่‡ดๅฏๅŠจๆ—ถ `Cannot find module pino-abstract-transport` ๅดฉๆบƒ๏ผˆ#449๏ผ‰ -- **fix(responses)**๏ผšไปŽ `/v1/responses` ่ทฏ็”ฑไธญ็งป้™ค `initTranslators()` โ€”โ€” ๅฏผ่‡ด Next.js worker ๅดฉๆบƒ๏ผŒๅ‡บ็Žฐ `the worker has exited` ๆœชๆ•่Žทๅผ‚ๅธธ๏ผŒๅœจ Codex CLI ่ฏทๆฑ‚ไธญ๏ผˆ#450๏ผ‰ +- **fix(docker)**: `pino-abstract-transport` and `pino-pretty` now explicitly copied in Docker runner stage โ€” Next.js standalone trace misses these peer deps, causing `Cannot find module pino-abstract-transport` crash on startup (#449) +- **fix(responses)**: Remove `initTranslators()` from `/v1/responses` route โ€” was crashing Next.js worker with `the worker has exited` uncaughtException on Codex CLI requests (#450) -### ๐Ÿ”ง ็ปดๆŠค +### ๐Ÿ”ง Maintenance -- **chore(deps)**๏ผš`package-lock.json` ็Žฐๅœจๅœจๆฏๆฌก็‰ˆๆœฌๅ‡็บงๆ—ถๆไบค๏ผŒไปฅ็กฎไฟ Docker `npm ci` ไฝฟ็”จ็ฒพ็กฎ็š„ไพ่ต–็‰ˆๆœฌ +- **chore(deps)**: `package-lock.json` now committed on every version bump to ensure Docker `npm ci` uses exact dependency versions --- ## [2.7.5] โ€” 2026-03-18 -> Sprint๏ผšUX ๆ”น่ฟ›ๅ’Œ Windows CLI ๅฅๅบทๆฃ€ๆŸฅไฟฎๅคใ€‚ +> Sprint: UX improvements and Windows CLI healthcheck fix. -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **fix(ux)**๏ผšๅœจ็™ปๅฝ•้กต้ขๆ˜พ็คบ้ป˜่ฎคๅฏ†็ ๆ็คบ โ€”โ€” ๆ–ฐ็”จๆˆท็Žฐๅœจไผšๅœจๅฏ†็ ่พ“ๅ…ฅๆก†ไธ‹ๆ–น็œ‹ๅˆฐ `"Default password: 123456"`๏ผˆ#437๏ผ‰ -- **fix(cli)**๏ผšClaude CLI ๅ’Œๅ…ถไป– npm ๅฎ‰่ฃ…็š„ๅทฅๅ…ท็Žฐๅœจๅœจ Windows ไธŠๆญฃ็กฎๆฃ€ๆต‹ไธบๅฏ่ฟ่กŒ โ€”โ€” spawn ไฝฟ็”จ `shell:true` ไปฅ่งฃๅ†ณ้€š่ฟ‡ PATHEXT ็š„ `.cmd` ๅŒ…่ฃ…ๅ™จ้—ฎ้ข˜๏ผˆ#447๏ผ‰ +- **fix(ux)**: Show default password hint on login page โ€” new users now see `"Default password: 123456"` below the password input (#437) +- **fix(cli)**: Claude CLI and other npm-installed tools now correctly detected as runnable on Windows โ€” spawn uses `shell:true` to resolve `.cmd` wrappers via PATHEXT (#447) --- ## [2.7.4] โ€” 2026-03-18 -> Sprint๏ผšๆœ็ดขๅทฅๅ…ทไปช่กจ็›˜ใ€i18n ไฟฎๅคใ€Copilot ้™ๅˆถใ€Serper ้ชŒ่ฏไฟฎๅคใ€‚ +> Sprint: Search Tools dashboard, i18n fixes, Copilot limits, Serper validation fix. -### ๐Ÿš€ ๆ–ฐ็‰นๆ€ง +### ๅŠŸ่ƒฝ็‰น็‚น -- **feat(search)**๏ผšๆ–ฐๅขžๆœ็ดขๆธธไนๅœบ๏ผˆ็ฌฌ 10 ไธช็ซฏ็‚น๏ผ‰ใ€ๆœ็ดขๅทฅๅ…ท้กต้ข๏ผŒๅŒ…ๅซๆไพ›ๅ•†ๆฏ”่พƒ/้‡ๆŽ’ๅบๆตๆฐด็บฟ/ๆœ็ดขๅŽ†ๅฒใ€ๆœฌๅœฐ้‡ๆŽ’ๅบ่ทฏ็”ฑใ€ๆœ็ดข API ่ฎค่ฏๅฎˆๅซ๏ผˆ#443 by @Regis-RCR๏ผ‰ - - ๆ–ฐ่ทฏ็”ฑ๏ผš`/dashboard/search-tools` - - ่ฐƒ่ฏ•้ƒจๅˆ†ไธ‹็š„ไพง่พนๆ ๆก็›ฎ - - `GET /api/search/providers` ๅ’Œ `GET /api/search/stats`๏ผŒๅธฆ่ฎค่ฏๅฎˆๅซ - - ๆœฌๅœฐๆไพ›ๅ•†่Š‚็‚น่ทฏ็”ฑ๏ผŒ็”จไบŽ `/v1/rerank` - - ๆœ็ดขๅ‘ฝๅ็ฉบ้—ดไธญ 30+ i18n ้”ฎ +- **feat(search)**: Add Search Playground (10th endpoint), Search Tools page with Compare Providers/Rerank Pipeline/Search History, local rerank routing, auth guards on search API (#443 by @Regis-RCR) + - New route: `/dashboard/search-tools` + - Sidebar entry under Debug section + - `GET /api/search/providers` and `GET /api/search/stats` with auth guards + - Local provider_nodes routing for `/v1/rerank` + - 30+ i18n keys in search namespace -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **fix(search)**๏ผšไฟฎๅค Brave ๆ–ฐ้—ป่ง„่ŒƒๅŒ–ๅ™จ๏ผˆๆญคๅ‰่ฟ”ๅ›ž 0 ไธช็ป“ๆžœ๏ผ‰๏ผŒๅœจ่ง„่ŒƒๅŒ–ๅŽๅผบๅˆถๆ‰ง่กŒ max_results ๆˆชๆ–ญ๏ผŒไฟฎๅค็ซฏ็‚น้กต้ข่Žทๅ– URL๏ผˆ#443 by @Regis-RCR๏ผ‰ -- **fix(analytics)**๏ผšๆœฌๅœฐๅŒ–ๅˆ†ๆžๆ—ฅ/ๆœŸๆ ‡็ญพ โ€”โ€” ็”จ `Intl.DateTimeFormat(locale)` ๆ›ฟๆข็กฌ็ผ–็ ็š„่‘ก่„็‰™่ฏญๅญ—็ฌฆไธฒ๏ผˆ#444 by @hijak๏ผ‰ -- **fix(copilot)**๏ผšไฟฎๆญฃ GitHub Copilot ่ดฆๆˆท็ฑปๅž‹ๆ˜พ็คบ๏ผŒไปŽ้™ๅˆถไปช่กจ็›˜่ฟ‡ๆปค่ฏฏๅฏผๆ€ง็š„ๆ— ้™้…้ข่กŒ๏ผˆ#445 by @hijak๏ผ‰ -- **fix(providers)**๏ผšๅœๆญขๆ‹’็ปๆœ‰ๆ•ˆ็š„ Serper API key โ€”โ€” ๅฐ†้ž 4xx ๅ“ๅบ”่ง†ไธบๆœ‰ๆ•ˆ่ฎค่ฏ๏ผˆ#446 by @hijak๏ผ‰ +- **fix(search)**: Fix Brave news normalizer (was returning 0 results), enforce max_results truncation post-normalization, fix Endpoints page fetch URL (#443 by @Regis-RCR) +- **fix(analytics)**: Localize analytics day/date labels โ€” replace hardcoded Portuguese strings with `Intl.DateTimeFormat(locale)` (#444 by @hijak) +- **fix(copilot)**: Correct GitHub Copilot account type display, filter misleading unlimited quota rows from limits dashboard (#445 by @hijak) +- **fix(providers)**: Stop rejecting valid Serper API keys โ€” treat non-4xx responses as valid authentication (#446 by @hijak) --- ## [2.7.3] โ€” 2026-03-18 -> Sprint๏ผšCodex ็›ดๆŽฅ API ้…้ขๅ›ž้€€ไฟฎๅคใ€‚ +> Sprint: Codex direct API quota fallback fix. -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **fix(codex)**๏ผšๅœจ็›ดๆŽฅ API ๅ›ž้€€ไธญ้˜ปๆญขๆฏๅ‘จๅทฒ่€—ๅฐฝ็š„่ดฆๆˆท๏ผˆ#440๏ผ‰ - - `resolveQuotaWindow()` ๅ‰็ผ€ๅŒน้…๏ผš`"weekly"` ็ŽฐๅœจๅŒน้… `"weekly (7d)"` ็ผ“ๅญ˜้”ฎ - - `applyCodexWindowPolicy()` ๆญฃ็กฎๅผบๅˆถๆ‰ง่กŒ `useWeekly`/`use5h` ๅผ€ๅ…ณ - - 4 ไธชๆ–ฐๅ›žๅฝ’ๆต‹่ฏ•๏ผˆๅ…ฑ 766 ไธช๏ผ‰ +- **fix(codex)**: Block weekly-exhausted accounts in direct API fallback (#440) + - `resolveQuotaWindow()` prefix matching: `"weekly"` now matches `"weekly (7d)"` cache keys + - `applyCodexWindowPolicy()` enforces `useWeekly`/`use5h` toggles correctly + - 4 new regression tests (766 total) --- ## [2.7.2] โ€” 2026-03-18 -> Sprint๏ผšๆต…่‰ฒๆจกๅผ UI ๅฏนๆฏ”ๅบฆไฟฎๅคใ€‚ +> Sprint: Light mode UI contrast fixes. -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **fix(logs)**๏ผšไฟฎๅค่ฏทๆฑ‚ๆ—ฅๅฟ—่ฟ‡ๆปคๆŒ‰้’ฎๅ’Œ combo ๅพฝ็ซ ็š„ๆต…่‰ฒๆจกๅผๅฏนๆฏ”ๅบฆ๏ผˆ#378๏ผ‰ - - ้”™่ฏฏ/ๆˆๅŠŸ/Combo ่ฟ‡ๆปคๆŒ‰้’ฎ็Žฐๅœจๅœจๆต…่‰ฒๆจกๅผไธ‹ๅฏ่ฏป - - Combo ่กŒๅพฝ็ซ ๅœจๆต…่‰ฒๆจกๅผไธ‹ไฝฟ็”จๆ›ดๅผบ็š„็ดซ่‰ฒ +- **fix(logs)**: Fix light mode contrast in request logs filter buttons and combo badge (#378) + - Error/Success/Combo filter buttons now readable in light mode + - Combo row badge uses stronger violet in light mode --- ## [2.7.1] โ€” 2026-03-17 -> Sprint๏ผš็ปŸไธ€ Web ๆœ็ดข่ทฏ็”ฑ๏ผˆPOST /v1/search๏ผ‰๏ผŒไฝฟ็”จ 5 ไธชๆไพ›ๅ•† + Next.js 16.1.7 ๅฎ‰ๅ…จไฟฎๅค๏ผˆ6 ไธช CVE๏ผ‰ใ€‚ +> Sprint: Unified web search routing (POST /v1/search) with 5 providers + Next.js 16.1.7 security fixes (6 CVEs). -### โœจ ๆ–ฐ็‰นๆ€ง +### โœจ New Features -- **feat(search)**๏ผš็ปŸไธ€ Web ๆœ็ดข่ทฏ็”ฑ โ€”โ€” `POST /v1/search`๏ผŒไฝฟ็”จ 5 ไธชๆไพ›ๅ•†๏ผˆSerperใ€Braveใ€Perplexityใ€Exaใ€Tavily๏ผ‰ - - ่ทจๆไพ›ๅ•†่‡ชๅŠจๆ•…้šœ่ฝฌ็งป๏ผŒๆฏๆœˆ 6500+ ๆฌกๅ…่ดนๆœ็ดข - - ๅ†…ๅญ˜็ผ“ๅญ˜๏ผŒๅธฆ่ฏทๆฑ‚ๅˆๅนถ๏ผˆๅฏ้…็ฝฎ TTL๏ผ‰ - - ไปช่กจ็›˜๏ผš`/dashboard/analytics` ไธญ็š„ๆœ็ดขๅˆ†ๆžๆ ‡็ญพ้กต๏ผŒๅŒ…ๅซๆไพ›ๅ•†ๆ‹†ๅˆ†ใ€็ผ“ๅญ˜ๅ‘ฝไธญ็Ž‡ใ€ๆˆๆœฌ่ทŸ่ธช - - ๆ–ฐ API๏ผš`GET /api/v1/search/analytics`๏ผŒ็”จไบŽๆœ็ดข่ฏทๆฑ‚็ปŸ่ฎก - - ๆ•ฐๆฎๅบ“่ฟ็งป๏ผš`call_logs` ไธญ็š„ `request_type` ๅˆ—๏ผŒ็”จไบŽ้ž่Šๅคฉ่ฏทๆฑ‚่ฟฝ่ธช - - Zod ้ชŒ่ฏ๏ผˆ`v1SearchSchema`๏ผ‰ใ€่ฎค่ฏ้—จๆŽงใ€้€š่ฟ‡ `recordCost()` ่ฎฐๅฝ•ๆˆๆœฌ +- **feat(search)**: Unified web search routing โ€” `POST /v1/search` with 5 providers (Serper, Brave, Perplexity, Exa, Tavily) + - Auto-failover across providers, 6,500+ free searches/month + - In-memory cache with request coalescing (configurable TTL) + - Dashboard: Search Analytics tab in `/dashboard/analytics` with provider breakdown, cache hit rate, cost tracking + - New API: `GET /api/v1/search/analytics` for search request statistics + - DB migration: `request_type` column on `call_logs` for non-chat request tracking + - Zod validation (`v1SearchSchema`), auth-gated, cost recorded via `recordCost()` -### ๐Ÿ”’ ๅฎ‰ๅ…จ +### ๅฎ‰ๅ…จ -- **deps**๏ผšNext.js 16.1.6 โ†’ 16.1.7 โ€”โ€” ไฟฎๅค 6 ไธช CVE๏ผš - - **ไธฅ้‡**๏ผšCVE-2026-29057๏ผˆ้€š่ฟ‡ http-proxy ็š„ HTTP ่ฏทๆฑ‚่ตฐ็ง๏ผ‰ - - **้ซ˜**๏ผšCVE-2026-27977ใ€CVE-2026-27978๏ผˆWebSocket + Server Actions๏ผ‰ - - **ไธญ**๏ผšCVE-2026-27979ใ€CVE-2026-27980ใ€CVE-2026-jcc7 +- **deps**: Next.js 16.1.6 โ†’ 16.1.7 โ€” fixes 6 CVEs: + - **Critical**: CVE-2026-29057 (HTTP request smuggling via http-proxy) + - **High**: CVE-2026-27977, CVE-2026-27978 (WebSocket + Server Actions) + - **Medium**: CVE-2026-27979, CVE-2026-27980, CVE-2026-jcc7 -### ๐Ÿ“ ๆ–ฐๅขžๆ–‡ไปถ +### ๐Ÿ“ New Files -| ๆ–‡ไปถ | ็›ฎ็š„ | -| ---------------------------------------------------------------- | ------------------------------------- | -| `open-sse/handlers/search.ts` | ๆœ็ดขๅค„็†ๅ™จ๏ผŒ5 ๆไพ›ๅ•†่ทฏ็”ฑ | -| `open-sse/config/searchRegistry.ts` | ๆไพ›ๅ•†ๆณจๅ†Œ่กจ๏ผˆ่ฎค่ฏใ€ๆˆๆœฌใ€้…้ขใ€TTL๏ผ‰ | -| `open-sse/services/searchCache.ts` | ๅ†…ๅญ˜็ผ“ๅญ˜๏ผŒๅธฆ่ฏทๆฑ‚ๅˆๅนถ | -| `src/app/api/v1/search/route.ts` | Next.js ่ทฏ็”ฑ๏ผˆPOST + GET๏ผ‰ | -| `src/app/api/v1/search/analytics/route.ts` | ๆœ็ดข็ปŸ่ฎก API | -| `src/app/(dashboard)/dashboard/analytics/SearchAnalyticsTab.tsx` | ๅˆ†ๆžไปช่กจ็›˜ๆ ‡็ญพ้กต | -| `src/lib/db/migrations/007_search_request_type.sql` | ๆ•ฐๆฎๅบ“่ฟ็งป | -| `tests/unit/search-registry.test.mjs` | 277 ่กŒๅ•ๅ…ƒๆต‹่ฏ• | +| File | Purpose | +| ---------------------------------------------------------------- | ------------------------------------------ | +| `open-sse/handlers/search.ts` | Search handler with 5-provider routing | +| `open-sse/config/searchRegistry.ts` | Provider registry (auth, cost, quota, TTL) | +| `open-sse/services/searchCache.ts` | In-memory cache with request coalescing | +| `src/app/api/v1/search/route.ts` | Next.js route (POST + GET) | +| `src/app/api/v1/search/analytics/route.ts` | Search stats API | +| `src/app/(dashboard)/dashboard/analytics/SearchAnalyticsTab.tsx` | Analytics dashboard tab | +| `src/lib/db/migrations/007_search_request_type.sql` | DB migration | +| `tests/unit/search-registry.test.mjs` | 277 lines of unit tests | --- ## [2.7.0] โ€” 2026-03-17 -> Sprint๏ผšๅ— ClawRouter ๅฏๅ‘็š„ๅŠŸ่ƒฝ โ€”โ€” toolCalling ๆ ‡ๅฟ—ใ€ๅคš่ฏญ่จ€ๆ„ๅ›พๆฃ€ๆต‹ใ€ๅŸบๅ‡†้ฉฑๅŠจๅ›ž้€€ใ€่ฏทๆฑ‚ๅŽป้‡ใ€ๅฏๆ’ๆ‹” RouterStrategyใ€Grok-4 Fast + GLM-5 + MiniMax M2.5 + Kimi K2.5 ๅฎšไปทใ€‚ +> Sprint: ClawRouter-inspired features โ€” toolCalling flag, multilingual intent detection, benchmark-driven fallback, request deduplication, pluggable RouterStrategy, Grok-4 Fast + GLM-5 + MiniMax M2.5 + Kimi K2.5 pricing. -### โœจ ๆ–ฐๆจกๅž‹ไธŽๅฎšไปท +### โœจ New Models & Pricing -- **feat(pricing)**๏ผšxAI Grok-4 Fast โ€”โ€” `$0.20/$0.50 per 1M tokens`๏ผŒ1143ms p50 ๅปถ่ฟŸ๏ผŒๆ”ฏๆŒๅทฅๅ…ท่ฐƒ็”จ -- **feat(pricing)**๏ผšxAI Grok-4๏ผˆๆ ‡ๅ‡†๏ผ‰โ€”โ€” `$0.20/$1.50 per 1M tokens`๏ผŒๆŽจ็†ๆ——่ˆฐ -- **feat(pricing)**๏ผšGLM-5๏ผˆ้€š่ฟ‡ Z.AI๏ผ‰โ€”โ€” `$0.5/1M`๏ผŒ128K ่พ“ๅ‡บไธŠไธ‹ๆ–‡ -- **feat(pricing)**๏ผšMiniMax M2.5 โ€”โ€” `$0.30/1M input`๏ผŒๆŽจ็† + ไปฃ็†ไปปๅŠก -- **feat(pricing)**๏ผšDeepSeek V3.2 โ€”โ€” ๆ›ดๆ–ฐๅฎšไปท `$0.27/$1.10 per 1M` -- **feat(pricing)**๏ผšKimi K2.5๏ผˆ้€š่ฟ‡ Moonshot API๏ผ‰โ€”โ€” ็›ดๆŽฅ Moonshot API ่ฎฟ้—ฎ -- **feat(providers)**๏ผšๆ–ฐๅขž Z.AI ๆไพ›ๅ•†๏ผˆ`zai` ๅˆซๅ๏ผ‰โ€”โ€” GLM-5 ็ณปๅˆ—๏ผŒไฝฟ็”จ 128K ่พ“ๅ‡บ +- **feat(pricing)**: xAI Grok-4 Fast โ€” `$0.20/$0.50 per 1M tokens`, 1143ms p50 latency, tool calling supported +- **feat(pricing)**: xAI Grok-4 (standard) โ€” `$0.20/$1.50 per 1M tokens`, reasoning flagship +- **feat(pricing)**: GLM-5 via Z.AI โ€” `$0.5/1M`, 128K output context +- **feat(pricing)**: MiniMax M2.5 โ€” `$0.30/1M input`, reasoning + agentic tasks +- **feat(pricing)**: DeepSeek V3.2 โ€” updated pricing `$0.27/$1.10 per 1M` +- **feat(pricing)**: Kimi K2.5 via Moonshot API โ€” direct Moonshot API access +- **feat(providers)**: Z.AI provider added (`zai` alias) โ€” GLM-5 family with 128K output -### ๐Ÿง  ่ทฏ็”ฑๆ™บ่ƒฝ +### ๐Ÿง  Routing Intelligence -- **feat(registry)**๏ผšๆไพ›ๅ•†ๆณจๅ†Œ่กจไธญๆฏๆจกๅž‹็š„ `toolCalling` ๆ ‡ๅฟ— โ€”โ€” combo ็Žฐๅœจๅฏไปฅๅๅฅฝ/่ฆๆฑ‚ๆ”ฏๆŒๅทฅๅ…ท่ฐƒ็”จ็š„ๆจกๅž‹ -- **feat(scoring)**๏ผšๅคš่ฏญ่จ€ๆ„ๅ›พๆฃ€ๆต‹๏ผŒ็”จไบŽ AutoCombo ่ฏ„ๅˆ† โ€”โ€” PT/ZH/ES/AR ่„šๆœฌ/่ฏญ่จ€ๆจกๅผๆ นๆฎ่ฏทๆฑ‚ไธŠไธ‹ๆ–‡ๅฝฑๅ“ๆจกๅž‹้€‰ๆ‹ฉ -- **feat(fallback)**๏ผšๅŸบๅ‡†้ฉฑๅŠจ็š„ๅ›ž้€€้“พ โ€”โ€” ไฝฟ็”จ็œŸๅฎžๅปถ่ฟŸๆ•ฐๆฎ๏ผˆๆฅ่‡ช `comboMetrics` ็š„ p50๏ผ‰ๅŠจๆ€้‡ๆ–ฐๆŽ’ๅบๅ›ž้€€ไผ˜ๅ…ˆ็บง -- **feat(dedup)**๏ผš้€š่ฟ‡ๅ†…ๅฎนๅ“ˆๅธŒ็š„่ฏทๆฑ‚ๅŽป้‡ โ€”โ€” 5 ็ง’ๅน‚็ญ‰็ช—ๅฃ้˜ฒๆญข้‡ๅคๅฎขๆˆท็ซฏ้‡่ฏ•ๅฏผ่‡ด็š„ๆไพ›ๅ•†่ฐƒ็”จ -- **feat(router)**๏ผš`autoCombo/routerStrategy.ts` ไธญๅฏๆ’ๆ‹”็š„ `RouterStrategy` ๆŽฅๅฃ โ€”โ€” ๅฏไปฅๆณจๅ…ฅ่‡ชๅฎšไน‰่ทฏ็”ฑ้€ป่พ‘๏ผŒๆ— ้œ€ไฟฎๆ”นๆ ธๅฟƒ +- **feat(registry)**: `toolCalling` flag per model in provider registry โ€” combos can now prefer/require tool-calling capable models +- **feat(scoring)**: Multilingual intent detection for AutoCombo scoring โ€” PT/ZH/ES/AR script/language patterns influence model selection per request context +- **feat(fallback)**: Benchmark-driven fallback chains โ€” real latency data (p50 from `comboMetrics`) used to re-order fallback priority dynamically +- **feat(dedup)**: Request deduplication via content-hash โ€” 5-second idempotency window prevents duplicate provider calls from retrying clients +- **feat(router)**: Pluggable `RouterStrategy` interface in `autoCombo/routerStrategy.ts` โ€” custom routing logic can be injected without modifying core -### ๐Ÿ”ง MCP ๆœๅŠกๅ™จๆ”น่ฟ› +### ๐Ÿ”ง MCP Server Improvements -- **feat(mcp)**๏ผš2 ไธชๆ–ฐ็š„้ซ˜็บงๅทฅๅ…ท schema๏ผš`omniroute_get_provider_metrics`๏ผˆๆฏๆไพ›ๅ•† p50/p95/p99๏ผ‰ๅ’Œ `omniroute_explain_route`๏ผˆ่ทฏ็”ฑๅ†ณ็ญ–่งฃ้‡Š๏ผ‰ -- **feat(mcp)**๏ผšMCP ๅทฅๅ…ท่ฎค่ฏ่Œƒๅ›ดๆ›ดๆ–ฐ โ€”โ€” ๆ–ฐๅขž `metrics:read` ่Œƒๅ›ด๏ผŒ็”จไบŽๆไพ›ๅ•†ๆŒ‡ๆ ‡ๅทฅๅ…ท -- **feat(mcp)**๏ผš`omniroute_best_combo_for_task` ็ŽฐๅœจๆŽฅๅ— `languageHint` ๅ‚ๆ•ฐ๏ผŒ็”จไบŽๅคš่ฏญ่จ€่ทฏ็”ฑ +- **feat(mcp)**: 2 new advanced tool schemas: `omniroute_get_provider_metrics` (p50/p95/p99 per provider) and `omniroute_explain_route` (routing decision explanation) +- **feat(mcp)**: MCP tool auth scopes updated โ€” `metrics:read` scope added for provider metrics tools +- **feat(mcp)**: `omniroute_best_combo_for_task` now accepts `languageHint` parameter for multilingual routing -### ๐Ÿ“Š ๅฏ่ง‚ๆต‹ๆ€ง +### ๐Ÿ“Š Observability -- **feat(metrics)**๏ผšๆ‰ฉๅฑ• `comboMetrics.ts`๏ผŒไฝฟ็”จๆฏๆไพ›ๅ•†/่ดฆๆˆท็š„ๅฎžๆ—ถๅปถ่ฟŸ็™พๅˆ†ไฝ่ฟฝ่ธช -- **feat(health)**๏ผšๅฅๅบท API๏ผˆ`/api/monitoring/health`๏ผ‰็Žฐๅœจ่ฟ”ๅ›žๆฏๆไพ›ๅ•†็š„ `p50Latency` ๅ’Œ `errorRate` ๅญ—ๆฎต -- **feat(usage)**๏ผš็”จ้‡ๅŽ†ๅฒ่ฟ็งป๏ผŒ็”จไบŽๆฏๆจกๅž‹ๅปถ่ฟŸ่ฟฝ่ธช +- **feat(metrics)**: `comboMetrics.ts` extended with real-time latency percentile tracking per provider/account +- **feat(health)**: Health API (`/api/monitoring/health`) now returns per-provider `p50Latency` and `errorRate` fields +- **feat(usage)**: Usage history migration for per-model latency tracking -### ๐Ÿ—„๏ธ ๆ•ฐๆฎๅบ“่ฟ็งป +### ๐Ÿ—„๏ธ DB Migrations -- **feat(migrations)**๏ผš`combo_metrics` ่กจไธญๆ–ฐๅขž `latency_p50` ๅˆ— โ€”โ€” ้›ถ็ ดๅๆ€ง๏ผŒๅฏน็Žฐๆœ‰็”จๆˆทๅฎ‰ๅ…จ +- **feat(migrations)**: New column `latency_p50` in `combo_metrics` table โ€” zero-breaking, safe for existing users -### ๐Ÿ› Bug ไฟฎๅค / ๅ…ณ้—ญ +### ๐Ÿ› Bug Fixes / Closures -- **close(#411)**๏ผšWindows ไธŠ better-sqlite3 ๅ“ˆๅธŒๆจกๅ—่งฃๆž โ€”โ€” ๅทฒๅœจ v2.6.10๏ผˆf02c5b5๏ผ‰ไฟฎๅค -- **close(#409)**๏ผš้™„ๅŠ ๆ–‡ไปถๆ—ถ GitHub Copilot ่Šๅคฉ่กฅๅ…จไฝฟ็”จ Claude ๆจกๅž‹ๅคฑ่ดฅ โ€”โ€” ๅทฒๅœจ v2.6.9๏ผˆ838f1d6๏ผ‰ไฟฎๅค -- **close(#405)**๏ผš#411 ็š„้‡ๅค โ€”โ€” ๅทฒ่งฃๅ†ณ +- **close(#411)**: better-sqlite3 hashed module resolution on Windows โ€” fixed in v2.6.10 (f02c5b5) +- **close(#409)**: GitHub Copilot chat completions fail with Claude models when files attached โ€” fixed in v2.6.9 (838f1d6) +- **close(#405)**: Duplicate of #411 โ€” resolved ## [2.6.10] โ€” 2026-03-17 -> Windows ไฟฎๅค๏ผšๆ— ้œ€ node-gyp/Python/MSVC ็š„ better-sqlite3 ้ข„ๆž„ๅปบไธ‹่ฝฝ๏ผˆ#426๏ผ‰ใ€‚ +> Windows fix: better-sqlite3 prebuilt download without node-gyp/Python/MSVC (#426). -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **fix(install/#426)**๏ผšๅœจ Windows ไธŠ๏ผŒ`npm install -g omniroute` ๆญคๅ‰ไผšๅคฑ่ดฅ๏ผŒๆŠฅ้”™ `better_sqlite3.node is not a valid Win32 application`๏ผŒๅ› ไธบๆ†็ป‘็š„ๅŽŸ็”ŸไบŒ่ฟ›ๅˆถๆ–‡ไปถๆ˜ฏไธบ Linux ็ผ–่ฏ‘็š„ใ€‚ๅœจ `scripts/postinstall.mjs` ไธญๆ–ฐๅขž **็ญ–็•ฅ 1.5**๏ผšไฝฟ็”จ `@mapbox/node-pre-gyp install --fallback-to-build=false`๏ผˆๆ†็ป‘ๅœจ `better-sqlite3` ไธญ๏ผ‰ไธ‹่ฝฝๅฝ“ๅ‰ OS/arch ็š„ๆญฃ็กฎ้ข„ๆž„ๅปบไบŒ่ฟ›ๅˆถๆ–‡ไปถ๏ผŒๆ— ้œ€ไปปไฝ•ๆž„ๅปบๅทฅๅ…ท๏ผˆๆ— ้œ€ node-gypใ€Pythonใ€MSVC๏ผ‰ใ€‚ไป…ๅœจไธ‹่ฝฝๅคฑ่ดฅๆ—ถๅ›ž้€€ๅˆฐ `npm rebuild`ใ€‚ๆ–ฐๅขžๅนณๅฐ็‰นๅฎš็š„้”™่ฏฏๆถˆๆฏ๏ผŒ้™„ๅธฆๆธ…ๆ™ฐ็š„ๆ‰‹ๅŠจไฟฎๅค่ฏดๆ˜Žใ€‚ +- **fix(install/#426)**: On Windows, `npm install -g omniroute` used to fail with `better_sqlite3.node is not a valid Win32 application` because the bundled native binary was compiled for Linux. Adds **Strategy 1.5** to `scripts/postinstall.mjs`: uses `@mapbox/node-pre-gyp install --fallback-to-build=false` (bundled within `better-sqlite3`) to download the correct prebuilt binary for the current OS/arch without requiring any build tools (no node-gyp, no Python, no MSVC). Falls back to `npm rebuild` only if the download fails. Adds platform-specific error messages with clear manual fix instructions. --- ## [2.6.9] โ€” 2026-03-17 -> CI ไฟฎๅค๏ผˆt11 any-budget๏ผ‰ใ€bug ไฟฎๅค #409๏ผˆ้€š่ฟ‡ Copilot+Claude ็š„ๆ–‡ไปถ้™„ไปถ๏ผ‰ใ€ๅ‘ๅธƒๅทฅไฝœๆตไฟฎๆญฃใ€‚ +> CI fixes (t11 any-budget), bug fix #409 (file attachments via Copilot+Claude), release workflow correction. -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **fix(ci)**๏ผšไปŽ `openai-responses.ts` ๅ’Œ `chatCore.ts` ็š„ๆณจ้‡Šไธญ็งป้™คๅ•่ฏ "any"๏ผŒ่ฟ™ไบ›ๆณจ้‡Šๅฏผ่‡ด t11 `\bany\b` ้ข„็ฎ—ๆฃ€ๆŸฅๅคฑ่ดฅ๏ผˆๆญฃๅˆ™่ฎกๆ•ฐๆณจ้‡Šๆ—ถ็š„่ฏฏๆŠฅ๏ผ‰ -- **fix(chatCore)**๏ผšๅœจ่ฝฌๅ‘็ป™ๆไพ›ๅ•†ไน‹ๅ‰่ง„่ŒƒๅŒ–ไธๆ”ฏๆŒ็š„ๅ†…ๅฎน้ƒจๅˆ†็ฑปๅž‹๏ผˆ#409 โ€”โ€” Cursor ๅœจ้™„ๅŠ  `.md` ๆ–‡ไปถๆ—ถๅ‘้€ `{type:"file"}`๏ผ›Copilot ๅ’Œๅ…ถไป– OpenAI ๅ…ผๅฎนๆไพ›ๅ•†ๆ‹’็ป๏ผŒๆŠฅ้”™ "type has to be either 'image_url' or 'text'"๏ผ›ไฟฎๅคๅฐ† `file`/`document` ๅ—่ฝฌๆขไธบ `text` ๅนถไธขๅผƒๆœช็Ÿฅ็ฑปๅž‹๏ผ‰ +- **fix(ci)**: Remove word "any" from comments in `openai-responses.ts` and `chatCore.ts` that were failing the t11 `\bany\b` budget check (false positive from regex counting comments) +- **fix(chatCore)**: Normalize unsupported content part types before forwarding to providers (#409 โ€” Cursor sends `{type:"file"}` when `.md` files are attached; Copilot and other OpenAI-compat providers reject with "type has to be either 'image_url' or 'text'"; fix converts `file`/`document` blocks to `text` and drops unknown types) -### ๐Ÿ”ง ๅทฅไฝœๆต +### ๐Ÿ”ง Workflow -- **chore(generate-release)**๏ผšๆ–ฐๅขžๅŽŸๅญๆไบค่ง„ๅˆ™ โ€”โ€” ็‰ˆๆœฌๅ‡็บง๏ผˆ`npm version patch`๏ผ‰ๅฟ…้กปๅœจๆไบคๅŠŸ่ƒฝๆ–‡ไปถไน‹ๅ‰ๅ‘็”Ÿ๏ผŒไปฅ็กฎไฟๆ ‡็ญพๅง‹็ปˆๆŒ‡ๅ‘ๅŒ…ๅซๆ‰€ๆœ‰็‰ˆๆœฌๅ˜ๆ›ด็š„ๆไบค +- **chore(generate-release)**: Add ATOMIC COMMIT RULE โ€” version bump (`npm version patch`) MUST happen before committing feature files to ensure tag always points to a commit containing all version changes together --- ## [2.6.8] โ€” 2026-03-17 -> Sprint๏ผšCombo ไฝœไธบ Agent๏ผˆ็ณป็ปŸๆ็คบ่ฏ + ๅทฅๅ…ท่ฟ‡ๆปค๏ผ‰ใ€Context ็ผ“ๅญ˜ไฟๆŠคใ€่‡ชๅŠจๆ›ดๆ–ฐใ€่ฏฆ็ป†ๆ—ฅๅฟ—ใ€MITM Kiro IDEใ€‚ +> Sprint: Combo as Agent (system prompt + tool filter), Context Caching Protection, Auto-Update, Detailed Logs, MITM Kiro IDE. -### ๐Ÿ—„๏ธ ๆ•ฐๆฎๅบ“่ฟ็งป๏ผˆ้›ถ็ ดๅๆ€ง โ€”โ€” ๅฏน็Žฐๆœ‰็”จๆˆทๅฎ‰ๅ…จ๏ผ‰ +### ๐Ÿ—„๏ธ DB Migrations (zero-breaking โ€” safe for existing users) -- **005_combo_agent_fields.sql**๏ผš`ALTER TABLE combos ADD COLUMN system_message TEXT DEFAULT NULL`๏ผŒ`tool_filter_regex TEXT DEFAULT NULL`๏ผŒ`context_cache_protection INTEGER DEFAULT 0` -- **006_detailed_request_logs.sql**๏ผšๆ–ฐๅขž `request_detail_logs` ่กจ๏ผŒไฝฟ็”จ 500 ๆก็›ฎ็Žฏๅฝข็ผ“ๅ†ฒๅŒบ่งฆๅ‘ๅ™จ๏ผŒ้€š่ฟ‡่ฎพ็ฝฎๅผ€ๅ…ณ้€‰ๆ‹ฉๅŠ ๅ…ฅ +- **005_combo_agent_fields.sql**: `ALTER TABLE combos ADD COLUMN system_message TEXT DEFAULT NULL`, `tool_filter_regex TEXT DEFAULT NULL`, `context_cache_protection INTEGER DEFAULT 0` +- **006_detailed_request_logs.sql**: New `request_detail_logs` table with 500-entry ring-buffer trigger, opt-in via settings toggle -### โœจ ๆ–ฐ็‰นๆ€ง +### ๅŠŸ่ƒฝ็‰น็‚น -- **feat(combo)**๏ผšๆฏ Combo ็ณป็ปŸๆถˆๆฏ่ฆ†็›–๏ผˆ#399 โ€”โ€” `system_message` ๅญ—ๆฎตๅœจ่ฝฌๅ‘็ป™ๆไพ›ๅ•†ไน‹ๅ‰ๆ›ฟๆขๆˆ–ๆณจๅ…ฅ็ณป็ปŸๆ็คบ่ฏ๏ผ‰ -- **feat(combo)**๏ผšๆฏ Combo ๅทฅๅ…ท่ฟ‡ๆปคๆญฃๅˆ™่กจ่พพๅผ๏ผˆ#399 โ€”โ€” `tool_filter_regex` ไป…ไฟ็•™ๅŒน้…ๆจกๅผ็š„ๅทฅๅ…ท๏ผ›ๆ”ฏๆŒ OpenAI + Anthropic ๆ ผๅผ๏ผ‰ -- **feat(combo)**๏ผšContext ็ผ“ๅญ˜ไฟๆŠค๏ผˆ#401 โ€”โ€” `context_cache_protection` ไฝฟ็”จ `provider/model` ๆ ‡่ฎฐๅ“ๅบ”๏ผŒๅนถไธบไผš่ฏ่ฟž็ปญๆ€งๅ›บๅฎšๆจกๅž‹๏ผ‰ -- **feat(settings)**๏ผš้€š่ฟ‡่ฎพ็ฝฎ่‡ชๅŠจๆ›ดๆ–ฐ๏ผˆ#320 โ€”โ€” `GET /api/system/version` + `POST /api/system/update` โ€”โ€” ๆฃ€ๆŸฅ npm ๆณจๅ†Œ่กจๅนถๅœจๅŽๅฐๆ›ดๆ–ฐ๏ผŒไฝฟ็”จ pm2 ้‡ๅฏ๏ผ‰ -- **feat(logs)**๏ผš่ฏฆ็ป†่ฏทๆฑ‚ๆ—ฅๅฟ—๏ผˆ#378 โ€”โ€” ๅœจ 4 ไธช้˜ถๆฎตๆ•่ŽทๅฎŒๆ•ด็š„ๆตๆฐด็บฟไฝ“๏ผšๅฎขๆˆท็ซฏ่ฏทๆฑ‚ใ€็ฟป่ฏ‘ๅŽ็š„่ฏทๆฑ‚ใ€ๆไพ›ๅ•†ๅ“ๅบ”ใ€ๅฎขๆˆท็ซฏๅ“ๅบ” โ€”โ€” ้€‰ๆ‹ฉๅŠ ๅ…ฅๅผ€ๅ…ณ๏ผŒ64KB ่ฃๅ‰ช๏ผŒ500 ๆก็›ฎ็Žฏๅฝข็ผ“ๅ†ฒๅŒบ๏ผ‰ -- **feat(mitm)**๏ผšMITM Kiro IDE ้…็ฝฎ๏ผˆ#336 โ€”โ€” `src/mitm/targets/kiro.ts` ็›ฎๆ ‡ไธบ api.anthropic.com๏ผŒๅค็”จ็Žฐๆœ‰ MITM ๅŸบ็ก€่ฎพๆ–ฝ๏ผ‰ +- **feat(combo)**: System Message Override per Combo (#399 โ€” `system_message` field replaces or injects system prompt before forwarding to provider) +- **feat(combo)**: Tool Filter Regex per Combo (#399 โ€” `tool_filter_regex` keeps only tools matching pattern; supports OpenAI + Anthropic formats) +- **feat(combo)**: Context Caching Protection (#401 โ€” `context_cache_protection` tags responses with `provider/model` and pins model for session continuity) +- **feat(settings)**: Auto-Update via Settings (#320 โ€” `GET /api/system/version` + `POST /api/system/update` โ€” checks npm registry and updates in background with pm2 restart) +- **feat(logs)**: Detailed Request Logs (#378 โ€” captures full pipeline bodies at 4 stages: client request, translated request, provider response, client response โ€” opt-in toggle, 64KB trim, 500-entry ring-buffer) +- **feat(mitm)**: MITM Kiro IDE profile (#336 โ€” `src/mitm/targets/kiro.ts` targets api.anthropic.com, reuses existing MITM infrastructure) --- ## [2.6.7] โ€” 2026-03-17 -> Sprint๏ผšSSE ๆ”น่ฟ›ใ€ๆœฌๅœฐๆไพ›ๅ•†่Š‚็‚นๆ‰ฉๅฑ•ใ€ไปฃ็†ๆณจๅ†Œ่กจใ€Claude ้€ไผ ไฟฎๅคใ€‚ +> Sprint: SSE improvements, local provider_nodes extensions, proxy registry, Claude passthrough fixes. -### โœจ ๆ–ฐ็‰นๆ€ง +### ๅŠŸ่ƒฝ็‰น็‚น -- **feat(health)**๏ผšๆœฌๅœฐ `provider_nodes` ็š„ๅŽๅฐๅฅๅบทๆฃ€ๆŸฅ๏ผŒไฝฟ็”จๆŒ‡ๆ•ฐ้€€้ฟ๏ผˆ30sโ†’300s๏ผ‰ๅ’Œ `Promise.allSettled` ไปฅ้ฟๅ…้˜ปๅกž๏ผˆ#423๏ผŒ@Regis-RCR๏ผ‰ -- **feat(embeddings)**๏ผšๅฐ† `/v1/embeddings` ่ทฏ็”ฑๅˆฐๆœฌๅœฐ `provider_nodes` โ€”โ€” `buildDynamicEmbeddingProvider()` ๅธฆไธปๆœบๅ้ชŒ่ฏ๏ผˆ#422๏ผŒ@Regis-RCR๏ผ‰ -- **feat(audio)**๏ผšๅฐ† TTS/STT ่ทฏ็”ฑๅˆฐๆœฌๅœฐ `provider_nodes` โ€”โ€” `buildDynamicAudioProvider()` ๅธฆ SSRF ไฟๆŠค๏ผˆ#416๏ผŒ@Regis-RCR๏ผ‰ -- **feat(proxy)**๏ผšไปฃ็†ๆณจๅ†Œ่กจใ€็ฎก็† API ๅ’Œ้…้ข้™ๅˆถๆณ›ๅŒ–๏ผˆ#429๏ผŒ@Regis-RCR๏ผ‰ +- **feat(health)**: Background health check for local `provider_nodes` with exponential backoff (30sโ†’300s) and `Promise.allSettled` to avoid blocking (#423, @Regis-RCR) +- **feat(embeddings)**: Route `/v1/embeddings` to local `provider_nodes` โ€” `buildDynamicEmbeddingProvider()` with hostname validation (#422, @Regis-RCR) +- **feat(audio)**: Route TTS/STT to local `provider_nodes` โ€” `buildDynamicAudioProvider()` with SSRF protection (#416, @Regis-RCR) +- **feat(proxy)**: Proxy registry, management APIs, and quota-limit generalization (#429, @Regis-RCR) -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **fix(sse)**๏ผšๅฝ“็›ฎๆ ‡ไธบ OpenAI ๅ…ผๅฎนๆ—ถๅ‰ฅ็ฆป Claude ็‰นๅฎšๅญ—ๆฎต๏ผˆ`metadata`ใ€`anthropic_version`๏ผ‰๏ผˆ#421๏ผŒ@prakersh๏ผ‰ -- **fix(sse)**๏ผšๅœจ้€ไผ ๆตๆจกๅผไธญๆๅ– Claude SSE ็”จ้‡๏ผˆ`input_tokens`ใ€`output_tokens`ใ€็ผ“ๅญ˜ token๏ผ‰๏ผˆ#420๏ผŒ@prakersh๏ผ‰ -- **fix(sse)**๏ผšไธบๅทฅๅ…ท่ฐƒ็”จ็”Ÿๆˆๅ›ž้€€ `call_id`๏ผŒ็”จไบŽ็ผบๅคฑ/็ฉบ ID๏ผˆ#419๏ผŒ@prakersh๏ผ‰ -- **fix(sse)**๏ผšClaude ๅˆฐ Claude ้€ไผ  โ€”โ€” ๅฎŒๅ…จๆœช็ปไฟฎๆ”นๅœฐ่ฝฌๅ‘่ฏทๆฑ‚ไฝ“๏ผŒไธ้‡ๆ–ฐ็ฟป่ฏ‘๏ผˆ#418๏ผŒ@prakersh๏ผ‰ -- **fix(sse)**๏ผšๅœจ Claude Code ไธŠไธ‹ๆ–‡ๅŽ‹็ผฉๅŽ่ฟ‡ๆปคๅญค็ซ‹็š„ `tool_result` ้กน๏ผŒไปฅ้ฟๅ… 400 ้”™่ฏฏ๏ผˆ#417๏ผŒ@prakersh๏ผ‰ -- **fix(sse)**๏ผšๅœจ Responses API ็ฟป่ฏ‘ๅ™จไธญ่ทณ่ฟ‡็ฉบๅ็งฐๅทฅๅ…ท่ฐƒ็”จ๏ผŒไปฅ้˜ฒๆญข `placeholder_tool` ๆ— ้™ๅพช็Žฏ๏ผˆ#415๏ผŒ@prakersh๏ผ‰ -- **fix(sse)**๏ผšๅœจ็ฟป่ฏ‘ไน‹ๅ‰ๅ‰ฅ็ฆป็ฉบๆ–‡ๆœฌๅ†…ๅฎนๅ—๏ผˆ#427๏ผŒ@prakersh๏ผ‰ -- **fix(api)**๏ผšไธบ Claude OAuth ๆต‹่ฏ•้…็ฝฎๆทปๅŠ  `refreshable: true`๏ผˆ#428๏ผŒ@prakersh๏ผ‰ +- **fix(sse)**: Strip Claude-specific fields (`metadata`, `anthropic_version`) when target is OpenAI-compat (#421, @prakersh) +- **fix(sse)**: Extract Claude SSE usage (`input_tokens`, `output_tokens`, cache tokens) in passthrough stream mode (#420, @prakersh) +- **fix(sse)**: Generate fallback `call_id` for tool calls with missing/empty IDs (#419, @prakersh) +- **fix(sse)**: Claude-to-Claude passthrough โ€” forward body completely untouched, no re-translation (#418, @prakersh) +- **fix(sse)**: Filter orphaned `tool_result` items after Claude Code context compaction to avoid 400 errors (#417, @prakersh) +- **fix(sse)**: Skip empty-name tool calls in Responses API translator to prevent `placeholder_tool` infinite loops (#415, @prakersh) +- **fix(sse)**: Strip empty text content blocks before translation (#427, @prakersh) +- **fix(api)**: Add `refreshable: true` to Claude OAuth test config (#428, @prakersh) -### ๐Ÿ“ฆ ไพ่ต– +### ๐Ÿ“ฆ Dependencies -- ๅ‡็บง `vitest`ใ€`@vitest/*` ๅ’Œ็›ธๅ…ณ devDependencies๏ผˆ#414๏ผŒ@dependabot๏ผ‰ +- Bump `vitest`, `@vitest/*` and related devDependencies (#414, @dependabot) --- ## [2.6.6] โ€” 2026-03-17 -> ็ƒญไฟฎๅค๏ผšTurbopack/Docker ๅ…ผๅฎนๆ€ง โ€”โ€” ไปŽๆ‰€ๆœ‰ `src/` ๅฏผๅ…ฅไธญ็งป้™ค `node:` ๅ่ฎฎใ€‚ +> Hotfix: Turbopack/Docker compatibility โ€” remove `node:` protocol from all `src/` imports. -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **fix(build)**๏ผšไปŽ `src/` ไธ‹ 17 ไธชๆ–‡ไปถ็š„ `import` ่ฏญๅฅไธญ็งป้™คไบ† `node:` ๅ่ฎฎๅ‰็ผ€ใ€‚`node:fs`ใ€`node:path`ใ€`node:url`ใ€`node:os` ็ญ‰ๅฏผๅ…ฅๅœจ Turbopack ๆž„ๅปบ๏ผˆNext.js 15 Docker๏ผ‰ไธญๅฏผ่‡ด `Ecmascript file had an error`๏ผŒไปฅๅŠไปŽ่พƒๆ—ง็š„ npm ๅ…จๅฑ€ๅฎ‰่ฃ…ๅ‡็บงๆ—ถใ€‚ๅ—ๅฝฑๅ“ๆ–‡ไปถ๏ผš`migrationRunner.ts`ใ€`core.ts`ใ€`backup.ts`ใ€`prompts.ts`ใ€`dataPaths.ts` ไปฅๅŠ `src/app/api/` ๅ’Œ `src/lib/` ไธญ็š„ๅ…ถไป– 12 ไธชๆ–‡ไปถใ€‚ -- **chore(workflow)**๏ผšๆ›ดๆ–ฐไบ† `generate-release.md`๏ผŒไฝฟ Docker Hub ๅŒๆญฅๅ’ŒๅŒ VPS ้ƒจ็ฝฒๆˆไธบๆฏๆฌกๅ‘ๅธƒ็š„ **ๅผบๅˆถ** ๆญฅ้ชคใ€‚ +- **fix(build)**: Removed `node:` protocol prefix from `import` statements in 17 files under `src/`. The `node:fs`, `node:path`, `node:url`, `node:os` etc. imports caused `Ecmascript file had an error` on Turbopack builds (Next.js 15 Docker) and on upgrades from older npm global installs. Affected files: `migrationRunner.ts`, `core.ts`, `backup.ts`, `prompts.ts`, `dataPaths.ts`, and 12 others in `src/app/api/` and `src/lib/`. +- **chore(workflow)**: Updated `generate-release.md` to make Docker Hub sync and dual-VPS deploy **mandatory** steps in every release. --- ## [2.6.5] โ€” 2026-03-17 -> Sprint๏ผšๆŽจ็†ๆจกๅž‹ๅ‚ๆ•ฐ่ฟ‡ๆปคใ€ๆœฌๅœฐๆไพ›ๅ•† 404 ไฟฎๅคใ€Kilo Gateway ๆไพ›ๅ•†ใ€ไพ่ต–ๅ‡็บงใ€‚ +> Sprint: reasoning model param filtering, local provider 404 fix, Kilo Gateway provider, dependency bumps. -### โœจ ๆ–ฐ็‰นๆ€ง +### โœจ New Features -- **feat(api)**๏ผšๆ–ฐๅขž **Kilo Gateway**๏ผˆ`api.kilo.ai`๏ผ‰ไฝœไธบๆ–ฐ็š„ API Key ๆไพ›ๅ•†๏ผˆๅˆซๅ `kg`๏ผ‰โ€”โ€” 335+ ๆจกๅž‹๏ผŒ6 ไธชๅ…่ดนๆจกๅž‹๏ผŒ3 ไธช่‡ชๅŠจ่ทฏ็”ฑๆจกๅž‹๏ผˆ`kilo-auto/frontier`ใ€`kilo-auto/balanced`ใ€`kilo-auto/free`๏ผ‰ใ€‚้€ไผ ๆจกๅž‹้€š่ฟ‡ `/api/gateway/models` ็ซฏ็‚นๆ”ฏๆŒใ€‚๏ผˆPR #408 by @Regis-RCR๏ผ‰ +- **feat(api)**: Added **Kilo Gateway** (`api.kilo.ai`) as a new API Key provider (alias `kg`) โ€” 335+ models, 6 free models, 3 auto-routing models (`kilo-auto/frontier`, `kilo-auto/balanced`, `kilo-auto/free`). Passthrough models supported via `/api/gateway/models` endpoint. (PR #408 by @Regis-RCR) -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **fix(sse)**๏ผšไธบๆŽจ็†ๆจกๅž‹๏ผˆo1ใ€o1-miniใ€o1-proใ€o3ใ€o3-mini๏ผ‰ๅ‰ฅ็ฆปไธๆ”ฏๆŒ็š„ๅ‚ๆ•ฐใ€‚`o1`/`o3` ็ณปๅˆ—ๆจกๅž‹ๆ‹’็ป `temperature`ใ€`top_p`ใ€`frequency_penalty`ใ€`presence_penalty`ใ€`logprobs`ใ€`top_logprobs` ๅ’Œ `n`๏ผŒ่ฟ”ๅ›ž HTTP 400ใ€‚ๅ‚ๆ•ฐ็Žฐๅœจๅœจ่ฝฌๅ‘ๅ‰ๅœจ `chatCore` ๅฑ‚่ขซๅ‰ฅ็ฆปใ€‚ไฝฟ็”จๆฏๆจกๅž‹็š„ๅฃฐๆ˜Žๅผ `unsupportedParams` ๅญ—ๆฎตๅ’Œ้ข„่ฎก็ฎ—็š„ O(1) Map ่ฟ›่กŒๆŸฅๆ‰พใ€‚๏ผˆPR #412 by @Regis-RCR๏ผ‰ -- **fix(sse)**๏ผšๆœฌๅœฐๆไพ›ๅ•† 404 ็Žฐๅœจๅฏผ่‡ด **ไป…ๆจกๅž‹้”ๅฎš๏ผˆ5 ็ง’๏ผ‰**๏ผŒ่€Œไธๆ˜ฏ่ฟžๆŽฅ็บง้”ๅฎš๏ผˆ2 ๅˆ†้’Ÿ๏ผ‰ใ€‚ๅฝ“ๆœฌๅœฐๆŽจ็†ๅŽ็ซฏ๏ผˆOllamaใ€LM Studioใ€oMLX๏ผ‰ๅฏนๆœช็Ÿฅๆจกๅž‹่ฟ”ๅ›ž 404 ๆ—ถ๏ผŒ่ฟžๆŽฅไฟๆŒๆดป่ทƒ๏ผŒๅ…ถไป–ๆจกๅž‹็ซ‹ๅณ็ปง็ปญๅทฅไฝœใ€‚ๅŒๆ—ถไฟฎๅคไบ†ไธ€ไธช้ข„ๅ…ˆๅญ˜ๅœจ็š„ bug๏ผš`model` ๆœชไผ ้€’็ป™ `markAccountUnavailable()`ใ€‚้€š่ฟ‡ไธปๆœบๅ๏ผˆ`localhost`ใ€`127.0.0.1`ใ€`::1`๏ผŒๅฏ้€š่ฟ‡ `LOCAL_HOSTNAMES` ็Žฏๅขƒๅ˜้‡ๆ‰ฉๅฑ•๏ผ‰ๆฃ€ๆต‹ๆœฌๅœฐๆไพ›ๅ•†ใ€‚๏ผˆPR #410 by @Regis-RCR๏ผ‰ +- **fix(sse)**: Strip unsupported parameters for reasoning models (o1, o1-mini, o1-pro, o3, o3-mini). Models in the `o1`/`o3` family reject `temperature`, `top_p`, `frequency_penalty`, `presence_penalty`, `logprobs`, `top_logprobs`, and `n` with HTTP 400. Parameters are now stripped at the `chatCore` layer before forwarding. Uses a declarative `unsupportedParams` field per model and a precomputed O(1) Map for lookup. (PR #412 by @Regis-RCR) +- **fix(sse)**: Local provider 404 now results in a **model-only lockout (5 seconds)** instead of a connection-level lockout (2 minutes). When a local inference backend (Ollama, LM Studio, oMLX) returns 404 for an unknown model, the connection remains active and other models continue working immediately. Also fixes a pre-existing bug where `model` was not passed to `markAccountUnavailable()`. Local providers detected via hostname (`localhost`, `127.0.0.1`, `::1`, extensible via `LOCAL_HOSTNAMES` env var). (PR #410 by @Regis-RCR) -### ๐Ÿ“ฆ ไพ่ต– +### ๐Ÿ“ฆ Dependencies - `better-sqlite3` 12.6.2 โ†’ 12.8.0 - `undici` 7.24.2 โ†’ 7.24.4 @@ -1992,392 +2016,394 @@ OmniRoute ็Žฐๅœจๆฏ **24 ๅฐๆ—ถ**่‡ชๅŠจๅˆทๆ–ฐๅทฒ่ฟžๆŽฅๆไพ›ๅ•†็š„ๆจกๅž‹ๅˆ—่กจ ## [2.6.4] โ€” 2026-03-17 -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **fix(providers)**๏ผš็งป้™คไบ† 5 ไธชๆไพ›ๅ•†ไธญไธๅญ˜ๅœจ็š„ๆจกๅž‹ๅ็งฐ๏ผš - - **gemini / gemini-cli**๏ผš็งป้™คไบ† `gemini-3.1-pro/flash` ๅ’Œ `gemini-3-*-preview`๏ผˆๅœจ Google API v1beta ไธญไธๅญ˜ๅœจ๏ผ‰๏ผ›ๆ›ฟๆขไธบ `gemini-2.5-pro`ใ€`gemini-2.5-flash`ใ€`gemini-2.0-flash`ใ€`gemini-1.5-pro/flash` - - **antigravity**๏ผš็งป้™คไบ† `gemini-3.1-pro-high/low` ๅ’Œ `gemini-3-flash`๏ผˆๆ— ๆ•ˆ็š„ๅ†…้ƒจๅˆซๅ๏ผ‰๏ผ›ๆ›ฟๆขไธบ็œŸๅฎž็š„ 2.x ๆจกๅž‹ - - **github (Copilot)**๏ผš็งป้™คไบ† `gemini-3-flash-preview` ๅ’Œ `gemini-3-pro-preview`๏ผ›ๆ›ฟๆขไธบ `gemini-2.5-flash` - - **nvidia**๏ผšไฟฎๆญฃไบ† `nvidia/llama-3.3-70b-instruct` โ†’ `meta/llama-3.3-70b-instruct`๏ผˆNVIDIA NIM ๅฏน Meta ๆจกๅž‹ไฝฟ็”จ `meta/` ๅ‘ฝๅ็ฉบ้—ด๏ผ‰๏ผ›ๆ–ฐๅขžไบ† `nvidia/llama-3.1-70b-instruct` ๅ’Œ `nvidia/llama-3.1-405b-instruct` -- **fix(db/combo)**๏ผšๆ›ดๆ–ฐไบ†่ฟœ็จ‹ๆ•ฐๆฎๅบ“ไธญ็š„ `free-stack` combo๏ผš็งป้™คไบ† `qw/qwen3-coder-plus`๏ผˆๅˆทๆ–ฐ token ่ฟ‡ๆœŸ๏ผ‰๏ผŒไฟฎๆญฃไบ† `nvidia/llama-3.3-70b-instruct` โ†’ `nvidia/meta/llama-3.3-70b-instruct`๏ผŒไฟฎๆญฃไบ† `gemini/gemini-3.1-flash` โ†’ `gemini/gemini-2.5-flash`๏ผŒๆ–ฐๅขžไบ† `if/deepseek-v3.2` +- **fix(providers)**: Removed non-existent model names across 5 providers: + - **gemini / gemini-cli**: removed `gemini-3.1-pro/flash` and `gemini-3-*-preview` (don't exist in Google API v1beta); replaced with `gemini-2.5-pro`, `gemini-2.5-flash`, `gemini-2.0-flash`, `gemini-1.5-pro/flash` + - **antigravity**: removed `gemini-3.1-pro-high/low` and `gemini-3-flash` (invalid internal aliases); replaced with real 2.x models + - **github (Copilot)**: removed `gemini-3-flash-preview` and `gemini-3-pro-preview`; replaced with `gemini-2.5-flash` + - **nvidia**: corrected `nvidia/llama-3.3-70b-instruct` โ†’ `meta/llama-3.3-70b-instruct` (NVIDIA NIM uses `meta/` namespace for Meta models); added `nvidia/llama-3.1-70b-instruct` and `nvidia/llama-3.1-405b-instruct` +- **fix(db/combo)**: Updated `free-stack` combo on remote DB: removed `qw/qwen3-coder-plus` (expired refresh token), corrected `nvidia/llama-3.3-70b-instruct` โ†’ `nvidia/meta/llama-3.3-70b-instruct`, corrected `gemini/gemini-3.1-flash` โ†’ `gemini/gemini-2.5-flash`, added `if/deepseek-v3.2` --- ## [2.6.3] โ€” 2026-03-16 -> Sprint๏ผšzod/pino hash-strip ็ƒ˜็„™ๅˆฐๆž„ๅปบๆตๆฐด็บฟไธญ๏ผŒๆ–ฐๅขž Synthetic ๆไพ›ๅ•†๏ผŒไฟฎๆญฃ VPS PM2 ่ทฏๅพ„ใ€‚ +> Sprint: zod/pino hash-strip baked into build pipeline, Synthetic provider added, VPS PM2 path corrected. -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **fix(build)**๏ผšTurbopack hash-strip ็Žฐๅœจๅœจ **็ผ–่ฏ‘ๆ—ถ** ๅฏนๆ‰€ๆœ‰ๅŒ…่ฟ่กŒ โ€”โ€” ไธไป…ไป…ๆ˜ฏ `better-sqlite3`ใ€‚`prepublish.mjs` ไธญ็š„ๆญฅ้ชค 5.6 ้ๅŽ† `app/.next/server/` ไธญ็š„ๆฏไธช `.js` ๆ–‡ไปถ๏ผŒๅนถไปŽไปปไฝ•ๅ“ˆๅธŒๅŒ–็š„ `require()` ไธญๅ‰ฅ็ฆป 16 ๅญ—็ฌฆๅๅ…ญ่ฟ›ๅˆถๅŽ็ผ€ใ€‚ไฟฎๅคไบ†ๅ…จๅฑ€ npm ๅฎ‰่ฃ…ไธญ็š„ `zod-dcb22c...`ใ€`pino-...` ็ญ‰ MODULE_NOT_FOUND ้—ฎ้ข˜ใ€‚ๅ…ณ้—ญ #398 -- **fix(deploy)**๏ผšไธคไธช VPS ไธŠ็š„ PM2 ๆŒ‡ๅ‘ไบ†่ฟ‡ๆ—ถ็š„ git-clone ็›ฎๅฝ•ใ€‚้‡ๆ–ฐ้…็ฝฎไธบ npm ๅ…จๅฑ€ๅŒ…ไธญ็š„ `app/server.js`ใ€‚ๆ›ดๆ–ฐไบ† `/deploy-vps` ๅทฅไฝœๆต๏ผŒไฝฟ็”จ `npm pack + scp`๏ผˆnpm ๆณจๅ†Œ่กจๆ‹’็ป 299MB ็š„ๅŒ…๏ผ‰ใ€‚ +- **fix(build)**: Turbopack hash-strip now runs at **compile time** for ALL packages โ€” not just `better-sqlite3`. Step 5.6 in `prepublish.mjs` walks every `.js` in `app/.next/server/` and strips the 16-char hex suffix from any hashed `require()`. Fixes `zod-dcb22c...`, `pino-...`, etc. MODULE_NOT_FOUND on global npm installs. Closes #398 +- **fix(deploy)**: PM2 on both VPS was pointing to stale git-clone directories. Reconfigured to `app/server.js` in the npm global package. Updated `/deploy-vps` workflow to use `npm pack + scp` (npm registry rejects 299MB packages). -### โœจ ๆ–ฐ็‰นๆ€ง +### ๅŠŸ่ƒฝ็‰น็‚น -- **feat(provider)**๏ผšSynthetic๏ผˆ[synthetic.new](https://synthetic.new)๏ผ‰โ€”โ€” ๆณจ้‡้š็ง็š„ OpenAI ๅ…ผๅฎนๆŽจ็†ใ€‚`passthroughModels: true`๏ผŒ็”จไบŽๅŠจๆ€ HuggingFace ๆจกๅž‹็›ฎๅฝ•ใ€‚ๅˆๅง‹ๆจกๅž‹๏ผšKimi K2.5ใ€MiniMax M2.5ใ€GLM 4.7ใ€DeepSeek V3.2ใ€‚๏ผˆPR #404 by @Regis-RCR๏ผ‰ +- **feat(provider)**: Synthetic ([synthetic.new](https://synthetic.new)) โ€” privacy-focused OpenAI-compatible inference. `passthroughModels: true` for dynamic HuggingFace model catalog. Initial models: Kimi K2.5, MiniMax M2.5, GLM 4.7, DeepSeek V3.2. (PR #404 by @Regis-RCR) -### ๐Ÿ“‹ ๅทฒๅ…ณ้—ญ็š„้—ฎ้ข˜ +### ๐Ÿ“‹ Issues Closed -- **close #398**๏ผšnpm hash ๅ›žๅฝ’ โ€”โ€” ้€š่ฟ‡็ผ–่ฏ‘ๆ—ถ hash-strip ๅœจ prepublish ไธญไฟฎๅค -- **triage #324**๏ผšๆฒกๆœ‰ๆญฅ้ชค็š„ bug ๆˆชๅ›พ โ€”โ€” ่ฏทๆฑ‚้‡็Žฐ่ฏฆๆƒ… +- **close #398**: npm hash regression โ€” fixed by compile-time hash-strip in prepublish +- **triage #324**: Bug screenshot without steps โ€” requested reproduction details --- ## [2.6.2] โ€” 2026-03-16 -> Sprint๏ผšๆจกๅ—ๅ“ˆๅธŒๅฎŒๅ…จไฟฎๅค๏ผŒๅˆๅนถ 2 ไธช PR๏ผˆAnthropic ๅทฅๅ…ท่ฟ‡ๆปค + ่‡ชๅฎšไน‰็ซฏ็‚น่ทฏๅพ„๏ผ‰๏ผŒๆ–ฐๅขž Alibaba Cloud DashScope ๆไพ›ๅ•†๏ผŒๅ…ณ้—ญ 3 ไธช้™ˆๆ—ง้—ฎ้ข˜ใ€‚ +> Sprint: module hashing fully fixed, 2 PRs merged (Anthropic tools filter + custom endpoint paths), Alibaba Cloud DashScope provider added, 3 stale issues closed. -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **fix(build)**๏ผšๆ‰ฉๅฑ• webpack `externals` hash-strip ไปฅ่ฆ†็›–ๆ‰€ๆœ‰ `serverExternalPackages`๏ผŒ่€Œไธไป…ไป…ๆ˜ฏ `better-sqlite3`ใ€‚Next.js 16 Turbopack ๅฐ† `zod`ใ€`pino` ๅ’Œๅ…ถไป–ๆœๅŠกๅ™จๅค–้ƒจๅŒ…ๅ“ˆๅธŒๅŒ–ไธบ็ฑปไผผ `zod-dcb22c6336e0bc69` ็š„ๅ็งฐ๏ผŒ่ฟ™ไบ›ๅ็งฐๅœจ่ฟ่กŒๆ—ถไธๅญ˜ๅœจไบŽ `node_modules` ไธญใ€‚HASH_PATTERN ๆญฃๅˆ™ๆ•่Žทๆ‰€ๆœ‰ๆƒ…ๅ†ต็Žฐๅœจๅ‰ฅ็ฆป 16 ๅญ—็ฌฆๅŽ็ผ€ๅนถๅ›ž้€€ๅˆฐๅŸบ็ก€ๅŒ…ๅใ€‚่ฟ˜ๅœจ `prepublish.mjs` ไธญๆทปๅŠ ไบ† `NEXT_PRIVATE_BUILD_WORKER=0` ไปฅๅŠ ๅผบ webpack ๆจกๅผ๏ผŒไปฅๅŠๆž„ๅปบๅŽๆ‰ซๆๆŠฅๅ‘Šไปปไฝ•ๅ‰ฉไฝ™็š„ๅ“ˆๅธŒๅผ•็”จใ€‚๏ผˆ#396ใ€#398ใ€PR #403๏ผ‰ -- **fix(chat)**๏ผšAnthropic ๆ ผๅผ็š„ๅทฅๅ…ทๅ็งฐ๏ผˆไธๅธฆ `.function` ๅŒ…่ฃ…็š„ `tool.name`๏ผ‰่ขซ #346 ๅผ•ๅ…ฅ็š„็ฉบๅ็งฐ่ฟ‡ๆปคๅ™จ้™้ป˜ไธขๅผƒใ€‚LiteLLM ไปฃ็†่ฏทๆฑ‚ๅœจ Anthropic Messages API ๆ ผๅผไธญไฝฟ็”จ `anthropic/` ๅ‰็ผ€๏ผŒๅฏผ่‡ดๆ‰€ๆœ‰ๅทฅๅ…ท่ขซ่ฟ‡ๆปค๏ผŒAnthropic ่ฟ”ๅ›ž `400: tool_choice.any may only be specified while providing tools`ใ€‚้€š่ฟ‡ๅœจ `tool.function.name` ็ผบๅคฑๆ—ถๅ›ž้€€ๅˆฐ `tool.name` ไฟฎๅคใ€‚ๆทปๅŠ ไบ† 8 ไธชๅ›žๅฝ’ๅ•ๅ…ƒๆต‹่ฏ•ใ€‚๏ผˆPR #397๏ผ‰ +- **fix(build)**: Extended webpack `externals` hash-strip to cover ALL `serverExternalPackages`, not just `better-sqlite3`. Next.js 16 Turbopack hashes `zod`, `pino`, and every other server-external package into names like `zod-dcb22c6336e0bc69` that don't exist in `node_modules` at runtime. A HASH_PATTERN regex catch-all now strips the 16-char suffix and falls back to the base package name. Also added `NEXT_PRIVATE_BUILD_WORKER=0` in `prepublish.mjs` to reinforce webpack mode, plus a post-build scan that reports any remaining hashed refs. (#396, #398, PR #403) +- **fix(chat)**: Anthropic-format tool names (`tool.name` without `.function` wrapper) were silently dropped by the empty-name filter introduced in #346. LiteLLM proxies requests with `anthropic/` prefix in Anthropic Messages API format, causing all tools to be filtered and Anthropic to return `400: tool_choice.any may only be specified while providing tools`. Fixed by falling back to `tool.name` when `tool.function.name` is absent. Added 8 regression unit tests. (PR #397) -### โœจ ๆ–ฐ็‰นๆ€ง +### ๅŠŸ่ƒฝ็‰น็‚น -- **feat(api)**๏ผšOpenAI ๅ…ผๅฎนๆไพ›ๅ•†่Š‚็‚น็š„่‡ชๅฎšไน‰็ซฏ็‚น่ทฏๅพ„ โ€”โ€” ๅœจๆไพ›ๅ•†่ฟžๆŽฅ UI ไธญไธบๆฏไธช่Š‚็‚น้…็ฝฎ `chatPath` ๅ’Œ `modelsPath`๏ผˆไพ‹ๅฆ‚ `/v4/chat/completions`๏ผ‰ใ€‚ๅŒ…ๆ‹ฌๆ•ฐๆฎๅบ“่ฟ็งป๏ผˆ`003_provider_node_custom_paths.sql`๏ผ‰ๅ’Œ URL ่ทฏๅพ„ๆธ…็†๏ผˆๆ—  `..` ้ๅŽ†๏ผŒๅฟ…้กปไปฅ `/` ๅผ€ๅคด๏ผ‰ใ€‚๏ผˆPR #400๏ผ‰ -- **feat(provider)**๏ผšๆ–ฐๅขž Alibaba Cloud DashScope ไฝœไธบ OpenAI ๅ…ผๅฎนๆไพ›ๅ•†ใ€‚ๅ›ฝ้™…็ซฏ็‚น๏ผš`dashscope-intl.aliyuncs.com/compatible-mode/v1`ใ€‚12 ไธชๆจกๅž‹๏ผš`qwen-max`ใ€`qwen-plus`ใ€`qwen-turbo`ใ€`qwen3-coder-plus/flash`ใ€`qwq-plus`ใ€`qwq-32b`ใ€`qwen3-32b`ใ€`qwen3-235b-a22b`ใ€‚่ฎค่ฏ๏ผšBearer API keyใ€‚ +- **feat(api)**: Custom endpoint paths for OpenAI-compatible provider nodes โ€” configure `chatPath` and `modelsPath` per node (e.g. `/v4/chat/completions`) in the provider connection UI. Includes a DB migration (`003_provider_node_custom_paths.sql`) and URL path sanitization (no `..` traversal, must start with `/`). (PR #400) +- **feat(provider)**: Alibaba Cloud DashScope added as OpenAI-compatible provider. International endpoint: `dashscope-intl.aliyuncs.com/compatible-mode/v1`. 12 models: `qwen-max`, `qwen-plus`, `qwen-turbo`, `qwen3-coder-plus/flash`, `qwq-plus`, `qwq-32b`, `qwen3-32b`, `qwen3-235b-a22b`. Auth: Bearer API key. -### ๐Ÿ“‹ ๅทฒๅ…ณ้—ญ็š„้—ฎ้ข˜ +### ๐Ÿ“‹ Issues Closed -- **close #323**๏ผšCline ่ฟžๆŽฅ้”™่ฏฏ `[object Object]` โ€”โ€” ๅทฒๅœจ v2.3.7 ไฟฎๅค๏ผ›ๆŒ‡ๅฏผ็”จๆˆทไปŽ v2.2.9 ๅ‡็บง -- **close #337**๏ผšKiro ็งฏๅˆ†่ฟฝ่ธช โ€”โ€” ๅทฒๅœจ v2.5.5๏ผˆ#381๏ผ‰ๅฎž็Žฐ๏ผ›ๅผ•ๅฏผ็”จๆˆทๆŸฅ็œ‹ Dashboard โ†’ Usage -- **triage #402**๏ผšARM64 macOS DMG ๆŸๅ โ€”โ€” ่ฏทๆฑ‚ macOS ็‰ˆๆœฌใ€ๅ…ทไฝ“้”™่ฏฏ๏ผŒๅนถๅปบ่ฎฎ `xattr -d com.apple.quarantine` ่งฃๅ†ณๆ–นๆกˆ +- **close #323**: Cline connection error `[object Object]` โ€” fixed in v2.3.7; instructed user to upgrade from v2.2.9 +- **close #337**: Kiro credit tracking โ€” implemented in v2.5.5 (#381); pointed user to Dashboard โ†’ Usage +- **triage #402**: ARM64 macOS DMG damaged โ€” requested macOS version, exact error, and advised `xattr -d com.apple.quarantine` workaround --- ## [2.6.1] โ€” 2026-03-15 -> ๅ…ณ้”ฎๅฏๅŠจไฟฎๅค๏ผšv2.6.0 ๅ…จๅฑ€ npm ๅฎ‰่ฃ…ๅดฉๆบƒ๏ผŒๅ‡บ็Žฐ 500 ้”™่ฏฏ๏ผŒๅŽŸๅ› ๆ˜ฏ Next.js 16 instrumentation hook ไธญ็š„ Turbopack/webpack ๆจกๅ—ๅๅ“ˆๅธŒ bugใ€‚ +> Critical startup fix: v2.6.0 global npm installs crashed with a 500 error due to a Turbopack/webpack module-name hashing bug in the Next.js 16 instrumentation hook. -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **fix(build)**๏ผšๅผบๅˆถ `better-sqlite3` ๅœจ webpack ๆœๅŠกๅ™จๅŒ…ไธญๅง‹็ปˆไปฅๅ…ถ็ฒพ็กฎ็š„ๅŒ…ๅ่ขซ requireใ€‚Next.js 16 ๅฐ† instrumentation hook ็ผ–่ฏ‘ๅˆฐๅ•็‹ฌ็š„ chunk ไธญ๏ผŒๅนถๅ‘ๅ‡บ `require('better-sqlite3-')` โ€”โ€” ไธ€ไธชไธๅญ˜ๅœจ็š„ๅ“ˆๅธŒๆจกๅ—ๅๅœจ `node_modules` ไธญ โ€”โ€” ๅณไฝฟ่ฏฅๅŒ…ๅˆ—ๅœจ `serverExternalPackages` ไธญใ€‚ไธบๆœๅŠกๅ™จ webpack ้…็ฝฎๆทปๅŠ ไบ†ๆ˜พๅผ็š„ `externals` ๅ‡ฝๆ•ฐ๏ผŒไฝฟๆ‰“ๅŒ…ๅ™จๅง‹็ปˆๅ‘ๅ‡บ `require('better-sqlite3')`๏ผŒ่งฃๅ†ณไบ†ๅนฒๅ‡€ๅ…จๅฑ€ๅฎ‰่ฃ…ไธญ็š„ๅฏๅŠจ `500 Internal Server Error`ใ€‚๏ผˆ#394๏ผŒPR #395๏ผ‰ +- **fix(build)**: Force `better-sqlite3` to always be required by its exact package name in the webpack server bundle. Next.js 16 compiled the instrumentation hook into a separate chunk and emitted `require('better-sqlite3-')` โ€” a hashed module name that doesn't exist in `node_modules` โ€” even though the package was listed in `serverExternalPackages`. Added an explicit `externals` function to the server webpack config so the bundler always emits `require('better-sqlite3')`, resolving the startup `500 Internal Server Error` on clean global installs. (#394, PR #395) ### ๐Ÿ”ง CI -- **ci**๏ผšไธบ `npm-publish.yml` ๆทปๅŠ ไบ† `workflow_dispatch`๏ผŒๅธฆ็‰ˆๆœฌๅŒๆญฅไฟๆŠค๏ผŒ็”จไบŽๆ‰‹ๅŠจ่งฆๅ‘๏ผˆ#392๏ผ‰ -- **ci**๏ผšไธบ `docker-publish.yml` ๆทปๅŠ ไบ† `workflow_dispatch`๏ผŒๅฐ† GitHub Actions ๆ›ดๆ–ฐๅˆฐๆœ€ๆ–ฐ็‰ˆๆœฌ๏ผˆ#392๏ผ‰ +- **ci**: Added `workflow_dispatch` to `npm-publish.yml` with version sync safeguard for manual triggers (#392) +- **ci**: Added `workflow_dispatch` to `docker-publish.yml`, updated GitHub Actions to latest versions (#392) --- ## [2.6.0] - 2026-03-15 -> ้—ฎ้ข˜่งฃๅ†ณๅ†ฒๅˆบ๏ผš4 ไธช bug ไฟฎๅคใ€ๆ—ฅๅฟ— UX ๆ”น่ฟ›ใ€ๆ–ฐๅขž Kiro ็งฏๅˆ†่ฟฝ่ธชใ€‚ +> Issue resolution sprint: 4 bugs fixed, logs UX improved, Kiro credit tracking added. -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **fix(media)**๏ผšๆœช้…็ฝฎๆ—ถ ComfyUI ๅ’Œ SD WebUI ไธๅ†ๅ‡บ็Žฐๅœจๅช’ไฝ“้กต้ข็š„ๆไพ›ๅ•†ๅˆ—่กจไธญ โ€”โ€” ๆŒ‚่ฝฝๆ—ถ่Žทๅ– `/api/providers` ๅนถ้š่—ๆฒกๆœ‰่ฟžๆŽฅ็š„ๆœฌๅœฐๆไพ›ๅ•†๏ผˆ#390๏ผ‰ -- **fix(auth)**๏ผšRound-robin ไธๅ†ๅœจๅ†ทๅดๅŽ็ซ‹ๅณ้‡ๆ–ฐ้€‰ๆ‹ฉๅ—้™่ดฆๆˆท โ€”โ€” `backoffLevel` ็Žฐๅœจ็”จไฝœ LRU ่ฝฎๆขไธญ็š„ไธป่ฆๆŽ’ๅบ้”ฎ๏ผˆ#340๏ผ‰ -- **fix(oauth)**๏ผšQoder๏ผˆๅ’Œๅ…ถไป–้‡ๅฎšๅ‘ๅˆฐ่‡ชๅทฑ UI ็š„ๆไพ›ๅ•†๏ผ‰ไธๅ†่ฎฉ OAuth ๆจกๆ€ๆก†ๅกๅœจ "Waiting for Authorization" โ€”โ€” ๅผน็ช—ๅ…ณ้—ญๆฃ€ๆต‹ๅ™จ่‡ชๅŠจๅˆ‡ๆขๅˆฐๆ‰‹ๅŠจ URL ่พ“ๅ…ฅๆจกๅผ๏ผˆ#344๏ผ‰ -- **fix(logs)**๏ผš่ฏทๆฑ‚ๆ—ฅๅฟ—่กจ็Žฐๅœจๅœจๆต…่‰ฒๆจกๅผไธ‹ๅฏ่ฏป โ€”โ€” ็Šถๆ€ๅพฝ็ซ ใ€token ่ฎกๆ•ฐๅ’Œ combo ๆ ‡็ญพไฝฟ็”จ่‡ช้€‚ๅบ” `dark:` ้ขœ่‰ฒ็ฑป๏ผˆ#378๏ผ‰ +- **fix(media)**: ComfyUI and SD WebUI no longer appear in the Media page provider list when unconfigured โ€” fetches `/api/providers` on mount and hides local providers with no connections (#390) +- **fix(auth)**: Round-robin no longer re-selects rate-limited accounts immediately after cooldown โ€” `backoffLevel` is now used as primary sort key in the LRU rotation (#340) +- **fix(oauth)**: Qoder (and other providers that redirect to their own UI) no longer leave the OAuth modal stuck at "Waiting for Authorization" โ€” popup-closed detector auto-transitions to manual URL input mode (#344) +- **fix(logs)**: Request log table is now readable in light mode โ€” status badges, token counts, and combo tags use adaptive `dark:` color classes (#378) -### โœจ ๆ–ฐ็‰นๆ€ง +### ๅŠŸ่ƒฝ็‰น็‚น -- **feat(kiro)**๏ผš็”จ้‡ๆŠ“ๅ–ๅ™จไธญๆ–ฐๅขž Kiro ็งฏๅˆ†่ฟฝ่ธช โ€”โ€” ไปŽ AWS CodeWhisperer ็ซฏ็‚นๆŸฅ่ฏข `getUserCredits`๏ผˆ#337๏ผ‰ +- **feat(kiro)**: Kiro credit tracking added to usage fetcher โ€” queries `getUserCredits` from AWS CodeWhisperer endpoint (#337) -### ๐Ÿ›  ๆ‚้กน +### ๐Ÿ›  Chores + +- **chore(tests)**: Aligned `test:plan3`, `test:fixes`, `test:security` to use same `tsx/esm` loader as `npm test` โ€” eliminates module resolution false negatives in targeted runs (PR #386) --- ## [2.5.9] - 2026-03-15 -> Codex ๅŽŸ็”Ÿ้€ไผ ไฟฎๅค + ่ทฏ็”ฑไฝ“้ชŒ่ฏๅผบๅŒ–ใ€‚ +> Codex native passthrough fix + route body validation hardening. -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **fix(codex)**๏ผšไธบ Codex ๅฎขๆˆท็ซฏไฟ็•™ๅŽŸ็”Ÿ Responses API ้€ไผ  โ€”โ€” ้ฟๅ…ไธๅฟ…่ฆ็š„็ฟป่ฏ‘ๅ˜ๆ›ด๏ผˆPR #387๏ผ‰ -- **fix(api)**๏ผš้ชŒ่ฏ pricing/sync ๅ’Œ task-routing ่ทฏ็”ฑไธญ็š„่ฏทๆฑ‚ไฝ“ โ€”โ€” ้˜ฒๆญข็•ธๅฝข่พ“ๅ…ฅๅฏผ่‡ดๅดฉๆบƒ๏ผˆPR #388๏ผ‰ -- **fix(auth)**๏ผšJWT ๅฏ†้’ฅๅœจ้‡ๅฏ้—ดๆŒไน…ๅŒ–๏ผŒ้€š่ฟ‡ `src/lib/db/secrets.ts` โ€”โ€” ๆถˆ้™ค pm2 ้‡ๅฏๅŽ็š„ 401 ้”™่ฏฏ๏ผˆPR #388๏ผ‰ +- **fix(codex)**: Preserve native Responses API passthrough for Codex clients โ€” avoids unnecessary translation mutations (PR #387) +- **fix(api)**: Validate request bodies on pricing/sync and task-routing routes โ€” prevents crashes from malformed inputs (PR #388) +- **fix(auth)**: JWT secrets persist across restarts via `src/lib/db/secrets.ts` โ€” eliminates 401 errors after pm2 restart (PR #388) --- ## [2.5.8] - 2026-03-15 -> ๆž„ๅปบไฟฎๅค๏ผšๆขๅคๅ›  v2.5.7 ไธๅฎŒๆ•ดๅ‘ๅธƒ่€Œไธญๆ–ญ็š„ VPS ่ฟžๆŽฅใ€‚ +> Build fix: restore VPS connectivity broken by v2.5.7 incomplete publish. -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **fix(build)**๏ผš`scripts/prepublish.mjs` ไปไฝฟ็”จๅทฒๅผƒ็”จ็š„ `--webpack` ๆ ‡ๅฟ—๏ผŒๅฏผ่‡ด Next.js ็‹ฌ็ซ‹ๆž„ๅปบ้™้ป˜ๅคฑ่ดฅ โ€”โ€” npm ๅ‘ๅธƒๆ—ถ็ผบๅฐ‘ `app/server.js`๏ผŒ็ ดๅไบ† VPS ้ƒจ็ฝฒ +- **fix(build)**: `scripts/prepublish.mjs` still used deprecated `--webpack` flag causing Next.js standalone build to fail silently โ€” npm publish completed without `app/server.js`, breaking VPS deployment --- ## [2.5.7] - 2026-03-15 -> ๅช’ไฝ“ๆธธไนๅœบ้”™่ฏฏๅค„็†ไฟฎๅคใ€‚ +> Media playground error handling fixes. -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **fix(media)**๏ผšๅฝ“้Ÿณ้ข‘ไธๅŒ…ๅซ่ฏญ้Ÿณ๏ผˆ้Ÿณไนใ€้™้Ÿณ๏ผ‰ๆ—ถ๏ผŒ่ฝฌๅฝ•ๆ˜พ็คบ "API Key Required" ่ฏฏๆŠฅ โ€”โ€” ็Žฐๅœจๆ˜พ็คบ "No speech detected" -- **fix(media)**๏ผš`audioTranscription.ts` ๅ’Œ `audioSpeech.ts` ไธญ็š„ `upstreamErrorResponse` ็Žฐๅœจ่ฟ”ๅ›žๆญฃ็กฎ็š„ JSON๏ผˆ`{error:{message}}`๏ผ‰๏ผŒไฝฟ MediaPageClient ่ƒฝๅคŸๆญฃ็กฎๆฃ€ๆต‹ 401/403 ๅ‡ญ่ฏ้”™่ฏฏ -- **fix(media)**๏ผš`parseApiError` ็Žฐๅœจๅค„็† Deepgram ็š„ `err_msg` ๅญ—ๆฎต๏ผŒๅนถๅœจ้”™่ฏฏๆถˆๆฏไธญๆฃ€ๆต‹ `"api key"`๏ผŒ็”จไบŽๅ‡†็กฎ็š„ๅ‡ญ่ฏ้”™่ฏฏๅˆ†็ฑป +- **fix(media)**: Transcription "API Key Required" false positive when audio contains no speech (music, silence) โ€” now shows "No speech detected" instead +- **fix(media)**: `upstreamErrorResponse` in `audioTranscription.ts` and `audioSpeech.ts` now returns proper JSON (`{error:{message}}`), enabling correct 401/403 credential error detection in the MediaPageClient +- **fix(media)**: `parseApiError` now handles Deepgram's `err_msg` field and detects `"api key"` in error messages for accurate credential error classification --- ## [2.5.6] - 2026-03-15 -> ๅ…ณ้”ฎๅฎ‰ๅ…จ/่ฎค่ฏไฟฎๅค๏ผšAntigravity OAuth ๆŸๅ + ้‡ๅฏๅŽ JWT ไผš่ฏไธขๅคฑใ€‚ +> Critical security/auth fixes: Antigravity OAuth broken + JWT sessions lost after restart. -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **fix(oauth) #384**๏ผšAntigravity Google OAuth ็Žฐๅœจๆญฃ็กฎๅ‘ token ็ซฏ็‚นๅ‘้€ `client_secret`ใ€‚`ANTIGRAVITY_OAUTH_CLIENT_SECRET` ็š„ๅ›ž้€€ๆ˜ฏ็ฉบๅญ—็ฌฆไธฒ๏ผŒไธบๅ‡ๅ€ผ โ€”โ€” ๅ› ๆญค `client_secret` ไปŽๆœชๅŒ…ๅซๅœจ่ฏทๆฑ‚ไธญ๏ผŒๅฏผ่‡ดๆ‰€ๆœ‰ๆฒกๆœ‰่‡ชๅฎšไน‰็Žฏๅขƒๅ˜้‡็š„็”จๆˆทๅ‡บ็Žฐ `"client_secret is missing"` ้”™่ฏฏใ€‚ๅ…ณ้—ญ #383ใ€‚ -- **fix(auth) #385**๏ผš`JWT_SECRET` ็Žฐๅœจๅœจ้ฆ–ๆฌก็”Ÿๆˆๆ—ถๆŒไน…ๅŒ–ๅˆฐ SQLite๏ผˆ`namespace='secrets'`๏ผ‰๏ผŒๅนถๅœจๅŽ็ปญๅฏๅŠจๆ—ถ้‡ๆ–ฐๅŠ ่ฝฝใ€‚ๆญคๅ‰๏ผŒๆฏๆฌก่ฟ›็จ‹ๅฏๅŠจๆ—ถ้ƒฝไผš็”Ÿๆˆๆ–ฐ็š„้šๆœบๅฏ†้’ฅ๏ผŒๅฏผ่‡ดไปปไฝ•้‡ๅฏๆˆ–ๅ‡็บงๅŽๆ‰€ๆœ‰็Žฐๆœ‰ cookie/ไผš่ฏๅคฑๆ•ˆใ€‚ๅฝฑๅ“ `JWT_SECRET` ๅ’Œ `API_KEY_SECRET`ใ€‚ๅ…ณ้—ญ #382ใ€‚ +- **fix(oauth) #384**: Antigravity Google OAuth now correctly sends `client_secret` to the token endpoint. The fallback for `ANTIGRAVITY_OAUTH_CLIENT_SECRET` was an empty string, which is falsy โ€” so `client_secret` was never included in the request, causing `"client_secret is missing"` errors for all users without a custom env var. Closes #383. +- **fix(auth) #385**: `JWT_SECRET` is now persisted to SQLite (`namespace='secrets'`) on first generation and reloaded on subsequent starts. Previously, a new random secret was generated each process startup, invalidating all existing cookies/sessions after any restart or upgrade. Affects both `JWT_SECRET` and `API_KEY_SECRET`. Closes #382. --- ## [2.5.5] - 2026-03-15 -> ๆจกๅž‹ๅˆ—่กจๅŽป้‡ไฟฎๅคใ€Electron ็‹ฌ็ซ‹ๆž„ๅปบๅผบๅŒ–ๅ’Œ Kiro ็งฏๅˆ†่ฟฝ่ธชใ€‚ +> Model list dedup fix, Electron standalone build hardening, and Kiro credit tracking. -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **fix(models) #380**๏ผš`GET /api/models` ็Žฐๅœจๅœจๆž„ๅปบๆดป่ทƒๆไพ›ๅ•†่ฟ‡ๆปคๅ™จๆ—ถๅŒ…ๅซๆไพ›ๅ•†ๅˆซๅ โ€”โ€” `claude`๏ผˆๅˆซๅ `cc`๏ผ‰ๅ’Œ `github`๏ผˆๅˆซๅ `gh`๏ผ‰็š„ๆจกๅž‹ๅง‹็ปˆๆ˜พ็คบ๏ผŒๆ— ่ฎบๆ˜ฏๅฆ้…็ฝฎไบ†่ฟžๆŽฅ๏ผŒๅ› ไธบ `PROVIDER_MODELS` ้”ฎๆ˜ฏๅˆซๅ๏ผŒไฝ†ๆ•ฐๆฎๅบ“่ฟžๆŽฅๅญ˜ๅ‚จๅœจๆไพ›ๅ•† ID ไธ‹ใ€‚้€š่ฟ‡ๆ‰ฉๅฑ•ๆฏไธชๆดป่ทƒๆไพ›ๅ•† ID ไปฅ้€š่ฟ‡ `PROVIDER_ID_TO_ALIAS` ๅŒ…ๅซๅ…ถๅˆซๅๆฅไฟฎๅคใ€‚ๅ…ณ้—ญ #353ใ€‚ -- **fix(electron) #379**๏ผšๆ–ฐๅขž `scripts/prepare-electron-standalone.mjs`๏ผŒๅœจ Electron ๆ‰“ๅŒ…ๅ‰ๅ‡†ๅค‡ไธ“็”จ็š„ `/.next/electron-standalone` ๅŒ…ใ€‚ๅฆ‚ๆžœ `node_modules` ๆ˜ฏ็ฌฆๅท้“พๆŽฅๅˆ™ไธญๆญขๅนถๆ˜พ็คบๆธ…ๆ™ฐ้”™่ฏฏ๏ผˆelectron-builder ไผšๅฐ†ๆž„ๅปบๆœบๅ™จไธŠ็š„่ฟ่กŒๆ—ถไพ่ต–ๆ‰“ๅŒ…๏ผ‰ใ€‚้€š่ฟ‡ `path.basename` ่ฟ›่กŒ่ทจๅนณๅฐ่ทฏๅพ„ๆธ…็†ใ€‚By @kfiramarใ€‚ +- **fix(models) #380**: `GET /api/models` now includes provider aliases when building the active-provider filter โ€” models for `claude` (alias `cc`) and `github` (alias `gh`) were always shown regardless of whether a connection was configured, because `PROVIDER_MODELS` keys are aliases but DB connections are stored under provider IDs. Fixed by expanding each active provider ID to also include its alias via `PROVIDER_ID_TO_ALIAS`. Closes #353. +- **fix(electron) #379**: New `scripts/prepare-electron-standalone.mjs` stages a dedicated `/.next/electron-standalone` bundle before Electron packaging. Aborts with a clear error if `node_modules` is a symlink (electron-builder would ship a runtime dependency on the build machine). Cross-platform path sanitization via `path.basename`. By @kfiramar. -### โœจ ๆ–ฐ็‰นๆ€ง +### โœจ New Features -- **feat(kiro) #381**๏ผšKiro ็งฏๅˆ†ไฝ™้ข่ฟฝ่ธช โ€”โ€” ้€š่ฟ‡่ฐƒ็”จ `codewhisperer.us-east-1.amazonaws.com/getUserCredits`๏ผˆไธŽ Kiro IDE ๅ†…้ƒจไฝฟ็”จ็š„็ซฏ็‚น็›ธๅŒ๏ผ‰๏ผŒ็”จ้‡็ซฏ็‚น็Žฐๅœจไธบ Kiro ่ดฆๆˆท่ฟ”ๅ›ž็งฏๅˆ†ๆ•ฐๆฎใ€‚่ฟ”ๅ›žๅ‰ฉไฝ™็งฏๅˆ†ใ€ๆ€ป้ขๅบฆใ€็ปญ่ฎขๆ—ฅๆœŸๅ’Œ่ฎข้˜…ๅฑ‚็บงใ€‚ๅ…ณ้—ญ #337ใ€‚ +- **feat(kiro) #381**: Kiro credit balance tracking โ€” usage endpoint now returns credit data for Kiro accounts by calling `codewhisperer.us-east-1.amazonaws.com/getUserCredits` (same endpoint Kiro IDE uses internally). Returns remaining credits, total allowance, renewal date, and subscription tier. Closes #337. ## [2.5.4] - 2026-03-15 -> ๆ—ฅๅฟ—ๅ™จๅฏๅŠจไฟฎๅคใ€็™ปๅฝ•ๅผ•ๅฏผๅฎ‰ๅ…จไฟฎๅคๅ’Œๅผ€ๅ‘ HMR ๅฏ้ ๆ€งๆ”น่ฟ›ใ€‚CI ๅŸบ็ก€่ฎพๆ–ฝๅผบๅŒ–ใ€‚ +> Logger startup fix, login bootstrap security fix, and dev HMR reliability improvement. CI infrastructure hardened. -### ๐Ÿ› Bug ไฟฎๅค๏ผˆPRs #374, #375, #376 by @kfiramar๏ผ‰ +### ๐Ÿ› Bug Fixes (PRs #374, #375, #376 by @kfiramar) -- **fix(logger) #376**๏ผšๆขๅค pino ไผ ่พ“ๆ—ฅๅฟ—ๅ™จ่ทฏๅพ„ โ€”โ€” pino ๆ‹’็ป `formatters.level` ไธŽ `transport.targets` ็ป„ๅˆไฝฟ็”จใ€‚ไผ ่พ“ๆ”ฏๆŒ็š„้…็ฝฎ็Žฐๅœจ้€š่ฟ‡ `getTransportCompatibleConfig()` ๅ‰ฅ็ฆป็บงๅˆซๆ ผๅผๅŒ–ๅ™จใ€‚ๅŒๆ—ถไฟฎๆญฃไบ† `/api/logs/console` ไธญ็š„ๆ•ฐๅญ—็บงๅˆซๆ˜ ๅฐ„๏ผš`30โ†’info, 40โ†’warn, 50โ†’error`๏ผˆๆญคๅ‰ๅ็งปไบ†ไธ€ไฝ๏ผ‰ใ€‚ -- **fix(login) #375**๏ผš็™ปๅฝ•้กต้ข็ŽฐๅœจไปŽๅ…ฌๅ…ฑ `/api/settings/require-login` ็ซฏ็‚นๅผ•ๅฏผ๏ผŒ่€Œไธๆ˜ฏๅ—ไฟๆŠค็š„ `/api/settings`ใ€‚ๅœจๅฏ†็ ไฟๆŠค่ฎพ็ฝฎไธญ๏ผŒ้ข„่ฎค่ฏ้กต้ขๆ”ถๅˆฐ 401 ๅนถไธๅฟ…่ฆๅœฐๅ›ž้€€ๅˆฐๅฎ‰ๅ…จ้ป˜่ฎคๅ€ผใ€‚ๅ…ฌๅ…ฑ่ทฏ็”ฑ็Žฐๅœจ่ฟ”ๅ›žๆ‰€ๆœ‰ๅผ•ๅฏผๅ…ƒๆ•ฐๆฎ๏ผˆ`requireLogin`ใ€`hasPassword`ใ€`setupComplete`๏ผ‰๏ผŒ้”™่ฏฏๆ—ถไฝฟ็”จไฟๅฎˆ็š„ 200 ๅ›ž้€€ใ€‚ -- **fix(dev) #374**๏ผšๅœจ `next.config.mjs` ไธญๅฐ† `localhost` ๅ’Œ `127.0.0.1` ๆทปๅŠ ๅˆฐ `allowedDevOrigins` โ€”โ€” ้€š่ฟ‡ๅ›ž็Žฏๅœฐๅ€่ฎฟ้—ฎๅบ”็”จๆ—ถ HMR websocket ่ขซ้˜ปๅกž๏ผŒไบง็”Ÿ้‡ๅค็š„่ทจๅŸŸ่ญฆๅ‘Šใ€‚ +- **fix(logger) #376**: Restore pino transport logger path โ€” `formatters.level` combined with `transport.targets` is rejected by pino. Transport-backed configs now strip the level formatter via `getTransportCompatibleConfig()`. Also corrects numeric level mapping in `/api/logs/console`: `30โ†’info, 40โ†’warn, 50โ†’error` (was shifted by one). +- **fix(login) #375**: Login page now bootstraps from the public `/api/settings/require-login` endpoint instead of the protected `/api/settings`. In password-protected setups, the pre-auth page was receiving a 401 and falling back to safe defaults unnecessarily. The public route now returns all bootstrap metadata (`requireLogin`, `hasPassword`, `setupComplete`) with a conservative 200 fallback on error. +- **fix(dev) #374**: Add `localhost` and `127.0.0.1` to `allowedDevOrigins` in `next.config.mjs` โ€” HMR websocket was blocked when accessing the app via loopback address, producing repeated cross-origin warnings. -### ๐Ÿ”ง CI ไธŽๅŸบ็ก€่ฎพๆ–ฝ +### ๐Ÿ”ง CI & Infrastructure -- **ESLint OOM ไฟฎๅค**๏ผš`eslint.config.mjs` ็Žฐๅœจๅฟฝ็•ฅ `vscode-extension/**`ใ€`electron/**`ใ€`docs/**`ใ€`app/.next/**` ๅ’Œ `clipr/**` โ€”โ€” ESLint ๅ› ๆ‰ซๆ VS Code ไบŒ่ฟ›ๅˆถ blob ๅ’Œ็ผ–่ฏ‘ๅ—ๅฏผ่‡ด JS ๅ † OOM ๅดฉๆบƒใ€‚ -- **ๅ•ๅ…ƒๆต‹่ฏ•ไฟฎๅค**๏ผšไปŽ 2 ไธชๆต‹่ฏ•ๆ–‡ไปถไธญ็งป้™คไบ†่ฟ‡ๆ—ถ็š„ `ALTER TABLE provider_connections ADD COLUMN "group"` โ€”โ€” ่ฏฅๅˆ—็Žฐๅœจๆ˜ฏๅŸบ็ก€ schema ็š„ไธ€้ƒจๅˆ†๏ผˆๅœจ #373 ไธญๆทปๅŠ ๏ผ‰๏ผŒๅฏผ่‡ดๆฏๆฌก CI ่ฟ่กŒๅ‡บ็Žฐ `SQLITE_ERROR: duplicate column name`ใ€‚ -- **Pre-commit ้’ฉๅญ**๏ผšๅœจ `.husky/pre-commit` ไธญๆทปๅŠ ไบ† `npm run test:unit` โ€”โ€” ๅ•ๅ…ƒๆต‹่ฏ•็Žฐๅœจๅœจๅˆฐ่พพ CI ไน‹ๅ‰้˜ปๆญขๆŸๅ็š„ๆไบคใ€‚ +- **ESLint OOM fix**: `eslint.config.mjs` now ignores `vscode-extension/**`, `electron/**`, `docs/**`, `app/.next/**`, and `clipr/**` โ€” ESLint was crashing with a JS heap OOM by scanning VS Code binary blobs and compiled chunks. +- **Unit test fix**: Removed stale `ALTER TABLE provider_connections ADD COLUMN "group"` from 2 test files โ€” column is now part of the base schema (added in #373), causing `SQLITE_ERROR: duplicate column name` on every CI run. +- **Pre-commit hook**: Added `npm run test:unit` to `.husky/pre-commit` โ€” unit tests now block broken commits before they reach CI. ## [2.5.3] - 2026-03-14 -> ๅ…ณ้”ฎ bug ไฟฎๅค๏ผšๆ•ฐๆฎๅบ“ schema ่ฟ็งปใ€ๅฏๅŠจ็ŽฏๅขƒๅŠ ่ฝฝใ€ๆไพ›ๅ•†้”™่ฏฏ็Šถๆ€ๆธ…้™คๅ’Œ i18n ๅทฅๅ…ทๆ็คบไฟฎๅคใ€‚ๆฏไธช PR ้กถ้ƒจ็š„ไปฃ็ ่ดจ้‡ๆ”น่ฟ›ใ€‚ +> Critical bugfixes: DB schema migration, startup env loading, provider error state clearing, and i18n tooltip fix. Code quality improvements on top of each PR. -### ๐Ÿ› Bug ไฟฎๅค๏ผˆPRs #369, #371, #372, #373 by @kfiramar๏ผ‰ +### ๐Ÿ› Bug Fixes (PRs #369, #371, #372, #373 by @kfiramar) -- **fix(db) #373**๏ผšไธบๅŸบ็ก€ schema ๆทปๅŠ  `provider_connections.group` ๅˆ— + ๅ›žๅกซ่ฟ็งป๏ผŒ็”จไบŽ็Žฐๆœ‰ๆ•ฐๆฎๅบ“ โ€”โ€” ่ฏฅๅˆ—ๅœจๆ‰€ๆœ‰ๆŸฅ่ฏขไธญไฝฟ็”จ๏ผŒไฝ†ๅœจ schema ๅฎšไน‰ไธญ็ผบๅคฑ -- **fix(i18n) #371**๏ผš็”จ็Žฐๆœ‰็š„ `providers.delete` ้”ฎๆ›ฟๆขไธๅญ˜ๅœจ็š„ `t("deleteConnection")` ้”ฎ โ€”โ€” ไฟฎๅคๆไพ›ๅ•†่ฏฆๆƒ…้กต้ข็š„ `MISSING_MESSAGE: providers.deleteConnection` ่ฟ่กŒๆ—ถ้”™่ฏฏ -- **fix(auth) #372**๏ผšๅœจ็œŸๆญฃๆขๅคๅŽๆธ…้™คๆไพ›ๅ•†่ดฆๆˆทไธญ็š„้™ˆๆ—ง้”™่ฏฏๅ…ƒๆ•ฐๆฎ๏ผˆ`errorCode`ใ€`lastErrorType`ใ€`lastErrorSource`๏ผ‰โ€”โ€” ๆญคๅ‰๏ผŒๆขๅค็š„่ดฆๆˆท็ปง็ปญๆ˜พ็คบไธบๅคฑ่ดฅ -- **fix(startup) #369**๏ผš็ปŸไธ€ `npm run start`ใ€`run-standalone.mjs` ๅ’Œ Electron ไธญ็š„็ŽฏๅขƒๅŠ ่ฝฝ๏ผŒ้ตๅพช `DATA_DIR/.env โ†’ ~/.omniroute/.env โ†’ ./.env` ไผ˜ๅ…ˆ็บง โ€”โ€” ้˜ฒๆญขๅœจ็Žฐๆœ‰ๅŠ ๅฏ†ๆ•ฐๆฎๅบ“ไธŠ็”Ÿๆˆๆ–ฐ็š„ `STORAGE_ENCRYPTION_KEY` +- **fix(db) #373**: Add `provider_connections.group` column to base schema + backfill migration for existing databases โ€” column was used in all queries but missing from schema definition +- **fix(i18n) #371**: Replace non-existent `t("deleteConnection")` key with existing `providers.delete` key โ€” fixes `MISSING_MESSAGE: providers.deleteConnection` runtime error on provider detail page +- **fix(auth) #372**: Clear stale error metadata (`errorCode`, `lastErrorType`, `lastErrorSource`) from provider accounts after genuine recovery โ€” previously, recovered accounts kept appearing as failed +- **fix(startup) #369**: Unify env loading across `npm run start`, `run-standalone.mjs`, and Electron to respect `DATA_DIR/.env โ†’ ~/.omniroute/.env โ†’ ./.env` priority โ€” prevents generating a new `STORAGE_ENCRYPTION_KEY` over an existing encrypted database -### ๐Ÿ”ง ไปฃ็ ่ดจ้‡ +### ๐Ÿ”ง Code Quality -- ่ฎฐๅฝ•ไบ† `auth.ts` ไธญ `result.success` ไธŽ `response?.ok` ๆจกๅผ๏ผˆไธค่€…้ƒฝๆ˜ฏๆœ‰ๆ„ไธบไน‹๏ผŒ็Žฐๅทฒ่ฏดๆ˜Ž๏ผ‰ -- ๅœจ `electron/main.js` ไธญ่ง„่ŒƒๅŒ–ไบ† `overridePath?.trim()` ไปฅๅŒน้… `bootstrap-env.mjs` -- ๅœจ Electron ๅฏๅŠจไธญๆทปๅŠ ไบ† `preferredEnv` ๅˆๅนถ้กบๅบๆณจ้‡Š +- Documented `result.success` vs `response?.ok` patterns in `auth.ts` (both intentional, now explained) +- Normalized `overridePath?.trim()` in `electron/main.js` to match `bootstrap-env.mjs` +- Added `preferredEnv` merge order comment in Electron startup -> Codex ่ดฆๆˆท้…้ข็ญ–็•ฅ๏ผŒๅธฆ่‡ชๅŠจ่ฝฎๆขใ€ๅฟซ้€Ÿๅฑ‚็บงๅˆ‡ๆขใ€gpt-5.4 ๆจกๅž‹ๅ’Œๅˆ†ๆžๆ ‡็ญพไฟฎๅคใ€‚ +> Codex account quota policy with auto-rotation, fast tier toggle, gpt-5.4 model, and analytics label fix. -### โœจ ๆ–ฐ็‰นๆ€ง๏ผˆPRs #366, #367, #368๏ผ‰ +### โœจ New Features (PRs #366, #367, #368) -- **Codex ้…้ข็ญ–็•ฅ๏ผˆPR #366๏ผ‰**๏ผšๆไพ›ๅ•†ไปช่กจ็›˜ไธญ็š„ๆฏ่ดฆๆˆท 5h/ๆฏๅ‘จ้…้ข็ช—ๅฃๅผ€ๅ…ณใ€‚ๅฝ“ๅฏ็”จ็š„็ช—ๅฃ่พพๅˆฐ 90% ้˜ˆๅ€ผๆ—ถ่‡ชๅŠจ่ทณ่ฟ‡่ดฆๆˆท๏ผŒๅนถๅœจ `resetAt` ๅŽ้‡ๆ–ฐๆŽฅ็บณใ€‚ๅŒ…ๆ‹ฌ `quotaCache.ts`๏ผŒๅธฆๆ— ๅ‰ฏไฝœ็”จ็š„็Šถๆ€่Žทๅ–ๅ™จใ€‚ -- **Codex ๅฟซ้€Ÿๅฑ‚็บงๅˆ‡ๆข๏ผˆPR #367๏ผ‰**๏ผšDashboard โ†’ Settings โ†’ Codex Service Tierใ€‚้ป˜่ฎคๅ…ณ้—ญ็š„ๅผ€ๅ…ณไป…ไธบ Codex ่ฏทๆฑ‚ๆณจๅ…ฅ `service_tier: "flex"`๏ผŒ้™ไฝŽๆˆๆœฌ็บฆ 80%ใ€‚ๅ…จๆ ˆ๏ผšUI ๆ ‡็ญพ้กต + API ็ซฏ็‚น + ๆ‰ง่กŒๅ™จ + ็ฟป่ฏ‘ๅ™จ + ๅฏๅŠจๆขๅคใ€‚ -- **gpt-5.4 ๆจกๅž‹๏ผˆPR #368๏ผ‰**๏ผšไธบ Codex ๆจกๅž‹ๆณจๅ†Œ่กจๆทปๅŠ  `cx/gpt-5.4` ๅ’Œ `codex/gpt-5.4`ใ€‚ๅŒ…ๅซๅ›žๅฝ’ๆต‹่ฏ•ใ€‚ +- **Codex Quota Policy (PR #366)**: Per-account 5h/weekly quota window toggles in Provider dashboard. Accounts are automatically skipped when enabled windows reach 90% threshold and re-admitted after `resetAt`. Includes `quotaCache.ts` with side-effect free status getter. +- **Codex Fast Tier Toggle (PR #367)**: Dashboard โ†’ Settings โ†’ Codex Service Tier. Default-off toggle injects `service_tier: "flex"` only for Codex requests, reducing cost ~80%. Full stack: UI tab + API endpoint + executor + translator + startup restore. +- **gpt-5.4 Model (PR #368)**: Adds `cx/gpt-5.4` and `codex/gpt-5.4` to the Codex model registry. Regression test included. -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **fix #356**๏ผšๅˆ†ๆžๅ›พ่กจ๏ผˆ้กถ็บงๆไพ›ๅ•†ใ€ๆŒ‰่ดฆๆˆทใ€ๆไพ›ๅ•†ๆ‹†ๅˆ†๏ผ‰็Žฐๅœจไธบ OpenAI ๅ…ผๅฎนๆไพ›ๅ•†ๆ˜พ็คบไบบ็ฑปๅฏ่ฏป็š„ๆไพ›ๅ•†ๅ็งฐ/ๆ ‡็ญพ๏ผŒ่€Œไธๆ˜ฏๅŽŸๅง‹ๅ†…้ƒจ IDใ€‚ +- **fix #356**: Analytics charts (Top Provider, By Account, Provider Breakdown) now display human-readable provider names/labels instead of raw internal IDs for OpenAI-compatible providers. -> ไธป่ฆๅ‘ๅธƒ๏ผšstrict-random ่ทฏ็”ฑ็ญ–็•ฅใ€API key ่ฎฟ้—ฎๆŽงๅˆถใ€่ฟžๆŽฅ็ป„ใ€ๅค–้ƒจๅฎšไปทๅŒๆญฅๅ’Œ thinking ๆจกๅž‹ใ€combo ๆต‹่ฏ•ใ€ๅทฅๅ…ทๅ็งฐ้ชŒ่ฏ็š„ๅ…ณ้”ฎ bug ไฟฎๅคใ€‚ +> Major release: strict-random routing strategy, API key access controls, connection groups, external pricing sync, and critical bug fixes for thinking models, combo testing, and tool name validation. -### โœจ ๆ–ฐ็‰นๆ€ง๏ผˆPRs #363 & #365๏ผ‰ +### โœจ New Features (PRs #363 & #365) -- **Strict-Random ่ทฏ็”ฑ็ญ–็•ฅ**๏ผšFisher-Yates ๆด—็‰Œ็‰Œ็ป„๏ผŒๅธฆ้˜ฒ้‡ๅคไฟ่ฏๅ’Œๅนถๅ‘่ฏทๆฑ‚็š„ไบ’ๆ–ฅๅบๅˆ—ๅŒ–ใ€‚ๆฏไธช combo ๅ’Œๆฏไธชๆไพ›ๅ•†็‹ฌ็ซ‹็š„็‰Œ็ป„ใ€‚ -- **API Key ่ฎฟ้—ฎๆŽงๅˆถ**๏ผš`allowedConnections`๏ผˆ้™ๅˆถ key ๅฏไฝฟ็”จ็š„่ฟžๆŽฅ๏ผ‰ใ€`is_active`๏ผˆๅฏ็”จ/็ฆ็”จ key๏ผŒ่ฟ”ๅ›ž 403๏ผ‰ใ€`accessSchedule`๏ผˆๅŸบไบŽๆ—ถ้—ด็š„่ฎฟ้—ฎๆŽงๅˆถ๏ผ‰ใ€`autoResolve` ๅผ€ๅ…ณใ€้€š่ฟ‡ PATCH ้‡ๅ‘ฝๅ keyใ€‚ -- **่ฟžๆŽฅ็ป„**๏ผšๆŒ‰็Žฏๅขƒๅˆ†็ป„ๆไพ›ๅ•†่ฟžๆŽฅใ€‚Limits ้กต้ขไธญ็š„ๆ‰‹้ฃŽ็ด่ง†ๅ›พ๏ผŒไฝฟ็”จ localStorage ๆŒไน…ๅŒ–ๅ’Œๆ™บ่ƒฝ่‡ชๅŠจๅˆ‡ๆขใ€‚ -- **ๅค–้ƒจๅฎšไปทๅŒๆญฅ๏ผˆLiteLLM๏ผ‰**๏ผš3 ๅฑ‚ๅฎšไปท่งฃๆž๏ผˆ็”จๆˆท่ฆ†็›– โ†’ ๅŒๆญฅ โ†’ ้ป˜่ฎค๏ผ‰ใ€‚้€š่ฟ‡ `PRICING_SYNC_ENABLED=true` ้€‰ๆ‹ฉๅŠ ๅ…ฅใ€‚MCP ๅทฅๅ…ท `omniroute_sync_pricing`ใ€‚23 ไธชๆ–ฐๆต‹่ฏ•ใ€‚ -- **i18n**๏ผš30 ็ง่ฏญ่จ€ๆ›ดๆ–ฐ๏ผŒไฝฟ็”จ strict-random ็ญ–็•ฅใ€API key ็ฎก็†ๅญ—็ฌฆไธฒใ€‚pt-BR ๅฎŒๅ…จ็ฟป่ฏ‘ใ€‚ +- **Strict-Random Routing Strategy**: Fisher-Yates shuffle deck with anti-repeat guarantee and mutex serialization for concurrent requests. Independent decks per combo and per provider. +- **API Key Access Controls**: `allowedConnections` (restrict which connections a key can use), `is_active` (enable/disable key with 403), `accessSchedule` (time-based access control), `autoResolve` toggle, rename keys via PATCH. +- **Connection Groups**: Group provider connections by environment. Accordion view in Limits page with localStorage persistence and smart auto-switch. +- **External Pricing Sync (LiteLLM)**: 3-tier pricing resolution (user overrides โ†’ synced โ†’ defaults). Opt-in via `PRICING_SYNC_ENABLED=true`. MCP tool `omniroute_sync_pricing`. 23 new tests. +- **i18n**: 30 languages updated with strict-random strategy, API key management strings. pt-BR fully translated. -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **fix #355**๏ผšๆต็ฉบ้—ฒ่ถ…ๆ—ถไปŽ 60 ็ง’ๅขžๅŠ ๅˆฐ 300 ็ง’ โ€”โ€” ้˜ฒๆญขๅœจ้•ฟๆ—ถ้—ดๆŽจ็†้˜ถๆฎตไธญๆญขๆ‰ฉๅฑ• thinking ๆจกๅž‹๏ผˆclaude-opus-4-6ใ€o3 ็ญ‰๏ผ‰ใ€‚ๅฏ้€š่ฟ‡ `STREAM_IDLE_TIMEOUT_MS` ้…็ฝฎใ€‚ -- **fix #350**๏ผšCombo ๆต‹่ฏ•็Žฐๅœจไฝฟ็”จๅ†…้ƒจๅคด็ป•่ฟ‡ `REQUIRE_API_KEY=true`๏ผŒๅนถๆ™ฎ้ไฝฟ็”จ OpenAI ๅ…ผๅฎนๆ ผๅผใ€‚่ถ…ๆ—ถไปŽ 15 ็ง’ๅปถ้•ฟๅˆฐ 20 ็ง’ใ€‚ -- **fix #346**๏ผšไฝฟ็”จ็ฉบ `function.name` ็š„ๅทฅๅ…ท๏ผˆ็”ฑ Claude Code ่ฝฌๅ‘๏ผ‰็Žฐๅœจๅœจๅˆฐ่พพไธŠๆธธๆไพ›ๅ•†ไน‹ๅ‰่ขซ่ฟ‡ๆปค๏ผŒ้˜ฒๆญข "Invalid input[N].name: empty string" ้”™่ฏฏใ€‚ +- **fix #355**: Stream idle timeout increased from 60s to 300s โ€” prevents aborting extended-thinking models (claude-opus-4-6, o3, etc.) during long reasoning phases. Configurable via `STREAM_IDLE_TIMEOUT_MS`. +- **fix #350**: Combo test now bypasses `REQUIRE_API_KEY=true` using internal header, and uses OpenAI-compatible format universally. Timeout extended from 15s to 20s. +- **fix #346**: Tools with empty `function.name` (forwarded by Claude Code) are now filtered before upstream providers receive them, preventing "Invalid input[N].name: empty string" errors. -### ๐Ÿ—‘๏ธ ๅทฒๅ…ณ้—ญ็š„้—ฎ้ข˜ +### ๐Ÿ—‘๏ธ Closed Issues -- **#341**๏ผš่ฐƒ่ฏ•้ƒจๅˆ†ๅทฒ็งป้™ค โ€”โ€” ๆ›ฟๆขไธบ `/dashboard/logs` ๅ’Œ `/dashboard/health`ใ€‚ +- **#341**: Debug section removed โ€” replacement is `/dashboard/logs` and `/dashboard/health`. -> API Key Round-Robin ๆ”ฏๆŒ๏ผŒ็”จไบŽๅคš key ๆไพ›ๅ•†่ฎพ็ฝฎ๏ผŒไปฅๅŠ็กฎ่ฎค้€š้…็ฌฆ่ทฏ็”ฑๅ’Œ้…้ข็ช—ๅฃๆปšๅŠจๅทฒๅฐฑไฝใ€‚ +> API Key Round-Robin support for multi-key provider setups, and confirmation of wildcard routing and quota window rolling already in place. -### โœจ ๆ–ฐ็‰นๆ€ง +### โœจ New Features -- **API Key Round-Robin (T07)**๏ผšๆไพ›ๅ•†่ฟžๆŽฅ็ŽฐๅœจๅฏไปฅๆŒๆœ‰ๅคšไธช API key๏ผˆ็ผ–่พ‘่ฟžๆŽฅ โ†’ ้ขๅค– API key๏ผ‰ใ€‚่ฏทๆฑ‚ๅœจไธป key + ้ขๅค– key ไน‹้—ด่ฝฎ่ฝฌ๏ผŒ้€š่ฟ‡ `providerSpecificData.extraApiKeys[]`ใ€‚key ๆŒ‰่ฟžๆŽฅๅœจๅ†…ๅญ˜ไธญ็ดขๅผ•ๆŒๆœ‰ โ€”โ€” ๆ— ้œ€ๆ•ฐๆฎๅบ“ schema ๅ˜ๆ›ดใ€‚ +- **API Key Round-Robin (T07)**: Provider connections can now hold multiple API keys (Edit Connection โ†’ Extra API Keys). Requests rotate round-robin between primary + extra keys via `providerSpecificData.extraApiKeys[]`. Keys are held in-memory indexed per connection โ€” no DB schema changes required. -### ๐Ÿ“ ๅทฒๅฎž็Žฐ๏ผˆๅฎก่ฎก็กฎ่ฎค๏ผ‰ +### ๐Ÿ“ Already Implemented (confirmed in audit) -- **้€š้…็ฌฆๆจกๅž‹่ทฏ็”ฑ (T13)**๏ผš`wildcardRouter.ts` ไฝฟ็”จ glob ้ฃŽๆ ผ้€š้…็ฌฆๅŒน้…๏ผˆ`gpt*`ใ€`claude-?-sonnet` ็ญ‰๏ผ‰ๅทฒ้›†ๆˆๅˆฐ `model.ts` ไธญ๏ผŒๅธฆ็‰นๅผ‚ๆ€งๆŽ’ๅใ€‚ -- **้…้ข็ช—ๅฃๆปšๅŠจ (T08)**๏ผš`accountFallback.ts:isModelLocked()` ๅทฒ่‡ชๅŠจๆŽจ่ฟ›็ช—ๅฃ โ€”โ€” ๅฆ‚ๆžœ `Date.now() > entry.until`๏ผŒ้”็ซ‹ๅณๅˆ ้™ค๏ผˆๆ— ้™ˆๆ—ง้˜ปๅกž๏ผ‰ใ€‚ +- **Wildcard Model Routing (T13)**: `wildcardRouter.ts` with glob-style wildcard matching (`gpt*`, `claude-?-sonnet`, etc.) is already integrated into `model.ts` with specificity ranking. +- **Quota Window Rolling (T08)**: `accountFallback.ts:isModelLocked()` already auto-advances the window โ€” if `Date.now() > entry.until`, lock is deleted immediately (no stale blocking). -> UI ๆ‰“็ฃจใ€่ทฏ็”ฑ็ญ–็•ฅ่กฅๅ……ๅ’Œ็”จ้‡้™ๅˆถ็š„ไผ˜้›…้”™่ฏฏๅค„็†ใ€‚ +> UI polish, routing strategy additions, and graceful error handling for usage limits. -### โœจ ๆ–ฐ็‰นๆ€ง +### โœจ New Features -- **Fill-First & P2C ่ทฏ็”ฑ็ญ–็•ฅ**๏ผšไธบ combo ็ญ–็•ฅ้€‰ๆ‹ฉๅ™จๆทปๅŠ ไบ† `fill-first`๏ผˆๅœจ็ปง็ปญไน‹ๅ‰ๆŽ’็ฉบ้…้ข๏ผ‰ๅ’Œ `p2c`๏ผˆPower-of-Two-Choices ไฝŽๅปถ่ฟŸ้€‰ๆ‹ฉ๏ผ‰๏ผŒๅธฆๅฎŒๆ•ดๆŒ‡ๅฏผ้ขๆฟๅ’Œ้ขœ่‰ฒ็ผ–็ ๅพฝ็ซ ใ€‚ -- **Free Stack ้ข„่ฎพๆจกๅž‹**๏ผšไฝฟ็”จ Free Stack ๆจกๆฟๅˆ›ๅปบ combo ๆ—ถ๏ผŒ็Žฐๅœจ่‡ชๅŠจๅกซๅ…… 7 ไธชๆœ€ไฝณๅ…่ดนๆไพ›ๅ•†ๆจกๅž‹๏ผˆGemini CLIใ€Kiroใ€Qoderร—2ใ€Qwenใ€NVIDIA NIMใ€Groq๏ผ‰ใ€‚็”จๆˆทๅช้œ€ๆฟ€ๆดปๆไพ›ๅ•†ๅณๅฏ่Žทๅพ—ๅผ€็ฎฑๅณ็”จ็š„ $0/ๆœˆ comboใ€‚ -- **ๆ›ดๅฎฝ็š„ Combo ๆจกๆ€ๆก†**๏ผšๅˆ›ๅปบ/็ผ–่พ‘ combo ๆจกๆ€ๆก†็Žฐๅœจไฝฟ็”จ `max-w-4xl`๏ผŒไปฅไพฟ่ˆ’้€‚ๅœฐ็ผ–่พ‘ๅคงๅž‹ comboใ€‚ +- **Fill-First & P2C Routing Strategies**: Added `fill-first` (drain quota before moving on) and `p2c` (Power-of-Two-Choices low-latency selection) to combo strategy picker, with full guidance panels and color-coded badges. +- **Free Stack Preset Models**: Creating a combo with the Free Stack template now auto-fills 7 best-in-class free provider models (Gemini CLI, Kiro, Qoderร—2, Qwen, NVIDIA NIM, Groq). Users just activate the providers and get a $0/month combo out-of-the-box. +- **Wider Combo Modal**: Create/Edit combo modal now uses `max-w-4xl` for comfortable editing of large combos. -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **Limits ้กต้ข HTTP 500๏ผˆ็”จไบŽ Codex & GitHub๏ผ‰**๏ผšๅฝ“ๆไพ›ๅ•†่ฟ”ๅ›ž 401/403๏ผˆ่ฟ‡ๆœŸ token๏ผ‰ๆ—ถ๏ผŒ`getCodexUsage()` ๅ’Œ `getGitHubUsage()` ็Žฐๅœจ่ฟ”ๅ›ž็”จๆˆทๅ‹ๅฅฝ็š„ๆถˆๆฏ๏ผŒ่€Œไธๆ˜ฏๆŠ›ๅ‡บๅผ‚ๅธธๅฏผ่‡ด Limits ้กต้ขๅ‡บ็Žฐ 500 ้”™่ฏฏใ€‚ -- **MaintenanceBanner ่ฏฏๆŠฅ**๏ผšๆจชๅน…ไธๅ†ๅœจ้กต้ขๅŠ ่ฝฝๆ—ถ่™šๅ‡ๆ˜พ็คบ "Server is unreachable"ใ€‚้€š่ฟ‡ๅœจๆŒ‚่ฝฝๆ—ถ็ซ‹ๅณ่ฐƒ็”จ `checkHealth()` ๅนถ็งป้™ค้™ˆๆ—ง็š„ `show` ็Šถๆ€้—ญๅŒ…ๆฅไฟฎๅคใ€‚ -- **ๆไพ›ๅ•†ๅ›พๆ ‡ๅทฅๅ…ทๆ็คบ**๏ผšๆไพ›ๅ•†่ฟžๆŽฅ่กŒไธญ็š„็ผ–่พ‘๏ผˆ้“…็ฌ”๏ผ‰ๅ’Œๅˆ ้™คๅ›พๆ ‡ๆŒ‰้’ฎ็Žฐๅœจๆœ‰ๅŽŸ็”Ÿ HTML ๅทฅๅ…ทๆ็คบ โ€”โ€” ๆ‰€ๆœ‰ 6 ไธชๆ“ไฝœๅ›พๆ ‡็Žฐๅœจ้ƒฝๆœ‰่‡ชๆ–‡ๆกฃ่ฏดๆ˜Žใ€‚ +- **Limits page HTTP 500 for Codex & GitHub**: `getCodexUsage()` and `getGitHubUsage()` now return a user-friendly message when the provider returns 401/403 (expired token), instead of throwing and causing a 500 error on the Limits page. +- **MaintenanceBanner false-positive**: Banner no longer shows "Server is unreachable" spuriously on page load. Fixed by calling `checkHealth()` immediately on mount and removing stale `show`-state closure. +- **Provider icon tooltips**: Edit (pencil) and delete icon buttons in the provider connection row now have native HTML tooltips โ€” all 6 action icons are now self-documented. -> ๆฅ่‡ช็คพๅŒบ้—ฎ้ข˜ๅˆ†ๆž็š„ๅคš้กนๆ”น่ฟ›ใ€ๆ–ฐๆไพ›ๅ•†ๆ”ฏๆŒใ€token ่ฟฝ่ธชใ€ๆจกๅž‹่ทฏ็”ฑๅ’Œๆตๅผไผ ่พ“ๅฏ้ ๆ€ง็š„ bug ไฟฎๅคใ€‚ +> Multiple improvements from community issue analysis, new provider support, bug fixes for token tracking, model routing, and streaming reliability. -### โœจ ๆ–ฐ็‰นๆ€ง +### โœจ New Features -- **ไปปๅŠกๆ„Ÿ็Ÿฅๆ™บ่ƒฝ่ทฏ็”ฑ (T05)**๏ผšๅŸบไบŽ่ฏทๆฑ‚ๅ†…ๅฎน็ฑปๅž‹็š„่‡ชๅŠจๆจกๅž‹้€‰ๆ‹ฉ โ€”โ€” ็ผ–็  โ†’ deepseek-chat๏ผŒๅˆ†ๆž โ†’ gemini-2.5-pro๏ผŒ่ง†่ง‰ โ†’ gpt-4o๏ผŒๆ‘˜่ฆ โ†’ gemini-2.5-flashใ€‚ๅฏ้€š่ฟ‡่ฎพ็ฝฎ้…็ฝฎใ€‚ๆ–ฐๅขž `GET/PUT/POST /api/settings/task-routing` APIใ€‚ -- **HuggingFace ๆไพ›ๅ•†**๏ผšๆ–ฐๅขž HuggingFace Router ไฝœไธบ OpenAI ๅ…ผๅฎนๆไพ›ๅ•†๏ผŒไฝฟ็”จ Llama 3.1 70B/8Bใ€Qwen 2.5 72Bใ€Mistral 7Bใ€Phi-3.5 Miniใ€‚ -- **Vertex AI ๆไพ›ๅ•†**๏ผšๆ–ฐๅขž Vertex AI (Google Cloud) ๆไพ›ๅ•†๏ผŒไฝฟ็”จ Gemini 2.5 Pro/Flashใ€Gemma 2 27Bใ€Claude๏ผˆ้€š่ฟ‡ Vertex๏ผ‰ใ€‚ -- **ๆธธไนๅœบๆ–‡ไปถไธŠไผ **๏ผš็”จไบŽ่ฝฌๅฝ•็š„้Ÿณ้ข‘ไธŠไผ ใ€็”จไบŽ่ง†่ง‰ๆจกๅž‹็š„ๅ›พๅƒไธŠไผ ๏ผˆๆŒ‰ๆจกๅž‹ๅ็งฐ่‡ชๅŠจๆฃ€ๆต‹๏ผ‰ใ€็”จไบŽๅ›พๅƒ็”Ÿๆˆ็ป“ๆžœ็š„ๅ†…่”ๅ›พๅƒๆธฒๆŸ“ใ€‚ -- **ๆจกๅž‹้€‰ๆ‹ฉ่ง†่ง‰ๅ้ฆˆ**๏ผšๅทฒๅœจ combo ้€‰ๆ‹ฉๅ™จไธญๆทปๅŠ ็š„ๆจกๅž‹็Žฐๅœจๆ˜พ็คบ โœ“ ็ปฟ่‰ฒๅพฝ็ซ  โ€”โ€” ้˜ฒๆญข้‡ๅคๆททๆท†ใ€‚ -- **Qwen ๅ…ผๅฎนๆ€ง (PR #352)**๏ผšๆ›ดๆ–ฐไบ† User-Agent ๅ’Œ CLI ๆŒ‡็บน่ฎพ็ฝฎ๏ผŒ็”จไบŽ Qwen ๆไพ›ๅ•†ๅ…ผๅฎนๆ€งใ€‚ -- **Round-Robin ็Šถๆ€็ฎก็† (PR #349)**๏ผšๅขžๅผบไบ† round-robin ้€ป่พ‘ไปฅๅค„็†ๆŽ’้™ค็š„่ดฆๆˆทๅนถๆญฃ็กฎ็ปดๆŠค่ฝฎๆข็Šถๆ€ใ€‚ -- **ๅ‰ช่ดดๆฟ UX (PR #360)**๏ผšๅŠ ๅ›บไบ†ๅ‰ช่ดดๆฟๆ“ไฝœ๏ผŒๅธฆ้žๅฎ‰ๅ…จไธŠไธ‹ๆ–‡็š„ๅ›ž้€€๏ผ›Claude ๅทฅๅ…ท่ง„่ŒƒๅŒ–ๆ”น่ฟ›ใ€‚ +- **Task-Aware Smart Routing (T05)**: Automatic model selection based on request content type โ€” coding โ†’ deepseek-chat, analysis โ†’ gemini-2.5-pro, vision โ†’ gpt-4o, summarization โ†’ gemini-2.5-flash. Configurable via Settings. New `GET/PUT/POST /api/settings/task-routing` API. +- **HuggingFace Provider**: Added HuggingFace Router as an OpenAI-compatible provider with Llama 3.1 70B/8B, Qwen 2.5 72B, Mistral 7B, Phi-3.5 Mini. +- **Vertex AI Provider**: Added Vertex AI (Google Cloud) provider with Gemini 2.5 Pro/Flash, Gemma 2 27B, Claude via Vertex. +- **Playground File Uploads**: Audio upload for transcription, image upload for vision models (auto-detect by model name), inline image rendering for image generation results. +- **Model Select Visual Feedback**: Already-added models in combo picker now show โœ“ green badge โ€” prevents duplicate confusion. +- **Qwen Compatibility (PR #352)**: Updated User-Agent and CLI fingerprint settings for Qwen provider compatibility. +- **Round-Robin State Management (PR #349)**: Enhanced round-robin logic to handle excluded accounts and maintain rotation state correctly. +- **Clipboard UX (PR #360)**: Hardened clipboard operations with fallback for non-secure contexts; Claude tool normalization improvements. -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **Fix #302 โ€” OpenAI SDK stream=False ไธขๅผƒ tool_calls**๏ผšT01 Accept ๅคดๅๅ•†ไธๅ†ๅœจ `body.stream` ๆ˜พๅผไธบ `false` ๆ—ถๅผบๅˆถๆตๅผไผ ่พ“ใ€‚ๆญคๅ‰ๅฏผ่‡ดไฝฟ็”จ OpenAI Python SDK ้žๆตๅผๆจกๅผๆ—ถ tool_calls ่ขซ้™้ป˜ไธขๅผƒใ€‚ -- **Fix #73 โ€” Claude Haiku ๅœจๆฒกๆœ‰ๆไพ›ๅ•†ๅ‰็ผ€็š„ๆƒ…ๅ†ตไธ‹่ทฏ็”ฑๅˆฐ OpenAI**๏ผšไธๅธฆๆไพ›ๅ•†ๅ‰็ผ€ๅ‘้€็š„ `claude-*` ๆจกๅž‹็Žฐๅœจๆญฃ็กฎ่ทฏ็”ฑๅˆฐ `antigravity` (Anthropic) ๆไพ›ๅ•†ใ€‚่ฟ˜ๆทปๅŠ ไบ† `gemini-*`/`gemma-*` โ†’ `gemini` ๅฏๅ‘ๅผ่ง„ๅˆ™ใ€‚ -- **Fix #74 โ€” Antigravity/Claude ๆตๅผไผ ่พ“็š„ Token ่ฎกๆ•ฐๅง‹็ปˆไธบ 0**๏ผšๆบๅธฆ `input_tokens` ็š„ `message_start` SSE ไบ‹ไปถๆœช่ขซ `extractUsage()` ่งฃๆž๏ผŒๅฏผ่‡ดๆ‰€ๆœ‰่พ“ๅ…ฅ token ่ฎกๆ•ฐไธขๅคฑใ€‚่พ“ๅ…ฅ/่พ“ๅ‡บ token ่ฟฝ่ธช็Žฐๅœจๅฏนๆตๅผๅ“ๅบ”ๆญฃ็กฎๅทฅไฝœใ€‚ -- **Fix #180 โ€” ๆจกๅž‹ๅฏผๅ…ฅ้‡ๅค๏ผŒๆ— ๅ้ฆˆ**๏ผš`ModelSelectModal` ็Žฐๅœจไธบๅทฒๅœจ combo ไธญ็š„ๆจกๅž‹ๆ˜พ็คบ โœ“ ็ปฟ่‰ฒ้ซ˜ไบฎ๏ผŒไฝฟๅ…ถๆ˜Žๆ˜พๅทฒ่ขซๆทปๅŠ ใ€‚ -- **ๅช’ไฝ“้กต้ข็”Ÿๆˆ้”™่ฏฏ**๏ผšๅ›พๅƒ็ป“ๆžœ็ŽฐๅœจๆธฒๆŸ“ไธบ `` ๆ ‡็ญพ๏ผŒ่€Œไธๆ˜ฏๅŽŸๅง‹ JSONใ€‚่ฝฌๅฝ•็ป“ๆžœๆ˜พ็คบไธบๅฏ่ฏปๆ–‡ๆœฌใ€‚ๅ‡ญ่ฏ้”™่ฏฏๆ˜พ็คบ็ฅ็€่‰ฒๆจชๅน…๏ผŒ่€Œไธๆ˜ฏ้™้ป˜ๅคฑ่ดฅใ€‚ -- **ๆไพ›ๅ•†้กต้ข็š„ Token ๅˆทๆ–ฐๆŒ‰้’ฎ**๏ผšไธบ OAuth ๆไพ›ๅ•†ๆทปๅŠ ไบ†ๆ‰‹ๅŠจ token ๅˆทๆ–ฐ UIใ€‚ +- **Fix #302 โ€” OpenAI SDK stream=False drops tool_calls**: T01 Accept header negotiation no longer forces streaming when `body.stream` is explicitly `false`. Was causing tool_calls to be silently dropped when using the OpenAI Python SDK in non-streaming mode. +- **Fix #73 โ€” Claude Haiku routed to OpenAI without provider prefix**: `claude-*` models sent without a provider prefix now correctly route to the `antigravity` (Anthropic) provider. Added `gemini-*`/`gemma-*` โ†’ `gemini` heuristic as well. +- **Fix #74 โ€” Token counts always 0 for Antigravity/Claude streaming**: The `message_start` SSE event which carries `input_tokens` was not being parsed by `extractUsage()`, causing all input token counts to drop. Input/output token tracking now works correctly for streaming responses. +- **Fix #180 โ€” Model import duplicates with no feedback**: `ModelSelectModal` now shows โœ“ green highlight for models already in the combo, making it obvious they're already added. +- **Media page generation errors**: Image results now render as `` tags instead of raw JSON. Transcription results shown as readable text. Credential errors show an amber banner instead of silent failure. +- **Token refresh button on provider page**: Manual token refresh UI added for OAuth providers. -### ๐Ÿ”ง ๆ”น่ฟ› +### ๐Ÿ”ง Improvements -- **ๆไพ›ๅ•†ๆณจๅ†Œ่กจ**๏ผšHuggingFace ๅ’Œ Vertex AI ๆทปๅŠ ๅˆฐ `providerRegistry.ts` ๅ’Œ `providers.ts`๏ผˆๅ‰็ซฏ๏ผ‰ใ€‚ -- **่ฏปๅ–็ผ“ๅญ˜**๏ผšๆ–ฐๅขž `src/lib/db/readCache.ts`๏ผŒ็”จไบŽ้ซ˜ๆ•ˆ็š„ๆ•ฐๆฎๅบ“่ฏปๅ–็ผ“ๅญ˜ใ€‚ -- **้…้ข็ผ“ๅญ˜**๏ผšๆ”น่ฟ›ไบ†้…้ข็ผ“ๅญ˜๏ผŒไฝฟ็”จๅŸบไบŽ TTL ็š„้ฉฑ้€ใ€‚ +- **Provider Registry**: HuggingFace and Vertex AI added to `providerRegistry.ts` and `providers.ts` (frontend). +- **Read Cache**: New `src/lib/db/readCache.ts` for efficient DB read caching. +- **Quota Cache**: Improved quota cache with TTL-based eviction. -### ๐Ÿ“ฆ ไพ่ต– +### ๐Ÿ“ฆ Dependencies - `dompurify` โ†’ 3.3.3 (PR #347) - `undici` โ†’ 7.24.2 (PR #348, #361) - `docker/setup-qemu-action` โ†’ v4 (PR #342) - `docker/setup-buildx-action` โ†’ v4 (PR #343) -### ๐Ÿ“ ๆ–ฐๅขžๆ–‡ไปถ +### ๐Ÿ“ New Files -| ๆ–‡ไปถ | ็›ฎ็š„ | -| --------------------------------------------- | -------------------------------- | -| `open-sse/services/taskAwareRouter.ts` | ไปปๅŠกๆ„Ÿ็Ÿฅ่ทฏ็”ฑ้€ป่พ‘๏ผˆ7 ็งไปปๅŠก็ฑปๅž‹๏ผ‰ | -| `src/app/api/settings/task-routing/route.ts` | ไปปๅŠก่ทฏ็”ฑ้…็ฝฎ API | -| `src/app/api/providers/[id]/refresh/route.ts` | ๆ‰‹ๅŠจ OAuth token ๅˆทๆ–ฐ | -| `src/lib/db/readCache.ts` | ้ซ˜ๆ•ˆ็š„ๆ•ฐๆฎๅบ“่ฏปๅ–็ผ“ๅญ˜ | -| `src/shared/utils/clipboard.ts` | ๅŠ ๅ›บ็š„ๅ‰ช่ดดๆฟ๏ผŒๅธฆๅ›ž้€€ | +| File | Purpose | +| --------------------------------------------- | --------------------------------------- | +| `open-sse/services/taskAwareRouter.ts` | Task-aware routing logic (7 task types) | +| `src/app/api/settings/task-routing/route.ts` | Task routing config API | +| `src/app/api/providers/[id]/refresh/route.ts` | Manual OAuth token refresh | +| `src/lib/db/readCache.ts` | Efficient DB read cache | +| `src/shared/utils/clipboard.ts` | Hardened clipboard with fallback | ## [2.4.1] - 2026-03-13 -### ๐Ÿ› ไฟฎๅค +### ๐Ÿ› Fix -- **Combos ๆจกๆ€ๆก†๏ผšFree Stack ๅฏ่งไธ”็ชๅ‡บ** โ€”โ€” Free Stack ๆจกๆฟ่ขซ้š่—๏ผˆ3 ๅˆ—็ฝ‘ๆ ผไธญ็š„็ฌฌ 4 ไธช๏ผ‰ใ€‚ไฟฎๅค๏ผš็งปๅŠจๅˆฐไฝ็ฝฎ 1๏ผŒๅˆ‡ๆขไธบ 2x2 ็ฝ‘ๆ ผ๏ผŒไฝฟๆ‰€ๆœ‰ 4 ไธชๆจกๆฟๅฏ่ง๏ผŒ็ปฟ่‰ฒ่พนๆก† + FREE ๅพฝ็ซ ้ซ˜ไบฎใ€‚ +- **Combos modal: Free Stack visible and prominent** โ€” Free Stack template was hidden (4th in 3-column grid). Fixed: moved to position 1, switched to 2x2 grid so all 4 templates are visible, green border + FREE badge highlight. ## [2.4.0] - 2026-03-13 -> **ไธป่ฆๅ‘ๅธƒ** โ€”โ€” Free Stack ็”Ÿๆ€็ณป็ปŸใ€่ฝฌๅฝ•ๆธธไนๅœบ overhaulใ€44+ ๆไพ›ๅ•†ใ€ๅ…จ้ข็š„ๅ…่ดนๅฑ‚ๆ–‡ๆกฃๅ’Œๅ…จ้ข็š„ UI ๆ”น่ฟ›ใ€‚ +> **Major release** โ€” Free Stack ecosystem, transcription playground overhaul, 44+ providers, comprehensive free tier documentation, and UI improvements across the board. -### โœจ ๆ–ฐ็‰นๆ€ง +### ๅŠŸ่ƒฝ็‰น็‚น -- **Combos: Free Stack ๆจกๆฟ** โ€”โ€” ๆ–ฐๅขž็ฌฌ 4 ไธชๆจกๆฟ "Free Stack ($0)"๏ผŒไฝฟ็”จ Kiro + Qoder + Qwen + Gemini CLI ็š„่ฝฎ่ฝฌใ€‚้ฆ–ๆฌกไฝฟ็”จๆ—ถๅปบ่ฎฎ้ข„ๆž„ๅปบ็š„้›ถๆˆๆœฌ comboใ€‚ -- **Media/Transcription: Deepgram ไฝœไธบ้ป˜่ฎค** โ€”โ€” Deepgram (Nova 3, $200 ๅ…่ดน) ็Žฐๅœจๆ˜ฏ้ป˜่ฎค่ฝฌๅฝ•ๆไพ›ๅ•†ใ€‚AssemblyAI ($50 ๅ…่ดน) ๅ’Œ Groq Whisper (ๆฐธไน…ๅ…่ดน) ๆ˜พ็คบๅ…่ดน็งฏๅˆ†ๅพฝ็ซ ใ€‚ -- **README: "Start Free" ้ƒจๅˆ†** โ€”โ€” ๆ–ฐๅขžๆ—ฉๆœŸ README 5 ๆญฅ่กจๆ ผ๏ผŒๅฑ•็คบๅฆ‚ไฝ•ๅœจๅ‡ ๅˆ†้’Ÿๅ†…่ฎพ็ฝฎ้›ถๆˆๆœฌ AIใ€‚ -- **README: Free Transcription Combo** โ€”โ€” ๆ–ฐๅขž้ƒจๅˆ†๏ผŒไฝฟ็”จ Deepgram/AssemblyAI/Groq combo ๅปบ่ฎฎๅ’Œๆฏๆไพ›ๅ•†ๅ…่ดน็งฏๅˆ†่ฏฆๆƒ…ใ€‚ -- **providers.ts: hasFree ๆ ‡ๅฟ—** โ€”โ€” NVIDIA NIMใ€Cerebras ๅ’Œ Groq ๆ ‡่ฎฐ hasFree ๅพฝ็ซ ๅ’Œ freeNote๏ผŒ็”จไบŽๆไพ›ๅ•† UIใ€‚ -- **i18n: templateFreeStack ้”ฎ** โ€”โ€” Free Stack combo ๆจกๆฟ็ฟป่ฏ‘ๅนถๅŒๆญฅๅˆฐๆ‰€ๆœ‰ 30 ็ง่ฏญ่จ€ใ€‚ +- **Combos: Free Stack template** โ€” New 4th template "Free Stack ($0)" using round-robin across Kiro + Qoder + Qwen + Gemini CLI. Suggests the pre-built zero-cost combo on first use. +- **Media/Transcription: Deepgram as default** โ€” Deepgram (Nova 3, $200 free) is now the default transcription provider. AssemblyAI ($50 free) and Groq Whisper (free forever) shown with free credit badges. +- **README: "Start Free" section** โ€” New early-README 5-step table showing how to set up zero-cost AI in minutes. +- **README: Free Transcription Combo** โ€” New section with Deepgram/AssemblyAI/Groq combo suggestion and per-provider free credit details. +- **providers.ts: hasFree flag** โ€” NVIDIA NIM, Cerebras, and Groq marked with hasFree badge and freeNote for the providers UI. +- **i18n: templateFreeStack keys** โ€” Free Stack combo template translated and synced to all 30 languages. ## [2.3.16] - 2026-03-13 -### ๐Ÿ“– ๆ–‡ๆกฃ +### ๆ–‡ๆกฃ -- **README: 44+ ๆไพ›ๅ•†** โ€”โ€” ๅฐ†ๆ‰€ๆœ‰ 3 ๅค„ "36+ ๆไพ›ๅ•†" ๆ›ดๆ–ฐไธบ "44+"๏ผŒๅๆ˜ ๅฎž้™…ไปฃ็ ๅบ“่ฎกๆ•ฐ๏ผˆproviders.ts ไธญ 44 ไธชๆไพ›ๅ•†๏ผ‰ -- **README: ๆ–ฐ้ƒจๅˆ† "๐Ÿ†“ Free Models โ€” What You Actually Get"** โ€”โ€” ๆทปๅŠ ไบ† 7 ๆไพ›ๅ•†่กจๆ ผ๏ผŒไฝฟ็”จๆฏๆจกๅž‹้€Ÿ็Ž‡้™ๅˆถ๏ผšKiro๏ผˆ้€š่ฟ‡ AWS Builder ID ็š„ Claude ๆ— ้™๏ผ‰ใ€Qoder๏ผˆ5 ไธชๆจกๅž‹ๆ— ้™๏ผ‰ใ€Qwen๏ผˆ4 ไธชๆจกๅž‹ๆ— ้™๏ผ‰ใ€Gemini CLI๏ผˆ180K/ๆœˆ๏ผ‰ใ€NVIDIA NIM๏ผˆ~40 RPM ๆฐธไน…ๅผ€ๅ‘๏ผ‰ใ€Cerebras๏ผˆ1M tok/ๅคฉ / 60K TPM๏ผ‰ใ€Groq๏ผˆ30 RPM / 14.4K RPD๏ผ‰ใ€‚ๅŒ…ๅซ Ultimate Free Stack combo ๆŽจ่ใ€‚ -- **README: ๅฎšไปท่กจๆ›ดๆ–ฐ** โ€”โ€” ไธบ API KEY ๅฑ‚็บงๆทปๅŠ ไบ† Cerebras๏ผŒไฟฎๅค NVIDIA ไปŽ "1000 credits" ๅˆฐ "dev-forever free"๏ผŒๆ›ดๆ–ฐไบ† Qoder/Qwen ๆจกๅž‹่ฎกๆ•ฐๅ’Œๅ็งฐ -- **README: Qoder 8โ†’5 ๆจกๅž‹**๏ผˆๅ‘ฝๅ๏ผškimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2๏ผ‰ -- **README: Qwen 3โ†’4 ๆจกๅž‹**๏ผˆๅ‘ฝๅ๏ผšqwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model๏ผ‰ +- **README: 44+ Providers** โ€” Updated all 3 occurrences of "36+ providers" to "44+" reflecting the actual codebase count (44 providers in providers.ts) +- **README: New Section "๐Ÿ†“ Free Models โ€” What You Actually Get"** โ€” Added 7-provider table with per-model rate limits for: Kiro (Claude unlimited via AWS Builder ID), Qoder (5 models unlimited), Qwen (4 models unlimited), Gemini CLI (180K/mo), NVIDIA NIM (~40 RPM dev-forever), Cerebras (1M tok/day / 60K TPM), Groq (30 RPM / 14.4K RPD). Includes the \/usr/bin/bash Ultimate Free Stack combo recommendation. +- **README: Pricing Table Updated** โ€” Added Cerebras to API KEY tier, fixed NVIDIA from "1000 credits" to "dev-forever free", updated Qoder/Qwen model counts and names +- **README: Qoder 8โ†’5 models** (named: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2) +- **README: Qwen 3โ†’4 models** (named: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model) ## [2.3.15] - 2026-03-13 -### โœจ ๆ–ฐ็‰นๆ€ง +### ๅŠŸ่ƒฝ็‰น็‚น -- **Auto-Combo ไปช่กจ็›˜๏ผˆๅฑ‚็บงไผ˜ๅ…ˆ็บง๏ผ‰**๏ผšๅœจ `/dashboard/auto-combo` ๅ› ๅญๅˆ†่งฃๆ˜พ็คบไธญๆทปๅŠ ไบ† `๐Ÿท๏ธ Tier` ไฝœไธบ็ฌฌ 7 ไธช่ฏ„ๅˆ†ๅ› ๅญๆ ‡็ญพ โ€”โ€” ๆ‰€ๆœ‰ 7 ไธช Auto-Combo ่ฏ„ๅˆ†ๅ› ๅญ็Žฐๅœจๅฏ่งใ€‚ -- **i18n โ€” autoCombo ้ƒจๅˆ†**๏ผšไธบๆ‰€ๆœ‰ 30 ไธช่ฏญ่จ€ๆ–‡ไปถๆทปๅŠ ไบ† 20 ไธชๆ–ฐ็ฟป่ฏ‘้”ฎ๏ผŒ็”จไบŽ Auto-Combo ไปช่กจ็›˜๏ผˆ`title`ใ€`status`ใ€`modePack`ใ€`providerScores`ใ€`factorTierPriority` ็ญ‰๏ผ‰ใ€‚ +- **Auto-Combo Dashboard (Tier Priority)**: Added `๐Ÿท๏ธ Tier` as the 7th scoring factor label in the `/dashboard/auto-combo` factor breakdown display โ€” all 7 Auto-Combo scoring factors are now visible. +- **i18n โ€” autoCombo section**: Added 20 new translation keys for the Auto-Combo dashboard (`title`, `status`, `modePack`, `providerScores`, `factorTierPriority`, etc.) to all 30 language files. ## [2.3.14] - 2026-03-13 -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **Qoder OAuth (#339)**๏ผšๆขๅคไบ†ๆœ‰ๆ•ˆ็š„้ป˜่ฎค `clientSecret` โ€”โ€” ๆญคๅ‰ๆ˜ฏ็ฉบๅญ—็ฌฆไธฒ๏ผŒๅฏผ่‡ดๆฏๆฌก่ฟžๆŽฅๅฐ่ฏ•้ƒฝๅ‡บ็Žฐ "Bad client credentials"ใ€‚ๅ…ฌๅ…ฑๅ‡ญไฝ“็Žฐๅœจๆ˜ฏ้ป˜่ฎคๅ›ž้€€๏ผˆๅฏ้€š่ฟ‡ `QODER_OAUTH_CLIENT_SECRET` ็Žฏๅขƒๅ˜้‡่ฆ†็›–๏ผ‰ใ€‚ -- **MITM server not found (#335)**๏ผš`prepublish.mjs` ็Žฐๅœจๅœจๅคๅˆถๅˆฐ npm ๅŒ…ไน‹ๅ‰ไฝฟ็”จ `tsc` ๅฐ† `src/mitm/*.ts` ็ผ–่ฏ‘ไธบ JavaScriptใ€‚ๆญคๅ‰ๅชๅคๅˆถๅŽŸๅง‹ `.ts` ๆ–‡ไปถ โ€”โ€” ๆ„ๅ‘ณ็€ `server.js` ๅœจ npm/Volta ๅ…จๅฑ€ๅฎ‰่ฃ…ไธญไปŽๆœชๅญ˜ๅœจ่ฟ‡ใ€‚ -- **GeminiCLI missing projectId (#338)**๏ผšๅฝ“ๅญ˜ๅ‚จ็š„ๅ‡ญ่ฏไธญ็ผบๅฐ‘ `projectId` ๆ—ถ๏ผˆไพ‹ๅฆ‚ Docker ้‡ๅฏๅŽ๏ผ‰๏ผŒOmniRoute ็Žฐๅœจ่ฎฐๅฝ•่ญฆๅ‘Šๅนถๅฐ่ฏ•่ฏทๆฑ‚ โ€”โ€” ่ฟ”ๅ›žๆœ‰ๆ„ไน‰็š„ๆไพ›ๅ•†็ซฏ้”™่ฏฏ๏ผŒ่€Œไธๆ˜ฏ OmniRoute ๅดฉๆบƒใ€‚ -- **Electron ็‰ˆๆœฌไธๅŒน้… (#323)**๏ผšๅฐ† `electron/package.json` ็‰ˆๆœฌๅŒๆญฅๅˆฐ `2.3.13`๏ผˆๆญคๅ‰ๆ˜ฏ `2.0.13`๏ผ‰๏ผŒไฝฟๆกŒ้ขไบŒ่ฟ›ๅˆถ็‰ˆๆœฌไธŽ npm ๅŒ…ๅŒน้…ใ€‚ +- **Qoder OAuth (#339)**: Restored the valid default `clientSecret` โ€” was previously an empty string, causing "Bad client credentials" on every connect attempt. The public credential is now the default fallback (overridable via `QODER_OAUTH_CLIENT_SECRET` env var). +- **MITM server not found (#335)**: `prepublish.mjs` now compiles `src/mitm/*.ts` to JavaScript using `tsc` before copying to the npm bundle. Previously only raw `.ts` files were copied โ€” meaning `server.js` never existed in npm/Volta global installs. +- **GeminiCLI missing projectId (#338)**: Instead of throwing a hard 500 error when `projectId` is missing from stored credentials (e.g. after Docker restart), OmniRoute now logs a warning and attempts the request โ€” returning a meaningful provider-side error instead of an OmniRoute crash. +- **Electron version mismatch (#323)**: Synced `electron/package.json` version to `2.3.13` (was `2.0.13`) so the desktop binary version matches the npm package. -### โœจ ๆ–ฐๆจกๅž‹ (#334) +### โœจ New Models (#334) -- **Kiro**๏ผš`claude-sonnet-4`ใ€`claude-opus-4.6`ใ€`deepseek-v3.2`ใ€`minimax-m2.1`ใ€`qwen3-coder-next`ใ€`auto` -- **Codex**๏ผš`gpt5.4` +- **Kiro**: `claude-sonnet-4`, `claude-opus-4.6`, `deepseek-v3.2`, `minimax-m2.1`, `qwen3-coder-next`, `auto` +- **Codex**: `gpt5.4` -### ๐Ÿ”ง ๆ”น่ฟ› +### ๐Ÿ”ง Improvements -- **ๅฑ‚็บง่ฏ„ๅˆ†๏ผˆAPI + ้ชŒ่ฏ๏ผ‰**๏ผšไธบ `ScoringWeights` Zod schema ๅ’Œ `combos/auto` API ่ทฏ็”ฑๆทปๅŠ ไบ† `tierPriority`๏ผˆๆƒ้‡ `0.05`๏ผ‰โ€”โ€” ็ฌฌ 7 ไธช่ฏ„ๅˆ†ๅ› ๅญ็ŽฐๅœจๅฎŒๅ…จ่ขซ REST API ๆŽฅๅ—ๅนถๅœจ่พ“ๅ…ฅๆ—ถ้ชŒ่ฏใ€‚`stability` ๆƒ้‡ไปŽ `0.10` ่ฐƒๆ•ดๅˆฐ `0.05`๏ผŒไปฅไฟๆŒๆ€ปๅ’Œ = `1.0`ใ€‚ +- **Tier Scoring (API + Validation)**: Added `tierPriority` (weight `0.05`) to the `ScoringWeights` Zod schema and the `combos/auto` API route โ€” the 7th scoring factor is now fully accepted by the REST API and validated on input. `stability` weight adjusted from `0.10` to `0.05` to keep total sum = `1.0`. -### โœจ ๆ–ฐ็‰นๆ€ง +### โœจ New Features -- **ๅˆ†ๅฑ‚้…้ข่ฏ„ๅˆ†๏ผˆAuto-Combo๏ผ‰**๏ผšๆทปๅŠ ไบ† `tierPriority` ไฝœไธบ็ฌฌ 7 ไธช่ฏ„ๅˆ†ๅ› ๅญ โ€”โ€” ๅฝ“ๅ…ถไป–ๅ› ็ด ็›ธๅŒๆ—ถ๏ผŒ็Žฐๅœจไผ˜ๅ…ˆ้€‰ๆ‹ฉ Ultra/Pro ๅฑ‚็บง็š„่ดฆๆˆท๏ผŒ่€Œไธๆ˜ฏ Free ๅฑ‚็บงใ€‚`ProviderCandidate` ไธญๆ–ฐๅขžๅฏ้€‰ๅญ—ๆฎต `accountTier` ๅ’Œ `quotaResetIntervalSecs`ใ€‚ๆ‰€ๆœ‰ 4 ไธชๆจกๅผๅŒ…ๅทฒๆ›ดๆ–ฐ๏ผˆ`ship-fast`ใ€`cost-saver`ใ€`quality-first`ใ€`offline-friendly`๏ผ‰ใ€‚ -- **ๅฎถๆ—ๅ†…ๆจกๅž‹ๅ›ž้€€ (T5)**๏ผšๅฝ“ๆจกๅž‹ไธๅฏ็”จๆ—ถ๏ผˆ404/400/403๏ผ‰๏ผŒOmniRoute ็Žฐๅœจๅœจ่ฟ”ๅ›ž้”™่ฏฏไน‹ๅ‰่‡ชๅŠจๅ›ž้€€ๅˆฐๅŒๅฎถๆ—็š„ๅ…„ๅผŸๆจกๅž‹๏ผˆ`modelFamilyFallback.ts`๏ผ‰ใ€‚ -- **ๅฏ้…็ฝฎ็š„ API ๆกฅๆŽฅ่ถ…ๆ—ถ**๏ผš`API_BRIDGE_PROXY_TIMEOUT_MS` ็Žฏๅขƒๅ˜้‡ๅ…่ฎธๆ“ไฝœๅ‘˜่ฐƒๆ•ดไปฃ็†่ถ…ๆ—ถ๏ผˆ้ป˜่ฎค 30 ็ง’๏ผ‰ใ€‚ไฟฎๅคๆ…ข้€ŸไธŠๆธธๅ“ๅบ”็š„ 504 ้”™่ฏฏใ€‚๏ผˆ#332๏ผ‰ -- **Star History**๏ผšๅฐ†ๆ‰€ๆœ‰ 30 ไธช README ไธญ็š„ star-history.com ๅฐ้ƒจไปถๆ›ฟๆขไธบ starchart.cc๏ผˆ`?variant=adaptive`๏ผ‰โ€”โ€” ้€‚ๅบ”ๆต…่‰ฒ/ๆทฑ่‰ฒไธป้ข˜๏ผŒๅฎžๆ—ถๆ›ดๆ–ฐใ€‚ +- **Tiered Quota Scoring (Auto-Combo)**: Added `tierPriority` as a 7th scoring factor โ€” accounts with Ultra/Pro tiers are now preferred over Free tiers when other factors are equal. New optional fields `accountTier` and `quotaResetIntervalSecs` on `ProviderCandidate`. All 4 mode packs updated (`ship-fast`, `cost-saver`, `quality-first`, `offline-friendly`). +- **Intra-Family Model Fallback (T5)**: When a model is unavailable (404/400/403), OmniRoute now automatically falls back to sibling models from the same family before returning an error (`modelFamilyFallback.ts`). +- **Configurable API Bridge Timeout**: `API_BRIDGE_PROXY_TIMEOUT_MS` env var lets operators tune the proxy timeout (default 30s). Fixes 504 errors on slow upstream responses. (#332) +- **Star History**: Replaced star-history.com widget with starchart.cc (`?variant=adaptive`) in all 30 READMEs โ€” adapts to light/dark theme, real-time updates. -### ๐Ÿ› Bug ไฟฎๅค +### ๐Ÿ› Bug Fixes -- **่ฎค่ฏ โ€”โ€” ้ฆ–ๆฌกๅฏ†็ **๏ผš่ฎพ็ฝฎ้ฆ–ไธชไปช่กจ็›˜ๅฏ†็ ๆ—ถ็ŽฐๅœจๆŽฅๅ— `INITIAL_PASSWORD` ็Žฏๅขƒๅ˜้‡ใ€‚ไฝฟ็”จ `timingSafeEqual` ่ฟ›่กŒๆ’ๅฎšๆ—ถ้—ดๆฏ”่พƒ๏ผŒ้˜ฒๆญขๆ—ถๅบๆ”ปๅ‡ปใ€‚๏ผˆ#333๏ผ‰ -- **README ๆˆชๆ–ญ**๏ผšไฟฎๅคไบ† Troubleshooting ้ƒจๅˆ†็ผบๅคฑ็š„ `` ้—ญๅˆๆ ‡็ญพ๏ผŒ่ฏฅๆ ‡็ญพๅฏผ่‡ด GitHub ๅœๆญขๆธฒๆŸ“ๅ…ถไธ‹ๆ–น็š„ๆ‰€ๆœ‰ๅ†…ๅฎน๏ผˆๆŠ€ๆœฏๆ ˆใ€ๆ–‡ๆกฃใ€่ทฏ็บฟๅ›พใ€่ดก็Œฎ่€…๏ผ‰ใ€‚ -- **pnpm install**๏ผšไปŽ `package.json` ไธญ็งป้™คไบ†ๅ†—ไฝ™็š„ `@swc/helpers` ่ฆ†็›–๏ผŒ่ฏฅ่ฆ†็›–ไธŽ็›ดๆŽฅไพ่ต–ๅ†ฒ็ช๏ผŒๅฏผ่‡ด pnpm ๅ‡บ็Žฐ `EOVERRIDE` ้”™่ฏฏใ€‚ๆทปๅŠ ไบ† `pnpm.onlyBuiltDependencies` ้…็ฝฎใ€‚ -- **CLI ่ทฏๅพ„ๆณจๅ…ฅ (T12)**๏ผšๅœจ `cliRuntime.ts` ไธญๆทปๅŠ ไบ† `isSafePath()` ้ชŒ่ฏๅ™จ๏ผŒไปฅ้˜ปๆญข่ทฏๅพ„้ๅŽ†ๅ’Œ `CLI_*_BIN` ็Žฏๅขƒๅ˜้‡ไธญ็š„ shell ๅ…ƒๅญ—็ฌฆใ€‚ -- **CI**๏ผšๅœจ่ฆ†็›–็งป้™คๅŽ้‡ๆ–ฐ็”Ÿๆˆ `package-lock.json`๏ผŒไปฅไฟฎๅค GitHub Actions ไธญ็š„ `npm ci` ๅคฑ่ดฅใ€‚ +- **Auth โ€” First-time password**: `INITIAL_PASSWORD` env var is now accepted when setting the first dashboard password. Uses `timingSafeEqual` for constant-time comparison, preventing timing attacks. (#333) +- **README Truncation**: Fixed a missing `` closing tag in the Troubleshooting section that caused GitHub to stop rendering everything below it (Tech Stack, Docs, Roadmap, Contributors). +- **pnpm install**: Removed redundant `@swc/helpers` override from `package.json` that conflicted with the direct dependency, causing `EOVERRIDE` errors on pnpm. Added `pnpm.onlyBuiltDependencies` config. +- **CLI Path Injection (T12)**: Added `isSafePath()` validator in `cliRuntime.ts` to block path traversal and shell metacharacters in `CLI_*_BIN` env vars. +- **CI**: Regenerated `package-lock.json` after override removal to fix `npm ci` failures on GitHub Actions. -### ๐Ÿ”ง ๆ”น่ฟ› +### ๐Ÿ”ง Improvements -- **ๅ“ๅบ”ๆ ผๅผ (T1)**๏ผš`response_format`๏ผˆjson_schema/json_object๏ผ‰็Žฐๅœจไฝœไธบ็ณป็ปŸๆ็คบ่ฏๆณจๅ…ฅ Claude๏ผŒๅฎž็Žฐ็ป“ๆž„ๅŒ–่พ“ๅ‡บๅ…ผๅฎนๆ€งใ€‚ -- **429 ้‡่ฏ• (T2)**๏ผšURL ๅ†…้‡่ฏ•็”จไบŽ 429 ๅ“ๅบ”๏ผˆ2 ๆฌกๅฐ่ฏ•๏ผŒ2 ็ง’ๅปถ่ฟŸ๏ผ‰๏ผŒ็„ถๅŽๅ›ž้€€ๅˆฐไธ‹ไธ€ไธช URLใ€‚ -- **Gemini CLI ่ฏทๆฑ‚ๅคด (T3)**๏ผšๆทปๅŠ ไบ† `User-Agent` ๅ’Œ `X-Goog-Api-Client` ๆŒ‡็บน่ฏทๆฑ‚ๅคด๏ผŒ็”จไบŽ Gemini CLI ๅ…ผๅฎนๆ€งใ€‚ -- **ๅฎšไปท็›ฎๅฝ• (T9)**๏ผšๆทปๅŠ ไบ† `deepseek-3.1`ใ€`deepseek-3.2` ๅ’Œ `qwen3-coder-next` ๅฎšไปทๆก็›ฎใ€‚ +- **Response Format (T1)**: `response_format` (json_schema/json_object) now injected as a system prompt for Claude, enabling structured output compatibility. +- **429 Retry (T2)**: Intra-URL retry for 429 responses (2ร— attempts with 2s delay) before falling back to next URL. +- **Gemini CLI Headers (T3)**: Added `User-Agent` and `X-Goog-Api-Client` fingerprint headers for Gemini CLI compatibility. +- **Pricing Catalog (T9)**: Added `deepseek-3.1`, `deepseek-3.2`, and `qwen3-coder-next` pricing entries. -### ๐Ÿ“ ๆ–ฐๅขžๆ–‡ไปถ +### ๐Ÿ“ New Files -| ๆ–‡ไปถ | ็›ฎ็š„ | -| ------------------------------------------ | ---------------------------- | -| `open-sse/services/modelFamilyFallback.ts` | ๆจกๅž‹ๅฎถๆ—ๅฎšไน‰ๅ’Œๅฎถๆ—ๅ†…ๅ›ž้€€้€ป่พ‘ | +| File | Purpose | +| ------------------------------------------ | -------------------------------------------------------- | +| `open-sse/services/modelFamilyFallback.ts` | Model family definitions and intra-family fallback logic | -### ไฟฎๅค +### Fixed -- **KiloCode**๏ผškilocode ๅฅๅบทๆฃ€ๆŸฅ่ถ…ๆ—ถๅทฒๅœจ v2.3.11 ไฟฎๅค -- **OpenCode**๏ผšๅฐ† opencode ๆทปๅŠ ๅˆฐ cliRuntime ๆณจๅ†Œ่กจ๏ผŒไฝฟ็”จ 15 ็ง’ๅฅๅบทๆฃ€ๆŸฅ่ถ…ๆ—ถ -- **OpenClaw / Cursor**๏ผšๅฐ†ๅฅๅบทๆฃ€ๆŸฅ่ถ…ๆ—ถๅขžๅŠ ๅˆฐ 15 ็ง’๏ผŒ็”จไบŽๆ…ขๅฏๅŠจๅ˜ไฝ“ -- **VPS**๏ผšๅฎ‰่ฃ… droid ๅ’Œ openclaw npm ๅŒ…๏ผ›ไธบ kiro-cli ๆฟ€ๆดป CLI_EXTRA_PATHS -- **cliRuntime**๏ผšๆทปๅŠ  opencode ๅทฅๅ…ทๆณจๅ†ŒๅนถๅขžๅŠ  continue ็š„่ถ…ๆ—ถ +- **KiloCode**: kilocode healthcheck timeout already fixed in v2.3.11 +- **OpenCode**: Add opencode to cliRuntime registry with 15s healthcheck timeout +- **OpenClaw / Cursor**: Increase healthcheck timeout to 15s for slow-start variants +- **VPS**: Install droid and openclaw npm packages; activate CLI_EXTRA_PATHS for kiro-cli +- **cliRuntime**: Add opencode tool registration and increase timeout for continue ## [2.3.11] - 2026-03-12 -### ไฟฎๅค +### Fixed -- **KiloCode healthcheck**๏ผšๅฐ† `healthcheckTimeoutMs` ไปŽ 4000ms ๅขžๅŠ ๅˆฐ 15000ms โ€”โ€” kilocode ๅœจๅฏๅŠจๆ—ถๆธฒๆŸ“ ASCII ๆ ‡ๅฟ—ๆจชๅน…๏ผŒๅœจๆ…ข/ๅ†ทๅฏๅŠจ็Žฏๅขƒไธญๅฏผ่‡ด่™šๅ‡็š„ `healthcheck_failed` +- **KiloCode healthcheck**: Increase `healthcheckTimeoutMs` from 4000ms to 15000ms โ€” kilocode renders an ASCII logo banner on startup causing false `healthcheck_failed` on slow/cold-start environments ## [2.3.10] - 2026-03-12 -### ไฟฎๅค +### Fixed -- **Lint**๏ผšไฟฎๅค `check:any-budget:t11` ๅคฑ่ดฅ โ€”โ€” ๅœจ OAuthModal.tsx ไธญๅฐ† `as any` ๆ›ฟๆขไธบ `as Record`๏ผˆ3 ๅค„๏ผ‰ +- **Lint**: Fix `check:any-budget:t11` failure โ€” replace `as any` with `as Record` in OAuthModal.tsx (3 occurrences) ### Docs -- **CLI-TOOLS.md**๏ผšๆ‰€ๆœ‰ 11 ไธช CLI ๅทฅๅ…ท็š„ๅฎŒๆ•ดๆŒ‡ๅ—๏ผˆclaudeใ€codexใ€geminiใ€opencodeใ€clineใ€kilocodeใ€continueใ€kiro-cliใ€cursorใ€droidใ€openclaw๏ผ‰ -- **i18n**๏ผšCLI-TOOLS.md ๅŒๆญฅๅˆฐ 30 ็ง่ฏญ่จ€๏ผŒๅธฆ็ฟป่ฏ‘็š„ๆ ‡้ข˜ๅ’Œไป‹็ป +- **CLI-TOOLS.md**: Complete guide for all 11 CLI tools (claude, codex, gemini, opencode, cline, kilocode, continue, kiro-cli, cursor, droid, openclaw) +- **i18n**: CLI-TOOLS.md synced to 30 languages with translated title + intro ## [2.3.8] - 2026-03-12 @@ -2385,41 +2411,41 @@ OmniRoute ็Žฐๅœจๆฏ **24 ๅฐๆ—ถ**่‡ชๅŠจๅˆทๆ–ฐๅทฒ่ฟžๆŽฅๆไพ›ๅ•†็š„ๆจกๅž‹ๅˆ—่กจ ### Added -- **/v1/completions**๏ผšๆ–ฐๅขžไผ ็ปŸ OpenAI completions ็ซฏ็‚น โ€”โ€” ๆŽฅๅ— `prompt` ๅญ—็ฌฆไธฒๅ’Œ `messages` ๆ•ฐ็ป„๏ผŒ่‡ชๅŠจ่ง„่ŒƒๅŒ–ไธบ่Šๅคฉๆ ผๅผ -- **EndpointPage**๏ผš็Žฐๅœจๆ˜พ็คบๆ‰€ๆœ‰ 3 ็ง OpenAI ๅ…ผๅฎน็ซฏ็‚น็ฑปๅž‹๏ผšChat Completionsใ€Responses API ๅ’Œ Legacy Completions -- **i18n**๏ผšไธบ 30 ไธช่ฏญ่จ€ๆ–‡ไปถๆทปๅŠ ไบ† `completionsLegacy/completionsLegacyDesc` +- **/v1/completions**: New legacy OpenAI completions endpoint โ€” accepts both `prompt` string and `messages` array, normalizes to chat format automatically +- **EndpointPage**: Now shows all 3 OpenAI-compatible endpoint types: Chat Completions, Responses API, and Legacy Completions +- **i18n**: Added `completionsLegacy/completionsLegacyDesc` to 30 language files -### ไฟฎๅค +### Fixed -- **OAuthModal**๏ผšไฟฎๅคๆ‰€ๆœ‰ OAuth ่ฟžๆŽฅ้”™่ฏฏไธญๆ˜พ็คบ็š„ `[object Object]` โ€”โ€” ๆญฃ็กฎไปŽ้”™่ฏฏๅ“ๅบ”ๅฏน่ฑกไธญๆๅ– `.message`๏ผŒๅœจๆ‰€ๆœ‰ 3 ไธช `throw new Error(data.error)` ่ฐƒ็”จไธญ๏ผˆexchangeใ€device-codeใ€authorize๏ผ‰ -- ๅฝฑๅ“ Clineใ€Codexใ€GitHubใ€Qwenใ€Kiro ๅ’Œๆ‰€ๆœ‰ๅ…ถไป– OAuth ๆไพ›ๅ•† +- **OAuthModal**: Fix `[object Object]` displayed on all OAuth connection errors โ€” properly extract `.message` from error response objects in all 3 `throw new Error(data.error)` calls (exchange, device-code, authorize) +- Affects Cline, Codex, GitHub, Qwen, Kiro, and all other OAuth providers ## [2.3.7] - 2026-03-12 -### ไฟฎๅค +### Fixed -- **Cline OAuth**๏ผšๅœจ base64 ่งฃ็ ไน‹ๅ‰ๆทปๅŠ  `decodeURIComponent`๏ผŒไปฅไพฟๆญฃ็กฎ่งฃๆžๆฅ่‡ชๅ›ž่ฐƒ URL ็š„ URL ็ผ–็ ่ฎค่ฏ็ ๏ผŒไฟฎๅค่ฟœ็จ‹๏ผˆLAN IP๏ผ‰่ฎพ็ฝฎไธญ็š„ "invalid or expired ๆŽˆๆƒ code" ้”™่ฏฏ -- **Cline OAuth**๏ผš`mapTokens` ็Žฐๅœจๅกซๅ…… `name = firstName + lastName || email`๏ผŒไฝฟ Cline ่ดฆๆˆทๆ˜พ็คบ็œŸๅฎž็”จๆˆทๅ๏ผŒ่€Œไธๆ˜ฏ "Account #ID" -- **OAuth ่ดฆๆˆทๅ็งฐ**๏ผšๆ‰€ๆœ‰ OAuth ไบคๆขๆต็จ‹๏ผˆexchangeใ€pollใ€poll-callback๏ผ‰็Žฐๅœจๅœจๅ็งฐ็ผบๅคฑๆ—ถ่ง„่ŒƒๅŒ– `name = email`๏ผŒไฝฟๆฏไธช OAuth ่ดฆๆˆทๅœจๆไพ›ๅ•†ไปช่กจ็›˜ไธŠๆ˜พ็คบๅ…ถ็”ตๅญ้‚ฎไปถไฝœไธบๆ˜พ็คบๆ ‡็ญพ -- **OAuth ่ดฆๆˆทๅ็งฐ**๏ผš็งป้™คไบ† `db/providers.ts` ไธญ้กบๅบ็š„ "Account N" ๅ›ž้€€ โ€”โ€” ๆฒกๆœ‰็”ตๅญ้‚ฎไปถ/ๅ็งฐ็š„่ดฆๆˆท็Žฐๅœจไฝฟ็”จๅŸบไบŽ็จณๅฎš ID ็š„ๆ ‡็ญพ๏ผŒ้€š่ฟ‡ `getAccountDisplayName()`๏ผŒ่€Œไธๆ˜ฏๅˆ ้™ค่ดฆๆˆทๆ—ถไผšๅ˜ๅŒ–็š„้กบๅบๅท +- **Cline OAuth**: Add `decodeURIComponent` before base64 decode so URL-encoded auth codes from the callback URL are parsed correctly, fixing "invalid or expired authorization code" errors on remote (LAN IP) setups +- **Cline OAuth**: `mapTokens` now populates `name = firstName + lastName || email` so Cline accounts show real user names instead of "Account #ID" +- **OAuth account names**: All OAuth exchange flows (exchange, poll, poll-callback) now normalize `name = email` when name is missing, so every OAuth account shows its email as the display label in the Providers dashboard +- **OAuth account names**: Removed sequential "Account N" fallback in `db/providers.ts` โ€” accounts with no email/name now use a stable ID-based label via `getAccountDisplayName()` instead of a sequential number that changes when accounts are deleted ## [2.3.6] - 2026-03-12 -### ไฟฎๅค +### Fixed -- **Provider test batch**๏ผšไฟฎๅคไบ† Zod schema ไปฅๆŽฅๅ— `providerId: null`๏ผˆๅ‰็ซฏไธบ้žๆไพ›ๅ•†ๆจกๅผๅ‘้€ null๏ผ‰๏ผ›ๆญคๅ‰ๅฏนๆ‰€ๆœ‰ๆ‰น้‡ๆต‹่ฏ•้”™่ฏฏๅœฐ่ฟ”ๅ›ž "Invalid ่ฏทๆฑ‚" -- **Provider test modal**๏ผš้€š่ฟ‡ๅœจ `setTestResults` ๅ’Œ `ProviderTestResultsView` ไธญๆธฒๆŸ“ไน‹ๅ‰ๅฐ† API ้”™่ฏฏๅฏน่ฑก่ง„่ŒƒๅŒ–ไธบๅญ—็ฌฆไธฒ๏ผŒไฟฎๅคไบ† `[object Object]` ๆ˜พ็คบ -- **i18n**๏ผšไธบ `en.json` ๆทปๅŠ ไบ†็ผบๅคฑ็š„้”ฎ `cliTools.toolDescriptions.opencode`ใ€`cliTools.toolDescriptions.kiro`ใ€`cliTools.guides.opencode`ใ€`cliTools.guides.kiro` -- **i18n**๏ผšๅœจๆ‰€ๆœ‰ 29 ไธช้ž่‹ฑ่ฏญ่ฏญ่จ€ๆ–‡ไปถไธญๅŒๆญฅไบ† 1111 ไธช็ผบๅคฑ็š„้”ฎ๏ผŒไฝฟ็”จ่‹ฑ่ฏญๅ€ผไฝœไธบๅ›ž้€€ +- **Provider test batch**: Fixed Zod schema to accept `providerId: null` (frontend sends null for non-provider modes); was incorrectly returning "Invalid request" for all batch tests +- **Provider test modal**: Fixed `[object Object]` display by normalizing API error objects to strings before rendering in `setTestResults` and `ProviderTestResultsView` +- **i18n**: Added missing keys `cliTools.toolDescriptions.opencode`, `cliTools.toolDescriptions.kiro`, `cliTools.guides.opencode`, `cliTools.guides.kiro` to `en.json` +- **i18n**: Synchronized 1111 missing keys across all 29 non-English language files using English values as fallbacks ## [2.3.5] - 2026-03-11 -### ไฟฎๅค +### Fixed -- **@swc/helpers**๏ผšๆทปๅŠ ไบ†ๆฐธไน…็š„ `postinstall` ไฟฎๅค๏ผŒๅฐ† `@swc/helpers` ๅคๅˆถๅˆฐ็‹ฌ็ซ‹ๅบ”็”จ็š„ `node_modules` ไธญ โ€”โ€” ้˜ฒๆญขๅ…จๅฑ€ npm ๅฎ‰่ฃ…ไธญ็š„ MODULE_NOT_FOUND ๅดฉๆบƒ +- **@swc/helpers**: Added permanent `postinstall` fix to copy `@swc/helpers` into the standalone app's `node_modules` โ€” prevents MODULE_NOT_FOUND crash on global npm installs ## [2.3.4] - 2026-03-10 ### Added -- ๅคšไธชๆไพ›ๅ•†้›†ๆˆๅ’Œไปช่กจ็›˜ๆ”น่ฟ› +- Multiple provider integrations and dashboard improvements diff --git a/docs/i18n/zh-CN/CLI-TOOLS.md b/docs/i18n/zh-CN/CLI-TOOLS.md deleted file mode 100644 index 2cccb1f5c2..0000000000 --- a/docs/i18n/zh-CN/CLI-TOOLS.md +++ /dev/null @@ -1,344 +0,0 @@ -๐ŸŒ **่ฏญ่จ€:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CLI-TOOLS.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CLI-TOOLS.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CLI-TOOLS.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CLI-TOOLS.md) - -# CLI ๅทฅๅ…ท้…็ฝฎๆŒ‡ๅ— โ€” OmniRoute - -ๆœฌๆŒ‡ๅ—่ฏดๆ˜Žๅฆ‚ไฝ•ๅฎ‰่ฃ…ๅ’Œ้…็ฝฎๆ‰€ๆœ‰ๆ”ฏๆŒ็š„ AI ็ผ–็จ‹ CLI ๅทฅๅ…ท๏ผŒไปฅไฝฟ็”จ **OmniRoute** ไฝœไธบ็ปŸไธ€ๅŽ็ซฏ๏ผŒไธบๆ‚จๆไพ›้›†ไธญๅŒ–็š„ๅฏ†้’ฅ็ฎก็†ใ€ๆˆๆœฌ่ทŸ่ธชใ€ๆจกๅž‹ๅˆ‡ๆขไปฅๅŠๆ‰€ๆœ‰ๅทฅๅ…ท็š„่ฏทๆฑ‚ๆ—ฅๅฟ—่ฎฐๅฝ•ใ€‚ - ---- - -## ๅทฅไฝœๅŽŸ็† - -``` -Claude / Codex / OpenCode / Cline / KiloCode / Continue / Kiro / Cursor / Copilot - โ”‚ - โ–ผ (ๆ‰€ๆœ‰ๅทฅๅ…ทๆŒ‡ๅ‘ OmniRoute) - http://YOUR_SERVER:20128/v1 - โ”‚ - โ–ผ (OmniRoute ่ทฏ็”ฑๅˆฐๆญฃ็กฎ็š„ๆœๅŠกๅ•†) - Anthropic / OpenAI / Gemini / DeepSeek / Groq / Mistral / ... -``` - -**ไผ˜ๅŠฟ:** - -- ไธ€ไธช API ๅฏ†้’ฅ็ฎก็†ๆ‰€ๆœ‰ๅทฅๅ…ท -- ๅœจไปช่กจ็›˜ไธญ่ทจๆ‰€ๆœ‰ CLI ่ทŸ่ธชๆˆๆœฌ -- ๆ— ้œ€้‡ๆ–ฐ้…็ฝฎๆฏไธชๅทฅๅ…ทๅณๅฏๅˆ‡ๆขๆจกๅž‹ -- ๆœฌๅœฐๅ’Œ่ฟœ็จ‹ๆœๅŠกๅ™จ (VPS) ๅ‡ๅฏไฝฟ็”จ - ---- - -## ๆ”ฏๆŒ็š„ๅทฅๅ…ท๏ผˆไปฅไปช่กจ็›˜ไธบๅ‡†๏ผ‰ - -ไปช่กจ็›˜ไธญ `/dashboard/cli-tools` ็š„ๅก็‰‡็”ฑ `src/shared/constants/cliTools.ts` ็”Ÿๆˆใ€‚ -ๅฝ“ๅ‰ๅˆ—่กจ (v3.0.0-rc.16): - -| ๅทฅๅ…ท | ID | ๅ‘ฝไปค | ้…็ฝฎๆจกๅผ | ๅฎ‰่ฃ…ๆ–นๅผ | -| ----------------- | ------------- | ------------ | -------- | ------------ | -| **Claude Code** | `claude` | `claude` | env | npm | -| **OpenAI Codex** | `codex` | `codex` | custom | npm | -| **Factory Droid** | `droid` | `droid` | custom | ๅ†…็ฝฎ/CLI | -| **OpenClaw** | `openclaw` | `openclaw` | custom | ๅ†…็ฝฎ/CLI | -| **Cursor** | `cursor` | app | guide | ๆกŒ้ขๅบ”็”จ | -| **Cline** | `cline` | `cline` | custom | npm | -| **Kilo Code** | `kilo` | `kilocode` | custom | npm | -| **Continue** | `continue` | extension | guide | VS Code | -| **Antigravity** | `antigravity` | internal | mitm | OmniRoute | -| **GitHub Copilot**| `copilot` | extension | custom | VS Code | -| **OpenCode** | `opencode` | `opencode` | guide | npm | -| **Kiro AI** | `kiro` | app/cli | mitm | ๆกŒ้ข/CLI | - -### CLI ๆŒ‡็บนๅŒๆญฅ๏ผˆไปฃ็† + ่ฎพ็ฝฎ๏ผ‰ - -`/dashboard/agents` ๅ’Œ `Settings > CLI Fingerprint` ไฝฟ็”จ `src/shared/constants/cliCompatProviders.ts`ใ€‚ -่ฟ™็กฎไฟๆœๅŠกๅ•† ID ไธŽ CLI ๅก็‰‡ๅ’Œๆ—ง็‰ˆ ID ไฟๆŒไธ€่‡ดใ€‚ - -| CLI ID | ๆŒ‡็บนๆœๅŠกๅ•† ID | -| ------ | ------------- | -| `kilo` | `kilocode` | -| `copilot` | `github` | -| `claude` / `codex` / `antigravity` / `kiro` / `cursor` / `cline` / `opencode` / `droid` / `openclaw` | ็›ธๅŒ ID | - -ไธบๅ…ผๅฎนๆ€งไฟ็•™็š„ๆ—ง็‰ˆ ID๏ผš`copilot`ใ€`kimi-coding`ใ€`qwen`ใ€‚ - ---- - -## ็ฌฌ 1 ๆญฅ โ€” ่Žทๅ– OmniRoute API ๅฏ†้’ฅ - -1. ๆ‰“ๅผ€ OmniRoute ไปช่กจ็›˜ โ†’ **API Manager** (`/dashboard/api-manager`) -2. ็‚นๅ‡ป **Create API Key** -3. ๅ‘ฝๅ๏ผˆไพ‹ๅฆ‚ `cli-tools`๏ผ‰ๅนถ้€‰ๆ‹ฉๆ‰€ๆœ‰ๆƒ้™ -4. ๅคๅˆถๅฏ†้’ฅ โ€” ไธ‹้ข็š„ๆฏไธช CLI ้ƒฝ้œ€่ฆไฝฟ็”จ - -> ๅฏ†้’ฅๆ ผๅผ็ฑปไผผ๏ผš`sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` - ---- - -## ็ฌฌ 2 ๆญฅ โ€” ๅฎ‰่ฃ… CLI ๅทฅๅ…ท - -ๆ‰€ๆœ‰ๅŸบไบŽ npm ็š„ๅทฅๅ…ท้œ€่ฆ Node.js 18+๏ผš - -```bash -# Claude Code (Anthropic) -npm install -g @anthropic-ai/claude-code - -# OpenAI Codex -npm install -g @openai/codex - -# OpenCode -npm install -g opencode-ai - -# Cline -npm install -g cline - -# KiloCode -npm install -g kilocode - -# Kiro CLI (Amazon โ€” ้œ€่ฆ curl + unzip) -apt-get install -y unzip # Debian/Ubuntu -curl -fsSL https://cli.kiro.dev/install | bash -export PATH="$HOME/.local/bin:$PATH" # ๆทปๅŠ ๅˆฐ ~/.bashrc -``` - -**้ชŒ่ฏ:** - -```bash -claude --version # 2.x.x -codex --version # 0.x.x -opencode --version # x.x.x -cline --version # 2.x.x -kilocode --version # x.x.x (ๆˆ–: kilo --version) -kiro-cli --version # 1.x.x -``` - ---- - -## ็ฌฌ 3 ๆญฅ โ€” ่ฎพ็ฝฎๅ…จๅฑ€็Žฏๅขƒๅ˜้‡ - -ๆทปๅŠ ๅˆฐ `~/.bashrc`๏ผˆๆˆ– `~/.zshrc`๏ผ‰๏ผŒ็„ถๅŽ่ฟ่กŒ `source ~/.bashrc`๏ผš - -```bash -# OmniRoute ็ปŸไธ€็ซฏ็‚น -export OPENAI_BASE_URL="http://localhost:20128/v1" -export OPENAI_API_KEY="sk-your-omniroute-key" -export ANTHROPIC_BASE_URL="http://localhost:20128/v1" -export ANTHROPIC_API_KEY="sk-your-omniroute-key" -export GEMINI_BASE_URL="http://localhost:20128/v1" -export GEMINI_API_KEY="sk-your-omniroute-key" -``` - -> ๅฏนไบŽ**่ฟœ็จ‹ๆœๅŠกๅ™จ**๏ผŒๅฐ† `localhost:20128` ๆ›ฟๆขไธบๆœๅŠกๅ™จ IP ๆˆ–ๅŸŸๅ๏ผŒ -> ไพ‹ๅฆ‚ `http://192.168.0.15:20128`ใ€‚ - ---- - -## ็ฌฌ 4 ๆญฅ โ€” ้…็ฝฎๅ„ๅทฅๅ…ท - -### Claude Code - -```bash -# ้€š่ฟ‡ CLI: -claude config set --global api-base-url http://localhost:20128/v1 - -# ๆˆ–ๅˆ›ๅปบ ~/.claude/settings.json: -mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF -{ - "apiBaseUrl": "http://localhost:20128/v1", - "apiKey": "sk-your-omniroute-key" -} -EOF -``` - -**ๆต‹่ฏ•:** `claude "say hello"` - ---- - -### OpenAI Codex - -```bash -mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF -model: auto -apiKey: sk-your-omniroute-key -apiBaseUrl: http://localhost:20128/v1 -EOF -``` - -**ๆต‹่ฏ•:** `codex "what is 2+2?"` - ---- - -### OpenCode - -```bash -mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF -[provider.openai] -base_url = "http://localhost:20128/v1" -api_key = "sk-your-omniroute-key" -EOF -``` - -**ๆต‹่ฏ•:** `opencode` - ---- - -### Cline (CLI ๆˆ– VS Code) - -**CLI ๆจกๅผ:** - -```bash -mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF -{ - "apiProvider": "openai", - "openAiBaseUrl": "http://localhost:20128/v1", - "openAiApiKey": "sk-your-omniroute-key" -} -EOF -``` - -**VS Code ๆจกๅผ:** -Cline ๆ‰ฉๅฑ•่ฎพ็ฝฎ โ†’ API Provider: `OpenAI Compatible` โ†’ Base URL: `http://localhost:20128/v1` - -ๆˆ–ไฝฟ็”จ OmniRoute ไปช่กจ็›˜ โ†’ **CLI Tools โ†’ Cline โ†’ Apply Config**ใ€‚ - ---- - -### KiloCode (CLI ๆˆ– VS Code) - -**CLI ๆจกๅผ:** - -```bash -kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key -``` - -**VS Code ่ฎพ็ฝฎ:** - -```json -{ - "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", - "kilo-code.apiKey": "sk-your-omniroute-key" -} -``` - -ๆˆ–ไฝฟ็”จ OmniRoute ไปช่กจ็›˜ โ†’ **CLI Tools โ†’ KiloCode โ†’ Apply Config**ใ€‚ - ---- - -### Continue (VS Code ๆ‰ฉๅฑ•) - -็ผ–่พ‘ `~/.continue/config.yaml`: - -```yaml -models: - - name: OmniRoute - provider: openai - model: auto - apiBase: http://localhost:20128/v1 - apiKey: sk-your-omniroute-key - default: true -``` - -็ผ–่พ‘ๅŽ้‡ๅฏ VS Codeใ€‚ - ---- - -### Kiro CLI (Amazon) - -```bash -# ็™ปๅฝ•ๆ‚จ็š„ AWS/Kiro ่ดฆๆˆท: -kiro-cli login - -# CLI ไฝฟ็”จ่‡ชๆœ‰่ฎค่ฏ โ€” Kiro CLI ๆœฌ่บซไธ้œ€่ฆ OmniRoute ไฝœไธบๅŽ็ซฏใ€‚ -# ๅฐ† kiro-cli ไธŽๅ…ถไป–ๅทฅๅ…ท็š„ OmniRoute ไธ€่ตทไฝฟ็”จใ€‚ -kiro-cli status -``` - ---- - -### Cursor (ๆกŒ้ขๅบ”็”จ) - -> **ๆณจๆ„:** Cursor ้€š่ฟ‡ๅ…ถไบ‘็ซฏ่ทฏ็”ฑ่ฏทๆฑ‚ใ€‚ๅฏนไบŽ OmniRoute ้›†ๆˆ๏ผŒ -> ๅœจ OmniRoute Settings ไธญๅฏ็”จ **Cloud Endpoint** ๅนถไฝฟ็”จๆ‚จ็š„ๅ…ฌๅ…ฑๅŸŸๅ URLใ€‚ - -้€š่ฟ‡ GUI: **Settings โ†’ Models โ†’ OpenAI API Key** - -- Base URL: `https://your-domain.com/v1` -- API Key: ๆ‚จ็š„ OmniRoute ๅฏ†้’ฅ - ---- - -## ไปช่กจ็›˜่‡ชๅŠจ้…็ฝฎ - -OmniRoute ไปช่กจ็›˜ๅฏ่‡ชๅŠจ้…็ฝฎๅคงๅคšๆ•ฐๅทฅๅ…ท๏ผš - -1. ๅ‰ๅพ€ `http://localhost:20128/dashboard/cli-tools` -2. ๅฑ•ๅผ€ไปปๆ„ๅทฅๅ…ทๅก็‰‡ -3. ไปŽไธ‹ๆ‹‰่œๅ•้€‰ๆ‹ฉๆ‚จ็š„ API ๅฏ†้’ฅ -4. ็‚นๅ‡ป **Apply Config**๏ผˆๅฆ‚ๆžœๆฃ€ๆต‹ๅˆฐๅทฅๅ…ทๅทฒๅฎ‰่ฃ…๏ผ‰ -5. ๆˆ–ๆ‰‹ๅŠจๅคๅˆถ็”Ÿๆˆ็š„้…็ฝฎ็‰‡ๆฎต - ---- - -## ๅ†…็ฝฎไปฃ็†๏ผšDroid & OpenClaw - -**Droid** ๅ’Œ **OpenClaw** ๆ˜ฏ็›ดๆŽฅๅ†…็ฝฎไบŽ OmniRoute ็š„ AI ไปฃ็† โ€” ๆ— ้œ€ๅฎ‰่ฃ…ใ€‚ -ๅฎƒไปฌไฝœไธบๅ†…้ƒจ่ทฏ็”ฑ่ฟ่กŒ๏ผŒ่‡ชๅŠจไฝฟ็”จ OmniRoute ็š„ๆจกๅž‹่ทฏ็”ฑใ€‚ - -- ่ฎฟ้—ฎ๏ผš`http://localhost:20128/dashboard/agents` -- ้…็ฝฎ๏ผšไธŽๆ‰€ๆœ‰ๅ…ถไป–ๅทฅๅ…ทไฝฟ็”จ็›ธๅŒ็š„็ป„ๅˆๅ’ŒๆœๅŠกๅ•† -- ๆ— ้œ€ API ๅฏ†้’ฅๆˆ– CLI ๅฎ‰่ฃ… - ---- - -## ๅฏ็”จ API ็ซฏ็‚น - -| ็ซฏ็‚น | ๆ่ฟฐ | ็”จ้€” | -| -------------------------- | ------------------------ | -------------------------- | -| `/v1/chat/completions` | ๆ ‡ๅ‡†่Šๅคฉ๏ผˆๆ‰€ๆœ‰ๆœๅŠกๅ•†๏ผ‰ | ๆ‰€ๆœ‰็Žฐไปฃๅทฅๅ…ท | -| `/v1/responses` | Responses API๏ผˆOpenAI ๆ ผๅผ๏ผ‰| Codexใ€ไปฃ็†ๅทฅไฝœๆต | -| `/v1/completions` | ๆ—ง็‰ˆๆ–‡ๆœฌ่กฅๅ…จ | ไฝฟ็”จ `prompt:` ็š„ๆ—งๅทฅๅ…ท | -| `/v1/embeddings` | ๆ–‡ๆœฌๅตŒๅ…ฅ | RAGใ€ๆœ็ดข | -| `/v1/images/generations` | ๅ›พๅƒ็”Ÿๆˆ | DALL-Eใ€Flux ็ญ‰ | -| `/v1/audio/speech` | ๆ–‡ๆœฌ่ฝฌ่ฏญ้Ÿณ | ElevenLabsใ€OpenAI TTS | -| `/v1/audio/transcriptions` | ่ฏญ้Ÿณ่ฝฌๆ–‡ๅญ— | Deepgramใ€AssemblyAI | - ---- - -## ๆ•…้šœๆŽ’้™ค - -| ้”™่ฏฏ | ๅŽŸๅ›  | ่งฃๅ†ณๆ–นๆกˆ | -| ------------------------- | --------------------- | ------------------------------------------ | -| `Connection refused` | OmniRoute ๆœช่ฟ่กŒ | `pm2 start omniroute` | -| `401 Unauthorized` | API ๅฏ†้’ฅ้”™่ฏฏ | ๅœจ `/dashboard/api-manager` ๆฃ€ๆŸฅ | -| `No combo configured` | ๆ— ๆดปๅŠจ่ทฏ็”ฑ็ป„ๅˆ | ๅœจ `/dashboard/combos` ่ฎพ็ฝฎ | -| `invalid model` | ๆจกๅž‹ไธๅœจ็›ฎๅฝ•ไธญ | ไฝฟ็”จ `auto` ๆˆ–ๆฃ€ๆŸฅ `/dashboard/providers` | -| CLI ๆ˜พ็คบ "not installed" | ไบŒ่ฟ›ๅˆถๆ–‡ไปถไธๅœจ PATH ไธญ| ๆฃ€ๆŸฅ `which ` | -| `kiro-cli: not found` | ไธๅœจ PATH ไธญ | `export PATH="$HOME/.local/bin:$PATH"` | - ---- - -## ๅฟซ้€Ÿ่ฎพ็ฝฎ่„šๆœฌ๏ผˆไธ€ๆกๅ‘ฝไปค๏ผ‰ - -```bash -# ๅฎ‰่ฃ…ๆ‰€ๆœ‰ CLI ๅนถไธบ OmniRoute ้…็ฝฎ๏ผˆๆ›ฟๆขไธบๆ‚จ็š„ๅฏ†้’ฅๅ’ŒๆœๅŠกๅ™จ URL๏ผ‰ -OMNIROUTE_URL="http://localhost:20128/v1" -OMNIROUTE_KEY="sk-your-omniroute-key" - -npm install -g @anthropic-ai/claude-code @openai/codex opencode-ai cline kilocode - -# Kiro CLI -apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash - -# ๅ†™ๅ…ฅ้…็ฝฎ -mkdir -p ~/.claude ~/.codex ~/.config/opencode ~/.continue - -cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" -cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" -cat >> ~/.bashrc << EOF -export OPENAI_BASE_URL="$OMNIROUTE_URL" -export OPENAI_API_KEY="$OMNIROUTE_KEY" -export ANTHROPIC_BASE_URL="$OMNIROUTE_URL" -export ANTHROPIC_API_KEY="$OMNIROUTE_KEY" -EOF - -source ~/.bashrc -echo "โœ… ๆ‰€ๆœ‰ CLI ๅทฒๅฎ‰่ฃ…ๅนถ้…็ฝฎไธบไฝฟ็”จ OmniRoute" -``` diff --git a/docs/i18n/zh-CN/CODEBASE_DOCUMENTATION.md b/docs/i18n/zh-CN/CODEBASE_DOCUMENTATION.md deleted file mode 100644 index 9aef6ea9b1..0000000000 --- a/docs/i18n/zh-CN/CODEBASE_DOCUMENTATION.md +++ /dev/null @@ -1,589 +0,0 @@ -# OmniRoute โ€” ไปฃ็ ๅบ“ๆ–‡ๆกฃ - -๐ŸŒ **่ฏญ่จ€:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](../pt-BR/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](../es/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](../fr/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](../it/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](../ru/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](../zh-CN/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](../de/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](../in/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](../th/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](../uk-UA/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](../ar/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](../ja/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](../vi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](../bg/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](../da/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](../fi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](../he/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](../hu/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](../id/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](../ko/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](../ms/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](../nl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](../no/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](../pt/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](../ro/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](../pl/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](../sk/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](../sv/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](../phi/CODEBASE_DOCUMENTATION.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](../cs/CODEBASE_DOCUMENTATION.md) - -> **OmniRoute** ๅคšๆไพ›ๅ•† AI ไปฃ็†่ทฏ็”ฑๅ™จ็š„ๅ…จ้ขๆ–ฐๆ‰‹ๅ‹ๅฅฝๆŒ‡ๅ—ใ€‚ - ---- - -## 1. OmniRoute ๆ˜ฏไป€ไนˆ๏ผŸ - -OmniRoute ๆ˜ฏไธ€ไธช**ไปฃ็†่ทฏ็”ฑๅ™จ**๏ผŒไฝไบŽ AI ๅฎขๆˆท็ซฏ๏ผˆClaude CLIใ€Codexใ€Cursor IDE ็ญ‰๏ผ‰ๅ’Œ AI ๆไพ›ๅ•†๏ผˆAnthropicใ€Googleใ€OpenAIใ€AWSใ€GitHub ็ญ‰๏ผ‰ไน‹้—ดใ€‚ๅฎƒ่งฃๅ†ณไบ†ไธ€ไธชๅคง้—ฎ้ข˜๏ผš - -> **ไธๅŒ็š„ AI ๅฎขๆˆท็ซฏไฝฟ็”จไธๅŒ็š„"่ฏญ่จ€"๏ผˆAPI ๆ ผๅผ๏ผ‰๏ผŒไธๅŒ็š„ AI ๆไพ›ๅ•†ไนŸๆœŸๆœ›ไธๅŒ็š„"่ฏญ่จ€"ใ€‚** OmniRoute ่‡ชๅŠจๅœจๅฎƒไปฌไน‹้—ด่ฟ›่กŒ็ฟป่ฏ‘ใ€‚ - -ๅฏไปฅๆŠŠๅฎƒๆƒณ่ฑกๆˆ่”ๅˆๅ›ฝ็š„ไธ‡่ƒฝ็ฟป่ฏ‘ๅ‘˜ โ€” ไปปไฝ•ไปฃ่กจ้ƒฝๅฏไปฅ่ฏดไปปไฝ•่ฏญ่จ€๏ผŒ็ฟป่ฏ‘ๅ‘˜ไผšไธบไปปไฝ•ๅ…ถไป–ไปฃ่กจ่ฟ›่กŒ่ฝฌๆขใ€‚ - ---- - -## 2. ๆžถๆž„ๆฆ‚่ฟฐ - -```mermaid -graph LR - subgraph Clients[ๅฎขๆˆท็ซฏ] - A[Claude CLI] - B[Codex] - C[Cursor IDE] - D[OpenAI ๅ…ผๅฎน] - end - - subgraph omniroute[OmniRoute] - E[ๅค„็†ๅ™จๅฑ‚] - F[็ฟป่ฏ‘ๅ™จๅฑ‚] - G[ๆ‰ง่กŒๅ™จๅฑ‚] - H[ๆœๅŠกๅฑ‚] - 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 -``` - -### ๆ ธๅฟƒๅŽŸๅˆ™๏ผšไธญๅฟƒ่พๅฐ„็ฟป่ฏ‘ - -ๆ‰€ๆœ‰ๆ ผๅผ็ฟป่ฏ‘้ƒฝ้€š่ฟ‡ **OpenAI ๆ ผๅผไฝœไธบไธญๅฟƒ** ่ฟ›่กŒ๏ผš - -``` -ๅฎขๆˆท็ซฏๆ ผๅผ โ†’ [OpenAI ไธญๅฟƒ] โ†’ ๆไพ›ๅ•†ๆ ผๅผ ๏ผˆ่ฏทๆฑ‚๏ผ‰ -ๆไพ›ๅ•†ๆ ผๅผ โ†’ [OpenAI ไธญๅฟƒ] โ†’ ๅฎขๆˆท็ซฏๆ ผๅผ ๏ผˆๅ“ๅบ”๏ผ‰ -``` - -่ฟ™ๆ„ๅ‘ณ็€ไฝ ๅช้œ€่ฆ **N ไธช็ฟป่ฏ‘ๅ™จ**๏ผˆๆฏ็งๆ ผๅผไธ€ไธช๏ผ‰่€Œไธๆ˜ฏ **Nยฒ**๏ผˆๆฏๅฏนๆ ผๅผไธ€ไธช๏ผ‰ใ€‚ - ---- - -## 3. ้กน็›ฎ็ป“ๆž„ - -``` -omniroute/ -โ”œโ”€โ”€ open-sse/ โ† ๆ ธๅฟƒไปฃ็†ๅบ“๏ผˆๅฏ็งปๆค๏ผŒๆก†ๆžถๆ— ๅ…ณ๏ผ‰ -โ”‚ โ”œโ”€โ”€ index.js โ† ไธปๅ…ฅๅฃ็‚น๏ผŒๅฏผๅ‡บๆ‰€ๆœ‰ๅ†…ๅฎน -โ”‚ โ”œโ”€โ”€ config/ โ† ้…็ฝฎๅ’Œๅธธ้‡ -โ”‚ โ”œโ”€โ”€ executors/ โ† ๆไพ›ๅ•†็‰นๅฎš็š„่ฏทๆฑ‚ๆ‰ง่กŒ -โ”‚ โ”œโ”€โ”€ handlers/ โ† ่ฏทๆฑ‚ๅค„็†็ผ–ๆŽ’ -โ”‚ โ”œโ”€โ”€ services/ โ† ไธšๅŠก้€ป่พ‘๏ผˆ่ฎค่ฏใ€ๆจกๅž‹ใ€ๅŽๅค‡ใ€็”จ้‡๏ผ‰ -โ”‚ โ”œโ”€โ”€ translator/ โ† ๆ ผๅผ็ฟป่ฏ‘ๅผ•ๆ“Ž -โ”‚ โ”‚ โ”œโ”€โ”€ request/ โ† ่ฏทๆฑ‚็ฟป่ฏ‘ๅ™จ๏ผˆ8 ไธชๆ–‡ไปถ๏ผ‰ -โ”‚ โ”‚ โ”œโ”€โ”€ response/ โ† ๅ“ๅบ”็ฟป่ฏ‘ๅ™จ๏ผˆ7 ไธชๆ–‡ไปถ๏ผ‰ -โ”‚ โ”‚ โ””โ”€โ”€ helpers/ โ† ๅ…ฑไบซ็ฟป่ฏ‘ๅทฅๅ…ท๏ผˆ6 ไธชๆ–‡ไปถ๏ผ‰ -โ”‚ โ””โ”€โ”€ utils/ โ† ๅทฅๅ…ทๅ‡ฝๆ•ฐ -โ”œโ”€โ”€ src/ โ† ๅบ”็”จๅฑ‚๏ผˆExpress/Worker ่ฟ่กŒๆ—ถ๏ผ‰ -โ”‚ โ”œโ”€โ”€ app/ โ† Web UIใ€API ่ทฏ็”ฑใ€ไธญ้—ดไปถ -โ”‚ โ”œโ”€โ”€ lib/ โ† ๆ•ฐๆฎๅบ“ใ€่ฎค่ฏๅ’Œๅ…ฑไบซๅบ“ไปฃ็  -โ”‚ โ”œโ”€โ”€ mitm/ โ† ไธญ้—ดไบบไปฃ็†ๅทฅๅ…ท -โ”‚ โ”œโ”€โ”€ models/ โ† ๆ•ฐๆฎๅบ“ๆจกๅž‹ -โ”‚ โ”œโ”€โ”€ shared/ โ† ๅ…ฑไบซๅทฅๅ…ท๏ผˆopen-sse ็š„ๅŒ…่ฃ…ๅ™จ๏ผ‰ -โ”‚ โ”œโ”€โ”€ sse/ โ† SSE ็ซฏ็‚นๅค„็†ๅ™จ -โ”‚ โ””โ”€โ”€ store/ โ† ็Šถๆ€็ฎก็† -โ”œโ”€โ”€ data/ โ† ่ฟ่กŒๆ—ถๆ•ฐๆฎ๏ผˆๅ‡ญ่ฏใ€ๆ—ฅๅฟ—๏ผ‰ -โ”‚ โ””โ”€โ”€ provider-credentials.json ๏ผˆๅค–้ƒจๅ‡ญ่ฏ่ฆ†็›–๏ผŒๅทฒ gitignore๏ผ‰ -โ””โ”€โ”€ tester/ โ† ๆต‹่ฏ•ๅทฅๅ…ท -``` - ---- - -## 4. ๆจกๅ—้€ไธ€ๅˆ†่งฃ - -### 4.1 ้…็ฝฎ๏ผˆ`open-sse/config/`๏ผ‰ - -ๆ‰€ๆœ‰ๆไพ›ๅ•†้…็ฝฎ็š„**ๅ•ไธ€ไบ‹ๅฎžๆฅๆบ**ใ€‚ - -| ๆ–‡ไปถ | ็”จ้€” | -| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `constants.ts` | `PROVIDERS` ๅฏน่ฑก๏ผŒๅŒ…ๅซๆฏไธชๆไพ›ๅ•†็š„ๅŸบ็ก€ URLใ€OAuth ๅ‡ญ่ฏ๏ผˆ้ป˜่ฎคๅ€ผ๏ผ‰ใ€่ฏทๆฑ‚ๅคดๅ’Œ้ป˜่ฎค็ณป็ปŸๆ็คบ่ฏใ€‚่ฟ˜ๅฎšไน‰ไบ† `HTTP_STATUS`ใ€`ERROR_TYPES`ใ€`COOLDOWN_MS`ใ€`BACKOFF_CONFIG` ๅ’Œ `SKIP_PATTERNS`ใ€‚ | -| `credentialLoader.ts` | ไปŽ `data/provider-credentials.json` ๅŠ ่ฝฝๅค–้ƒจๅ‡ญ่ฏ๏ผŒๅนถๅˆๅนถ่ฆ†็›– `PROVIDERS` ไธญ็š„็กฌ็ผ–็ ้ป˜่ฎคๅ€ผใ€‚ๅœจไฟๆŒๅ‘ๅŽๅ…ผๅฎนๆ€ง็š„ๅŒๆ—ถๅฐ†ๅฏ†้’ฅไฟๆŒๅœจๆบไปฃ็ ๆŽงๅˆถไน‹ๅค–ใ€‚ | -| `providerModels.ts` | ไธญๅคฎๆจกๅž‹ๆณจๅ†Œ่กจ๏ผšๅฐ†ๆไพ›ๅ•†ๅˆซๅๆ˜ ๅฐ„ๅˆฐๆจกๅž‹ IDใ€‚ๅ‡ฝๆ•ฐๅฆ‚ `getModels()`ใ€`getProviderByAlias()`ใ€‚ | -| `codexInstructions.ts` | ๆณจๅ…ฅๅˆฐ Codex ่ฏทๆฑ‚ไธญ็š„็ณป็ปŸๆŒ‡ไปค๏ผˆ็ผ–่พ‘็บฆๆŸใ€ๆฒ™็ฎฑ่ง„ๅˆ™ใ€ๅฎกๆ‰น็ญ–็•ฅ๏ผ‰ใ€‚ | -| `defaultThinkingSignature.ts` | Claude ๅ’Œ Gemini ๆจกๅž‹็š„้ป˜่ฎค"thinking"็ญพๅใ€‚ | -| `ollamaModels.ts` | ๆœฌๅœฐ Ollama ๆจกๅž‹็š„ๆจกๅผๅฎšไน‰๏ผˆๅ็งฐใ€ๅคงๅฐใ€ๅฎถๆ—ใ€้‡ๅŒ–๏ผ‰ใ€‚ | - -#### ๅ‡ญ่ฏๅŠ ่ฝฝๆต็จ‹ - -```mermaid -flowchart TD - A["ๅบ”็”จๅฏๅŠจ"] --> B["constants.ts ๅฎšไน‰ PROVIDERS\nไฝฟ็”จ็กฌ็ผ–็ ้ป˜่ฎคๅ€ผ"] - B --> C{"data/provider-credentials.json\nๅญ˜ๅœจ๏ผŸ"} - C -->|ๆ˜ฏ| D["credentialLoader ่ฏปๅ– JSON"] - C -->|ๅฆ| E["ไฝฟ็”จ็กฌ็ผ–็ ้ป˜่ฎคๅ€ผ"] - D --> F{"ๅฏนไบŽ JSON ไธญ็š„ๆฏไธชๆไพ›ๅ•†"} - F --> G{"ๆไพ›ๅ•†ๅญ˜ๅœจไบŽ\nPROVIDERS ไธญ๏ผŸ"} - G -->|ๅฆ| H["่ฎฐๅฝ•่ญฆๅ‘Š๏ผŒ่ทณ่ฟ‡"] - G -->|ๆ˜ฏ| I{"ๅ€ผๆ˜ฏๅฏน่ฑก๏ผŸ"} - I -->|ๅฆ| J["่ฎฐๅฝ•่ญฆๅ‘Š๏ผŒ่ทณ่ฟ‡"] - I -->|ๆ˜ฏ| K["ๅˆๅนถ clientIdใ€clientSecretใ€\ntokenUrlใ€authUrlใ€refreshUrl"] - K --> F - H --> F - J --> F - F -->|ๅฎŒๆˆ| L["PROVIDERS ๅ‡†ๅค‡ๅฅฝ\nไฝฟ็”จๅˆๅนถๅŽ็š„ๅ‡ญ่ฏ"] - E --> L -``` - ---- - -### 4.2 ๆ‰ง่กŒๅ™จ๏ผˆ`open-sse/executors/`๏ผ‰ - -ๆ‰ง่กŒๅ™จไฝฟ็”จ**็ญ–็•ฅๆจกๅผ**ๅฐ่ฃ…**ๆไพ›ๅ•†็‰นๅฎš้€ป่พ‘**ใ€‚ๆฏไธชๆ‰ง่กŒๅ™จๆ นๆฎ้œ€่ฆ่ฆ†็›–ๅŸบ็ฑปๆ–นๆณ•ใ€‚ - -```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 -``` - -| ๆ‰ง่กŒๅ™จ | ๆไพ›ๅ•† | ๅ…ณ้”ฎ็‰นๆ€ง | -| ---------------- | ------------------------------------------ | ------------------------------------------------------------------------------------ | -| `base.ts` | โ€” | ๆŠฝ่ฑกๅŸบ็ฑป๏ผšURL ๆž„ๅปบใ€่ฏทๆฑ‚ๅคดใ€้‡่ฏ•้€ป่พ‘ใ€ๅ‡ญ่ฏๅˆทๆ–ฐ | -| `default.ts` | Claudeใ€Geminiใ€OpenAIใ€GLMใ€Kimiใ€MiniMax | ๆ ‡ๅ‡†ๆไพ›ๅ•†็š„้€š็”จ OAuth Token ๅˆทๆ–ฐ | -| `antigravity.ts` | Google Cloud Code | ้กน็›ฎ/ไผš่ฏ ID ็”Ÿๆˆใ€ๅคš URL ๅŽๅค‡ใ€ไปŽ้”™่ฏฏๆถˆๆฏ่งฃๆž่‡ชๅฎšไน‰้‡่ฏ•๏ผˆ"reset after 2h7m23s"๏ผ‰ | -| `cursor.ts` | Cursor IDE | **ๆœ€ๅคๆ‚**๏ผšSHA-256 ๆ ก้ชŒๅ’Œ่ฎค่ฏใ€Protobuf ่ฏทๆฑ‚็ผ–็ ใ€ไบŒ่ฟ›ๅˆถ EventStream โ†’ SSE ๅ“ๅบ”่งฃๆž | -| `codex.ts` | OpenAI Codex | ๆณจๅ…ฅ็ณป็ปŸๆŒ‡ไปคใ€็ฎก็† Thinking ็บงๅˆซใ€็งป้™คไธๆ”ฏๆŒ็š„ๅ‚ๆ•ฐ | -| `gemini-cli.ts` | Google Gemini CLI | ่‡ชๅฎšไน‰ URL ๆž„ๅปบ๏ผˆ`streamGenerateContent`๏ผ‰ใ€Google OAuth Token ๅˆทๆ–ฐ | -| `github.ts` | GitHub Copilot | ๅŒ Token ็ณป็ปŸ๏ผˆGitHub OAuth + Copilot Token๏ผ‰ใ€ๆจกๆ‹Ÿ VSCode ่ฏทๆฑ‚ๅคด | -| `kiro.ts` | AWS CodeWhisperer | AWS EventStream ไบŒ่ฟ›ๅˆถ่งฃๆžใ€AMZN ไบ‹ไปถๅธงใ€Token ไผฐ็ฎ— | -| `index.ts` | โ€” | ๅทฅๅŽ‚๏ผšๅฐ†ๆไพ›ๅ•†ๅ็งฐๆ˜ ๅฐ„ๅˆฐๆ‰ง่กŒๅ™จ็ฑป๏ผŒๅธฆ้ป˜่ฎคๅŽๅค‡ | - ---- - -### 4.3 ๅค„็†ๅ™จ๏ผˆ`open-sse/handlers/`๏ผ‰ - -**็ผ–ๆŽ’ๅฑ‚** โ€” ๅ่ฐƒ็ฟป่ฏ‘ใ€ๆ‰ง่กŒใ€ๆตๅผไผ ่พ“ๅ’Œ้”™่ฏฏๅค„็†ใ€‚ - -| ๆ–‡ไปถ | ็”จ้€” | -| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -| `chatCore.ts` | **ไธญๅคฎ็ผ–ๆŽ’ๅ™จ**๏ผˆ็บฆ 600 ่กŒ๏ผ‰ใ€‚ๅค„็†ๅฎŒๆ•ด็š„่ฏทๆฑ‚็”Ÿๅ‘ฝๅ‘จๆœŸ๏ผšๆ ผๅผๆฃ€ๆต‹ โ†’ ็ฟป่ฏ‘ โ†’ ๆ‰ง่กŒๅ™จ่ฐƒๅบฆ โ†’ ๆตๅผ/้žๆตๅผๅ“ๅบ” โ†’ Token ๅˆทๆ–ฐ โ†’ ้”™่ฏฏๅค„็† โ†’ ็”จ้‡ๆ—ฅๅฟ—ใ€‚ | -| `responsesHandler.ts` | OpenAI Responses API ้€‚้…ๅ™จ๏ผšๅฐ† Responses ๆ ผๅผ โ†’ Chat Completions โ†’ ๅ‘้€ๅˆฐ `chatCore` โ†’ ๅฐ† SSE ่ฝฌๆขๅ›ž Responses ๆ ผๅผใ€‚ | -| `embeddings.ts` | Embedding ็”Ÿๆˆๅค„็†ๅ™จ๏ผš่งฃๆž Embedding ๆจกๅž‹ โ†’ ๆไพ›ๅ•†๏ผŒ่ฐƒๅบฆๅˆฐๆไพ›ๅ•† API๏ผŒ่ฟ”ๅ›ž OpenAI ๅ…ผๅฎน็š„ Embedding ๅ“ๅบ”ใ€‚ๆ”ฏๆŒ 6+ ไธชๆไพ›ๅ•†ใ€‚ | -| `imageGeneration.ts` | ๅ›พๅƒ็”Ÿๆˆๅค„็†ๅ™จ๏ผš่งฃๆžๅ›พๅƒๆจกๅž‹ โ†’ ๆไพ›ๅ•†๏ผŒๆ”ฏๆŒ OpenAI ๅ…ผๅฎนใ€Gemini-image๏ผˆAntigravity๏ผ‰ๅ’ŒๅŽๅค‡๏ผˆNebius๏ผ‰ๆจกๅผใ€‚่ฟ”ๅ›ž base64 ๆˆ– URL ๅ›พๅƒใ€‚ | - -#### ่ฏทๆฑ‚็”Ÿๅ‘ฝๅ‘จๆœŸ๏ผˆchatCore.ts๏ผ‰ - -```mermaid -sequenceDiagram - participant Client as ๅฎขๆˆท็ซฏ - participant chatCore - participant Translator as ็ฟป่ฏ‘ๅ™จ - participant Executor as ๆ‰ง่กŒๅ™จ - participant Provider as ๆไพ›ๅ•† - - Client->>chatCore: ่ฏทๆฑ‚๏ผˆไปปไฝ•ๆ ผๅผ๏ผ‰ - chatCore->>chatCore: ๆฃ€ๆต‹ๆบๆ ผๅผ - chatCore->>chatCore: ๆฃ€ๆŸฅ bypass ๆจกๅผ - chatCore->>chatCore: ่งฃๆžๆจกๅž‹ๅ’Œๆไพ›ๅ•† - chatCore->>Translator: ็ฟป่ฏ‘่ฏทๆฑ‚๏ผˆๆบ โ†’ OpenAI โ†’ ็›ฎๆ ‡๏ผ‰ - chatCore->>Executor: ่Žทๅ–ๆไพ›ๅ•†็š„ๆ‰ง่กŒๅ™จ - Executor->>Executor: ๆž„ๅปบ URLใ€่ฏทๆฑ‚ๅคดใ€่ฝฌๆข่ฏทๆฑ‚ - Executor->>Executor: ๅฆ‚้œ€่ฆๅˆ™ๅˆทๆ–ฐๅ‡ญ่ฏ - Executor->>Provider: HTTP fetch๏ผˆๆตๅผๆˆ–้žๆตๅผ๏ผ‰ - - alt ๆตๅผไผ ่พ“ - Provider-->>chatCore: SSE ๆต - chatCore->>chatCore: ้€š่ฟ‡ SSE ่ฝฌๆขๆต็ฎก้“ - Note over chatCore: ่ฝฌๆขๆต็ฟป่ฏ‘
ๆฏไธชๅ—๏ผš็›ฎๆ ‡ โ†’ OpenAI โ†’ ๆบ - chatCore-->>Client: ๅทฒ็ฟป่ฏ‘็š„ SSE ๆต - else ้žๆตๅผไผ ่พ“ - Provider-->>chatCore: JSON ๅ“ๅบ” - chatCore->>Translator: ็ฟป่ฏ‘ๅ“ๅบ” - chatCore-->>Client: ๅทฒ็ฟป่ฏ‘็š„ JSON - end - - alt ้”™่ฏฏ (401, 429, 500...) - chatCore->>Executor: ๅธฆๅ‡ญ่ฏๅˆทๆ–ฐ้‡่ฏ• - chatCore->>chatCore: ่ดฆๆˆทๅŽๅค‡้€ป่พ‘ - end -``` - ---- - -### 4.4 ๆœๅŠก๏ผˆ`open-sse/services/`๏ผ‰ - -ๆ”ฏๆŒๅค„็†ๅ™จๅ’Œๆ‰ง่กŒๅ™จ็š„ไธšๅŠก้€ป่พ‘ใ€‚ - -| ๆ–‡ไปถ | ็”จ้€” | -| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `provider.ts` | **ๆ ผๅผๆฃ€ๆต‹**๏ผˆ`detectFormat`๏ผ‰๏ผšๅˆ†ๆž่ฏทๆฑ‚ไฝ“็ป“ๆž„ไปฅ่ฏ†ๅˆซ Claude/OpenAI/Gemini/Antigravity/Responses ๆ ผๅผ๏ผˆๅŒ…ๆ‹ฌ Claude ็š„ `max_tokens` ๅฏๅ‘ๅผ๏ผ‰ใ€‚่ฟ˜ๆœ‰๏ผšURL ๆž„ๅปบใ€่ฏทๆฑ‚ๅคดๆž„ๅปบใ€Thinking ้…็ฝฎ่ง„่ŒƒๅŒ–ใ€‚ๆ”ฏๆŒ `openai-compatible-*` ๅ’Œ `anthropic-compatible-*` ๅŠจๆ€ๆไพ›ๅ•†ใ€‚ | -| `model.ts` | ๆจกๅž‹ๅญ—็ฌฆไธฒ่งฃๆž๏ผˆ`claude/model-name` โ†’ `{provider: "claude", model: "model-name"}`๏ผ‰ใ€ๅธฆๅ†ฒ็ชๆฃ€ๆต‹็š„ๅˆซๅ่งฃๆžใ€่พ“ๅ…ฅๆธ…็†๏ผˆๆ‹’็ป่ทฏๅพ„้ๅŽ†/ๆŽงๅˆถๅญ—็ฌฆ๏ผ‰ใ€ไปฅๅŠๆ”ฏๆŒๅผ‚ๆญฅๅˆซๅ่Žทๅ–ๅ™จ็š„ๆจกๅž‹ไฟกๆฏ่งฃๆžใ€‚ | -| `accountFallback.ts` | ้€Ÿ็Ž‡้™ๅˆถๅค„็†๏ผšๆŒ‡ๆ•ฐ้€€้ฟ๏ผˆ1s โ†’ 2s โ†’ 4s โ†’ ๆœ€ๅคง 2 ๅˆ†้’Ÿ๏ผ‰ใ€่ดฆๆˆทๅ†ทๅด็ฎก็†ใ€้”™่ฏฏๅˆ†็ฑป๏ผˆๅ“ชไบ›้”™่ฏฏ่งฆๅ‘ๅŽๅค‡๏ผŒๅ“ชไบ›ไธ่งฆๅ‘๏ผ‰ใ€‚ | -| `tokenRefresh.ts` | **ๆฏไธชๆไพ›ๅ•†**็š„ OAuth Token ๅˆทๆ–ฐ๏ผšGoogle๏ผˆGeminiใ€Antigravity๏ผ‰ใ€Claudeใ€Codexใ€Qwenใ€Qoderใ€GitHub๏ผˆOAuth + Copilot ๅŒ Token๏ผ‰ใ€Kiro๏ผˆAWS SSO OIDC + ็คพไบค่ฎค่ฏ๏ผ‰ใ€‚ๅŒ…ๆ‹ฌ่ฟ›่กŒไธญ Promise ๅŽป้‡็ผ“ๅญ˜ๅ’ŒๆŒ‡ๆ•ฐ้€€้ฟ้‡่ฏ•ใ€‚ | -| `combo.ts` | **Combo ๆจกๅž‹**๏ผšๅŽๅค‡ๆจกๅž‹้“พใ€‚ๅฆ‚ๆžœๆจกๅž‹ A ๅ› ๅฏๅŽๅค‡้”™่ฏฏๅคฑ่ดฅ๏ผŒๅฐ่ฏ•ๆจกๅž‹ B๏ผŒ็„ถๅŽ C๏ผŒไพๆญค็ฑปๆŽจใ€‚่ฟ”ๅ›žๅฎž้™…็š„ไธŠๆธธ็Šถๆ€็ ใ€‚ | -| `usage.ts` | ไปŽๆไพ›ๅ•† API ่Žทๅ–้…้ข/็”จ้‡ๆ•ฐๆฎ๏ผˆGitHub Copilot ้…้ขใ€Antigravity ๆจกๅž‹้…้ขใ€Codex ้€Ÿ็Ž‡้™ๅˆถใ€Kiro ็”จ้‡ๆ˜Ž็ป†ใ€Claude ่ฎพ็ฝฎ๏ผ‰ใ€‚ | -| `accountSelector.ts` | ๆ™บ่ƒฝ่ดฆๆˆท้€‰ๆ‹ฉไธŽ่ฏ„ๅˆ†็ฎ—ๆณ•๏ผš่€ƒ่™‘ไผ˜ๅ…ˆ็บงใ€ๅฅๅบท็Šถๆ€ใ€่ฝฎ่ฏขไฝ็ฝฎๅ’Œๅ†ทๅด็Šถๆ€๏ผŒไธบๆฏไธช่ฏทๆฑ‚้€‰ๆ‹ฉๆœ€ไผ˜่ดฆๆˆทใ€‚ | -| `contextManager.ts` | ่ฏทๆฑ‚ไธŠไธ‹ๆ–‡็”Ÿๅ‘ฝๅ‘จๆœŸ็ฎก็†๏ผšๅˆ›ๅปบๅ’Œ่ฟฝ่ธชๅธฆๆœ‰ๅ…ƒๆ•ฐๆฎ๏ผˆ่ฏทๆฑ‚ IDใ€ๆ—ถ้—ดๆˆณใ€ๆไพ›ๅ•†ไฟกๆฏ๏ผ‰็š„ๆฏ่ฏทๆฑ‚ไธŠไธ‹ๆ–‡ๅฏน่ฑก๏ผŒ็”จไบŽ่ฐƒ่ฏ•ๅ’Œๆ—ฅๅฟ—ใ€‚ | -| `ipFilter.ts` | ๅŸบไบŽ IP ็š„่ฎฟ้—ฎๆŽงๅˆถ๏ผšๆ”ฏๆŒ็™ฝๅๅ•ๅ’Œ้ป‘ๅๅ•ๆจกๅผใ€‚ๅœจๅค„็† API ่ฏทๆฑ‚ๅ‰ๆ นๆฎ้…็ฝฎ่ง„ๅˆ™้ชŒ่ฏๅฎขๆˆท็ซฏ IPใ€‚ | -| `sessionManager.ts` | ๅธฆๅฎขๆˆท็ซฏๆŒ‡็บน็š„ไผš่ฏ่ฟฝ่ธช๏ผšไฝฟ็”จๅ“ˆๅธŒๅฎขๆˆท็ซฏๆ ‡่ฏ†็ฌฆ่ฟฝ่ธชๆดปๅŠจไผš่ฏใ€็›‘ๆŽง่ฏทๆฑ‚่ฎกๆ•ฐใ€ๆไพ›ไผš่ฏๆŒ‡ๆ ‡ใ€‚ | -| `signatureCache.ts` | ๅŸบไบŽ่ฏทๆฑ‚็ญพๅ็š„ๅŽป้‡็ผ“ๅญ˜๏ผš้€š่ฟ‡็ผ“ๅญ˜่ฟ‘ๆœŸ่ฏทๆฑ‚็ญพๅๅนถๅœจๆ—ถ้—ด็ช—ๅฃๅ†…ไธบ็›ธๅŒ่ฏทๆฑ‚่ฟ”ๅ›ž็ผ“ๅญ˜ๅ“ๅบ”ๆฅ้˜ฒๆญข้‡ๅค่ฏทๆฑ‚ใ€‚ | -| `systemPrompt.ts` | ๅ…จๅฑ€็ณป็ปŸๆ็คบ่ฏๆณจๅ…ฅ๏ผšๅœจๆ‰€ๆœ‰่ฏทๆฑ‚ๅ‰็ฝฎๆˆ–่ฟฝๅŠ ๅฏ้…็ฝฎ็š„็ณป็ปŸๆ็คบ่ฏ๏ผŒๅธฆๆฏๆไพ›ๅ•†ๅ…ผๅฎนๆ€งๅค„็†ใ€‚ | -| `thinkingBudget.ts` | ๆŽจ็† Token ้ข„็ฎ—็ฎก็†๏ผšๆ”ฏๆŒ passthrough๏ผˆ้€ไผ ๏ผ‰ใ€auto๏ผˆๅ‰ฅ็ฆป Thinking ้…็ฝฎ๏ผ‰ใ€custom๏ผˆๅ›บๅฎš้ข„็ฎ—๏ผ‰ๅ’Œ adaptive๏ผˆๅคๆ‚ๅบฆ็ผฉๆ”พ๏ผ‰ๆจกๅผๆฅๆŽงๅˆถ Thinking/ๆŽจ็† Tokenใ€‚ | -| `wildcardRouter.ts` | ้€š้…็ฌฆๆจกๅž‹ๆจกๅผ่ทฏ็”ฑ๏ผšๆ นๆฎๅฏ็”จๆ€งๅ’Œไผ˜ๅ…ˆ็บงๅฐ†้€š้…็ฌฆๆจกๅผ๏ผˆๅฆ‚ `*/claude-*`๏ผ‰่งฃๆžไธบๅ…ทไฝ“็š„ๆไพ›ๅ•†/ๆจกๅž‹ๅฏนใ€‚ | - -#### Token ๅˆทๆ–ฐๅŽป้‡ - -```mermaid -sequenceDiagram - participant R1 as ่ฏทๆฑ‚ 1 - participant R2 as ่ฏทๆฑ‚ 2 - participant Cache as refreshPromiseCache - participant OAuth as OAuth ๆไพ›ๅ•† - - R1->>Cache: getAccessToken("gemini", token) - Cache->>Cache: ๆ— ่ฟ›่กŒไธญ Promise - Cache->>OAuth: ๅผ€ๅง‹ๅˆทๆ–ฐ - R2->>Cache: getAccessToken("gemini", token) - Cache->>Cache: ๆ‰พๅˆฐ่ฟ›่กŒไธญ Promise - Cache-->>R2: ่ฟ”ๅ›ž็Žฐๆœ‰ Promise - OAuth-->>Cache: ๆ–ฐ่ฎฟ้—ฎ Token - Cache-->>R1: ๆ–ฐ่ฎฟ้—ฎ Token - Cache-->>R2: ็›ธๅŒ่ฎฟ้—ฎ Token๏ผˆๅ…ฑไบซ๏ผ‰ - Cache->>Cache: ๅˆ ้™ค็ผ“ๅญ˜ๆก็›ฎ -``` - -#### ่ดฆๆˆทๅŽๅค‡็Šถๆ€ๆœบ - -```mermaid -stateDiagram-v2 - [*] --> Active - Active --> Error: ่ฏทๆฑ‚ๅคฑ่ดฅ (401/429/500) - Error --> Cooldown: ๅบ”็”จ้€€้ฟ - Cooldown --> Active: ๅ†ทๅด่ฟ‡ๆœŸ - Active --> Active: ่ฏทๆฑ‚ๆˆๅŠŸ๏ผˆ้‡็ฝฎ้€€้ฟ๏ผ‰ - - state Error { - [*] --> ClassifyError - ClassifyError --> ShouldFallback: ้€Ÿ็Ž‡้™ๅˆถ / ่ฎค่ฏ / ็žฌๆ€ - ClassifyError --> NoFallback: 400 ้”™่ฏฏ่ฏทๆฑ‚ - } - - state Cooldown { - [*] --> ExponentialBackoff - ExponentialBackoff: ็บงๅˆซ 0 = 1s - ExponentialBackoff: ็บงๅˆซ 1 = 2s - ExponentialBackoff: ็บงๅˆซ 2 = 4s - ExponentialBackoff: ๆœ€ๅคง = 2min - } -``` - -#### Combo ๆจกๅž‹้“พ - -```mermaid -flowchart LR - A["ๅธฆ Combo ๆจกๅž‹็š„่ฏทๆฑ‚"] --> B["ๆจกๅž‹ A"] - B -->|"2xx ๆˆๅŠŸ"| C["่ฟ”ๅ›žๅ“ๅบ”"] - B -->|"429/401/500"| D{"ๅฏๅŽๅค‡๏ผŸ"} - D -->|ๆ˜ฏ| E["ๆจกๅž‹ B"] - D -->|ๅฆ| F["่ฟ”ๅ›ž้”™่ฏฏ"] - E -->|"2xx ๆˆๅŠŸ"| C - E -->|"429/401/500"| G{"ๅฏๅŽๅค‡๏ผŸ"} - G -->|ๆ˜ฏ| H["ๆจกๅž‹ C"] - G -->|ๅฆ| F - H -->|"2xx ๆˆๅŠŸ"| C - H -->|"ๅคฑ่ดฅ"| I["ๅ…จ้ƒจๅคฑ่ดฅ โ†’\n่ฟ”ๅ›žๆœ€ๅŽ็Šถๆ€"] -``` - ---- - -### 4.5 ็ฟป่ฏ‘ๅ™จ๏ผˆ`open-sse/translator/`๏ผ‰ - -ไฝฟ็”จ่‡ชๆณจๅ†Œๆ’ไปถ็ณป็ปŸ็š„**ๆ ผๅผ็ฟป่ฏ‘ๅผ•ๆ“Ž**ใ€‚ - -#### ๆžถๆž„ - -```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 -``` - -| ็›ฎๅฝ• | ๆ–‡ไปถๆ•ฐ | ๆ่ฟฐ | -| ------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `request/` | 8 ไธช็ฟป่ฏ‘ๅ™จ | ๅœจไธๅŒๆ ผๅผไน‹้—ด่ฝฌๆข่ฏทๆฑ‚ไฝ“ใ€‚ๆฏไธชๆ–‡ไปถๅœจๅฏผๅ…ฅๆ—ถ้€š่ฟ‡ `register(from, to, fn)` ่‡ชๆณจๅ†Œใ€‚ | -| `response/` | 7 ไธช็ฟป่ฏ‘ๅ™จ | ๅœจไธๅŒๆ ผๅผไน‹้—ด่ฝฌๆขๆตๅผๅ“ๅบ”ๅ—ใ€‚ๅค„็† SSE ไบ‹ไปถ็ฑปๅž‹ใ€thinking ๅ—ใ€ๅทฅๅ…ท่ฐƒ็”จใ€‚ | -| `helpers/` | 6 ไธช่พ…ๅŠฉๅทฅๅ…ท | ๅ…ฑไบซๅทฅๅ…ท๏ผš`claudeHelper`๏ผˆ็ณป็ปŸๆ็คบ่ฏๆๅ–ใ€thinking ้…็ฝฎ๏ผ‰ใ€`geminiHelper`๏ผˆparts/contents ๆ˜ ๅฐ„๏ผ‰ใ€`openaiHelper`๏ผˆๆ ผๅผ่ฟ‡ๆปค๏ผ‰ใ€`toolCallHelper`๏ผˆID ็”Ÿๆˆใ€็ผบๅคฑๅ“ๅบ”ๆณจๅ…ฅ๏ผ‰ใ€`maxTokensHelper`ใ€`responsesApiHelper`ใ€‚ | -| `index.ts` | โ€” | ็ฟป่ฏ‘ๅผ•ๆ“Ž๏ผš`translateRequest()`ใ€`translateResponse()`ใ€็Šถๆ€็ฎก็†ใ€ๆณจๅ†Œ่กจใ€‚ | -| `formats.ts` | โ€” | ๆ ผๅผๅธธ้‡๏ผš`OPENAI`ใ€`CLAUDE`ใ€`GEMINI`ใ€`ANTIGRAVITY`ใ€`KIRO`ใ€`CURSOR`ใ€`OPENAI_RESPONSES`ใ€‚ | - -#### ๅ…ณ้”ฎ่ฎพ่ฎก๏ผš่‡ชๆณจๅ†Œๆ’ไปถ - -```javascript -// ๆฏไธช็ฟป่ฏ‘ๅ™จๆ–‡ไปถๅœจๅฏผๅ…ฅๆ—ถ่ฐƒ็”จ register()๏ผš -import { register } from "../index.js"; -register("claude", "openai", translateClaudeToOpenAI); - -// index.js ๅฏผๅ…ฅๆ‰€ๆœ‰็ฟป่ฏ‘ๅ™จๆ–‡ไปถ๏ผŒ่งฆๅ‘ๆณจๅ†Œ๏ผš -import "./request/claude-to-openai.js"; // โ† ่‡ชๆณจๅ†Œ -``` - ---- - -### 4.6 ๅทฅๅ…ท (`open-sse/utils/`) - -| ๆ–‡ไปถ | ็”จ้€” | -| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `error.ts` | ้”™่ฏฏๅ“ๅบ”ๆž„ๅปบ๏ผˆOpenAI ๅ…ผๅฎนๆ ผๅผ๏ผ‰ใ€ไธŠๆธธ้”™่ฏฏ่งฃๆžใ€ไปŽ้”™่ฏฏๆถˆๆฏไธญๆๅ– Antigravity ้‡่ฏ•ๆ—ถ้—ดใ€SSE ้”™่ฏฏๆตๅผไผ ่พ“ใ€‚ | -| `stream.ts` | **SSE ่ฝฌๆขๆต** โ€” ๆ ธๅฟƒๆตๅผ็ฎก้“ใ€‚ไธค็งๆจกๅผ๏ผš`TRANSLATE`๏ผˆๅฎŒๆ•ดๆ ผๅผ่ฝฌๆข๏ผ‰ๅ’Œ `PASSTHROUGH`๏ผˆ่ง„่ŒƒๅŒ– + ๆๅ–็”จ้‡๏ผ‰ใ€‚ๅค„็†ๅ—็ผ“ๅ†ฒใ€็”จ้‡ไผฐ็ฎ—ใ€ๅ†…ๅฎน้•ฟๅบฆ่ฟฝ่ธชใ€‚ๆฏๆต็‹ฌ็ซ‹็š„ encoder/decoder ๅฎžไพ‹้ฟๅ…ๅ…ฑไบซ็Šถๆ€ใ€‚ | -| `streamHelpers.ts` | ๅบ•ๅฑ‚ SSE ๅทฅๅ…ท๏ผš`parseSSELine`๏ผˆๅฎนๅฟ็ฉบ็™ฝ๏ผ‰ใ€`hasValuableContent`๏ผˆ่ฟ‡ๆปค OpenAI/Claude/Gemini ็š„็ฉบๅ—๏ผ‰ใ€`fixInvalidId`ใ€`formatSSE`๏ผˆๆ„Ÿ็Ÿฅๆ ผๅผ็š„ SSE ๅบๅˆ—ๅŒ–๏ผŒๆธ…็† `perf_metrics`๏ผ‰ใ€‚ | -| `usageTracking.ts` | ไปŽไปปไฝ•ๆ ผๅผๆๅ– Token ็”จ้‡๏ผˆClaude/OpenAI/Gemini/Responses๏ผ‰๏ผŒไฝฟ็”จ็‹ฌ็ซ‹็š„ๅทฅๅ…ท/ๆถˆๆฏๅญ—็ฌฆ-token ๆฏ”็Ž‡ไผฐ็ฎ—๏ผŒๆทปๅŠ ็ผ“ๅ†ฒ๏ผˆ2000 token ๅฎ‰ๅ…จ่พน้™…๏ผ‰๏ผŒๆ ผๅผ็‰นๅฎšๅญ—ๆฎต่ฟ‡ๆปค๏ผŒๅธฆ ANSI ้ขœ่‰ฒ็š„ๆŽงๅˆถๅฐๆ—ฅๅฟ—ใ€‚ | -| `requestLogger.ts` | ๅŸบไบŽๆ–‡ไปถ็š„่ฏทๆฑ‚ๆ—ฅๅฟ—๏ผˆ้€š่ฟ‡ `ENABLE_REQUEST_LOGS=true` ๅฏ็”จ๏ผ‰ใ€‚ๅˆ›ๅปบๅธฆ็ผ–ๅทๆ–‡ไปถ็š„ไผš่ฏๆ–‡ไปถๅคน๏ผš`1_req_client.json` โ†’ `7_res_client.txt`ใ€‚ๆ‰€ๆœ‰ I/O ๅผ‚ๆญฅ๏ผˆfire-and-forget๏ผ‰ใ€‚้ฎ่”ฝๆ•ๆ„Ÿ่ฏทๆฑ‚ๅคดใ€‚ | -| `bypassHandler.ts` | ๆ‹ฆๆˆช Claude CLI ็š„็‰นๅฎšๆจกๅผ๏ผˆๆ ‡้ข˜ๆๅ–ใ€้ข„็ƒญใ€่ฎกๆ•ฐ๏ผ‰ๅนถ่ฟ”ๅ›žๅ‡ๅ“ๅบ”่€Œไธ่ฐƒ็”จไปปไฝ•ๆไพ›ๅ•†ใ€‚ๆ”ฏๆŒๆตๅผๅ’Œ้žๆตๅผใ€‚ๆœ‰ๆ„้™ๅˆถๅœจ Claude CLI ่Œƒๅ›ดๅ†…ใ€‚ | -| `networkProxy.ts` | ไธบ็ป™ๅฎšๆไพ›ๅ•†่งฃๆžๅ‡บ็ซ™ไปฃ็† URL๏ผŒไผ˜ๅ…ˆ็บง๏ผšๆไพ›ๅ•†็‰นๅฎš้…็ฝฎ โ†’ ๅ…จๅฑ€้…็ฝฎ โ†’ ็Žฏๅขƒๅ˜้‡๏ผˆ`HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`๏ผ‰ใ€‚ๆ”ฏๆŒ `NO_PROXY` ๆŽ’้™คใ€‚้…็ฝฎ็ผ“ๅญ˜ 30 ็ง’ใ€‚ | - -#### SSE ๆต็ฎก้“ - -```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 -``` - -#### ่ฏทๆฑ‚ๆ—ฅๅฟ—ๅ™จไผš่ฏ็ป“ๆž„ - -``` -logs/ -โ””โ”€โ”€ claude_gemini_claude-sonnet_20260208_143045/ - โ”œโ”€โ”€ 1_req_client.json โ† ๅŽŸๅง‹ๅฎขๆˆท็ซฏ่ฏทๆฑ‚ - โ”œโ”€โ”€ 2_req_source.json โ† ๅˆๅง‹่ฝฌๆขๅŽ - โ”œโ”€โ”€ 3_req_openai.json โ† OpenAI ไธญ้—ดๆ ผๅผ - โ”œโ”€โ”€ 4_req_target.json โ† ๆœ€็ปˆ็›ฎๆ ‡ๆ ผๅผ - โ”œโ”€โ”€ 5_res_provider.txt โ† ๆไพ›ๅ•† SSE ๅ—๏ผˆๆตๅผ๏ผ‰ - โ”œโ”€โ”€ 5_res_provider.json โ† ๆไพ›ๅ•†ๅ“ๅบ”๏ผˆ้žๆตๅผ๏ผ‰ - โ”œโ”€โ”€ 6_res_openai.txt โ† OpenAI ไธญ้—ดๅ— - โ”œโ”€โ”€ 7_res_client.txt โ† ้ขๅ‘ๅฎขๆˆท็ซฏ็š„ SSE ๅ— - โ””โ”€โ”€ 6_error.json โ† ้”™่ฏฏ่ฏฆๆƒ…๏ผˆๅฆ‚ๆœ‰๏ผ‰ -``` - ---- - -### 4.7 ๅบ”็”จๅฑ‚๏ผˆ`src/`๏ผ‰ - -| ็›ฎๅฝ• | ็”จ้€” | -| ------------- | ---------------------------------------------------- | -| `src/app/` | Web UIใ€API ่ทฏ็”ฑใ€Express ไธญ้—ดไปถใ€OAuth ๅ›ž่ฐƒๅค„็†ๅ™จ | -| `src/lib/` | ๆ•ฐๆฎๅบ“่ฎฟ้—ฎ๏ผˆ`localDb.ts`ใ€`usageDb.ts`๏ผ‰ใ€่ฎค่ฏใ€ๅ…ฑไบซ | -| `src/mitm/` | ็”จไบŽๆ‹ฆๆˆชๆไพ›ๅ•†ๆต้‡็š„ไธญ้—ดไบบไปฃ็†ๅทฅๅ…ท | -| `src/models/` | ๆ•ฐๆฎๅบ“ๆจกๅž‹ๅฎšไน‰ | -| `src/shared/` | open-sse ๅ‡ฝๆ•ฐ็š„ๅŒ…่ฃ…ๅ™จ๏ผˆproviderใ€streamใ€error ็ญ‰๏ผ‰ | -| `src/sse/` | ๅฐ† open-sse ๅบ“่ฟžๆŽฅๅˆฐ Express ่ทฏ็”ฑ็š„ SSE ็ซฏ็‚นๅค„็†ๅ™จ | -| `src/store/` | ๅบ”็”จ็Šถๆ€็ฎก็† | - -#### ้‡่ฆ API ่ทฏ็”ฑ - -| ่ทฏ็”ฑ | ๆ–นๆณ• | ็”จ้€” | -| --------------------------------------------- | --------------- | ----------------------------------------------------------------- | -| `/api/provider-models` | GET/POST/DELETE | ๆฏๆไพ›ๅ•†่‡ชๅฎšไน‰ๆจกๅž‹็š„ CRUD | -| `/api/models/catalog` | GET | ๆŒ‰ๆไพ›ๅ•†ๅˆ†็ป„็š„ๆ‰€ๆœ‰ๆจกๅž‹๏ผˆ่Šๅคฉใ€Embeddingใ€ๅ›พๅƒใ€่‡ชๅฎšไน‰๏ผ‰็š„่šๅˆ็›ฎๅฝ• | -| `/api/settings/proxy` | GET/PUT/DELETE | ๅˆ†ๅฑ‚ๅ‡บ็ซ™ไปฃ็†้…็ฝฎ๏ผˆ`global/providers/combos/keys`๏ผ‰ | -| `/api/settings/proxy/test` | POST | ้ชŒ่ฏไปฃ็†่ฟžๆŽฅๅนถ่ฟ”ๅ›žๅ…ฌๅ…ฑ IP/ๅปถ่ฟŸ | -| `/v1/providers/[provider]/chat/completions` | POST | ๅธฆๆจกๅž‹้ชŒ่ฏ็š„ไธ“็”จๆฏๆไพ›ๅ•†่ŠๅคฉๅฎŒๆˆ | -| `/v1/providers/[provider]/embeddings` | POST | ๅธฆๆจกๅž‹้ชŒ่ฏ็š„ไธ“็”จๆฏๆไพ›ๅ•† Embedding | -| `/v1/providers/[provider]/images/generations` | POST | ๅธฆๆจกๅž‹้ชŒ่ฏ็š„ไธ“็”จๆฏๆไพ›ๅ•†ๅ›พๅƒ็”Ÿๆˆ | -| `/api/settings/ip-filter` | GET/PUT | IP ็™ฝๅๅ•/้ป‘ๅๅ•็ฎก็† | -| `/api/settings/thinking-budget` | GET/PUT | ๆŽจ็† Token ้ข„็ฎ—้…็ฝฎ๏ผˆpassthrough/auto/custom/adaptive๏ผ‰ | -| `/api/settings/system-prompt` | GET/PUT | ๆ‰€ๆœ‰่ฏทๆฑ‚็š„ๅ…จๅฑ€็ณป็ปŸๆ็คบ่ฏๆณจๅ…ฅ | -| `/api/sessions` | GET | ๆดปๅŠจไผš่ฏ่ฟฝ่ธชๅ’ŒๆŒ‡ๆ ‡ | -| `/api/rate-limits` | GET | ๆฏ่ดฆๆˆท้€Ÿ็Ž‡้™ๅˆถ็Šถๆ€ | - ---- - -## 5. ๅ…ณ้”ฎ่ฎพ่ฎกๆจกๅผ - -### 5.1 ไธญๅฟƒ่พๅฐ„็ฟป่ฏ‘ - -ๆ‰€ๆœ‰ๆ ผๅผ้ƒฝ้€š่ฟ‡ **OpenAI ๆ ผๅผไฝœไธบไธญๅฟƒ** ่ฟ›่กŒ็ฟป่ฏ‘ใ€‚ๆทปๅŠ ๆ–ฐๆไพ›ๅ•†ๅช้œ€่ฆ็ผ–ๅ†™**ไธ€ๅฏน**็ฟป่ฏ‘ๅ™จ๏ผˆๅˆฐ/ไปŽ OpenAI๏ผ‰๏ผŒ่€Œไธๆ˜ฏ N ๅฏนใ€‚ - -### 5.2 ๆ‰ง่กŒๅ™จ็ญ–็•ฅๆจกๅผ - -ๆฏไธชๆไพ›ๅ•†้ƒฝๆœ‰ไธ€ไธช็ปงๆ‰ฟ่‡ช `BaseExecutor` ็š„ไธ“็”จๆ‰ง่กŒๅ™จ็ฑปใ€‚`executors/index.ts` ไธญ็š„ๅทฅๅŽ‚ๅœจ่ฟ่กŒๆ—ถ้€‰ๆ‹ฉๆญฃ็กฎ็š„ๆ‰ง่กŒๅ™จใ€‚ - -### 5.3 ่‡ชๆณจๅ†Œๆ’ไปถ็ณป็ปŸ - -็ฟป่ฏ‘ๅ™จๆจกๅ—ๅœจๅฏผๅ…ฅๆ—ถ้€š่ฟ‡ `register()` ่‡ชๆณจๅ†Œใ€‚ๆทปๅŠ ๆ–ฐ็ฟป่ฏ‘ๅ™จๅช้œ€ๅˆ›ๅปบๆ–‡ไปถๅนถๅฏผๅ…ฅๅฎƒใ€‚ - -### 5.4 ๅธฆๆŒ‡ๆ•ฐ้€€้ฟ็š„่ดฆๆˆทๅŽๅค‡ - -ๅฝ“ๆไพ›ๅ•†่ฟ”ๅ›ž 429/401/500 ๆ—ถ๏ผŒ็ณป็ปŸๅฏไปฅๅˆ‡ๆขๅˆฐไธ‹ไธ€ไธช่ดฆๆˆท๏ผŒๅบ”็”จๆŒ‡ๆ•ฐๅ†ทๅด๏ผˆ1s โ†’ 2s โ†’ 4s โ†’ ๆœ€ๅคง 2min๏ผ‰ใ€‚ - -### 5.5 Combo ๆจกๅž‹้“พ - -"Combo"็ป„ๅˆๅคšไธช `provider/model` ๅญ—็ฌฆไธฒใ€‚ๅฆ‚ๆžœ็ฌฌไธ€ไธชๅคฑ่ดฅ๏ผŒ่‡ชๅŠจๅŽๅค‡ๅˆฐไธ‹ไธ€ไธชใ€‚ - -### 5.6 ๆœ‰็Šถๆ€ๆตๅผ็ฟป่ฏ‘ - -ๅ“ๅบ”็ฟป่ฏ‘้€š่ฟ‡ `initState()` ๆœบๅˆถๅœจ SSE ๅ—ไน‹้—ด็ปดๆŠค็Šถๆ€๏ผˆThinking ๅ—่ฟฝ่ธชใ€ๅทฅๅ…ท่ฐƒ็”จ็ดฏ็งฏใ€ๅ†…ๅฎนๅ—็ดขๅผ•๏ผ‰ใ€‚ - -### 5.7 ็”จ้‡ๅฎ‰ๅ…จ็ผ“ๅ†ฒ - -ๅœจๆŠฅๅ‘Š็š„็”จ้‡ไธญๆทปๅŠ  2000 Token ็ผ“ๅ†ฒ๏ผŒไปฅ้˜ฒๆญขๅฎขๆˆท็ซฏๅ› ็ณป็ปŸๆ็คบ่ฏๅ’Œๆ ผๅผ็ฟป่ฏ‘ๅผ€้”€่€Œ่พพๅˆฐไธŠไธ‹ๆ–‡็ช—ๅฃ้™ๅˆถใ€‚ - ---- - -## 6. ๆ”ฏๆŒ็š„ๆ ผๅผ - -| ๆ ผๅผ | ๆ–นๅ‘ | ๆ ‡่ฏ†็ฌฆ | -| ----------------------- | --------- | ------------------ | -| OpenAI Chat Completions | ๆบ + ็›ฎๆ ‡ | `openai` | -| OpenAI Responses API | ๆบ + ็›ฎๆ ‡ | `openai-responses` | -| Anthropic Claude | ๆบ + ็›ฎๆ ‡ | `claude` | -| Google Gemini | ๆบ + ็›ฎๆ ‡ | `gemini` | -| Google Gemini CLI | ไป…็›ฎๆ ‡ | `gemini-cli` | -| Antigravity | ๆบ + ็›ฎๆ ‡ | `antigravity` | -| AWS Kiro | ไป…็›ฎๆ ‡ | `kiro` | -| Cursor | ไป…็›ฎๆ ‡ | `cursor` | - ---- - -## 7. ๆ”ฏๆŒ็š„ๆไพ›ๅ•† - -| ๆไพ›ๅ•† | ่ฎค่ฏๆ–นๆณ• | ๆ‰ง่กŒๅ™จ | ๅ…ณ้”ฎ่ฏดๆ˜Ž | -| ------------------------ | ----------------------- | ----------- | --------------------------------- | -| Anthropic Claude | API ๅฏ†้’ฅๆˆ– OAuth | Default | ไฝฟ็”จ `x-api-key` ่ฏทๆฑ‚ๅคด | -| Google Gemini | API ๅฏ†้’ฅๆˆ– OAuth | Default | ไฝฟ็”จ `x-goog-api-key` ่ฏทๆฑ‚ๅคด | -| Google Gemini CLI | OAuth | GeminiCLI | ไฝฟ็”จ `streamGenerateContent` ็ซฏ็‚น | -| Antigravity | OAuth | Antigravity | ๅคš URL ๅŽๅค‡๏ผŒ่‡ชๅฎšไน‰้‡่ฏ•่งฃๆž | -| OpenAI | API ๅฏ†้’ฅ | Default | ๆ ‡ๅ‡† Bearer ่ฎค่ฏ | -| Codex | OAuth | Codex | ๆณจๅ…ฅ็ณป็ปŸๆŒ‡ไปค๏ผŒ็ฎก็† Thinking | -| GitHub Copilot | OAuth + Copilot Token | Github | ๅŒ Token๏ผŒๆจกๆ‹Ÿ VSCode ่ฏทๆฑ‚ๅคด | -| Kiro (AWS) | AWS SSO OIDC ๆˆ–็คพไบค | Kiro | ไบŒ่ฟ›ๅˆถ EventStream ่งฃๆž | -| Cursor IDE | ๆ ก้ชŒๅ’Œ่ฎค่ฏ | Cursor | Protobuf ็ผ–็ ๏ผŒSHA-256 ๆ ก้ชŒๅ’Œ | -| Qwen | OAuth | Default | ๆ ‡ๅ‡†่ฎค่ฏ | -| Qoder | OAuth๏ผˆBasic + Bearer๏ผ‰ | Default | ๅŒ่ฎค่ฏ่ฏทๆฑ‚ๅคด | -| OpenRouter | API ๅฏ†้’ฅ | Default | ๆ ‡ๅ‡† Bearer ่ฎค่ฏ | -| GLMใ€Kimiใ€MiniMax | API ๅฏ†้’ฅ | Default | Claude ๅ…ผๅฎน๏ผŒไฝฟ็”จ `x-api-key` | -| `openai-compatible-*` | API ๅฏ†้’ฅ | Default | ๅŠจๆ€๏ผšไปปไฝ• OpenAI ๅ…ผๅฎน็ซฏ็‚น | -| `anthropic-compatible-*` | API ๅฏ†้’ฅ | Default | ๅŠจๆ€๏ผšไปปไฝ• Claude ๅ…ผๅฎน็ซฏ็‚น | - ---- - -## 8. ๆ•ฐๆฎๆตๆ‘˜่ฆ - -### ๆตๅผ่ฏทๆฑ‚ - -```mermaid -flowchart LR - A["ๅฎขๆˆท็ซฏ"] --> B["detectFormat()"] - B --> C["translateRequest()\nๆบ โ†’ OpenAI โ†’ ็›ฎๆ ‡"] - C --> D["ๆ‰ง่กŒๅ™จ\nbuildUrl + buildHeaders"] - D --> E["fetch(providerURL)"] - E --> F["createSSEStream()\nTRANSLATE ๆจกๅผ"] - F --> G["parseSSELine()"] - G --> H["translateResponse()\n็›ฎๆ ‡ โ†’ OpenAI โ†’ ๆบ"] - H --> I["extractUsage()\n+ addBuffer"] - I --> J["formatSSE()"] - J --> K["ๅฎขๆˆท็ซฏๆŽฅๆ”ถ\nๅทฒ็ฟป่ฏ‘็š„ SSE"] - K --> L["logUsage()\nsaveRequestUsage()"] -``` - -### ้žๆตๅผ่ฏทๆฑ‚ - -```mermaid -flowchart LR - A["ๅฎขๆˆท็ซฏ"] --> B["detectFormat()"] - B --> C["translateRequest()\nๆบ โ†’ OpenAI โ†’ ็›ฎๆ ‡"] - C --> D["Executor.execute()"] - D --> E["translateResponse()\n็›ฎๆ ‡ โ†’ OpenAI โ†’ ๆบ"] - E --> F["่ฟ”ๅ›ž JSON\nๅ“ๅบ”"] -``` - -### Bypass ๆต็จ‹๏ผˆClaude CLI๏ผ‰ - -```mermaid -flowchart LR - A["Claude CLI ่ฏทๆฑ‚"] --> B{"ๅŒน้… bypass\nๆจกๅผ๏ผŸ"} - B -->|"ๆ ‡้ข˜/้ข„็ƒญ/่ฎกๆ•ฐ"| C["็”Ÿๆˆๅ‡\nOpenAI ๅ“ๅบ”"] - B -->|"ๆ— ๅŒน้…"| D["ๆญฃๅธธๆต็จ‹"] - C --> E["็ฟป่ฏ‘ไธบ\nๆบๆ ผๅผ"] - E --> F["่ฟ”ๅ›ž่€Œไธ\n่ฐƒ็”จๆไพ›ๅ•†"] -``` diff --git a/docs/i18n/zh-CN/CONTRIBUTING.md b/docs/i18n/zh-CN/CONTRIBUTING.md new file mode 100644 index 0000000000..5b4d4ea6c6 --- /dev/null +++ b/docs/i18n/zh-CN/CONTRIBUTING.md @@ -0,0 +1,299 @@ +# Contributing to OmniRoute (ไธญๆ–‡๏ผˆ็ฎ€ไฝ“๏ผ‰) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../CONTRIBUTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/CONTRIBUTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/CONTRIBUTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/CONTRIBUTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/CONTRIBUTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/CONTRIBUTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/CONTRIBUTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/CONTRIBUTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/CONTRIBUTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/CONTRIBUTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/CONTRIBUTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/CONTRIBUTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/CONTRIBUTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/CONTRIBUTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/CONTRIBUTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/CONTRIBUTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/CONTRIBUTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/CONTRIBUTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/CONTRIBUTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/CONTRIBUTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/CONTRIBUTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/CONTRIBUTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/CONTRIBUTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/CONTRIBUTING.md) + +--- + +Thank you for your interest in contributing! This guide covers everything you need to get started. + +--- + +## Development Setup + +### Prerequisites + +- **Node.js** >= 18 < 24 (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` | `20128` | Server port | +| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | Base URL for frontend | +| `JWT_SECRET` | (generate above) | JWT signing secret | +| `INITIAL_PASSWORD` | `CHANGEME` | First login password | +| `APP_LOG_LEVEL` | `info` | Log verbosity level | + +### Dashboard Settings + +The dashboard provides UI toggles for features that can also be configured via environment variables: + +| Setting Location | Toggle | Description | +| ------------------- | ------------------ | ------------------------------ | +| Settings โ†’ Advanced | Debug Mode | Enable debug request logs (UI) | +| Settings โ†’ General | Sidebar Visibility | Show/hide sidebar sections | + +These settings are stored in the database and persist across restarts, overriding env var defaults when set. + +### 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:20128/dashboard` +- **API**: `http://localhost:20128/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`, `mcp`, `a2a`, `memory`, `skills`. + +--- + +## Running Tests + +```bash +# All tests (unit + vitest + ecosystem + e2e) +npm run test:all + +# Single test file (Node.js native test runner โ€” most tests use this) +node --import tsx/esm --test tests/unit/your-file.test.mjs + +# Vitest (MCP server, autoCombo, cache) +npm run test:vitest + +# E2E tests (requires Playwright) +npm run test:e2e + +# Protocol clients E2E (MCP transports, A2A) +npm run test:protocols:e2e + +# Ecosystem compatibility tests +npm run test:ecosystem + +# Coverage (55% min statements/lines/functions; 60% branches) +npm run test:coverage +npm run coverage:report + +# Lint + format check +npm run lint +npm run check +``` + +Coverage notes: + +- `npm run test:coverage` measures source coverage for the main unit test suite, excludes `tests/**`, and includes `open-sse/**` +- `npm run coverage:report` prints the detailed file-by-file report from the latest coverage run +- `npm run test:coverage:legacy` preserves the older metric for historical comparison +- See `docs/COVERAGE_PLAN.md` for the phased coverage improvement roadmap + +Current test status: **122 unit test files** covering: + +- Provider translators and format conversion +- Rate limiting, circuit breaker, and resilience +- Semantic cache, idempotency, progress tracking +- Database operations and schema (21 DB modules) +- OAuth flows and authentication +- API endpoint validation (Zod v4) +- MCP server tools and scope enforcement +- Memory and Skills systems + +--- + +## Code Style + +- **ESLint** โ€” Run `npm run lint` before committing +- **Prettier** โ€” Auto-formatted via `lint-staged` on commit (2 spaces, semicolons, double quotes, 100 char width, es5 trailing commas) +- **TypeScript** โ€” All `src/` code uses `.ts`/`.tsx`; `open-sse/` uses `.ts`/`.js`; document with TSDoc (`@param`, `@returns`, `@throws`) +- **No `eval()`** โ€” ESLint enforces `no-eval`, `no-implied-eval`, `no-new-func` +- **Zod validation** โ€” Use Zod v4 schemas for all API input validation +- **Naming**: Files = camelCase/kebab-case, components = PascalCase, constants = UPPER_SNAKE + +--- + +## Project Structure + +``` +src/ # TypeScript (.ts / .tsx) +โ”œโ”€โ”€ app/ # Next.js 16 App Router +โ”‚ โ”œโ”€โ”€ (dashboard)/ # Dashboard pages (23 sections) +โ”‚ โ”œโ”€โ”€ api/ # API routes (51 directories) +โ”‚ โ””โ”€โ”€ login/ # Auth pages (.tsx) +โ”œโ”€โ”€ domain/ # Policy engine (policyEngine, comboResolver, costRules, etc.) +โ”œโ”€โ”€ lib/ # Core business logic (.ts) +โ”‚ โ”œโ”€โ”€ a2a/ # Agent-to-Agent v0.3 protocol server +โ”‚ โ”œโ”€โ”€ acp/ # Agent Communication Protocol registry +โ”‚ โ”œโ”€โ”€ compliance/ # Compliance policy engine +โ”‚ โ”œโ”€โ”€ db/ # SQLite database layer (21 modules + 16 migrations) +โ”‚ โ”œโ”€โ”€ memory/ # Persistent conversational memory +โ”‚ โ”œโ”€โ”€ oauth/ # OAuth providers, services, and utilities +โ”‚ โ”œโ”€โ”€ skills/ # Extensible skill framework +โ”‚ โ”œโ”€โ”€ usage/ # Usage tracking and cost calculation +โ”‚ โ””โ”€โ”€ localDb.ts # Re-export layer only โ€” never add logic here +โ”œโ”€โ”€ middleware/ # Request middleware (promptInjectionGuard) +โ”œโ”€โ”€ mitm/ # MITM proxy (cert, DNS, target routing) +โ”œโ”€โ”€ shared/ +โ”‚ โ”œโ”€โ”€ components/ # React components (.tsx) +โ”‚ โ”œโ”€โ”€ constants/ # Provider definitions (60+), MCP scopes, routing strategies +โ”‚ โ”œโ”€โ”€ utils/ # Circuit breaker, sanitizer, auth helpers +โ”‚ โ””โ”€โ”€ validation/ # Zod v4 schemas +โ””โ”€โ”€ sse/ # SSE proxy pipeline + +open-sse/ # @omniroute/open-sse workspace +โ”œโ”€โ”€ executors/ # 14 provider-specific request executors +โ”œโ”€โ”€ handlers/ # 11 request handlers (chat, responses, embeddings, images, etc.) +โ”œโ”€โ”€ mcp-server/ # MCP server (25 tools, 3 transports, 10 scopes) +โ”œโ”€โ”€ services/ # 36+ services (combo, autoCombo, rateLimitManager, etc.) +โ”œโ”€โ”€ translator/ # Format translators (OpenAI โ†” Claude โ†” Gemini โ†” Responses โ†” Ollama) +โ”œโ”€โ”€ transformer/ # Responses API transformer +โ””โ”€โ”€ utils/ # 22 utility modules (stream, TLS, proxy, logging) + +electron/ # Electron desktop app (cross-platform) + +tests/ +โ”œโ”€โ”€ unit/ # Node.js test runner (122 test files) +โ”œโ”€โ”€ integration/ # Integration tests +โ”œโ”€โ”€ e2e/ # Playwright tests +โ”œโ”€โ”€ security/ # Security tests +โ”œโ”€โ”€ translator/ # Translator-specific tests +โ””โ”€โ”€ load/ # Load tests + +docs/ # Documentation +โ”œโ”€โ”€ ARCHITECTURE.md # System architecture +โ”œโ”€โ”€ API_REFERENCE.md # All endpoints +โ”œโ”€โ”€ USER_GUIDE.md # Provider setup, CLI integration +โ”œโ”€โ”€ TROUBLESHOOTING.md # Common issues +โ”œโ”€โ”€ MCP-SERVER.md # MCP server (25 tools) +โ”œโ”€โ”€ A2A-SERVER.md # A2A agent protocol +โ”œโ”€โ”€ AUTO-COMBO.md # Auto-combo engine +โ”œโ”€โ”€ CLI-TOOLS.md # CLI tools integration +โ”œโ”€โ”€ COVERAGE_PLAN.md # Test coverage improvement plan +โ”œโ”€โ”€ openapi.yaml # OpenAPI specification +โ””โ”€โ”€ adr/ # Architecture Decision Records +``` + +--- + +## Adding a New Provider + +### Step 1: Register Provider Constants + +Add to `src/shared/constants/providers.ts` โ€” Zod-validated at module load. + +### Step 2: Add Executor (if custom logic needed) + +Create executor in `open-sse/executors/your-provider.ts` extending the base executor. + +### Step 3: Add Translator (if non-OpenAI format) + +Create request/response translators in `open-sse/translator/`. + +### Step 4: Add OAuth Config (if OAuth-based) + +Add OAuth credentials in `src/lib/oauth/constants/oauth.ts` and service in `src/lib/oauth/services/`. + +### Step 5: Register Models + +Add model definitions in `open-sse/config/providerRegistry.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 +- [ ] All inputs validated with Zod schemas +- [ ] CHANGELOG updated (if user-facing change) +- [ ] Documentation updated (if applicable) + +--- + +## Releasing + +Releases are managed via the `/generate-release` workflow. When a new GitHub Release is created, the package is **automatically published to npm** via GitHub Actions. + +--- + +## Getting Help + +- **Architecture**: See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) +- **API Reference**: See [`docs/API_REFERENCE.md`](docs/API_REFERENCE.md) +- **Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **ADRs**: See `docs/adr/` for architectural decision records diff --git a/docs/i18n/zh-CN/FEATURES.md b/docs/i18n/zh-CN/FEATURES.md deleted file mode 100644 index 60c9ace851..0000000000 --- a/docs/i18n/zh-CN/FEATURES.md +++ /dev/null @@ -1,143 +0,0 @@ -# OmniRoute โ€” ไปช่กจ็›˜ๅŠŸ่ƒฝๅฑ•็คบ - -๐ŸŒ **่ฏญ่จ€:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/FEATURES.md) - -OmniRoute ไปช่กจ็›˜ๅ„้ƒจๅˆ†็š„ๅฏ่ง†ๅŒ–ๆŒ‡ๅ—ใ€‚ - ---- - -## ๐Ÿ”Œ ๆœๅŠกๅ•† - -็ฎก็† AI ๆœๅŠกๅ•†่ฟžๆŽฅ๏ผšOAuth ๆœๅŠกๅ•†๏ผˆClaude Codeใ€Codexใ€Gemini CLI๏ผ‰ใ€API ๅฏ†้’ฅๆœๅŠกๅ•†๏ผˆGroqใ€DeepSeekใ€OpenRouter๏ผ‰ไปฅๅŠๅ…่ดนๆœๅŠกๅ•†๏ผˆQoderใ€Qwenใ€Kiro๏ผ‰ใ€‚Kiro ่ดฆๆˆทๅŒ…ๅซ้ขๅบฆไฝ™้ข่ทŸ่ธช โ€” ๅ‰ฉไฝ™้ขๅบฆใ€ๆ€ป้…้ขๅ’Œ็ปญๆœŸๆ—ฅๆœŸๅฏๅœจ Dashboard โ†’ Usage ไธญๆŸฅ็œ‹ใ€‚ - -![Providers Dashboard](screenshots/01-providers.png) - ---- - -## ๐ŸŽจ ็ป„ๅˆ - -ๅˆ›ๅปบๅ…ทๆœ‰ 6 ็ง็ญ–็•ฅ็š„ๆจกๅž‹่ทฏ็”ฑ็ป„ๅˆ๏ผšไผ˜ๅ…ˆ็บงใ€ๅŠ ๆƒใ€่ฝฎ่ฏขใ€้šๆœบใ€ๆœ€ๅฐ‘ไฝฟ็”จๅ’Œๆˆๆœฌไผ˜ๅŒ–ใ€‚ๆฏไธช็ป„ๅˆๅฏ้“พๆŽฅๅคšไธชๆจกๅž‹ๅนถๆ”ฏๆŒ่‡ชๅŠจๅ›ž้€€๏ผŒ่ฟ˜ๅŒ…ๆ‹ฌๅฟซ้€Ÿๆจกๆฟๅ’Œๅฐฑ็ปชๆฃ€ๆŸฅใ€‚ - -![Combos Dashboard](screenshots/02-combos.png) - ---- - -## ๐Ÿ“Š ๅˆ†ๆž - -ๅ…จ้ข็š„ไฝฟ็”จๅˆ†ๆž๏ผŒๅŒ…ๆ‹ฌ token ๆถˆ่€—ใ€ๆˆๆœฌไผฐ็ฎ—ใ€ๆดปๅŠจ็ƒญๅŠ›ๅ›พใ€ๆฏๅ‘จๅˆ†ๅธƒๅ›พ่กจไปฅๅŠๆŒ‰ๆœๅŠกๅ•†็ป†ๅˆ†ใ€‚ - -![Analytics Dashboard](screenshots/03-analytics.png) - ---- - -## ๐Ÿฅ ็ณป็ปŸๅฅๅบท - -ๅฎžๆ—ถ็›‘ๆŽง๏ผš่ฟ่กŒๆ—ถ้—ดใ€ๅ†…ๅญ˜ใ€็‰ˆๆœฌใ€ๅปถ่ฟŸ็™พๅˆ†ไฝๆ•ฐ๏ผˆp50/p95/p99๏ผ‰ใ€็ผ“ๅญ˜็ปŸ่ฎกๅ’ŒๆœๅŠกๅ•†็†”ๆ–ญๅ™จ็Šถๆ€ใ€‚ - -![Health Dashboard](screenshots/04-health.png) - ---- - -## ๐Ÿ”ง ็ฟป่ฏ‘ๅ™จๆต‹่ฏ•ๅœบ - -ๅ››็ง่ฐƒ่ฏ• API ็ฟป่ฏ‘็š„ๆจกๅผ๏ผš**Playground**๏ผˆๆ ผๅผ่ฝฌๆขๅ™จ๏ผ‰ใ€**Chat Tester**๏ผˆๅฎžๆ—ถ่ฏทๆฑ‚๏ผ‰ใ€**Test Bench**๏ผˆๆ‰น้‡ๆต‹่ฏ•๏ผ‰ๅ’Œ **Live Monitor**๏ผˆๅฎžๆ—ถๆต๏ผ‰ใ€‚ - -![Translator Playground](screenshots/05-translator.png) - ---- - -## ๐ŸŽฎ ๆจกๅž‹ๆต‹่ฏ•ๅœบ _(v2.0.9+)_ - -็›ดๆŽฅไปŽไปช่กจ็›˜ๆต‹่ฏ•ไปปไฝ•ๆจกๅž‹ใ€‚้€‰ๆ‹ฉๆœๅŠกๅ•†ใ€ๆจกๅž‹ๅ’Œ็ซฏ็‚น๏ผŒไฝฟ็”จ Monaco Editor ็ผ–ๅ†™ๆ็คบ๏ผŒๅฎžๆ—ถๆตๅผๅ“ๅบ”๏ผŒๅฏไธญ้€”ไธญๆญข๏ผŒๅนถๆŸฅ็œ‹่ฎกๆ—ถๆŒ‡ๆ ‡ใ€‚ - ---- - -## ๐ŸŽจ ไธป้ข˜ _(v2.0.5+)_ - -ๆ•ดไธชไปช่กจ็›˜ๅฏ่‡ชๅฎšไน‰้ขœ่‰ฒไธป้ข˜ใ€‚ๅฏไปŽ 7 ็ง้ข„่ฎพ้ขœ่‰ฒ๏ผˆ็Š็‘š่‰ฒใ€่“่‰ฒใ€็บข่‰ฒใ€็ปฟ่‰ฒใ€็ดซ็ฝ—ๅ…ฐ่‰ฒใ€ๆฉ™่‰ฒใ€้’่‰ฒ๏ผ‰ไธญ้€‰ๆ‹ฉ๏ผŒๆˆ–้€š่ฟ‡้€‰ๆ‹ฉไปปไฝ•ๅๅ…ญ่ฟ›ๅˆถ้ขœ่‰ฒๅˆ›ๅปบ่‡ชๅฎšไน‰ไธป้ข˜ใ€‚ๆ”ฏๆŒๆต…่‰ฒใ€ๆทฑ่‰ฒๅ’Œ่ทŸ้š็ณป็ปŸๆจกๅผใ€‚ - ---- - -## โš™๏ธ ่ฎพ็ฝฎ - -ๅ…จ้ข็š„่ฎพ็ฝฎ้ขๆฟ๏ผŒๅŒ…ๅซไปฅไธ‹ๆ ‡็ญพ้กต๏ผš - -- **้€š็”จ** โ€” ็ณป็ปŸๅญ˜ๅ‚จใ€ๅค‡ไปฝ็ฎก็†๏ผˆๅฏผๅ‡บ/ๅฏผๅ…ฅๆ•ฐๆฎๅบ“๏ผ‰ -- **ๅค–่ง‚** โ€” ไธป้ข˜้€‰ๆ‹ฉๅ™จ๏ผˆๆทฑ่‰ฒ/ๆต…่‰ฒ/่ทŸ้š็ณป็ปŸ๏ผ‰ใ€้ขœ่‰ฒไธป้ข˜้ข„่ฎพๅ’Œ่‡ชๅฎšไน‰้ขœ่‰ฒใ€ๅฅๅบทๆ—ฅๅฟ—ๅฏ่งๆ€งใ€ไพง่พนๆ ้กน็›ฎๅฏ่งๆ€งๆŽงๅˆถ -- **ๅฎ‰ๅ…จ** โ€” API ็ซฏ็‚นไฟๆŠคใ€่‡ชๅฎšไน‰ๆœๅŠกๅ•†ๅฑ่”ฝใ€IP ่ฟ‡ๆปคใ€ไผš่ฏไฟกๆฏ -- **่ทฏ็”ฑ** โ€” ๆจกๅž‹ๅˆซๅใ€ๅŽๅฐไปปๅŠก้™็บง -- **ๅผนๆ€ง** โ€” ้€Ÿ็Ž‡้™ๅˆถๆŒไน…ๅŒ–ใ€็†”ๆ–ญๅ™จ่ฐƒไผ˜ใ€่‡ชๅŠจ็ฆ็”จ่ขซๅฐ็ฆ่ดฆๆˆทใ€ๆœๅŠกๅ•†่ฟ‡ๆœŸ็›‘ๆŽง -- **้ซ˜็บง** โ€” ้…็ฝฎ่ฆ†็›–ใ€้…็ฝฎๅฎก่ฎก่ฟฝ่ธชใ€ๅ›ž้€€้™็บงๆจกๅผ - -![Settings Dashboard](screenshots/06-settings.png) - ---- - -## ๐Ÿ”ง CLI ๅทฅๅ…ท - -ไธ€้”ฎ้…็ฝฎ AI ็ผ–็จ‹ๅทฅๅ…ท๏ผšClaude Codeใ€Codex CLIใ€Gemini CLIใ€OpenClawใ€Kilo Codeใ€Antigravityใ€Clineใ€Continueใ€Cursor ๅ’Œ Factory Droidใ€‚ๅ…ทๅค‡่‡ชๅŠจๅŒ–้…็ฝฎๅบ”็”จ/้‡็ฝฎใ€่ฟžๆŽฅ้…็ฝฎๆ–‡ไปถๅ’Œๆจกๅž‹ๆ˜ ๅฐ„ๅŠŸ่ƒฝใ€‚ - -![CLI Tools Dashboard](screenshots/07-cli-tools.png) - ---- - -## ๐Ÿค– CLI ไปฃ็† _(v2.0.11+)_ - -ๅ‘็Žฐๅ’Œ็ฎก็† CLI ไปฃ็†็š„ไปช่กจ็›˜ใ€‚ๆ˜พ็คบ 14 ไธชๅ†…็ฝฎไปฃ็†๏ผˆCodexใ€Claudeใ€Gooseใ€Gemini CLIใ€OpenClawใ€Aiderใ€OpenCodeใ€Clineใ€Qwen Codeใ€ForgeCodeใ€Amazon Qใ€Open Interpreterใ€Cursor CLIใ€Warp๏ผ‰็š„็ฝ‘ๆ ผ่ง†ๅ›พ๏ผŒๅ…ทๆœ‰๏ผš - -- **ๅฎ‰่ฃ…็Šถๆ€** โ€” ๅทฒๅฎ‰่ฃ… / ๆœชๆ‰พๅˆฐ๏ผŒๅธฆ็‰ˆๆœฌๆฃ€ๆต‹ -- **ๅ่ฎฎๅพฝ็ซ ** โ€” stdioใ€HTTP ็ญ‰ -- **่‡ชๅฎšไน‰ไปฃ็†** โ€” ้€š่ฟ‡่กจๅ•ๆณจๅ†Œไปปไฝ• CLI ๅทฅๅ…ท๏ผˆๅ็งฐใ€ไบŒ่ฟ›ๅˆถๆ–‡ไปถใ€็‰ˆๆœฌๅ‘ฝไปคใ€ๅฏๅŠจๅ‚ๆ•ฐ๏ผ‰ -- **CLI ๆŒ‡็บนๅŒน้…** โ€” ๆŒ‰ๆœๅŠกๅ•†ๅˆ‡ๆขไปฅๅŒน้…ๅŽŸ็”Ÿ CLI ่ฏทๆฑ‚็ญพๅ๏ผŒๅœจไฟๆŒไปฃ็† IP ็š„ๅŒๆ—ถ้™ไฝŽๅฐ็ฆ้ฃŽ้™ฉ - ---- - -## ๐Ÿ–ผ๏ธ ๅช’ไฝ“ _(v2.0.3+)_ - -ไปŽไปช่กจ็›˜็”Ÿๆˆๅ›พๅƒใ€่ง†้ข‘ๅ’Œ้Ÿณไนใ€‚ๆ”ฏๆŒ OpenAIใ€xAIใ€Togetherใ€Hyperbolicใ€SD WebUIใ€ComfyUIใ€AnimateDiffใ€Stable Audio Open ๅ’Œ MusicGenใ€‚ - ---- - -## ๐Ÿ“ ่ฏทๆฑ‚ๆ—ฅๅฟ— - -ๅฎžๆ—ถ่ฏทๆฑ‚ๆ—ฅๅฟ—๏ผŒๆ”ฏๆŒๆŒ‰ๆœๅŠกๅ•†ใ€ๆจกๅž‹ใ€่ดฆๆˆทๅ’Œ API ๅฏ†้’ฅ่ฟ‡ๆปคใ€‚ๆ˜พ็คบ็Šถๆ€็ ใ€token ไฝฟ็”จ้‡ใ€ๅปถ่ฟŸๅ’Œๅ“ๅบ”่ฏฆๆƒ…ใ€‚ - -![Usage Logs](screenshots/08-usage.png) - ---- - -## ๐ŸŒ API ็ซฏ็‚น - -ๆ‚จ็š„็ปŸไธ€ API ็ซฏ็‚น๏ผŒๅŒ…ๅซ่ƒฝๅŠ›ๅˆ†่งฃ๏ผšChat Completionsใ€Responses APIใ€Embeddingsใ€Image Generationใ€Rerankingใ€Audio Transcriptionใ€Text-to-Speechใ€Moderations ไปฅๅŠๅทฒๆณจๅ†Œ็š„ API ๅฏ†้’ฅใ€‚ๆ”ฏๆŒ Cloudflare Quick Tunnel ้›†ๆˆๅ’Œไบ‘ไปฃ็†่ฟ›่กŒ่ฟœ็จ‹่ฎฟ้—ฎใ€‚ - -![Endpoint Dashboard](screenshots/09-endpoint.png) - ---- - -## ๐Ÿ”‘ API ๅฏ†้’ฅ็ฎก็† - -ๅˆ›ๅปบใ€้™ๅฎš่Œƒๅ›ดๅ’Œๆ’ค้”€ API ๅฏ†้’ฅใ€‚ๆฏไธชๅฏ†้’ฅๅฏ้™ๅˆถไธบ็‰นๅฎšๆจกๅž‹/ๆœๅŠกๅ•†๏ผŒๅ…ทๆœ‰ๅฎŒๅ…จ่ฎฟ้—ฎๆˆ–ๅช่ฏปๆƒ้™ใ€‚ๅฏ่ง†ๅŒ–ๅฏ†้’ฅ็ฎก็†ๅŠไฝฟ็”จ่ทŸ่ธชใ€‚ - ---- - -## ๐Ÿ“‹ ๅฎก่ฎกๆ—ฅๅฟ— - -็ฎก็†ๆ“ไฝœ่ทŸ่ธช๏ผŒๆ”ฏๆŒๆŒ‰ๆ“ไฝœ็ฑปๅž‹ใ€ๆ“ไฝœ่€…ใ€็›ฎๆ ‡ใ€IP ๅœฐๅ€ๅ’Œๆ—ถ้—ดๆˆณ่ฟ‡ๆปคใ€‚ๅฎŒๆ•ด็š„ๅฎ‰ๅ…จไบ‹ไปถๅŽ†ๅฒ่ฎฐๅฝ•ใ€‚ - ---- - -## ๐Ÿ–ฅ๏ธ ๆกŒ้ขๅบ”็”จ - -้€‚็”จไบŽ Windowsใ€macOS ๅ’Œ Linux ็š„ๅŽŸ็”Ÿ Electron ๆกŒ้ขๅบ”็”จใ€‚ๅฐ† OmniRoute ไฝœไธบ็‹ฌ็ซ‹ๅบ”็”จ่ฟ่กŒ๏ผŒๅ…ทๆœ‰็ณป็ปŸๆ‰˜็›˜้›†ๆˆใ€็ฆป็บฟๆ”ฏๆŒใ€่‡ชๅŠจๆ›ดๆ–ฐๅ’Œไธ€้”ฎๅฎ‰่ฃ…ใ€‚ - -ไธป่ฆ็‰นๆ€ง๏ผš - -- ๆœๅŠกๅ™จๅฐฑ็ปช่ฝฎ่ฏข๏ผˆๅ†ทๅฏๅŠจๆ—ถๆ— ็™ฝๅฑ๏ผ‰ -- ๅธฆ็ซฏๅฃ็ฎก็†็š„็ณป็ปŸๆ‰˜็›˜ -- ๅ†…ๅฎนๅฎ‰ๅ…จ็ญ–็•ฅ -- ๅ•ๅฎžไพ‹้”ๅฎš -- ้‡ๅฏๆ—ถ่‡ชๅŠจๆ›ดๆ–ฐ -- ๅนณๅฐๆกไปถๅŒ– UI๏ผˆmacOS ็บข็ปฟ็ฏใ€Windows/Linux ้ป˜่ฎคๆ ‡้ข˜ๆ ๏ผ‰ -- ๅผบๅŒ–็š„ Electron ๆž„ๅปบๆ‰“ๅŒ… โ€” ็‹ฌ็ซ‹ๅŒ…ไธญ็š„็ฌฆๅท้“พๆŽฅ `node_modules` ไผšๅœจๆ‰“ๅŒ…ๅ‰่ขซๆฃ€ๆต‹ๅนถๆ‹’็ป๏ผŒ้˜ฒๆญขๅฏนๆž„ๅปบๆœบๅ™จ็š„่ฟ่กŒๆ—ถไพ่ต– (v2.5.5+) - -๐Ÿ“– ๅฎŒๆ•ดๆ–‡ๆกฃ่ฏทๅ‚้˜… [`electron/README.md`](../electron/README.md)ใ€‚ diff --git a/docs/i18n/zh-CN/MCP-SERVER.md b/docs/i18n/zh-CN/MCP-SERVER.md deleted file mode 100644 index 0fe4860416..0000000000 --- a/docs/i18n/zh-CN/MCP-SERVER.md +++ /dev/null @@ -1,87 +0,0 @@ -๐ŸŒ **่ฏญ่จ€:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/MCP-SERVER.md) - ---- - -# OmniRoute MCP ๆœๅŠกๅ™จๆ–‡ๆกฃ - -> Model Context Protocol ๆœๅŠกๅ™จ๏ผŒๅŒ…ๅซ 16 ไธชๆ™บ่ƒฝๅทฅๅ…ท - -## ๅฎ‰่ฃ… - -OmniRoute MCP ๅทฒๅ†…็ฝฎใ€‚ไฝฟ็”จไปฅไธ‹ๅ‘ฝไปคๅฏๅŠจ๏ผš - -```bash -omniroute --mcp -``` - -ๆˆ–้€š่ฟ‡ open-sse ไผ ่พ“ๆ–นๅผ๏ผš - -```bash -# HTTP ๅฏๆตๅผไผ ่พ“ (็ซฏๅฃ 20130) -omniroute --dev # MCP ๅœจ /mcp ็ซฏ็‚น่‡ชๅŠจๅฏๅŠจ -``` - -## IDE ้…็ฝฎ - -่ฏทๅ‚้˜… [IDE Configs](integrations/ide-configs.md) ไบ†่งฃ Antigravityใ€Cursorใ€Copilot ๅ’Œ Claude Desktop ็š„่ฎพ็ฝฎๆ–นๆณ•ใ€‚ - ---- - -## ๅŸบ็ก€ๅทฅๅ…ท (8 ไธช) - -| ๅทฅๅ…ท | ๆ่ฟฐ | -| :------------------------------ | :-------------------------------- | -| `omniroute_get_health` | ็ฝ‘ๅ…ณๅฅๅบท็Šถๆ€ใ€็†”ๆ–ญๅ™จใ€่ฟ่กŒๆ—ถ้—ด | -| `omniroute_list_combos` | ๆ‰€ๆœ‰ๅทฒ้…็ฝฎ็š„็ป„ๅˆๅŠๅ…ถๆจกๅž‹ | -| `omniroute_get_combo_metrics` | ็‰นๅฎš็ป„ๅˆ็š„ๆ€ง่ƒฝๆŒ‡ๆ ‡ | -| `omniroute_switch_combo` | ้€š่ฟ‡ ID/ๅ็งฐๅˆ‡ๆขๆดปๅŠจ็ป„ๅˆ | -| `omniroute_check_quota` | ๆŒ‰ๆœๅŠกๅ•†ๆˆ–ๅ…จ้ƒจๆŸฅ่ฏข้…้ข็Šถๆ€ | -| `omniroute_route_request` | ้€š่ฟ‡ OmniRoute ๅ‘้€่ŠๅคฉๅฎŒๆˆ่ฏทๆฑ‚ | -| `omniroute_cost_report` | ๆŒ‡ๅฎšๆ—ถ้—ดๆฎต็š„ๆˆๆœฌๅˆ†ๆž | -| `omniroute_list_models_catalog` | ๅฎŒๆ•ดๆจกๅž‹็›ฎๅฝ•ๅŠ่ƒฝๅŠ›่ฏดๆ˜Ž | - -## ้ซ˜็บงๅทฅๅ…ท (8 ไธช) - -| ๅทฅๅ…ท | ๆ่ฟฐ | -| :--------------------------------- | :------------------------------------ | -| `omniroute_simulate_route` | ๅธฆๆœ‰ๅ›ž้€€ๆ ‘็š„่ทฏ็”ฑๆจกๆ‹Ÿ๏ผˆ็ฉบ่ท‘๏ผ‰ | -| `omniroute_set_budget_guard` | ไผš่ฏ้ข„็ฎ—ๅŠ้™็บง/้˜ปๆญข/ๅ‘Š่ญฆๆ“ไฝœ | -| `omniroute_set_resilience_profile` | ๅบ”็”จไฟๅฎˆ/ๅนณ่กก/ๆฟ€่ฟ›้ข„่ฎพ | -| `omniroute_test_combo` | ๅฎžๆ—ถๆต‹่ฏ•็ป„ๅˆไธญ็š„ๆ‰€ๆœ‰ๆจกๅž‹ | -| `omniroute_get_provider_metrics` | ๅ•ไธชๆœๅŠกๅ•†็š„่ฏฆ็ป†ๆŒ‡ๆ ‡ | -| `omniroute_best_combo_for_task` | ไปปๅŠก้€‚้…ๆŽจ่ๅŠๆ›ฟไปฃๆ–นๆกˆ | -| `omniroute_explain_route` | ่งฃ้‡ŠๅŽ†ๅฒ่ทฏ็”ฑๅ†ณ็ญ– | -| `omniroute_get_session_snapshot` | ๅฎŒๆ•ดไผš่ฏ็Šถๆ€๏ผšๆˆๆœฌใ€tokenใ€้”™่ฏฏ | - -## ่บซไปฝ้ชŒ่ฏ - -MCP ๅทฅๅ…ท้€š่ฟ‡ API ๅฏ†้’ฅไฝœ็”จๅŸŸ่ฟ›่กŒ่บซไปฝ้ชŒ่ฏใ€‚ๆฏไธชๅทฅๅ…ท้œ€่ฆ็‰นๅฎš็š„ไฝœ็”จๅŸŸ๏ผš - -| ไฝœ็”จๅŸŸ | ๅทฅๅ…ท | -| :------------- | :----------------------------------------------- | -| `read:health` | get_health, get_provider_metrics | -| `read:combos` | list_combos, get_combo_metrics | -| `write:combos` | switch_combo | -| `read:quota` | check_quota | -| `write:route` | route_request, simulate_route, test_combo | -| `read:usage` | cost_report, get_session_snapshot, explain_route | -| `write:config` | set_budget_guard, set_resilience_profile | -| `read:models` | list_models_catalog, best_combo_for_task | - -## ๅฎก่ฎกๆ—ฅๅฟ— - -ๆฏไธชๅทฅๅ…ท่ฐƒ็”จ้ƒฝไผš่ฎฐๅฝ•ๅˆฐ `mcp_tool_audit`๏ผŒๅŒ…ๅซ๏ผš - -- ๅทฅๅ…ทๅ็งฐใ€ๅ‚ๆ•ฐใ€็ป“ๆžœ -- ่€—ๆ—ถ๏ผˆๆฏซ็ง’๏ผ‰ใ€ๆˆๅŠŸ/ๅคฑ่ดฅ็Šถๆ€ -- API ๅฏ†้’ฅๅ“ˆๅธŒๅ€ผใ€ๆ—ถ้—ดๆˆณ - -## ๆ–‡ไปถ - -| ๆ–‡ไปถ | ็”จ้€” | -| :------------------------------------------- | :-------------------------------- | -| `open-sse/mcp-server/server.ts` | MCP ๆœๅŠกๅ™จๅˆ›ๅปบ + 16 ไธชๅทฅๅ…ทๆณจๅ†Œ | -| `open-sse/mcp-server/transport.ts` | Stdio + HTTP ไผ ่พ“ | -| `open-sse/mcp-server/auth.ts` | API ๅฏ†้’ฅ + ไฝœ็”จๅŸŸ้ชŒ่ฏ | -| `open-sse/mcp-server/audit.ts` | ๅทฅๅ…ท่ฐƒ็”จๅฎก่ฎกๆ—ฅๅฟ— | -| `open-sse/mcp-server/tools/advancedTools.ts` | 8 ไธช้ซ˜็บงๅทฅๅ…ทๅค„็†ๅ™จ | diff --git a/docs/i18n/zh-CN/README.md b/docs/i18n/zh-CN/README.md index 23084d87eb..a28f829e7f 100644 --- a/docs/i18n/zh-CN/README.md +++ b/docs/i18n/zh-CN/README.md @@ -1,14 +1,14 @@ -# ๐Ÿš€ OmniRoute โ€” ๅ…่ดน AI ็ฝ‘ๅ…ณ +# ๐Ÿš€ OmniRoute โ€” The Free AI Gateway (ไธญๆ–‡๏ผˆ็ฎ€ไฝ“๏ผ‰) -๐ŸŒ **่ฏญ่จ€:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/README.md) --- -### ๆฐธไธๅœๆญข็ผ–็ ใ€‚ๆ™บ่ƒฝ่ทฏ็”ฑๅˆฐ**ๅ…่ดนๅ’ŒไฝŽๆˆๆœฌ AI ๆจกๅž‹**๏ผŒ่‡ชๅŠจๅŽๅค‡ใ€‚ +### Never stop coding. Smart routing to **FREE & low-cost AI models** with automatic fallback. -_ๆ‚จ็š„้€š็”จ API ไปฃ็† โ€” ไธ€ไธช็ซฏ็‚น๏ผŒ67+ ไธชๆไพ›ๅ•†๏ผŒ้›ถๅœๆœบใ€‚็Žฐๅทฒๆ”ฏๆŒ **MCP ๅ’Œ A2A** ๆ™บ่ƒฝไฝ“็ผ–ๆŽ’ใ€‚_ +_Your universal API proxy โ€” one endpoint, 60+ providers, zero downtime. Now with **MCP Server (25 tools)**, **A2A Protocol**, **Memory/Skills Systems** & **Electron Desktop App**._ -**่ŠๅคฉๅฎŒๆˆ โ€ข Embedding โ€ข ๅ›พๅƒ็”Ÿๆˆ โ€ข ่ง†้ข‘ โ€ข ้Ÿณไน โ€ข ้Ÿณ้ข‘ โ€ข ้‡ๆŽ’ๅบ โ€ข **Web ๆœ็ดข** โ€ข MCP Server โ€ข A2A ๅ่ฎฎ โ€ข 100% TypeScript** +**Chat Completions โ€ข Embeddings โ€ข Image Generation โ€ข Video โ€ข Music โ€ข Audio โ€ข Reranking โ€ข **Web Search** โ€ข MCP Server โ€ข A2A Protocol โ€ข 100% TypeScript** --- @@ -22,126 +22,128 @@ _ๆ‚จ็š„้€š็”จ API ไปฃ็† โ€” ไธ€ไธช็ซฏ็‚น๏ผŒ67+ ไธชๆไพ›ๅ•†๏ผŒ้›ถๅœๆœบใ€‚็Žฐ [![Website](https://img.shields.io/badge/Website-omniroute.online-blue?logo=google-chrome&logoColor=white)](https://omniroute.online) [![WhatsApp](https://img.shields.io/badge/WhatsApp-Community-25D366?logo=whatsapp&logoColor=white)](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) -[๐ŸŒ ็ฝ‘็ซ™](https://omniroute.online) โ€ข [๐Ÿš€ ๅฟซ้€Ÿๅผ€ๅง‹](#-ๅฟซ้€Ÿๅผ€ๅง‹) โ€ข [๐Ÿ’ก ๅŠŸ่ƒฝ](#-ไธป่ฆๅŠŸ่ƒฝ) โ€ข [๐Ÿ“– ๆ–‡ๆกฃ](#-ๆ–‡ๆกฃ) โ€ข [๐Ÿ’ฐ ๅฎšไปท](#-ๅฎšไปทไธ€่งˆ) โ€ข [๐Ÿ’ฌ WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) +[๐ŸŒ Website](https://omniroute.online) โ€ข [๐Ÿš€ Quick Start](#-quick-start) โ€ข [๐Ÿ’ก Features](#-key-features) โ€ข [๐Ÿ“– Docs](#-documentation) โ€ข [๐Ÿ’ฐ Pricing](#-pricing-at-a-glance) โ€ข [๐Ÿ’ฌ WhatsApp](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) -๐ŸŒ **ๅฏ็”จ่ฏญ่จ€:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../README.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](../pt-BR/README.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](../es/README.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](../fr/README.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](../it/README.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](../ru/README.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](../zh-CN/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](../de/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](../in/README.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](../th/README.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](../uk-UA/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](../ar/README.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](../ja/README.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](../vi/README.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](../bg/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](../da/README.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](../fi/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](../he/README.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](../hu/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](../id/README.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](../ko/README.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](../ms/README.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](../nl/README.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](../no/README.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](../pt/README.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](../ro/README.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](../pl/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](../sk/README.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](../sv/README.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](../phi/README.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](../cs/README.md) +๐ŸŒ **Available in:** ๐Ÿ‡บ๐Ÿ‡ธ [English](README.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](docs/i18n/pt-BR/README.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](docs/i18n/es/README.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](docs/i18n/fr/README.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](docs/i18n/it/README.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](docs/i18n/ru/README.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](docs/i18n/zh-CN/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](docs/i18n/de/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](docs/i18n/in/README.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](docs/i18n/th/README.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](docs/i18n/uk-UA/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](docs/i18n/ar/README.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](docs/i18n/ja/README.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](docs/i18n/vi/README.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](docs/i18n/bg/README.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](docs/i18n/da/README.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](docs/i18n/fi/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](docs/i18n/he/README.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](docs/i18n/hu/README.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](docs/i18n/id/README.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](docs/i18n/ko/README.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](docs/i18n/ms/README.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](docs/i18n/nl/README.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](docs/i18n/no/README.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](docs/i18n/pt/README.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](docs/i18n/ro/README.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](docs/i18n/pl/README.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](docs/i18n/sk/README.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](docs/i18n/sv/README.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](docs/i18n/phi/README.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](docs/i18n/cs/README.md) --- -## ็ ดๅๆ€งๅ˜ๆ›ด๏ผš็ปŸไธ€ๆ—ฅๅฟ—ๅ‡็บง +## Breaking Change: Unified Logging Upgrade > [!WARNING] -> **ๆญค็‰ˆๆœฌ้‡ๆ–ฐ่ฎพ่ฎกไบ†็ฃ็›˜ไธŠ็š„่ฏทๆฑ‚ๆ—ฅๅฟ—ๅธƒๅฑ€ไปฅๅŠๆ—ฅๅฟ—็›ธๅ…ณ็Žฏๅขƒๅ˜้‡ใ€‚** +> **This release changes both the on-disk request log layout and the logging environment variables.** > -> ๅฆ‚ๆžœไฝ ๆญฃๅœจๅ‡็บง็Žฐๆœ‰ๅฎžไพ‹๏ผš +> If you are upgrading an existing instance: > -> - ่ฏทๆฑ‚ๆ—ฅๅฟ—็ŽฐๅœจไฝไบŽ `DATA_DIR/call_logs/YYYY-MM-DD/`๏ผŒๅนถไปฅ**ๆฏไธช่ฏทๆฑ‚ไธ€ไธช JSON artifact** ็š„ๅฝขๅผๅญ˜ๅ‚จใ€‚ -> - ๆ—ง็š„ `DATA_DIR/logs/` ไผš่ฏ็›ฎๅฝ•ๅ’Œ `DATA_DIR/log.txt` ๆฑ‡ๆ€ปๆ–‡ไปถๅทฒ่ขซ็งป้™คใ€‚ -> - ๅ‡็บงๅŽ็š„้ฆ–ๆฌกๅฏๅŠจๆ—ถ๏ผŒOmniRoute ไผšๅ…ˆๅœจ `DATA_DIR/log_archives/*.zip` ไธญๅˆ›ๅปบๅฎ‰ๅ…จๅค‡ไปฝ๏ผŒๅ†ๅˆ ้™คๆ—งๆ—ฅๅฟ—ๅธƒๅฑ€ใ€‚ -> - ๆ—ง็‰ˆๆ—ฅๅฟ—็Žฏๅขƒๅ˜้‡ๅฆ‚ `LOG_TO_FILE`ใ€`LOG_FILE_PATH`ใ€`LOG_MAX_FILE_SIZE`ใ€`LOG_RETENTION_DAYS`ใ€`LOG_LEVEL`ใ€`LOG_FORMAT`ใ€`ENABLE_REQUEST_LOGS`ใ€`CALL_LOGS_MAX`ใ€`CALL_LOG_PAYLOAD_MODE` ๅ’Œ `PROXY_LOG_MAX_ENTRIES` ๅทฒไธๅ†ๆ”ฏๆŒใ€‚ -> - ่ฏทๆ”น็”จๆ–ฐ็š„็Žฏๅขƒๅ˜้‡ๆจกๅž‹๏ผš +> - Request logs now live in `DATA_DIR/call_logs/YYYY-MM-DD/` as **one JSON artifact per request**. +> - The old `DATA_DIR/logs/` session folders and `DATA_DIR/log.txt` summary file are removed. +> - On the first startup after upgrading, OmniRoute creates a safety backup at `DATA_DIR/log_archives/*.zip` before removing the deprecated request log layout. +> - Legacy logging env vars such as `LOG_TO_FILE`, `LOG_FILE_PATH`, `LOG_MAX_FILE_SIZE`, `LOG_RETENTION_DAYS`, `LOG_LEVEL`, `LOG_FORMAT`, `ENABLE_REQUEST_LOGS`, `CALL_LOGS_MAX`, `CALL_LOG_PAYLOAD_MODE`, and `PROXY_LOG_MAX_ENTRIES` are no longer supported. +> - Use the new env model instead: > - `APP_LOG_TO_FILE` > - `APP_LOG_FILE_PATH` > - `APP_LOG_MAX_FILE_SIZE` > - `APP_LOG_RETENTION_DAYS` +> - `APP_LOG_MAX_FILES` > - `APP_LOG_LEVEL` > - `APP_LOG_FORMAT` > - `CALL_LOG_RETENTION_DAYS` +> - `CALL_LOG_MAX_ENTRIES` > -> ่ฏฆ็ป†ๅ‘ๅธƒไฟกๆฏๅ’Œๅ‡็บง่ฏดๆ˜Ž่ฏทๅ‚้˜… [CHANGELOG](../../../CHANGELOG.md)ใ€‚ +> For release details and upgrade notes, see the [CHANGELOG](CHANGELOG.md). --- -## ๐Ÿ†• v3.0.0 ๆ–ฐๅŠŸ่ƒฝ +## ๐Ÿ†• What's New -> **ไปŽ v2.9.5 ๅ‡็บง๏ผŸ** โ€” ๆŸฅ็œ‹[ๅฎŒๆ•ดๆ›ดๆ–ฐๆ—ฅๅฟ—](../../../CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main)ไบ†่งฃๆ‰€ๆœ‰ๆ›ดๆ”นใ€‚ +> **Upgrading from v2.9.5?** โ€” See the [full CHANGELOG](CHANGELOG.md#300--2026-03-22-release-candidate--not-yet-merged-to-main) for all changes. -| ้ข†ๅŸŸ | ๆ›ดๆ”น | -| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | -| ๐Ÿ”’ **CodeQL ๅฎ‰ๅ…จ** | ไฟฎๅคไบ† 10+ ไธช CodeQL ่ญฆๆŠฅ๏ผšpolynomial-redosใ€insecure-randomnessใ€shell-injection ไฟฎๅค | -| โœ… **่ทฏ็”ฑ้ชŒ่ฏ** | ๆ‰€ๆœ‰ 176 ไธช API ่ทฏ็”ฑ็Žฐๅทฒไฝฟ็”จ Zod ๆจกๅผ + `validateBody()` ้ชŒ่ฏ โ€” CI `check:route-validation:t06` ้€š่ฟ‡ | -| ๐Ÿ› **omniModel ๆ ‡็ญพๆณ„้œฒ** | ๅ†…้ƒจ `` ๆ ‡็ญพไธๅ†ๆณ„้œฒๅˆฐ SSE ๆตๅผๅ“ๅบ”ไธญ็š„ๅฎขๆˆท็ซฏ (#585) | -| ๐Ÿ”‘ **ๆณจๅ†Œๅฏ†้’ฅ API** | ้€š่ฟ‡ `POST /api/v1/registered-keys` ่‡ชๅŠจ้…็ฝฎ API ๅฏ†้’ฅ๏ผŒๆ”ฏๆŒๆฏๆไพ›ๅ•†/่ดฆๆˆท้…้ขๆ‰ง่กŒใ€ๅน‚็ญ‰ๆ€งใ€SHA-256 ๅญ˜ๅ‚จๅ’Œๅฏ้€‰ GitHub issue ๆŠฅๅ‘Š | -| ๐ŸŽจ **ๆไพ›ๅ•†ๅ›พๆ ‡** | ้€š่ฟ‡ `@lobehub/icons` (SVG) ๆไพ› 130+ ไธชๆไพ›ๅ•† Logo๏ผŒๅธฆ PNG โ†’ ้€š็”จๅŽๅค‡้“พ | -| ๐Ÿ”„ **ๆจกๅž‹่‡ชๅŠจๅŒๆญฅ** | 24 ๅฐๆ—ถ่ฐƒๅบฆๅ™จๅ’Œๆ‰‹ๅŠจ UI ๅˆ‡ๆข๏ผŒ็”จไบŽๅŒๆญฅๅ†…็ฝฎๅ’Œ่‡ชๅฎšไน‰ OpenAI ๅ…ผๅฎนๆไพ›ๅ•†็š„ๆจกๅž‹ๅˆ—่กจ | -| ๐ŸŒ **OpenCode Zen/Go** | ๆฅ่‡ช @kang-heewon ้€š่ฟ‡ PR #530 ็š„ไธคไธชๆ–ฐๆไพ›ๅ•†๏ผšๅ…่ดนๅฑ‚ + ่ฎข้˜…ๅฑ‚๏ผŒ้€š่ฟ‡ `OpencodeExecutor` | -| ๐Ÿ› **Gemini CLI OAuth** | Docker ไธญ็ผบๅฐ‘ `GEMINI_OAUTH_CLIENT_SECRET` ๆ—ถ็š„ๅฏๆ“ไฝœ้”™่ฏฏ๏ผˆไน‹ๅ‰ๆ˜ฏๆ™ฆๆถฉ็š„ Google ้”™่ฏฏ๏ผ‰ | -| ๐Ÿ› **OpenCode ้…็ฝฎ** | `saveOpenCodeConfig()` ็Žฐๅœจๆญฃ็กฎๅ†™ๅ…ฅ TOML ๅˆฐ `XDG_CONFIG_HOME` | -| ๐Ÿ› **ๅ›บๅฎšๆจกๅž‹่ฆ†็›–** | `body.model` ๅœจไธŠไธ‹ๆ–‡็ผ“ๅญ˜ไฟๆŠคๆ—ถๆญฃ็กฎ่ฎพ็ฝฎไธบ `pinnedModel` | -| ๐Ÿ› **Codex/Claude ๅพช็Žฏ** | `tool_result` ๅ—็Žฐๅœจ่ฝฌๆขไธบๆ–‡ๆœฌไปฅๅœๆญขๆ— ้™ๅพช็Žฏ | -| ๐Ÿ› **็™ปๅฝ•้‡ๅฎšๅ‘** | ่ทณ่ฟ‡ๅฏ†็ ่ฎพ็ฝฎๅŽ็™ปๅฝ•ไธๅ†ๅ†ป็ป“ | -| ๐Ÿ› **Windows ่ทฏๅพ„** | MSYS2/Git-Bash ่ทฏๅพ„ (`/c/...`) ่‡ชๅŠจ่ง„่ŒƒๅŒ–ไธบ `C:\...` | +| Area | Change | +| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| ๐Ÿ”’ **CodeQL Security** | Fixed 10+ CodeQL alerts: polynomial-redos, insecure-randomness, shell-injection remediation | +| โœ… **Route Validation** | All 176 API routes now validated with Zod schemas + `validateBody()` โ€” CI `check:route-validation:t06` passes | +| ๐Ÿ› **omniModel Tag Leak** | Internal `` tags no longer leak to clients in SSE streaming responses (#585) | +| ๐Ÿ”‘ **Registered Keys API** | Auto-provision API keys via `POST /api/v1/registered-keys` with per-provider/account quota enforcement, idempotency, SHA-256 storage, and optional GitHub issue reporting | +| ๐ŸŽจ **Provider Icons** | 130+ provider logos via `@lobehub/icons` (SVG) with PNG โ†’ generic fallback chain | +| ๐Ÿ”„ **Model Auto-Sync** | 24h scheduler and manual UI toggle to sync model lists for built-in and custom OpenAI-compatible providers | +| ๐ŸŒ **OpenCode Zen/Go** | Two new providers from @kang-heewon via PR #530: free tier + subscription tier via `OpencodeExecutor` | +| ๐Ÿ› **Gemini CLI OAuth** | Actionable error when `GEMINI_OAUTH_CLIENT_SECRET` is missing in Docker (was cryptic Google error) | +| ๐Ÿ› **OpenCode config** | `saveOpenCodeConfig()` now correctly writes TOML to `XDG_CONFIG_HOME` | +| ๐Ÿ› **Pinned model override** | `body.model` correctly set to `pinnedModel` on context-cache protection | +| ๐Ÿ› **Codex/Claude loop** | `tool_result` blocks now converted to text to stop infinite loops | +| ๐Ÿ› **Login redirect** | Login no longer freezes after skipping password setup | +| ๐Ÿ› **Windows paths** | MSYS2/Git-Bash paths (`/c/...`) normalized to `C:\...` automatically | --- -## ๐Ÿ–ผ๏ธ ไธปไปช่กจ็›˜ +## ๐Ÿ–ผ๏ธ Main Dashboard
- OmniRoute ไปช่กจ็›˜ + OmniRoute Dashboard
--- -## ๐Ÿ“ธ ไปช่กจ็›˜้ข„่งˆ +## ๐Ÿ“ธ Dashboard Preview
-็‚นๅ‡ปๆŸฅ็œ‹ไปช่กจ็›˜ๆˆชๅ›พ +Click to see dashboard screenshots -| ้กต้ข | ๆˆชๅ›พ | -| ------------ | ------------------------------------------------------- | -| **ๆไพ›ๅ•†** | ![ๆไพ›ๅ•†](../../../docs/screenshots/01-providers.png) | -| **Combo** | ![Combo](../../../docs/screenshots/02-combos.png) | -| **ๅˆ†ๆž** | ![ๅˆ†ๆž](../../../docs/screenshots/03-analytics.png) | -| **ๅฅๅบท** | ![ๅฅๅบท](../../../docs/screenshots/04-health.png) | -| **็ฟป่ฏ‘ๅ™จ** | ![็ฟป่ฏ‘ๅ™จ](../../../docs/screenshots/05-translator.png) | -| **่ฎพ็ฝฎ** | ![่ฎพ็ฝฎ](../../../docs/screenshots/06-settings.png) | -| **CLI ๅทฅๅ…ท** | ![CLI ๅทฅๅ…ท](../../../docs/screenshots/07-cli-tools.png) | -| **ไฝฟ็”จๆ—ฅๅฟ—** | ![ไฝฟ็”จ](../../../docs/screenshots/08-usage.png) | -| **็ซฏ็‚น** | ![็ซฏ็‚น](../../../docs/screenshots/09-endpoint.png) | +| Page | Screenshot | +| -------------- | ------------------------------------------------- | +| **Providers** | ![Providers](docs/screenshots/01-providers.png) | +| **Combos** | ![Combos](docs/screenshots/02-combos.png) | +| **Analytics** | ![Analytics](docs/screenshots/03-analytics.png) | +| **Health** | ![Health](docs/screenshots/04-health.png) | +| **Translator** | ![Translator](docs/screenshots/05-translator.png) | +| **Settings** | ![Settings](docs/screenshots/06-settings.png) | +| **CLI Tools** | ![CLI Tools](docs/screenshots/07-cli-tools.png) | +| **Usage Logs** | ![Usage](docs/screenshots/08-usage.png) | +| **Endpoints** | ![Endpoints](docs/screenshots/09-endpoint.png) |
--- -### ๐Ÿค– ไธบๆ‚จๅ–œ็ˆฑ็š„็ผ–็ ๆ™บ่ƒฝไฝ“ๆไพ›ๅ…่ดน AI ๆไพ›ๅ•† +### ๐Ÿค– Free AI Provider for your favorite coding agents -_้€š่ฟ‡ OmniRoute ่ฟžๆŽฅไปปไฝ• AI ้ฉฑๅŠจ็š„ IDE ๆˆ– CLI ๅทฅๅ…ท โ€” ๆ— ้™็ผ–็ ็š„ๅ…่ดน API ็ฝ‘ๅ…ณใ€‚_ +_Connect any AI-powered IDE or CLI tool through OmniRoute โ€” free API gateway for unlimited coding._
- OpenClaw
+ OpenClaw
OpenClaw
โญ 205K 		- NanoBot
+ NanoBot
NanoBot
โญ 20.9K 		- PicoClaw
+ PicoClaw
PicoClaw
โญ 14.6K 		- ZeroClaw
+ ZeroClaw
ZeroClaw
โญ 9.9K 		- IronClaw
+ IronClaw
IronClaw
โญ 2.1K @@ -150,35 +152,35 @@ _้€š่ฟ‡ OmniRoute ่ฟžๆŽฅไปปไฝ• AI ้ฉฑๅŠจ็š„ IDE ๆˆ– CLI ๅทฅๅ…ท โ€” ๆ— ้™็ผ–็ 
- OpenCode
+ OpenCode
OpenCode
โญ 106K 		- Codex CLI
+ Codex CLI
Codex CLI
โญ 60.8K 		- Claude Code
+ Claude Code
Claude Code
โญ 67.3K 		- Gemini CLI
+ Gemini CLI
Gemini CLI
โญ 94.7K 		- Kilo Code
+ Kilo Code
Kilo Code
โญ 15.5K @@ -186,527 +188,527 @@ _้€š่ฟ‡ OmniRoute ่ฟžๆŽฅไปปไฝ• AI ้ฉฑๅŠจ็š„ IDE ๆˆ– CLI ๅทฅๅ…ท โ€” ๆ— ้™็ผ–็ 
-๐Ÿ“ก ๆ‰€ๆœ‰ๆ™บ่ƒฝไฝ“้€š่ฟ‡ http://localhost:20128/v1 ๆˆ– http://cloud.omniroute.online/v1 ่ฟžๆŽฅ โ€” ไธ€ไธช้…็ฝฎ๏ผŒๆ— ้™ๆจกๅž‹ๅ’Œ้…้ข +๐Ÿ“ก All agents connect via http://localhost:20128/v1 or http://cloud.omniroute.online/v1 โ€” one config, unlimited models and quota --- -## ๐Ÿค” ไธบไป€ไนˆ้€‰ๆ‹ฉ OmniRoute๏ผŸ +## ๐Ÿค” Why OmniRoute? -**ๅœๆญขๆตช่ดน้‡‘้’ฑๅ’Œ็ขฐๅˆฐ้™ๅˆถ๏ผš** +**Stop wasting money and hitting limits:** -- ่ฎข้˜…้…้ขๆฏๆœˆๆœชไฝฟ็”จๅฐฑ่ฟ‡ๆœŸ -- ้€Ÿ็Ž‡้™ๅˆถ่ฎฉไฝ ๅœจ็ผ–็ ไธญ้€”ๅœๆญข -- ๆ˜‚่ดต็š„ API๏ผˆๆฏไธชๆไพ›ๅ•† $20-50/ๆœˆ๏ผ‰ -- ๆ‰‹ๅŠจๅœจๆไพ›ๅ•†ไน‹้—ดๅˆ‡ๆข +- Subscription quota expires unused every month +- Rate limits stop you mid-coding +- Expensive APIs ($20-50/month per provider) +- Manual switching between providers -**OmniRoute ่งฃๅ†ณ่ฟ™ไบ›้—ฎ้ข˜๏ผš** +**OmniRoute solves this:** -- โœ… **ๆœ€ๅคงๅŒ–่ฎข้˜…** - ่ฟฝ่ธช้…้ข๏ผŒๅœจ้‡็ฝฎๅ‰็”จๅฎŒๆฏไธ€็‚น -- โœ… **่‡ชๅŠจๅŽๅค‡** - ่ฎข้˜… โ†’ API ๅฏ†้’ฅ โ†’ ไพฟๅฎœ โ†’ ๅ…่ดน๏ผŒ้›ถๅœๆœบ -- โœ… **ๅคš่ดฆๆˆท** - ๆฏไธชๆไพ›ๅ•†ๅคš่ดฆๆˆท่ฝฎ่ฏข -- โœ… **้€š็”จ** - ้€‚็”จไบŽ Claude Codeใ€Codexใ€Gemini CLIใ€Cursorใ€Clineใ€OpenClawใ€ไปปไฝ• CLI ๅทฅๅ…ท +- โœ… **Maximize subscriptions** - Track quota, use every bit before reset +- โœ… **Auto fallback** - Subscription โ†’ API Key โ†’ Cheap โ†’ Free, zero downtime +- โœ… **Multi-account** - Round-robin between accounts per provider +- โœ… **Universal** - Works with Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, any CLI tool --- -## ๐Ÿ“ง ๆ”ฏๆŒ +## ๐Ÿ“ง Support -> ๐Ÿ’ฌ **ๅŠ ๅ…ฅๆˆ‘ไปฌ็š„็คพๅŒบ๏ผ** [WhatsApp ็พค็ป„](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) โ€” ่Žทๅ–ๅธฎๅŠฉใ€ๅˆ†ไบซๆŠ€ๅทงๅนถไฟๆŒๆ›ดๆ–ฐใ€‚ +> ๐Ÿ’ฌ **Join our community!** [WhatsApp Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) โ€” Get help, share tips, and stay updated. -- **็ฝ‘็ซ™**๏ผš[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) -- **WhatsApp**๏ผš[็คพๅŒบ็พค็ป„](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) -- **่ดก็Œฎ**๏ผšๆŸฅ็œ‹ [CONTRIBUTING.md](../../../CONTRIBUTING.md)๏ผŒๅผ€ๅฏ PR๏ผŒๆˆ–้€‰ๆ‹ฉไธ€ไธช `good first issue` -- **ๅŽŸๅง‹้กน็›ฎ**๏ผš[9router by decolua](https://github.com/decolua/9router) +- **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) +- **WhatsApp**: [Community Group](https://chat.whatsapp.com/JI7cDQ1GyaiDHhVBpLxf8b?mode=gi_t) +- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md), open a PR, or pick a `good first issue` +- **Original Project**: [9router by decolua](https://github.com/decolua/9router) -### ๐Ÿ› ๆŠฅๅ‘Š Bug๏ผŸ +### ๐Ÿ› Reporting a Bug? -ๅผ€ๅฏ issue ๆ—ถ๏ผŒ่ฏท่ฟ่กŒ็ณป็ปŸไฟกๆฏๅ‘ฝไปคๅนถ้™„ไธŠ็”Ÿๆˆ็š„ๆ–‡ไปถ๏ผš +When opening an issue, please run the system-info command and attach the generated file: ```bash npm run system-info ``` -่ฟ™ไผš็”Ÿๆˆไธ€ไธช `system-info.txt`๏ผŒๅŒ…ๅซไฝ ็š„ Node.js ็‰ˆๆœฌใ€OmniRoute ็‰ˆๆœฌใ€ๆ“ไฝœ็ณป็ปŸ่ฏฆๆƒ…ใ€ๅทฒๅฎ‰่ฃ…็š„ CLI ๅทฅๅ…ท๏ผˆiflowใ€geminiใ€claudeใ€codexใ€antigravityใ€droid ็ญ‰๏ผ‰ใ€Docker/PM2 ็Šถๆ€ๅ’Œ็ณป็ปŸๅŒ… โ€” ๆˆ‘ไปฌๅฟซ้€Ÿ้‡็Žฐ้—ฎ้ข˜ๆ‰€้œ€็š„ไธ€ๅˆ‡ใ€‚็›ดๆŽฅๅฐ†ๆ–‡ไปถ้™„ๅŠ ๅˆฐไฝ ็š„ GitHub issueใ€‚ +This generates a `system-info.txt` with your Node.js version, OmniRoute version, OS details, installed CLI tools (qoder, gemini, claude, codex, antigravity, droid, etc.), Docker/PM2 status, and system packages โ€” everything we need to reproduce your issue quickly. Attach the file directly to your GitHub issue. --- -## ๐Ÿ”„ ๅทฅไฝœๅŽŸ็† +## ๐Ÿ”„ How It Works ``` โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” -โ”‚ ไฝ ็š„ CLI โ”‚ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...) -โ”‚ ๅทฅๅ…ท โ”‚ +โ”‚ Your CLI โ”‚ (Claude Code, Codex, Gemini CLI, OpenClaw, Cursor, Cline...) +โ”‚ Tool โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ http://localhost:20128/v1 โ†“ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” -โ”‚ OmniRoute๏ผˆๆ™บ่ƒฝ่ทฏ็”ฑๅ™จ๏ผ‰ โ”‚ -โ”‚ โ€ข ๆ ผๅผ็ฟป่ฏ‘๏ผˆOpenAI โ†” Claude๏ผ‰ โ”‚ -โ”‚ โ€ข ้…้ข่ฟฝ่ธช + Embedding + ๅ›พๅƒ โ”‚ -โ”‚ โ€ข ่‡ชๅŠจ Token ๅˆทๆ–ฐ โ”‚ +โ”‚ OmniRoute (Smart Router) โ”‚ +โ”‚ โ€ข Format translation (OpenAI โ†” Claude) โ”‚ +โ”‚ โ€ข Quota tracking + Embeddings + Images โ”‚ +โ”‚ โ€ข Auto token refresh โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ - โ”œโ”€โ†’ [ๅฑ‚็บง 1๏ผš่ฎข้˜…] Claude Code, Codex, Gemini CLI - โ”‚ โ†“ ้…้ข่€—ๅฐฝ - โ”œโ”€โ†’ [ๅฑ‚็บง 2๏ผšAPI ๅฏ†้’ฅ] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM ็ญ‰ - โ”‚ โ†“ ้ข„็ฎ—้™ๅˆถ - โ”œโ”€โ†’ [ๅฑ‚็บง 3๏ผšไพฟๅฎœ] GLM ($0.6/1M), MiniMax ($0.2/1M) - โ”‚ โ†“ ้ข„็ฎ—้™ๅˆถ - โ””โ”€โ†’ [ๅฑ‚็บง 4๏ผšๅ…่ดน] Qoderใ€Qwenใ€Kiro๏ผˆๆ— ้™๏ผ‰ + โ”œโ”€โ†’ [Tier 1: SUBSCRIPTION] Claude Code, Codex, Gemini CLI + โ”‚ โ†“ quota exhausted + โ”œโ”€โ†’ [Tier 2: API KEY] DeepSeek, Groq, xAI, Mistral, NVIDIA NIM, etc. + โ”‚ โ†“ budget limit + โ”œโ”€โ†’ [Tier 3: CHEAP] GLM ($0.6/1M), MiniMax ($0.2/1M) + โ”‚ โ†“ budget limit + โ””โ”€โ†’ [Tier 4: FREE] Qoder, Qwen, Kiro (unlimited) -็ป“ๆžœ๏ผšๆฐธไธๅœๆญข็ผ–็ ๏ผŒๆœ€ๅฐๆˆๆœฌ +Result: Never stop coding, minimal cost ``` --- -## ๐ŸŽฏ OmniRoute ่งฃๅ†ณ็š„้—ฎ้ข˜ โ€” 30 ไธช็œŸๅฎž็—›็‚นๅ’Œ็”จไพ‹ +## ๐ŸŽฏ What OmniRoute Solves โ€” 30 Real Pain Points & Use Cases -> **ๆฏไธชไฝฟ็”จ AI ๅทฅๅ…ท็š„ๅผ€ๅ‘่€…ๆฏๅคฉ้ƒฝ้ขไธด่ฟ™ไบ›้—ฎ้ข˜ใ€‚** OmniRoute ๆ—จๅœจ่งฃๅ†ณๆ‰€ๆœ‰้—ฎ้ข˜ โ€” ไปŽๆˆๆœฌ่ถ…ๆ”ฏๅˆฐๅŒบๅŸŸๅฐ้”๏ผŒไปŽๆŸๅ็š„ OAuth ๆต็จ‹ๅˆฐๅ่ฎฎๆ“ไฝœๅ’Œไผไธšๅฏ่ง‚ๆต‹ๆ€งใ€‚ +> **Every developer using AI tools faces these problems daily.** OmniRoute was built to solve them all โ€” from cost overruns to regional blocks, from broken OAuth flows to protocol operations and enterprise observability.
-๐Ÿ’ธ 1. "ๆˆ‘ไธบๆ˜‚่ดต็š„่ฎข้˜…ไป˜่ดน๏ผŒไฝ†ไป็„ถ่ขซ้™ๅˆถๆ‰“ๆ–ญ" +๐Ÿ’ธ 1. "I pay for an expensive subscription but still get interrupted by limits" -ๅผ€ๅ‘่€…ๆฏๆœˆไธบ Claude Proใ€Codex Pro ๆˆ– GitHub Copilot ๆ”ฏไป˜ $20โ€“200ใ€‚ๅณไฝฟไป˜่ดน๏ผŒ้…้ขไนŸๆœ‰ไธŠ้™ โ€” 5 ๅฐๆ—ถไฝฟ็”จใ€ๆฏๅ‘จ้™ๅˆถๆˆ–ๆฏๅˆ†้’Ÿ้€Ÿ็Ž‡้™ๅˆถใ€‚ๅœจ็ผ–็ ไผš่ฏไธญ้€”๏ผŒๆไพ›ๅ•†ๅœๆญขๅ“ๅบ”๏ผŒๅผ€ๅ‘่€…ๅคฑๅŽปๅฟƒๆตๅ’Œ็”ŸไบงๅŠ›ใ€‚ +Developers pay $20โ€“200/month for Claude Pro, Codex Pro, or GitHub Copilot. Even paying, quota has a ceiling โ€” 5h of usage, weekly limits, or per-minute rate limits. Mid-coding session, the provider stops responding and the developer loses flow and productivity. -**OmniRoute ๅฆ‚ไฝ•่งฃๅ†ณ๏ผš** +**How OmniRoute solves it:** -- **ๆ™บ่ƒฝ 4 ๅฑ‚ๅŽๅค‡** โ€” ๅฆ‚ๆžœ่ฎข้˜…้…้ข็”จๅฎŒ๏ผŒ่‡ชๅŠจ้‡ๅฎšๅ‘ๅˆฐ API ๅฏ†้’ฅ โ†’ ไพฟๅฎœ โ†’ ๅ…่ดน๏ผŒ้›ถๆ‰‹ๅŠจๅนฒ้ข„ -- **ๅฎžๆ—ถ้…้ข่ฟฝ่ธช** โ€” ๆ˜พ็คบๅฎžๆ—ถ Token ๆถˆ่€—ๅ’Œ้‡็ฝฎๅ€’่ฎกๆ—ถ๏ผˆ5hใ€ๆฏๆ—ฅใ€ๆฏๅ‘จ๏ผ‰ -- **ๅคš่ดฆๆˆทๆ”ฏๆŒ** โ€” ๆฏไธชๆไพ›ๅ•†ๅคš่ดฆๆˆท่‡ชๅŠจ่ฝฎ่ฏข โ€” ๅฝ“ไธ€ไธช็”จๅฎŒๆ—ถ๏ผŒๅˆ‡ๆขๅˆฐไธ‹ไธ€ไธช -- **่‡ชๅฎšไน‰ Combo** โ€” ๅฏ่‡ชๅฎšไน‰็š„ๅŽๅค‡้“พ๏ผŒ6 ็งๅนณ่กก็ญ–็•ฅ๏ผˆๅกซๅ……ไผ˜ๅ…ˆใ€่ฝฎ่ฏขใ€P2Cใ€้šๆœบใ€ๆœ€ๅฐ‘ไฝฟ็”จใ€ๆˆๆœฌไผ˜ๅŒ–๏ผ‰ -- **Codex ๅ•†ไธš้…้ข** โ€” ็›ดๆŽฅๅœจไปช่กจ็›˜ไธญ็›‘ๆŽงๅ•†ไธš/ๅ›ข้˜ŸๅทฅไฝœๅŒบ้…้ข +- **Smart 4-Tier Fallback** โ€” If subscription quota runs out, automatically redirects to API Key โ†’ Cheap โ†’ Free with zero manual intervention +- **Real-Time Quota Tracking** โ€” Shows token consumption in real-time with reset countdown (5h, daily, weekly) +- **Multi-Account Support** โ€” Multiple accounts per provider with auto round-robin โ€” when one runs out, switches to the next +- **Custom Combos** โ€” Customizable fallback chains with 9 balancing strategies (priority, weighted, fill-first, round-robin, P2C, random, least-used, cost-optimized, strict-random) +- **Codex Business Quotas** โ€” Business/Team workspace quota monitoring directly in the dashboard
-๐Ÿ”Œ 2. "ๆˆ‘้œ€่ฆไฝฟ็”จๅคšไธชๆไพ›ๅ•†๏ผŒไฝ†ๆฏไธช้ƒฝๆœ‰ไธๅŒ็š„ API" +๐Ÿ”Œ 2. "I need to use multiple providers but each has a different API" -OpenAI ไฝฟ็”จไธ€็งๆ ผๅผ๏ผŒClaude๏ผˆAnthropic๏ผ‰ไฝฟ็”จๅฆไธ€็ง๏ผŒGemini ๅˆๆ˜ฏๅฆไธ€็งใ€‚ๅฆ‚ๆžœๅผ€ๅ‘่€…ๆƒณๆต‹่ฏ•ๆฅ่‡ชไธๅŒๆไพ›ๅ•†็š„ๆจกๅž‹ๆˆ–ๅœจๅฎƒไปฌไน‹้—ดๅŽๅค‡๏ผŒไป–ไปฌ้œ€่ฆ้‡ๆ–ฐ้…็ฝฎ SDKใ€ๆ›ดๆ”น็ซฏ็‚นใ€ๅค„็†ไธๅ…ผๅฎน็š„ๆ ผๅผใ€‚่‡ชๅฎšไน‰ๆไพ›ๅ•†๏ผˆFriendLIใ€NIM๏ผ‰ๆœ‰้žๆ ‡ๅ‡†็š„ๆจกๅž‹็ซฏ็‚นใ€‚ +OpenAI uses one format, Claude (Anthropic) uses another, Gemini yet another. If a dev wants to test models from different providers or fallback between them, they need to reconfigure SDKs, change endpoints, deal with incompatible formats. Custom providers (FriendLI, NIM) have non-standard model endpoints. -**OmniRoute ๅฆ‚ไฝ•่งฃๅ†ณ๏ผš** +**How OmniRoute solves it:** -- **็ปŸไธ€็ซฏ็‚น** โ€” ๅ•ไธช `http://localhost:20128/v1` ไฝœไธบๆ‰€ๆœ‰ 67+ ไธชๆไพ›ๅ•†็š„ไปฃ็† -- **ๆ ผๅผ็ฟป่ฏ‘** โ€” ่‡ชๅŠจไธ”้€ๆ˜Ž๏ผšOpenAI โ†” Claude โ†” Gemini โ†” Responses API -- **ๅ“ๅบ”ๆธ…็†** โ€” ๅ‰ฅ็ฆป็ ดๅ OpenAI SDK v1.83+ ็š„้žๆ ‡ๅ‡†ๅญ—ๆฎต๏ผˆ`x_groq`ใ€`usage_breakdown`ใ€`service_tier`๏ผ‰ -- **่ง’่‰ฒ่ง„่ŒƒๅŒ–** โ€” ไธบ้ž OpenAI ๆไพ›ๅ•†่ฝฌๆข `developer` โ†’ `system`๏ผ›ไธบ GLM/ERNIE ่ฝฌๆข `system` โ†’ `user` -- **Think ๆ ‡็ญพๆๅ–** โ€” ไปŽ DeepSeek R1 ็ญ‰ๆจกๅž‹ไธญๆๅ– `` ๅ—ๅˆฐๆ ‡ๅ‡†ๅŒ–็š„ `reasoning_content` -- **Gemini ็ป“ๆž„ๅŒ–่พ“ๅ‡บ** โ€” `json_schema` โ†’ `responseMimeType`/`responseSchema` ่‡ชๅŠจ่ฝฌๆข -- **`stream` ้ป˜่ฎคไธบ `false`** โ€” ไธŽ OpenAI ่ง„่Œƒๅฏน้ฝ๏ผŒ้ฟๅ… Python/Rust/Go SDK ไธญๆ„ๅค–็š„ SSE +- **Unified Endpoint** โ€” A single `http://localhost:20128/v1` serves as proxy for all 60+ providers +- **Format Translation** โ€” Automatic and transparent: OpenAI โ†” Claude โ†” Gemini โ†” Responses API +- **Response Sanitization** โ€” Strips non-standard fields (`x_groq`, `usage_breakdown`, `service_tier`) that break OpenAI SDK v1.83+ +- **Role Normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI providers; `system` โ†’ `user` for GLM/ERNIE +- **Think Tag Extraction** โ€” Extracts `` blocks from models like DeepSeek R1 into standardized `reasoning_content` +- **Structured Output for Gemini** โ€” `json_schema` โ†’ `responseMimeType`/`responseSchema` automatic conversion +- **`stream` defaults to `false`** โ€” Aligns with OpenAI spec, avoiding unexpected SSE in Python/Rust/Go SDKs
-๐ŸŒ 3. "ๆˆ‘็š„ AI ๆไพ›ๅ•†ๅฐ้”ไบ†ๆˆ‘็š„ๅœฐๅŒบ/ๅ›ฝๅฎถ" +๐ŸŒ 3. "My AI provider blocks my region/country" -OpenAI/Codex ็ญ‰ๆไพ›ๅ•†ๅฐ้”ๆฅ่‡ชๆŸไบ›ๅœฐ็†ๅŒบๅŸŸ็š„่ฎฟ้—ฎใ€‚็”จๆˆทๅœจ OAuth ๅ’Œ API ่ฟžๆŽฅๆœŸ้—ดๆ”ถๅˆฐ `unsupported_country_region_territory` ็ญ‰้”™่ฏฏใ€‚่ฟ™ๅฏนๆฅ่‡ชๅ‘ๅฑ•ไธญๅ›ฝๅฎถ็š„ๅผ€ๅ‘่€…ๅฐคๅ…ถไปคไบบๆฒฎไธงใ€‚ +Providers like OpenAI/Codex block access from certain geographic regions. Users get errors like `unsupported_country_region_territory` during OAuth and API connections. This is especially frustrating for developers from developing countries. -**OmniRoute ๅฆ‚ไฝ•่งฃๅ†ณ๏ผš** +**How OmniRoute solves it:** -- **3 ็บงไปฃ็†้…็ฝฎ** โ€” 3 ไธช็บงๅˆซ็š„ๅฏ้…็ฝฎไปฃ็†๏ผšๅ…จๅฑ€๏ผˆๆ‰€ๆœ‰ๆต้‡๏ผ‰ใ€ๆฏๆไพ›ๅ•†๏ผˆไป…ไธ€ไธชๆไพ›ๅ•†๏ผ‰ๅ’Œๆฏ่ฟžๆŽฅ/ๅฏ†้’ฅ -- **้ขœ่‰ฒ็ผ–็ ไปฃ็†ๅพฝ็ซ ** โ€” ๅฏ่ง†ๅŒ–ๆŒ‡็คบๅ™จ๏ผš๐ŸŸข ๅ…จๅฑ€ไปฃ็†ใ€๐ŸŸก ๆไพ›ๅ•†ไปฃ็†ใ€๐Ÿ”ต ่ฟžๆŽฅไปฃ็†๏ผŒๅง‹็ปˆๆ˜พ็คบ IP -- **้€š่ฟ‡ไปฃ็†็š„ OAuth Token ไบคๆข** โ€” OAuth ๆต็จ‹ไนŸ้€š่ฟ‡ไปฃ็†๏ผŒ่งฃๅ†ณ `unsupported_country_region_territory` -- **้€š่ฟ‡ไปฃ็†็š„่ฟžๆŽฅๆต‹่ฏ•** โ€” ่ฟžๆŽฅๆต‹่ฏ•ไฝฟ็”จ้…็ฝฎ็š„ไปฃ็†๏ผˆไธๅ†็›ดๆŽฅ็ป•่ฟ‡๏ผ‰ -- **SOCKS5 ๆ”ฏๆŒ** โ€” ๅฎŒๆ•ด็š„ SOCKS5 ไปฃ็†ๆ”ฏๆŒ็”จไบŽๅ‡บ็ซ™่ทฏ็”ฑ -- **TLS ๆŒ‡็บนไผช่ฃ…** โ€” ้€š่ฟ‡ `wreq-js` ๅฎž็Žฐ็ฑปๆต่งˆๅ™จ TLS ๆŒ‡็บนไปฅ็ป•่ฟ‡ๆœบๅ™จไบบๆฃ€ๆต‹ -- **๐Ÿ” CLI ๆŒ‡็บนๅŒน้…** โ€” ้‡ๆ–ฐๆŽ’ๅบ่ฏทๆฑ‚ๅคดๅ’Œ่ฏทๆฑ‚ไฝ“ๅญ—ๆฎตไปฅๅŒน้…ๅŽŸ็”Ÿ CLI ไบŒ่ฟ›ๅˆถ็ญพๅ๏ผŒๅคงๅน…้™ไฝŽ่ดฆๆˆทๆ ‡่ฎฐ้ฃŽ้™ฉใ€‚ไปฃ็† IP ่ขซไฟ็•™ โ€” ไฝ ๅŒๆ—ถ่Žทๅพ—้š่บซ**ๅ’Œ** IP ๆŽฉ่”ฝ +- **3-Level Proxy Config** โ€” Configurable proxy at 3 levels: global (all traffic), per-provider (one provider only), and per-connection/key +- **Color-Coded Proxy Badges** โ€” Visual indicators: ๐ŸŸข global proxy, ๐ŸŸก provider proxy, ๐Ÿ”ต connection proxy, always showing the IP +- **OAuth Token Exchange Through Proxy** โ€” OAuth flow also goes through the proxy, solving `unsupported_country_region_territory` +- **Connection Tests via Proxy** โ€” Connection tests use the configured proxy (no more direct bypass) +- **SOCKS5 Support** โ€” Full SOCKS5 proxy support for outbound routing +- **TLS Fingerprint Spoofing** โ€” Browser-like TLS fingerprint via `wreq-js` to bypass bot detection +- **๐Ÿ” CLI Fingerprint Matching** โ€” Reorders headers and body fields to match native CLI binary signatures, drastically reducing account flagging risk. The proxy IP is preserved โ€” you get both stealth **and** IP masking simultaneously
-๐Ÿ†“ 4. "ๆˆ‘ๆƒณไฝฟ็”จ AI ็ผ–็ ไฝ†ๆฒก้’ฑ" +๐Ÿ†“ 4. "I want to use AI for coding but I have no money" -ๅนถ้žๆฏไธชไบบ้ƒฝ่ƒฝๆฏๆœˆๆ”ฏไป˜ $20โ€“200 ็š„ AI ่ฎข้˜…่ดน็”จใ€‚ๅญฆ็”Ÿใ€ๆฅ่‡ชๆ–ฐๅ…ดๅ›ฝๅฎถ็š„ๅผ€ๅ‘่€…ใ€ไธšไฝ™็ˆฑๅฅฝ่€…ๅ’Œ่‡ช็”ฑ่Œไธš่€…้œ€่ฆไปฅ้›ถๆˆๆœฌ่ฎฟ้—ฎไผ˜่ดจๆจกๅž‹ใ€‚ +Not everyone can pay $20โ€“200/month for AI subscriptions. Students, devs from emerging countries, hobbyists, and freelancers need access to quality models at zero cost. -**OmniRoute ๅฆ‚ไฝ•่งฃๅ†ณ๏ผš** +**How OmniRoute solves it:** -- **ๅ†…็ฝฎๅ…่ดนๅฑ‚ๆไพ›ๅ•†** โ€” ๅŽŸ็”Ÿๆ”ฏๆŒ 100% ๅ…่ดนๆไพ›ๅ•†๏ผšQoder๏ผˆ้€š่ฟ‡ OAuth ็š„ 5 ไธชๆ— ้™ๆจกๅž‹๏ผškimi-k2-thinkingใ€qwen3-coder-plusใ€deepseek-r1ใ€minimax-m2ใ€kimi-k2๏ผ‰ใ€Qwen๏ผˆ4 ไธชๆ— ้™ๆจกๅž‹๏ผšqwen3-coder-plusใ€qwen3-coder-flashใ€qwen3-coder-nextใ€vision-model๏ผ‰ใ€Kiro๏ผˆๅ…่ดน็š„ Claude + AWS Builder ID๏ผ‰ใ€Gemini CLI๏ผˆๆฏๆœˆ 180K Token ๅ…่ดน๏ผ‰ -- **Ollama Cloud** โ€” `api.ollama.com` ไธŠ็š„ไบ‘ๆ‰˜็ฎก Ollama ๆจกๅž‹๏ผŒๅธฆๅ…่ดน"่ฝปๅบฆไฝฟ็”จ"ๅฑ‚็บง๏ผ›ไฝฟ็”จ `ollamacloud/` ๅ‰็ผ€ -- **็บฏๅ…่ดน Combo** โ€” ้“พๆŽฅ `gc/gemini-3-flash โ†’ if/kimi-k2-thinking โ†’ qw/qwen3-coder-plus` = $0/ๆœˆ๏ผŒ้›ถๅœๆœบ -- **NVIDIA NIM ๅ…่ดน่ฎฟ้—ฎ** โ€” ๅœจ build.nvidia.com ไธŠๆฐธไน…ๅ…่ดนๅผ€ๅ‘่ฎฟ้—ฎ 70+ ไธชๆจกๅž‹๏ผŒ็บฆ 40 RPM๏ผˆไปŽ็งฏๅˆ†่ฟ‡ๆธกๅˆฐ็บฏ้€Ÿ็Ž‡้™ๅˆถ๏ผ‰ -- **ๆˆๆœฌไผ˜ๅŒ–็ญ–็•ฅ** โ€” ่‡ชๅŠจ้€‰ๆ‹ฉๆœ€ไพฟๅฎœๅฏ็”จๆไพ›ๅ•†็š„่ทฏ็”ฑ็ญ–็•ฅ +- **Free Tier Providers Built-in** โ€” Native support for 100% free providers: Qoder (5 unlimited models via OAuth: kimi-k2-thinking, qwen3-coder-plus, deepseek-r1, minimax-m2, kimi-k2), Qwen (4 unlimited models: qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next, vision-model), Kiro (Claude + AWS Builder ID for free), Gemini CLI (180K tokens/month free) +- **Ollama Cloud** โ€” Cloud-hosted Ollama models at `api.ollama.com` with free "Light usage" tier; use `ollamacloud/` prefix +- **Free-Only Combos** โ€” Chain `gc/gemini-3-flash โ†’ if/kimi-k2-thinking โ†’ qw/qwen3-coder-plus` = $0/month with zero downtime +- **NVIDIA NIM Free Access** โ€” ~40 RPM dev-forever free access to 70+ models at build.nvidia.com (transitioning from credits to pure rate limits) +- **Cost Optimized Strategy** โ€” Routing strategy that automatically chooses the cheapest available provider
-๐Ÿ”’ 5. "ๆˆ‘้œ€่ฆไฟๆŠคๆˆ‘็š„ AI ็ฝ‘ๅ…ณๅ…ๅ—ๆœชๆŽˆๆƒ่ฎฟ้—ฎ" +๐Ÿ”’ 5. "I need to protect my AI gateway from unauthorized access" -ๅฐ† AI ็ฝ‘ๅ…ณๆšด้œฒๅˆฐ็ฝ‘็ปœ๏ผˆLANใ€VPSใ€Docker๏ผ‰ๆ—ถ๏ผŒไปปไฝ•ๆœ‰ๅœฐๅ€็š„ไบบ้ƒฝๅฏไปฅๆถˆ่€—ๅผ€ๅ‘่€…็š„ Token/้…้ขใ€‚ๆฒกๆœ‰ไฟๆŠค๏ผŒAPI ๅฎนๆ˜“่ขซๆปฅ็”จใ€ๆ็คบ่ฏๆณจๅ…ฅๅ’Œๆปฅ็”จใ€‚ +When exposing an AI gateway to the network (LAN, VPS, Docker), anyone with the address can consume the developer's tokens/quota. Without protection, APIs are vulnerable to misuse, prompt injection, and abuse. -**OmniRoute ๅฆ‚ไฝ•่งฃๅ†ณ๏ผš** +**How OmniRoute solves it:** -- **API ๅฏ†้’ฅ็ฎก็†** โ€” ๅœจไธ“็”จ็š„ `/dashboard/api-manager` ้กต้ขๆŒ‰ๆไพ›ๅ•†็”Ÿๆˆใ€่ฝฎๆขๅ’Œ่Œƒๅ›ด็•Œๅฎš -- **ๆจกๅž‹็บงๆƒ้™** โ€” ๅฐ† API ๅฏ†้’ฅ้™ๅˆถไธบ็‰นๅฎšๆจกๅž‹๏ผˆ`openai/*`ใ€้€š้…็ฌฆๆจกๅผ๏ผ‰๏ผŒๅธฆๅ…่ฎธๅ…จ้ƒจ/้™ๅˆถๅˆ‡ๆข -- **API ็ซฏ็‚นไฟๆŠค** โ€” `/v1/models` ้œ€่ฆๅฏ†้’ฅ๏ผŒๅนถไปŽๅˆ—่กจไธญ้˜ปๆญข็‰นๅฎšๆไพ›ๅ•† -- **่ฎค่ฏๅฎˆๅซ + CSRF ไฟๆŠค** โ€” ๆ‰€ๆœ‰ Dashboard ่ทฏ็”ฑ้ƒฝไฝฟ็”จ `withAuth` ไธญ้—ดไปถ + CSRF Token ไฟๆŠค -- **้€Ÿ็Ž‡้™ๅˆถๅ™จ** โ€” ๆฏ IP ้€Ÿ็Ž‡้™ๅˆถ๏ผŒๅฏ้…็ฝฎๆ—ถ้—ด็ช—ๅฃ -- **IP ่ฟ‡ๆปค** โ€” ็™ฝๅๅ•/้ป‘ๅๅ•็”จไบŽ่ฎฟ้—ฎๆŽงๅˆถ -- **ๆ็คบ่ฏๆณจๅ…ฅๅฎˆๅซ** โ€” ้’ˆๅฏนๆถๆ„ๆ็คบ่ฏๆจกๅผ็š„ๆธ…็† -- **AES-256-GCM ๅŠ ๅฏ†** โ€” ้™ๆ€ๅ‡ญ่ฏๅŠ ๅฏ† +- **API Key Management** โ€” Generation, rotation, and scoping per provider with a dedicated `/dashboard/api-manager` page +- **Model-Level Permissions** โ€” Restrict API keys to specific models (`openai/*`, wildcard patterns), with Allow All/Restrict toggle +- **API Endpoint Protection** โ€” Require a key for `/v1/models` and block specific providers from the listing +- **Auth Guard + CSRF Protection** โ€” All dashboard routes protected with `withAuth` middleware + CSRF tokens +- **Rate Limiter** โ€” Per-IP rate limiting with configurable windows +- **IP Filtering** โ€” Allowlist/blocklist for access control +- **Prompt Injection Guard** โ€” Sanitization against malicious prompt patterns +- **AES-256-GCM Encryption** โ€” Credentials encrypted at rest
-๐Ÿ›‘ 6. "ๆˆ‘็š„ๆไพ›ๅ•†ๅฎ•ๆœบ๏ผŒๆˆ‘ๅคฑๅŽปไบ†็ผ–็ ๅฟƒๆต" +๐Ÿ›‘ 6. "My provider went down and I lost my coding flow" -AI ๆไพ›ๅ•†ๅฏ่ƒฝๅ˜ๅพ—ไธ็จณๅฎšใ€่ฟ”ๅ›ž 5xx ้”™่ฏฏๆˆ–่พพๅˆฐไธดๆ—ถ้€Ÿ็Ž‡้™ๅˆถใ€‚ๅฆ‚ๆžœๅผ€ๅ‘่€…ไพ่ต–ๅ•ไธชๆไพ›ๅ•†๏ผŒไป–ไปฌไผš่ขซไธญๆ–ญใ€‚ๆฒกๆœ‰็†”ๆ–ญๅ™จ๏ผŒ้‡ๅค้‡่ฏ•ๅฏ่ƒฝไผšไฝฟๅบ”็”จ็จ‹ๅบๅดฉๆบƒใ€‚ +AI providers can become unstable, return 5xx errors, or hit temporary rate limits. If a dev depends on a single provider, they're interrupted. Without circuit breakers, repeated retries can crash the application. -**OmniRoute ๅฆ‚ไฝ•่งฃๅ†ณ๏ผš** +**How OmniRoute solves it:** -- **ๆฏๆจกๅž‹็†”ๆ–ญๅ™จ** โ€” ไฝฟ็”จๅฏ้…็ฝฎ้˜ˆๅ€ผๅ’Œๅ†ทๅด่‡ชๅŠจๆ‰“ๅผ€/ๅ…ณ้—ญ๏ผˆClosed/Open/Half-Open๏ผ‰๏ผŒๆŒ‰ๆจกๅž‹่Œƒๅ›ด็•Œๅฎšไปฅ้ฟๅ…็บง่”้˜ปๅกž -- **ๆŒ‡ๆ•ฐ้€€้ฟ** โ€” ๆธ่ฟ›ๅผ้‡่ฏ•ๅปถ่ฟŸ -- **้˜ฒๆƒŠ็พค** โ€” ไบ’ๆ–ฅ้” + ไฟกๅท้‡ไฟๆŠค๏ผŒ้˜ฒๆญขๅนถๅ‘้‡่ฏ•้ฃŽๆšด -- **Combo ๅŽๅค‡้“พ** โ€” ๅฆ‚ๆžœไธปๆไพ›ๅ•†ๅคฑ่ดฅ๏ผŒ่‡ชๅŠจ้€š่ฟ‡้“พๆกๅŽๅค‡๏ผŒๆ— ้œ€ๅนฒ้ข„ -- **Combo ็†”ๆ–ญๅ™จ** โ€” ่‡ชๅŠจ็ฆ็”จ Combo ้“พไธญๅคฑ่ดฅ็š„ๆไพ›ๅ•† -- **ๅฅๅบทไปช่กจ็›˜** โ€” ๆญฃๅธธ่ฟ่กŒๆ—ถ้—ด็›‘ๆŽงใ€็†”ๆ–ญๅ™จ็Šถๆ€ใ€้”ๅฎšใ€็ผ“ๅญ˜็ปŸ่ฎกใ€p50/p95/p99 ๅปถ่ฟŸ +- **Circuit Breaker per-model** โ€” Auto-open/close with configurable thresholds and cooldown (Closed/Open/Half-Open), scoped per-model to avoid cascading blocks +- **Exponential Backoff** โ€” Progressive retry delays +- **Anti-Thundering Herd** โ€” Mutex + semaphore protection against concurrent retry storms +- **Combo Fallback Chains** โ€” If the primary provider fails, automatically falls through the chain with no intervention +- **Combo Circuit Breaker** โ€” Auto-disables failing providers within a combo chain +- **Health Dashboard** โ€” Uptime monitoring, circuit breaker states, lockouts, cache stats, p50/p95/p99 latency
-๐Ÿ”ง 7. "้…็ฝฎๆฏไธช AI ๅทฅๅ…ทๆ—ข็น็ๅˆ้‡ๅค" +๐Ÿ”ง 7. "Configuring each AI tool is tedious and repetitive" -ๅผ€ๅ‘่€…ไฝฟ็”จ Cursorใ€Claude Codeใ€Codex CLIใ€OpenClawใ€Gemini CLIใ€Kilo Code... ๆฏไธชๅทฅๅ…ท้œ€่ฆไธๅŒ็š„้…็ฝฎ๏ผˆAPI ็ซฏ็‚นใ€ๅฏ†้’ฅใ€ๆจกๅž‹๏ผ‰ใ€‚ๅˆ‡ๆขๆไพ›ๅ•†ๆˆ–ๆจกๅž‹ๆ—ถ้‡ๆ–ฐ้…็ฝฎๆตช่ดนๆ—ถ้—ดใ€‚ +Developers use Cursor, Claude Code, Codex CLI, OpenClaw, Gemini CLI, Kilo Code... Each tool needs a different config (API endpoint, key, model). Reconfiguring when switching providers or models is a waste of time. -**OmniRoute ๅฆ‚ไฝ•่งฃๅ†ณ๏ผš** +**How OmniRoute solves it:** -- **CLI ๅทฅๅ…ทไปช่กจ็›˜** โ€” ไธ“็”จ้กต้ข๏ผŒไธ€้”ฎ่ฎพ็ฝฎ Claude Codeใ€Codex CLIใ€OpenClawใ€Kilo Codeใ€Antigravityใ€Cline -- **GitHub Copilot ้…็ฝฎ็”Ÿๆˆๅ™จ** โ€” ไธบ VS Code ็”Ÿๆˆ `chatLanguageModels.json`๏ผŒๆ‰น้‡้€‰ๆ‹ฉๆจกๅž‹ -- **ๅ…ฅ้—จๅ‘ๅฏผ** โ€” ไธบ้ฆ–ๆฌก็”จๆˆทๆไพ›ๆŒ‡ๅฏผ็š„ 4 ๆญฅ่ฎพ็ฝฎ -- **ไธ€ไธช็ซฏ็‚น๏ผŒๆ‰€ๆœ‰ๆจกๅž‹** โ€” ้…็ฝฎไธ€ๆฌก `http://localhost:20128/v1`๏ผŒ่ฎฟ้—ฎ 67+ ไธชๆไพ›ๅ•† +- **CLI Tools Dashboard** โ€” Dedicated page with one-click setup for Claude Code, Codex CLI, OpenClaw, Kilo Code, Antigravity, Cline +- **GitHub Copilot Config Generator** โ€” Generates `chatLanguageModels.json` for VS Code with bulk model selection +- **Onboarding Wizard** โ€” Guided 4-step setup for first-time users +- **One endpoint, all models** โ€” Configure `http://localhost:20128/v1` once, access 60+ providers
-๐Ÿ”‘ 8. "็ฎก็†ๆฅ่‡ชๅคšไธชๆไพ›ๅ•†็š„ OAuth Token ๆ˜ฏๅœฐ็‹ฑ" +๐Ÿ”‘ 8. "Managing OAuth tokens from multiple providers is hell" -Claude Codeใ€Codexใ€Gemini CLIใ€Copilot โ€” ๅ…จ้ƒจไฝฟ็”จๅธฆ่ฟ‡ๆœŸ Token ็š„ OAuth 2.0ใ€‚ๅผ€ๅ‘่€…้œ€่ฆไธๆ–ญ้‡ๆ–ฐ่ฎค่ฏ๏ผŒๅค„็† `client_secret is missing`ใ€`redirect_uri_mismatch` ๅ’Œ่ฟœ็จ‹ๆœๅŠกๅ™จไธŠ็š„ๅคฑ่ดฅใ€‚LAN/VPS ไธŠ็š„ OAuth ๅฐคๅ…ถๆˆ้—ฎ้ข˜ใ€‚ +Claude Code, Codex, Gemini CLI, Copilot โ€” all use OAuth 2.0 with expiring tokens. Developers need to re-authenticate constantly, deal with `client_secret is missing`, `redirect_uri_mismatch`, and failures on remote servers. OAuth on LAN/VPS is particularly problematic. -**OmniRoute ๅฆ‚ไฝ•่งฃๅ†ณ๏ผš** +**How OmniRoute solves it:** -- **่‡ชๅŠจ Token ๅˆทๆ–ฐ** โ€” OAuth Token ๅœจ่ฟ‡ๆœŸๅ‰ๅœจๅŽๅฐๅˆทๆ–ฐ -- **ๅ†…็ฝฎ OAuth 2.0๏ผˆPKCE๏ผ‰** โ€” Claude Codeใ€Codexใ€Gemini CLIใ€Copilotใ€Kiroใ€Qwenใ€Qoder ็š„่‡ชๅŠจๆต็จ‹ -- **ๅคš่ดฆๆˆท OAuth** โ€” ้€š่ฟ‡ JWT/ID Token ๆๅ–็š„ๆฏๆไพ›ๅ•†ๅคš่ดฆๆˆท -- **OAuth LAN/่ฟœ็จ‹ไฟฎๅค** โ€” `redirect_uri` ็š„็งๆœ‰ IP ๆฃ€ๆต‹ + ่ฟœ็จ‹ๆœๅŠกๅ™จ็š„ๆ‰‹ๅŠจ URL ๆจกๅผ -- **Nginx ๅŽ็š„ OAuth** โ€” ไฝฟ็”จ `window.location.origin` ๅฎž็Žฐๅๅ‘ไปฃ็†ๅ…ผๅฎนๆ€ง -- **่ฟœ็จ‹ OAuth ๆŒ‡ๅ—** โ€” VPS/Docker ไธŠ Google Cloud ๅ‡ญ่ฏ็š„ๅˆ†ๆญฅๆŒ‡ๅ— +- **Auto Token Refresh** โ€” OAuth tokens refresh in background before expiration +- **OAuth 2.0 (PKCE) Built-in** โ€” Automatic flow for Claude Code, Codex, Gemini CLI, Copilot, Kiro, Qwen, Qoder +- **Multi-Account OAuth** โ€” Multiple accounts per provider via JWT/ID token extraction +- **OAuth LAN/Remote Fix** โ€” Private IP detection for `redirect_uri` + manual URL mode for remote servers +- **OAuth Behind Nginx** โ€” Uses `window.location.origin` for reverse proxy compatibility +- **Remote OAuth Guide** โ€” Step-by-step guide for Google Cloud credentials on VPS/Docker
-๐Ÿ“Š 9. "ๆˆ‘ไธ็Ÿฅ้“่Šฑไบ†ๅคšๅฐ‘้’ฑๆˆ–่Šฑๅœจๅ“ช้‡Œ" +๐Ÿ“Š 9. "I don't know how much I'm spending or where" -ๅผ€ๅ‘่€…ไฝฟ็”จๅคšไธชไป˜่ดนๆไพ›ๅ•†ไฝ†ๆฒกๆœ‰็ปŸไธ€็š„ๆ”ฏๅ‡บ่ง†ๅ›พใ€‚ๆฏไธชๆไพ›ๅ•†้ƒฝๆœ‰่‡ชๅทฑ็š„่ฎก่ดนไปช่กจ็›˜๏ผŒไฝ†ๆฒกๆœ‰ๅˆๅนถ่ง†ๅ›พใ€‚ๆ„ๅค–ๆˆๆœฌๅฏ่ƒฝไผš็ดฏ็งฏใ€‚ +Developers use multiple paid providers but have no unified view of spending. Each provider has its own billing dashboard, but there's no consolidated view. Unexpected costs can pile up. -**OmniRoute ๅฆ‚ไฝ•่งฃๅ†ณ๏ผš** +**How OmniRoute solves it:** -- **ๆˆๆœฌๅˆ†ๆžไปช่กจ็›˜** โ€” ๆฏๆไพ›ๅ•†็š„ๆฏ Token ๆˆๆœฌ่ฟฝ่ธชๅ’Œ้ข„็ฎ—็ฎก็† -- **ๆฏๅฑ‚็บง้ข„็ฎ—้™ๅˆถ** โ€” ๆฏๅฑ‚็บงๆ”ฏๅ‡บไธŠ้™๏ผŒ่งฆๅ‘่‡ชๅŠจๅŽๅค‡ -- **ๆฏๆจกๅž‹ๅฎšไปท้…็ฝฎ** โ€” ๆฏๆจกๅž‹ๅฏ้…็ฝฎไปทๆ ผ -- **ๆฏ API ๅฏ†้’ฅไฝฟ็”จ็ปŸ่ฎก** โ€” ๆฏๅฏ†้’ฅ็š„่ฏทๆฑ‚่ฎกๆ•ฐๅ’Œๆœ€ๅŽไฝฟ็”จๆ—ถ้—ดๆˆณ -- **ๅˆ†ๆžไปช่กจ็›˜** โ€” ็ปŸ่ฎกๅกใ€ๆจกๅž‹ไฝฟ็”จๅ›พ่กจใ€ๅธฆๆˆๅŠŸ็Ž‡ๅ’Œๅปถ่ฟŸ็š„ๆไพ›ๅ•†่กจ +- **Cost Analytics Dashboard** โ€” Per-token cost tracking and budget management per provider +- **Budget Limits per Tier** โ€” Spending ceiling per tier that triggers automatic fallback +- **Per-Model Pricing Configuration** โ€” Configurable prices per model +- **Usage Statistics Per API Key** โ€” Request count and last-used timestamp per key +- **Analytics Dashboard** โ€” Stat cards, model usage chart, provider table with success rates and latency
-๐Ÿ› 10. "ๆˆ‘ๆ— ๆณ•่ฏŠๆ–ญ AI ่ฐƒ็”จไธญ็š„้”™่ฏฏๅ’Œ้—ฎ้ข˜" +๐Ÿ› 10. "I can't diagnose errors and problems in AI calls" -ๅฝ“่ฐƒ็”จๅคฑ่ดฅๆ—ถ๏ผŒๅผ€ๅ‘่€…ไธ็Ÿฅ้“ๆ˜ฏ้€Ÿ็Ž‡้™ๅˆถใ€่ฟ‡ๆœŸ Tokenใ€้”™่ฏฏๆ ผๅผ่ฟ˜ๆ˜ฏๆไพ›ๅ•†้”™่ฏฏใ€‚ไธๅŒ็ปˆ็ซฏ็š„ๅˆ†ๆ•ฃๆ—ฅๅฟ—ใ€‚ๆฒกๆœ‰ๅฏ่ง‚ๆต‹ๆ€ง๏ผŒ่ฐƒ่ฏ•ๅฐฑๆ˜ฏ่ฏ•้”™ใ€‚ +When a call fails, the dev doesn't know if it was a rate limit, expired token, wrong format, or provider error. Fragmented logs across different terminals. Without observability, debugging is trial-and-error. -**OmniRoute ๅฆ‚ไฝ•่งฃๅ†ณ๏ผš** +**How OmniRoute solves it:** -- **็ปŸไธ€ๆ—ฅๅฟ—ไปช่กจ็›˜** โ€” 4 ไธชๆ ‡็ญพ้กต๏ผš่ฏทๆฑ‚ๆ—ฅๅฟ—ใ€ไปฃ็†ๆ—ฅๅฟ—ใ€ๅฎก่ฎกๆ—ฅๅฟ—ใ€ๆŽงๅˆถๅฐ -- **ๆŽงๅˆถๅฐๆ—ฅๅฟ—ๆŸฅ็œ‹ๅ™จ** โ€” ๅฎžๆ—ถ็ปˆ็ซฏ้ฃŽๆ ผๆŸฅ็œ‹ๅ™จ๏ผŒๅธฆ้ขœ่‰ฒ็ผ–็ ็บงๅˆซใ€่‡ชๅŠจๆปšๅŠจใ€ๆœ็ดขใ€่ฟ‡ๆปค -- **SQLite ไปฃ็†ๆ—ฅๅฟ—** โ€” ๆŒไน…ๅŒ–ๆ—ฅๅฟ—๏ผŒๅœจๆœๅŠกๅ™จ้‡ๅฏๅŽไฟ็•™ -- **็ฟป่ฏ‘ๅ™จๆธธไนๅœบ** โ€” 4 ็ง่ฐƒ่ฏ•ๆจกๅผ๏ผšๆธธไนๅœบ๏ผˆๆ ผๅผ็ฟป่ฏ‘๏ผ‰ใ€่Šๅคฉๆต‹่ฏ•ๅ™จ๏ผˆๅพ€่ฟ”๏ผ‰ใ€ๆต‹่ฏ•ๅฐ๏ผˆๆ‰น้‡๏ผ‰ใ€ๅฎžๆ—ถ็›‘ๆŽง๏ผˆๅฎžๆ—ถ๏ผ‰ -- **่ฏทๆฑ‚้ฅๆต‹** โ€” p50/p95/p99 ๅปถ่ฟŸ + X-Request-Id ่ฟฝ่ธช -- **ๅŸบไบŽๆ–‡ไปถ็š„ๆ—ฅๅฟ—่ฝฎๆข** โ€” ๆŽงๅˆถๅฐๆ‹ฆๆˆชๅ™จๆ•่Žทๆ‰€ๆœ‰ๅ†…ๅฎนๅˆฐ JSON ๆ—ฅๅฟ—๏ผŒๅŸบไบŽๅคงๅฐ่ฝฎๆข -- **็ณป็ปŸไฟกๆฏๆŠฅๅ‘Š** โ€” `npm run system-info` ็”Ÿๆˆ `system-info.txt`๏ผŒๅŒ…ๅซๅฎŒๆ•ด็Žฏๅขƒ๏ผˆNode ็‰ˆๆœฌใ€OmniRoute ็‰ˆๆœฌใ€ๆ“ไฝœ็ณป็ปŸใ€CLI ๅทฅๅ…ทใ€Docker/PM2 ็Šถๆ€๏ผ‰ใ€‚ๆŠฅๅ‘Š้—ฎ้ข˜ๆ—ถ้™„ไธŠๅฎƒไปฅ่Žทๅพ—ๅณๆ—ถๅˆ†็ฑปใ€‚ +- **Unified Logs Dashboard** โ€” 4 tabs: Request Logs, Proxy Logs, Audit Logs, Console +- **Console Log Viewer** โ€” Real-time terminal-style viewer with color-coded levels, auto-scroll, search, filter +- **SQLite Proxy Logs** โ€” Persistent logs that survive server restarts +- **Translator Playground** โ€” 4 debugging modes: Playground (format translation), Chat Tester (round-trip), Test Bench (batch), Live Monitor (real-time) +- **Request Telemetry** โ€” p50/p95/p99 latency + X-Request-Id tracing +- **File-Based Logging with Rotation** โ€” App logs rotate by size, retention days, and archive count; call log artifacts rotate by retention days and file count +- **System Info Report** โ€” `npm run system-info` generates `system-info.txt` with your full environment (Node version, OmniRoute version, OS, CLI tools, Docker/PM2 status). Attach it when reporting issues for instant triage.
-๐Ÿ—๏ธ 11. "้ƒจ็ฝฒๅ’Œ็ปดๆŠค็ฝ‘ๅ…ณๅพˆๅคๆ‚" +๐Ÿ—๏ธ 11. "Deploying and maintaining the gateway is complex" -ๅœจไธๅŒ็Žฏๅขƒ๏ผˆๆœฌๅœฐใ€VPSใ€Dockerใ€ไบ‘๏ผ‰ไธญๅฎ‰่ฃ…ใ€้…็ฝฎๅ’Œ็ปดๆŠค AI ไปฃ็†้žๅธธ่€—่ดนไบบๅŠ›ใ€‚็กฌ็ผ–็ ่ทฏๅพ„ใ€็›ฎๅฝ•ไธŠ็š„ `EACCES`ใ€็ซฏๅฃๅ†ฒ็ชๅ’Œ่ทจๅนณๅฐๆž„ๅปบ็ญ‰้—ฎ้ข˜ๅขžๅŠ ไบ†ๆ‘ฉๆ“ฆใ€‚ +Installing, configuring, and maintaining an AI proxy across different environments (local, VPS, Docker, cloud) is labor-intensive. Problems like hardcoded paths, `EACCES` on directories, port conflicts, and cross-platform builds add friction. -**OmniRoute ๅฆ‚ไฝ•่งฃๅ†ณ๏ผš** +**How OmniRoute solves it:** -- **npm ๅ…จๅฑ€ๅฎ‰่ฃ…** โ€” `npm install -g omniroute && omniroute` โ€” ๅฎŒๆˆ -- **Docker ๅคšๅนณๅฐ** โ€” AMD64 + ARM64 ๅŽŸ็”Ÿๆ”ฏๆŒ๏ผˆApple Siliconใ€AWS Gravitonใ€Raspberry Pi๏ผ‰ -- **Docker Compose Profiles** โ€” `base`๏ผˆๆ—  CLI ๅทฅๅ…ท๏ผ‰ๅ’Œ `cli`๏ผˆๅธฆ Claude Codeใ€Codexใ€OpenClaw๏ผ‰ -- **Electron ๆกŒ้ขๅบ”็”จ** โ€” Windows/macOS/Linux ๅŽŸ็”Ÿๅบ”็”จ๏ผŒๅธฆ็ณป็ปŸๆ‰˜็›˜ใ€่‡ชๅŠจๅฏๅŠจใ€็ฆป็บฟๆจกๅผ -- **ๅˆ†็ฆป็ซฏๅฃๆจกๅผ** โ€” API ๅ’Œ Dashboard ๅœจไธๅŒ็ซฏๅฃไธŠ็”จไบŽ้ซ˜็บงๅœบๆ™ฏ๏ผˆๅๅ‘ไปฃ็†ใ€ๅฎนๅ™จ็ฝ‘็ปœ๏ผ‰ -- **ไบ‘ๅŒๆญฅ** โ€” ้€š่ฟ‡ Cloudflare Workers ่ทจ่ฎพๅค‡้…็ฝฎๅŒๆญฅ -- **ๆ•ฐๆฎๅบ“ๅค‡ไปฝ** โ€” ่‡ชๅŠจๅค‡ไปฝใ€ๆขๅคใ€ๅฏผๅ‡บๅ’Œๅฏผๅ…ฅๆ‰€ๆœ‰่ฎพ็ฝฎ +- **npm global install** โ€” `npm install -g omniroute && omniroute` โ€” done +- **Docker Multi-Platform** โ€” AMD64 + ARM64 native (Apple Silicon, AWS Graviton, Raspberry Pi) +- **Docker Compose Profiles** โ€” `base` (no CLI tools) and `cli` (with Claude Code, Codex, OpenClaw) +- **Electron Desktop App** โ€” Native app for Windows/macOS/Linux with system tray, auto-start, offline mode +- **Split-Port Mode** โ€” API and Dashboard on separate ports for advanced scenarios (reverse proxy, container networking) +- **Cloud Sync** โ€” Config synchronization across devices via Cloudflare Workers +- **DB Backups** โ€” Automatic backup, restore, export and import of all settings, with `DISABLE_SQLITE_AUTO_BACKUP` for externally managed backups
-๐ŸŒ 12. "็•Œ้ขไป…่‹ฑๆ–‡๏ผŒๆˆ‘็š„ๅ›ข้˜Ÿไธไผš่ฏด่‹ฑ่ฏญ" +๐ŸŒ 12. "The interface is English-only and my team doesn't speak English" -้ž่‹ฑ่ฏญๅ›ฝๅฎถ็š„ๅ›ข้˜Ÿ๏ผŒๅฐคๅ…ถๆ˜ฏๆ‹‰ไธ็พŽๆดฒใ€ไบšๆดฒๅ’Œๆฌงๆดฒ็š„ๅ›ข้˜Ÿ๏ผŒๅœจ็บฏ่‹ฑ่ฏญ็•Œ้ขไธŠๆŒฃๆ‰Žใ€‚่ฏญ่จ€้šœ็ข้™ไฝŽไบ†้‡‡็”จ็Ž‡ๅนถๅขžๅŠ ไบ†้…็ฝฎ้”™่ฏฏใ€‚ +Teams in non-English-speaking countries, especially in Latin America, Asia, and Europe, struggle with English-only interfaces. Language barriers reduce adoption and increase configuration errors. -**OmniRoute ๅฆ‚ไฝ•่งฃๅ†ณ๏ผš** +**How OmniRoute solves it:** -- **Dashboard i18n โ€” 30 ็ง่ฏญ่จ€** โ€” ๆ‰€ๆœ‰ 500+ ไธช้”ฎๅทฒ็ฟป่ฏ‘๏ผŒๅŒ…ๆ‹ฌ้˜ฟๆ‹‰ไผฏ่ฏญใ€ไฟๅŠ ๅˆฉไบš่ฏญใ€ไธน้บฆ่ฏญใ€ๅพท่ฏญใ€่ฅฟ็ญ็‰™่ฏญใ€่Šฌๅ…ฐ่ฏญใ€ๆณ•่ฏญใ€ๅธŒไผฏๆฅ่ฏญใ€ๅฐๅœฐ่ฏญใ€ๅŒˆ็‰™ๅˆฉ่ฏญใ€ๅฐๅบฆๅฐผ่ฅฟไบš่ฏญใ€ๆ„ๅคงๅˆฉ่ฏญใ€ๆ—ฅ่ฏญใ€้Ÿฉ่ฏญใ€้ฉฌๆฅ่ฏญใ€่ทๅ…ฐ่ฏญใ€ๆŒชๅจ่ฏญใ€ๆณขๅ…ฐ่ฏญใ€่‘ก่„็‰™่ฏญ๏ผˆPT/BR๏ผ‰ใ€็ฝ—้ฉฌๅฐผไบš่ฏญใ€ไฟ„่ฏญใ€ๆ–ฏๆด›ไผๅ…‹่ฏญใ€็‘žๅ…ธ่ฏญใ€ๆณฐ่ฏญใ€ไนŒๅ…‹ๅ…ฐ่ฏญใ€่ถŠๅ—่ฏญใ€ไธญๆ–‡ใ€่ฒๅพ‹ๅฎพ่ฏญใ€่‹ฑ่ฏญ -- **RTL ๆ”ฏๆŒ** โ€” ้˜ฟๆ‹‰ไผฏ่ฏญๅ’ŒๅธŒไผฏๆฅ่ฏญ็š„ไปŽๅณๅˆฐๅทฆๆ”ฏๆŒ -- **ๅคš่ฏญ่จ€ README** โ€” 30 ไธชๅฎŒๆ•ดๆ–‡ๆกฃ็ฟป่ฏ‘ -- **่ฏญ่จ€้€‰ๆ‹ฉๅ™จ** โ€” ๅคด้ƒจ็š„ๅœฐ็ƒๅ›พๆ ‡ๅฏๅฎžๆ—ถๅˆ‡ๆข +- **Dashboard i18n โ€” 30 Languages** โ€” All 500+ keys translated including Arabic, Bulgarian, Danish, German, Spanish, Finnish, French, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Dutch, Norwegian, Polish, Portuguese (PT/BR), Romanian, Russian, Slovak, Swedish, Thai, Ukrainian, Vietnamese, Chinese, Filipino, English +- **RTL Support** โ€” Right-to-left support for Arabic and Hebrew +- **Multi-Language READMEs** โ€” 30 complete documentation translations +- **Language Selector** โ€” Globe icon in header for real-time switching
-๐Ÿ”„ 13. "ๆˆ‘้œ€่ฆ็š„ไธไป…ๆ˜ฏ่Šๅคฉ โ€” ๆˆ‘้œ€่ฆๅตŒๅ…ฅใ€ๅ›พๅƒใ€้Ÿณ้ข‘" +๐Ÿ”„ 13. "I need more than chat โ€” I need embeddings, images, audio" -AI ไธไป…ไป…ๆ˜ฏ่Šๅคฉ่กฅๅ…จใ€‚ๅผ€ๅ‘่€…้œ€่ฆ็”Ÿๆˆๅ›พๅƒใ€่ฝฌๅฝ•้Ÿณ้ข‘ใ€ไธบ RAG ๅˆ›ๅปบๅตŒๅ…ฅใ€้‡ๆ–ฐๆŽ’ๅบๆ–‡ๆกฃๅ’Œๅฎกๆ ธๅ†…ๅฎนใ€‚ๆฏไธช API ้ƒฝๆœ‰ไธๅŒ็š„็ซฏ็‚นๅ’Œๆ ผๅผใ€‚ +AI isn't just chat completion. Devs need to generate images, transcribe audio, create embeddings for RAG, rerank documents, and moderate content. Each API has a different endpoint and format. -**OmniRoute ๅฆ‚ไฝ•่งฃๅ†ณ๏ผš** +**How OmniRoute solves it:** -- **Embeddings** โ€” `/v1/embeddings`๏ผŒ6 ไธชๆไพ›ๅ•†ๅ’Œ 9+ ไธชๆจกๅž‹ -- **ๅ›พๅƒ็”Ÿๆˆ** โ€” `/v1/images/generations`๏ผŒ10 ไธชๆไพ›ๅ•†ๅ’Œ 20+ ไธชๆจกๅž‹๏ผˆOpenAIใ€xAIใ€Togetherใ€Fireworksใ€Nebiusใ€Hyperbolicใ€NanoBananaใ€Antigravityใ€SD WebUIใ€ComfyUI๏ผ‰ -- **ๆ–‡ๆœฌ่ฝฌ่ง†้ข‘** โ€” `/v1/videos/generations` โ€” ComfyUI๏ผˆAnimateDiffใ€SVD๏ผ‰ๅ’Œ SD WebUI -- **ๆ–‡ๆœฌ่ฝฌ้Ÿณไน** โ€” `/v1/music/generations` โ€” ComfyUI๏ผˆStable Audio Openใ€MusicGen๏ผ‰ -- **้Ÿณ้ข‘่ฝฌๅฝ•** โ€” `/v1/audio/transcriptions` โ€” Whisper + Nvidia NIMใ€HuggingFaceใ€Qwen3 -- **ๆ–‡ๆœฌ่ฝฌ่ฏญ้Ÿณ** โ€” `/v1/audio/speech` โ€” ElevenLabsใ€Nvidia NIMใ€HuggingFaceใ€Coquiใ€Tortoiseใ€Qwen3ใ€**Inworld**ใ€**Cartesia**ใ€**PlayHT** + ็Žฐๆœ‰ๆไพ›ๅ•† -- **Moderations** โ€” `/v1/moderations` โ€” ๅ†…ๅฎนๅฎ‰ๅ…จๆฃ€ๆŸฅ -- **Reranking** โ€” `/v1/rerank` โ€” ๆ–‡ๆกฃ็›ธๅ…ณๆ€ง้‡ๆ–ฐๆŽ’ๅบ -- **Responses API** โ€” ๅฎŒๆ•ด็š„ `/v1/responses` ๆ”ฏๆŒ Codex +- **Embeddings** โ€” `/v1/embeddings` with 6 providers and 9+ models +- **Image Generation** โ€” `/v1/images/generations` with 10 providers and 20+ models (OpenAI, xAI, Together, Fireworks, Nebius, Hyperbolic, NanoBanana, Antigravity, SD WebUI, ComfyUI) +- **Text-to-Video** โ€” `/v1/videos/generations` โ€” ComfyUI (AnimateDiff, SVD) and SD WebUI +- **Text-to-Music** โ€” `/v1/music/generations` โ€” ComfyUI (Stable Audio Open, MusicGen) +- **Audio Transcription** โ€” `/v1/audio/transcriptions` โ€” Whisper + Nvidia NIM, HuggingFace, Qwen3 +- **Text-to-Speech** โ€” `/v1/audio/speech` โ€” ElevenLabs, Nvidia NIM, HuggingFace, Coqui, Tortoise, Qwen3, **Inworld**, **Cartesia**, **PlayHT**, + existing providers +- **Moderations** โ€” `/v1/moderations` โ€” Content safety checks +- **Reranking** โ€” `/v1/rerank` โ€” Document relevance reranking +- **Responses API** โ€” Full `/v1/responses` support for Codex
-๐Ÿงช 14. "ๆˆ‘ๆ— ๆณ•ๆต‹่ฏ•ๅ’Œๆฏ”่พƒๆจกๅž‹่ดจ้‡" +๐Ÿงช 14. "I have no way to test and compare quality across models" -ๅผ€ๅ‘่€…ๆƒณ็Ÿฅ้“ๅ“ชไธชๆจกๅž‹ๆœ€้€‚ๅˆไป–ไปฌ็š„็”จไพ‹ โ€” ไปฃ็ ใ€็ฟป่ฏ‘ใ€ๆŽจ็† โ€” ไฝ†ๆ‰‹ๅŠจๆฏ”่พƒๅพˆๆ…ขใ€‚ไธๅญ˜ๅœจ้›†ๆˆ็š„่ฏ„ไผฐๅทฅๅ…ทใ€‚ +Developers want to know which model is best for their use case โ€” code, translation, reasoning โ€” but comparing manually is slow. No integrated eval tools exist. -**OmniRoute ๅฆ‚ไฝ•่งฃๅ†ณ๏ผš** +**How OmniRoute solves it:** -- **LLM ่ฏ„ไผฐ** โ€” ้ป„้‡‘้›†ๆต‹่ฏ•๏ผŒ้ข„ๅŠ ่ฝฝ 10 ไธชๆกˆไพ‹๏ผŒๆถต็›–้—ฎๅ€™ใ€ๆ•ฐๅญฆใ€ๅœฐ็†ใ€ไปฃ็ ็”Ÿๆˆใ€JSON ๅˆ่ง„ๆ€งใ€็ฟป่ฏ‘ใ€Markdownใ€ๅฎ‰ๅ…จๆ‹’็ป -- **4 ็งๅŒน้…็ญ–็•ฅ** โ€” `exact`ใ€`contains`ใ€`regex`ใ€`custom`๏ผˆJS ๅ‡ฝๆ•ฐ๏ผ‰ -- **็ฟป่ฏ‘ๅ™จๆธธไนๅœบๆต‹่ฏ•ๅฐ** โ€” ๆ‰น้‡ๆต‹่ฏ•ๅคšไธช่พ“ๅ…ฅๅ’Œ้ข„ๆœŸ่พ“ๅ‡บ๏ผŒ่ทจๆไพ›ๅ•†ๆฏ”่พƒ -- **่Šๅคฉๆต‹่ฏ•ๅ™จ** โ€” ๅฎŒๆ•ดๅพ€่ฟ”๏ผŒๅธฆ่ง†่ง‰ๅ“ๅบ”ๆธฒๆŸ“ -- **ๅฎžๆ—ถ็›‘ๆŽง** โ€” ้€š่ฟ‡ไปฃ็†ๆตๅŠจ็š„ๆ‰€ๆœ‰่ฏทๆฑ‚็š„ๅฎžๆ—ถๆต +- **LLM Evaluations** โ€” Golden set testing with 10 pre-loaded cases covering greetings, math, geography, code generation, JSON compliance, translation, markdown, safety refusal +- **4 Match Strategies** โ€” `exact`, `contains`, `regex`, `custom` (JS function) +- **Translator Playground Test Bench** โ€” Batch testing with multiple inputs and expected outputs, cross-provider comparison +- **Chat Tester** โ€” Full round-trip with visual response rendering +- **Live Monitor** โ€” Real-time stream of all requests flowing through the proxy
-๐Ÿ“ˆ 15. "ๆˆ‘้œ€่ฆๅœจไธๆŸๅคฑๆ€ง่ƒฝ็š„ๆƒ…ๅ†ตไธ‹ๆ‰ฉๅฑ•" +๐Ÿ“ˆ 15. "I need to scale without losing performance" -้š็€่ฏทๆฑ‚้‡ๅขž้•ฟ๏ผŒๆฒกๆœ‰็ผ“ๅญ˜๏ผŒ็›ธๅŒ็š„้—ฎ้ข˜ไผšไบง็”Ÿ้‡ๅคๆˆๆœฌใ€‚ๆฒกๆœ‰ๅน‚็ญ‰ๆ€ง๏ผŒ้‡ๅค่ฏทๆฑ‚ๆตช่ดนๅค„็†ใ€‚ๅฟ…้กป้ตๅฎˆๆฏๆไพ›ๅ•†็š„้€Ÿ็Ž‡้™ๅˆถใ€‚ +As request volume grows, without caching the same questions generate duplicate costs. Without idempotency, duplicate requests waste processing. Per-provider rate limits must be respected. -**OmniRoute ๅฆ‚ไฝ•่งฃๅ†ณ๏ผš** +**How OmniRoute solves it:** -- **่ฏญไน‰็ผ“ๅญ˜** โ€” ไธคๅฑ‚็ผ“ๅญ˜๏ผˆ็ญพๅ + ่ฏญไน‰๏ผ‰้™ไฝŽๆˆๆœฌๅ’Œๅปถ่ฟŸ -- **่ฏทๆฑ‚ๅน‚็ญ‰ๆ€ง** โ€” 5 ็ง’ๅŽป้‡็ช—ๅฃ็”จไบŽ็›ธๅŒ่ฏทๆฑ‚ -- **้€Ÿ็Ž‡้™ๅˆถๆฃ€ๆต‹** โ€” ๆฏๆไพ›ๅ•†็š„ RPMใ€ๆœ€ๅฐ้—ด้š™ๅ’Œๆœ€ๅคงๅนถๅ‘่ฟฝ่ธช -- **ๅฏ็ผ–่พ‘้€Ÿ็Ž‡้™ๅˆถ** โ€” ่ฎพ็ฝฎ โ†’ ๅผนๆ€งไธญ็š„ๅฏ้…็ฝฎ้ป˜่ฎคๅ€ผ๏ผŒๅธฆๆŒไน…ๅŒ– -- **API ๅฏ†้’ฅ้ชŒ่ฏ็ผ“ๅญ˜** โ€” 3 ๅฑ‚็ผ“ๅญ˜็”จไบŽ็”Ÿไบงๆ€ง่ƒฝ -- **ๅฅๅบทไปช่กจ็›˜ไธŽ้ฅๆต‹** โ€” p50/p95/p99 ๅปถ่ฟŸใ€็ผ“ๅญ˜็ปŸ่ฎกใ€ๆญฃๅธธ่ฟ่กŒๆ—ถ้—ด +- **Semantic Cache** โ€” Two-tier cache (signature + semantic) reduces cost and latency +- **Request Idempotency** โ€” 5s deduplication window for identical requests +- **Rate Limit Detection** โ€” Per-provider RPM, min gap, and max concurrent tracking +- **Editable Rate Limits** โ€” Configurable defaults in Settings โ†’ Resilience with persistence +- **API Key Validation Cache** โ€” 3-tier cache for production performance +- **Health Dashboard with Telemetry** โ€” p50/p95/p99 latency, cache stats, uptime
-๐Ÿค– 16. "ๆˆ‘ๆƒณๅ…จๅฑ€ๆŽงๅˆถๆจกๅž‹่กŒไธบ" +๐Ÿค– 16. "I want to control model behavior globally" -ๅธŒๆœ›ๆ‰€ๆœ‰ๅ“ๅบ”้ƒฝไฝฟ็”จ็‰นๅฎš่ฏญ่จ€ใ€็‰นๅฎš่ฏญๆฐ”ๆˆ–้™ๅˆถๆŽจ็† Token ็š„ๅผ€ๅ‘่€…ใ€‚ๅœจๆฏไธชๅทฅๅ…ท/่ฏทๆฑ‚ไธญ้…็ฝฎ่ฟ™ไบ›ไธๅˆ‡ๅฎž้™…ใ€‚ +Developers who want all responses in a specific language, with a specific tone, or want to limit reasoning tokens. Configuring this in every tool/request is impractical. -**OmniRoute ๅฆ‚ไฝ•่งฃๅ†ณ๏ผš** +**How OmniRoute solves it:** -- **็ณป็ปŸๆ็คบ่ฏๆณจๅ…ฅ** โ€” ๅบ”็”จไบŽๆ‰€ๆœ‰่ฏทๆฑ‚็š„ๅ…จๅฑ€ๆ็คบ่ฏ -- **ๆ€่€ƒ้ข„็ฎ—้ชŒ่ฏ** โ€” ๆฏ่ฏทๆฑ‚็š„ๆŽจ็† Token ๅˆ†้…ๆŽงๅˆถ๏ผˆ็›ด้€šใ€่‡ชๅŠจใ€่‡ชๅฎšไน‰ใ€่‡ช้€‚ๅบ”๏ผ‰ -- **6 ็ง่ทฏ็”ฑ็ญ–็•ฅ** โ€” ็กฎๅฎš่ฏทๆฑ‚ๅฆ‚ไฝ•ๅˆ†ๅ‘็š„ๅ…จๅฑ€็ญ–็•ฅ -- **้€š้…็ฌฆ่ทฏ็”ฑๅ™จ** โ€” `provider/*` ๆจกๅผๅŠจๆ€่ทฏ็”ฑๅˆฐไปปไฝ•ๆไพ›ๅ•† -- **Combo ๅฏ็”จ/็ฆ็”จๅˆ‡ๆข** โ€” ็›ดๆŽฅไปŽไปช่กจ็›˜ๅˆ‡ๆข Combo -- **ๆไพ›ๅ•†ๅˆ‡ๆข** โ€” ไธ€้”ฎๅฏ็”จ/็ฆ็”จๆไพ›ๅ•†็š„ๆ‰€ๆœ‰่ฟžๆŽฅ -- **่ขซ้˜ปๆญข็š„ๆไพ›ๅ•†** โ€” ไปŽ `/v1/models` ๅˆ—่กจไธญๆŽ’้™ค็‰นๅฎšๆไพ›ๅ•† +- **System Prompt Injection** โ€” Global prompt applied to all requests +- **Thinking Budget Validation** โ€” Reasoning token allocation control per request (passthrough, auto, custom, adaptive) +- **9 Routing Strategies** โ€” Global strategies that determine how requests are distributed +- **Wildcard Router** โ€” `provider/*` patterns route dynamically to any provider +- **Combo Enable/Disable Toggle** โ€” Toggle combos directly from the dashboard +- **Provider Toggle** โ€” Enable/disable all connections for a provider with one click +- **Blocked Providers** โ€” Exclude specific providers from `/v1/models` listing
-๐Ÿงฐ 17. "ๆˆ‘้œ€่ฆ MCP ๅทฅๅ…ทไฝœไธบไธ€็บงไบงๅ“ๅŠŸ่ƒฝ" +๐Ÿงฐ 17. "I need MCP tools as first-class product capabilities" -่ฎธๅคš AI ็ฝ‘ๅ…ณไป…ๅฐ† MCP ไฝœไธบ้š่—็š„ๅฎž็Žฐ็ป†่Š‚ๅ…ฌๅผ€ใ€‚ๅ›ข้˜Ÿ้œ€่ฆๅฏ่งใ€ๅฏ็ฎก็†็š„ๆ“ไฝœๅฑ‚ใ€‚ +Many AI gateways expose MCP only as a hidden implementation detail. Teams need a visible, manageable operation layer. -**OmniRoute ๅฆ‚ไฝ•่งฃๅ†ณ๏ผš** +**How OmniRoute solves it:** -- MCP ๅ‡บ็Žฐๅœจไปช่กจ็›˜ๅฏผ่ˆชๅ’Œ็ซฏ็‚นๅ่ฎฎๆ ‡็ญพไธญ -- ไธ“็”จ MCP ็ฎก็†้กต้ข๏ผŒๅธฆ่ฟ›็จ‹ใ€ๅทฅๅ…ทใ€่Œƒๅ›ดๅ’Œๅฎก่ฎก -- `omniroute --mcp` ๅ’Œๅฎขๆˆท็ซฏๅ…ฅ้—จ็š„ๅ†…็ฝฎๅฟซ้€ŸๅฏๅŠจ +- MCP appears in the dashboard navigation and endpoint protocol tab +- Dedicated MCP management page with process, tools, scopes, and audit +- Built-in quick-start for `omniroute --mcp` and client onboarding
-๐Ÿง  18. "ๆˆ‘้œ€่ฆๅธฆๅŒๆญฅ + ๆตไปปๅŠก่ทฏๅพ„็š„ A2A ็ผ–ๆŽ’" +๐Ÿง  18. "I need A2A orchestration with sync + stream task paths" -ไปฃ็†ๅทฅไฝœๆต้œ€่ฆ็›ดๆŽฅๅ›žๅคๅ’Œๅธฆ็”Ÿๅ‘ฝๅ‘จๆœŸๆŽงๅˆถ็š„้•ฟๆœŸๆตๆ‰ง่กŒใ€‚ +Agent workflows need both direct replies and long-running streamed execution with lifecycle control. -**OmniRoute ๅฆ‚ไฝ•่งฃๅ†ณ๏ผš** +**How OmniRoute solves it:** -- A2A JSON-RPC ็ซฏ็‚น๏ผˆ`POST /a2a`๏ผ‰๏ผŒๅธฆ `message/send` ๅ’Œ `message/stream` -- SSE ๆต๏ผŒๅธฆ็ปˆ็ซฏ็Šถๆ€ไผ ๆ’ญ -- ไปปๅŠก็”Ÿๅ‘ฝๅ‘จๆœŸ API๏ผš`tasks/get` ๅ’Œ `tasks/cancel` +- A2A JSON-RPC endpoint (`POST /a2a`) with `message/send` and `message/stream` +- SSE streaming with terminal state propagation +- Task lifecycle APIs for `tasks/get` and `tasks/cancel`
-๐Ÿ›ฐ๏ธ 19. "ๆˆ‘้œ€่ฆ็œŸๅฎž็š„ MCP ่ฟ›็จ‹ๅฅๅบท๏ผŒ่€Œไธๆ˜ฏ็Œœๆต‹็š„็Šถๆ€" +๐Ÿ›ฐ๏ธ 19. "I need real MCP process health, not guessed status" -่ฟ่ฅๅ›ข้˜Ÿ้œ€่ฆ็Ÿฅ้“ MCP ๆ˜ฏๅฆ็œŸ็š„ๆดป็€๏ผŒ่€Œไธไป…ไป…ๆ˜ฏ API ๆ˜ฏๅฆๅฏ่พพใ€‚ +Operational teams need to know if MCP is actually alive, not just whether an API is reachable. -**OmniRoute ๅฆ‚ไฝ•่งฃๅ†ณ๏ผš** +**How OmniRoute solves it:** -- ่ฟ่กŒๆ—ถๅฟƒ่ทณๆ–‡ไปถ๏ผŒๅธฆ PIDใ€ๆ—ถ้—ดๆˆณใ€ไผ ่พ“ใ€ๅทฅๅ…ท่ฎกๆ•ฐๅ’Œ่Œƒๅ›ดๆจกๅผ -- MCP ็Šถๆ€ API๏ผŒ็ป“ๅˆๅฟƒ่ทณ + ๆœ€่ฟ‘ๆดปๅŠจ -- UI ็Šถๆ€ๅก๏ผŒ็”จไบŽ่ฟ›็จ‹/ๆญฃๅธธ่ฟ่กŒๆ—ถ้—ด/ๅฟƒ่ทณๆ–ฐ้ฒœๅบฆ +- Runtime heartbeat file with PID, timestamps, transport, tool count, and scope mode +- MCP status API combining heartbeat + recent activity +- UI status cards for process/uptime/heartbeat freshness
-๐Ÿ“‹ 20. "ๆˆ‘้œ€่ฆๅฏๅฎก่ฎก็š„ MCP ๅทฅๅ…ทๆ‰ง่กŒ" +๐Ÿ“‹ 20. "I need auditable MCP tool execution" -ๅฝ“ๅทฅๅ…ทๆ”นๅ˜้…็ฝฎๆˆ–่งฆๅ‘ๆ“ไฝœๆ—ถ๏ผŒๅ›ข้˜Ÿ้œ€่ฆๅ–่ฏๅฏ่ฟฝๆบฏๆ€งใ€‚ +When tools mutate config or trigger ops actions, teams need forensic traceability. -**OmniRoute ๅฆ‚ไฝ•่งฃๅ†ณ๏ผš** +**How OmniRoute solves it:** -- ๅŸบไบŽ SQLite ็š„ MCP ๅทฅๅ…ท่ฐƒ็”จๅฎก่ฎกๆ—ฅๅฟ— -- ๆŒ‰ๅทฅๅ…ทใ€ๆˆๅŠŸ/ๅคฑ่ดฅใ€API ๅฏ†้’ฅๅ’Œๅˆ†้กต่ฟ‡ๆปค -- Dashboard ๅฎก่ฎก่กจ + ็”จไบŽ่‡ชๅŠจๅŒ–็š„็ปŸ่ฎก็ซฏ็‚น +- SQLite-backed audit logging for MCP tool calls +- Filters by tool, success/failure, API key, and pagination +- Dashboard audit table + stats endpoints for automation
-๐Ÿ” 21. "ๆˆ‘้œ€่ฆๆฏไธช้›†ๆˆ็š„่Œƒๅ›ดๅŒ– MCP ๆƒ้™" +๐Ÿ” 21. "I need scoped MCP permissions per integration" -ไธๅŒ็š„ๅฎขๆˆท็ซฏๅบ”่ฏฅๅ…ทๆœ‰ๅฏนๅทฅๅ…ท็ฑปๅˆซ็š„ๆœ€ๅฐๆƒ้™่ฎฟ้—ฎใ€‚ +Different clients should have least-privilege access to tool categories. -**OmniRoute ๅฆ‚ไฝ•่งฃๅ†ณ๏ผš** +**How OmniRoute solves it:** -- 9 ไธช็ฒ’ๅบฆๅŒ–็š„ MCP ่Œƒๅ›ด็”จไบŽๅ—ๆŽงๅทฅๅ…ท่ฎฟ้—ฎ -- MCP ็ฎก็† UI ไธญ็š„่Œƒๅ›ดๅผบๅˆถๅ’Œๅฏ่งๆ€ง -- ็”จไบŽๆ“ไฝœๅทฅๅ…ท็š„ๅฎ‰ๅ…จ้ป˜่ฎคๅงฟๆ€ +- 10 granular MCP scopes for controlled tool access +- Scope enforcement and visibility in MCP management UI +- Safe default posture for operational tooling
-โš™๏ธ 22. "ๆˆ‘้œ€่ฆๆ— ้œ€้‡ๆ–ฐ้ƒจ็ฝฒ็š„ๆ“ไฝœๆŽงๅˆถ" +โš™๏ธ 22. "I need operational controls without redeploying" -ๅ›ข้˜Ÿๅœจไบ‹ไปถๆˆ–ๆˆๆœฌไบ‹ไปถๆœŸ้—ด้œ€่ฆๅฟซ้€Ÿ่ฟ่กŒๆ—ถๆ›ดๆ”นใ€‚ +Teams need quick runtime changes during incidents or cost events. -**OmniRoute ๅฆ‚ไฝ•่งฃๅ†ณ๏ผš** +**How OmniRoute solves it:** -- ็›ดๆŽฅไปŽ MCP ไปช่กจ็›˜ๅˆ‡ๆข Combo ๆฟ€ๆดป -- ไปŽ้ข„ๅฎšไน‰็ญ–็•ฅๅŒ…ๅบ”็”จๅผนๆ€ง้…็ฝฎๆ–‡ไปถ -- ไปŽๅŒไธ€ๆ“ไฝœ้ขๆฟ้‡็ฝฎ็†”ๆ–ญๅ™จ็Šถๆ€ +- Switch combo activation directly from MCP dashboard +- Apply resilience profiles from pre-defined policy packs +- Reset circuit breaker state from the same operations panel
-๐Ÿ”„ 23. "ๆˆ‘้œ€่ฆๅฎžๆ—ถ A2A ไปปๅŠก็”Ÿๅ‘ฝๅ‘จๆœŸๅฏ่งๆ€งๅ’Œๅ–ๆถˆ" +๐Ÿ”„ 23. "I need live A2A task lifecycle visibility and cancellation" -ๆฒกๆœ‰็”Ÿๅ‘ฝๅ‘จๆœŸๅฏ่งๆ€ง๏ผŒไปปๅŠกไบ‹ไปถๅ˜ๅพ—้šพไปฅๅˆ†็ฑปใ€‚ +Without lifecycle visibility, task incidents become hard to triage. -**OmniRoute ๅฆ‚ไฝ•่งฃๅ†ณ๏ผš** +**How OmniRoute solves it:** -- ๆŒ‰็Šถๆ€/ๆŠ€่ƒฝๅˆ—ๅ‡บ/่ฟ‡ๆปคไปปๅŠก๏ผŒๅธฆๅˆ†้กต -- ้’ปๅ–ไปปๅŠกๅ…ƒๆ•ฐๆฎใ€ไบ‹ไปถๅ’Œๅทฅไปถ -- ไปปๅŠกๅ–ๆถˆ็ซฏ็‚นๅ’Œ UI ๆ“ไฝœ๏ผŒๅธฆ็กฎ่ฎค +- Task listing/filtering by state/skill with pagination +- Drill-down on task metadata, events, and artifacts +- Task cancellation endpoint and UI action with confirmation
-๐ŸŒŠ 24. "ๆˆ‘้œ€่ฆ A2A ่ดŸ่ฝฝ็š„ๆดปๅŠจๆตๆŒ‡ๆ ‡" +๐ŸŒŠ 24. "I need active stream metrics for A2A load" -ๆตๅทฅไฝœๆต้œ€่ฆๅฏนๅนถๅ‘ๅ’Œๅฎžๆ—ถ่ฟžๆŽฅ็š„ๆ“ไฝœๆดžๅฏŸใ€‚ +Streaming workflows require operational insight into concurrency and live connections. -**OmniRoute ๅฆ‚ไฝ•่งฃๅ†ณ๏ผš** +**How OmniRoute solves it:** -- ๆดปๅŠจๆต่ฎกๆ•ฐๅ™จ้›†ๆˆๅˆฐ A2A ็Šถๆ€ไธญ -- ๆœ€ๅŽไปปๅŠกๆ—ถ้—ดๆˆณๅ’Œๆฏ็Šถๆ€่ฎกๆ•ฐ -- A2A ไปช่กจ็›˜ๅก็”จไบŽๅฎžๆ—ถ่ฟ็ปด็›‘ๆŽง +- Active stream counters integrated into A2A status +- Last task timestamp and per-state counts +- A2A dashboard cards for real-time ops monitoring
-๐Ÿชช 25. "ๆˆ‘้œ€่ฆๅฎขๆˆท็ซฏ็š„ๆ ‡ๅ‡†ไปฃ็†ๅ‘็Žฐ" +๐Ÿชช 25. "I need standard agent discovery for clients" -ๅค–้ƒจๅฎขๆˆท็ซฏๅ’Œ็ผ–ๆŽ’ๅ™จ้œ€่ฆๆœบๅ™จๅฏ่ฏป็š„ๅ…ƒๆ•ฐๆฎไปฅ่ฟ›่กŒๅ…ฅ้—จใ€‚ +External clients and orchestrators need machine-readable metadata for onboarding. -**OmniRoute ๅฆ‚ไฝ•่งฃๅ†ณ๏ผš** +**How OmniRoute solves it:** -- ๅœจ `/.well-known/agent.json` ๅ…ฌๅผ€ไปฃ็†ๅก -- ็ฎก็† UI ไธญๆ˜พ็คบ็š„ๅŠŸ่ƒฝๅ’ŒๆŠ€่ƒฝ -- A2A ็Šถๆ€ API ๅŒ…ๆ‹ฌ็”จไบŽ่‡ชๅŠจๅŒ–็š„ๅ‘็Žฐๅ…ƒๆ•ฐๆฎ +- Agent Card exposed at `/.well-known/agent.json` +- Capabilities and skills shown in management UI +- A2A status API includes discovery metadata for automation
-๐Ÿงญ 26. "ๆˆ‘้œ€่ฆไบงๅ“ UX ไธญ็š„ๅ่ฎฎๅฏๅ‘็Žฐๆ€ง" +๐Ÿงญ 26. "I need protocol discoverability in the product UX" -ๅฆ‚ๆžœ็”จๆˆทๆ— ๆณ•ๅ‘็Žฐๅ่ฎฎ็•Œ้ข๏ผŒ้‡‡็”จ็Ž‡ๅ’Œๆ”ฏๆŒ่ดจ้‡ไผšไธ‹้™ใ€‚ +If users cannot discover protocol surfaces, adoption and support quality drop. -**OmniRoute ๅฆ‚ไฝ•่งฃๅ†ณ๏ผš** +**How OmniRoute solves it:** -- ๅˆๅนถ็š„**็ซฏ็‚น**้กต้ข๏ผŒๅธฆ Proxyใ€MCPใ€A2A ๅ’Œ API ็ซฏ็‚น็š„ๆ ‡็ญพ้กต -- MCP ๅ’Œ A2A ็š„ๅ†…่”ๆœๅŠก็Šถๆ€ๅˆ‡ๆข๏ผˆๅœจ็บฟ/็ฆป็บฟ๏ผ‰ -- ไปŽๆฆ‚่งˆๅˆฐไธ“็”จ็ฎก็†ๆ ‡็ญพ็š„้“พๆŽฅ +- Consolidated **Endpoints** page with tabs for Proxy, MCP, A2A, and API Endpoints +- Inline service status toggles (Online/Offline) for MCP and A2A +- Links from overview to dedicated management tabs
-๐Ÿงช 27. "ๆˆ‘้œ€่ฆไฝฟ็”จ็œŸๅฎžๅฎขๆˆท็ซฏ่ฟ›่กŒ็ซฏๅˆฐ็ซฏๅ่ฎฎ้ชŒ่ฏ" +๐Ÿงช 27. "I need end-to-end protocol validation with real clients" -ๆจกๆ‹Ÿๆต‹่ฏ•ไธ่ถณไปฅๅœจๅ‘ๅธƒๅ‰้ชŒ่ฏๅ่ฎฎๅ…ผๅฎนๆ€งใ€‚ +Mock tests are not enough to validate protocol compatibility before release. -**OmniRoute ๅฆ‚ไฝ•่งฃๅ†ณ๏ผš** +**How OmniRoute solves it:** -- E2E ๅฅ—ไปถๅฏๅŠจๅบ”็”จๅนถไฝฟ็”จ็œŸๅฎž็š„ MCP SDK ๅฎขๆˆท็ซฏไผ ่พ“ -- A2A ๅฎขๆˆท็ซฏๆต‹่ฏ•๏ผŒ็”จไบŽๅ‘็Žฐใ€ๅ‘้€ใ€ๆตใ€่Žทๅ–ๅ’Œๅ–ๆถˆๆต็จ‹ -- ้’ˆๅฏน MCP ๅฎก่ฎกๅ’Œ A2A ไปปๅŠก API ็š„ไบคๅ‰ๆฃ€ๆŸฅๆ–ญ่จ€ +- E2E suite that boots app and uses real MCP SDK client transport +- A2A client tests for discovery, send, stream, get, and cancel flows +- Cross-check assertions against MCP audit and A2A tasks APIs
-๐Ÿ“ก 28. "ๆˆ‘้œ€่ฆ่ทจๆ‰€ๆœ‰็•Œ้ข็š„็ปŸไธ€ๅฏ่ง‚ๆต‹ๆ€ง" +๐Ÿ“ก 28. "I need unified observability across all interfaces" -ๆŒ‰ๅ่ฎฎๆ‹†ๅˆ†ๅฏ่ง‚ๆต‹ๆ€งไผšไบง็”Ÿ็›ฒ็‚นๅนถๅปถ้•ฟ MTTRใ€‚ +Splitting observability by protocol creates blind spots and longer MTTR. -**OmniRoute ๅฆ‚ไฝ•่งฃๅ†ณ๏ผš** +**How OmniRoute solves it:** -- ็ปŸไธ€ไปช่กจ็›˜/ๆ—ฅๅฟ—/ๅˆ†ๆžๅœจไธ€ไธชไบงๅ“ไธญ -- OpenAIใ€MCP ๅ’Œ A2A ๅฑ‚็š„ๅฅๅบท + ๅฎก่ฎก + ่ฏทๆฑ‚้ฅๆต‹ -- ็”จไบŽ็Šถๆ€ๅ’Œ่‡ชๅŠจๅŒ–็š„ๆ“ไฝœ API +- Unified dashboards/logs/analytics in one product +- Health + audit + request telemetry across OpenAI, MCP, and A2A layers +- Operational APIs for status and automation
-๐Ÿ’ผ 29. "ๆˆ‘้œ€่ฆไธ€ไธช่ฟ่กŒๆ—ถ็”จไบŽไปฃ็† + ๅทฅๅ…ท + ไปฃ็†็ผ–ๆŽ’" +๐Ÿ’ผ 29. "I need one runtime for proxy + tools + agent orchestration" -่ฟ่กŒ่ฎธๅคšๅ•็‹ฌ็š„ๆœๅŠกไผšๅขžๅŠ ๆ“ไฝœๆˆๆœฌๅ’Œๆ•…้šœๆจกๅผใ€‚ +Running many separate services increases operational cost and failure modes. -**OmniRoute ๅฆ‚ไฝ•่งฃๅ†ณ๏ผš** +**How OmniRoute solves it:** -- OpenAI ๅ…ผๅฎนไปฃ็†ใ€MCP ๆœๅŠกๅ™จๅ’Œ A2A ๆœๅŠกๅ™จๅœจไธ€ไธชๅ †ๆ ˆไธญ -- ๅ…ฑไบซ่ฎค่ฏใ€ๅผนๆ€งใ€ๆ•ฐๆฎๅญ˜ๅ‚จๅ’Œๅฏ่ง‚ๆต‹ๆ€ง -- ่ทจๆ‰€ๆœ‰ไบคไบ’็•Œ้ข็š„ไธ€่‡ด็ญ–็•ฅๆจกๅž‹ +- OpenAI-compatible proxy, MCP server, and A2A server in one stack +- Shared auth, resilience, data store, and observability +- Consistent policy model across all interaction surfaces
-๐Ÿš€ 30. "ๆˆ‘้œ€่ฆๅœจๆฒกๆœ‰่ƒถๆฐดไปฃ็ ่”“ๅปถ็š„ๆƒ…ๅ†ตไธ‹ไบคไป˜ไปฃ็†ๅทฅไฝœๆต" +๐Ÿš€ 30. "I need to ship agentic workflows without glue-code sprawl" -ๅ›ข้˜Ÿๅœจๆ‹ผๆŽฅๅคšไธชไธดๆ—ถๆœๅŠกๅ’Œ่„šๆœฌๆ—ถๅคฑๅŽป้€Ÿๅบฆใ€‚ +Teams lose velocity when stitching multiple ad-hoc services and scripts. -**OmniRoute ๅฆ‚ไฝ•่งฃๅ†ณ๏ผš** +**How OmniRoute solves it:** -- ไธบๅฎขๆˆท็ซฏๅ’Œไปฃ็†ๆไพ›็ปŸไธ€็š„็ซฏ็‚น็ญ–็•ฅ -- ๅ†…็ฝฎๅ่ฎฎ็ฎก็† UI ๅ’Œๅ†’็ƒŸ้ชŒ่ฏ่ทฏๅพ„ -- ็”Ÿไบงๅฐฑ็ปช็š„ๅŸบ็ก€๏ผˆๅฎ‰ๅ…จใ€ๆ—ฅๅฟ—ใ€ๅผนๆ€งใ€ๅค‡ไปฝ๏ผ‰ +- Unified endpoint strategy for clients and agents +- Built-in protocol management UIs and smoke validation paths +- Production-ready foundations (security, logging, resilience, backup)
-### ็คบไพ‹่กŒๅŠจๆ‰‹ๅ†Œ๏ผˆ้›†ๆˆ็”จไพ‹๏ผ‰ +### Example Playbooks (Integrated Use Cases) -**่กŒๅŠจๆ‰‹ๅ†Œ A๏ผšๆœ€ๅคงๅŒ–ไป˜่ดน่ฎข้˜… + ไพฟๅฎœๅค‡ไปฝ** +**Playbook A: Maximize paid subscription + cheap backup** ```txt Combo: "maximize-claude" @@ -714,11 +716,11 @@ Combo: "maximize-claude" 2. glm/glm-4.7 3. if/kimi-k2-thinking -ๆฏๆœˆๆˆๆœฌ๏ผš$20 + ๅฐ้ขๅค‡ไปฝๆ”ฏๅ‡บ -็ป“ๆžœ๏ผšๆ›ด้ซ˜่ดจ้‡๏ผŒๅ‡ ไนŽ้›ถไธญๆ–ญ +Monthly cost: $20 + small backup spend +Outcome: higher quality, near-zero interruption ``` -**่กŒๅŠจๆ‰‹ๅ†Œ B๏ผš้›ถๆˆๆœฌ็ผ–็ ๅ †ๆ ˆ** +**Playbook B: Zero-cost coding stack** ```txt Combo: "free-forever" @@ -726,11 +728,11 @@ Combo: "free-forever" 2. if/kimi-k2-thinking 3. qw/qwen3-coder-plus -ๆฏๆœˆๆˆๆœฌ๏ผš$0 -็ป“ๆžœ๏ผš็จณๅฎš็š„ๅ…่ดน็ผ–็ ๅทฅไฝœๆต +Monthly cost: $0 +Outcome: stable free coding workflow ``` -**่กŒๅŠจๆ‰‹ๅ†Œ C๏ผš24/7 ๆฐธไน…ๅœจ็บฟๅŽๅค‡้“พ** +**Playbook C: 24/7 always-on fallback chain** ```txt Combo: "always-on" @@ -740,64 +742,64 @@ Combo: "always-on" 4. minimax/MiniMax-M2.1 5. if/kimi-k2-thinking -็ป“ๆžœ๏ผšๅฏนๆˆชๆญขๆ—ฅๆœŸๅ…ณ้”ฎๅทฅไฝœ่ดŸ่ฝฝ็š„ๆทฑๅบฆๅŽๅค‡ๆทฑๅบฆ +Outcome: deep fallback depth for deadline-critical workloads ``` -**่กŒๅŠจๆ‰‹ๅ†Œ D๏ผšไฝฟ็”จ MCP + A2A ็š„ไปฃ็†่ฟ็ปด** +**Playbook D: Agent ops with MCP + A2A** ```txt -1) ๅฏๅŠจ MCP ไผ ่พ“๏ผˆ`omniroute --mcp`๏ผ‰็”จไบŽๅทฅๅ…ท้ฉฑๅŠจ็š„ๆ“ไฝœ -2) ้€š่ฟ‡ `message/send` ๅ’Œ `message/stream` ่ฟ่กŒ A2A ไปปๅŠก -3) ้€š่ฟ‡ /dashboard/endpoint๏ผˆMCP ๅ’Œ A2A ๆ ‡็ญพ้กต๏ผ‰่ง‚ๅฏŸ -4) ้€š่ฟ‡ๅ†…่”็Šถๆ€ๆŽงๅˆถๅˆ‡ๆขๆœๅŠก +1) Start MCP transport (`omniroute --mcp`) for tool-driven operations +2) Run A2A tasks via `message/send` and `message/stream` +3) Observe via /dashboard/endpoint (MCP and A2A tabs) +4) Toggle services via inline status controls ``` --- -## ๐Ÿ†“ ๅ…่ดนๅผ€ๅง‹ โ€” ้›ถ้…็ฝฎๆˆๆœฌ +## ๐Ÿ†“ Start Free โ€” Zero Configuration Cost -> ๅœจๅ‡ ๅˆ†้’Ÿๅ†…ไปฅ **$0/ๆœˆ**่ฎพ็ฝฎ AI ็ผ–็ ใ€‚่ฟžๆŽฅ่ฟ™ไบ›ๅ…่ดน่ดฆๆˆทๅนถไฝฟ็”จๅ†…็ฝฎ็š„ **Free Stack** Comboใ€‚ +> Setup AI coding in minutes at **$0/month**. Connect these free accounts and use the built-in **Free Stack** combo. -| ๆญฅ้ชค | ๆ“ไฝœ | ่งฃ้”็š„ๆไพ›ๅ•† | -| ---- | ---------------------------------------------- | ------------------------------------------------------------- | -| 1 | ่ฟžๆŽฅ **Kiro**๏ผˆAWS Builder ID OAuth๏ผ‰ | Claude Sonnet 4.5ใ€Haiku 4.5 โ€” **ๆ— ้™** | -| 2 | ่ฟžๆŽฅ **Qoder**๏ผˆGoogle OAuth๏ผ‰ | kimi-k2-thinkingใ€qwen3-coder-plusใ€deepseek-r1... โ€” **ๆ— ้™** | -| 3 | ่ฟžๆŽฅ **Qwen**๏ผˆ่ฎพๅค‡ไปฃ็ ๏ผ‰ | qwen3-coder-plusใ€qwen3-coder-flash... โ€” **ๆ— ้™** | -| 4 | ่ฟžๆŽฅ **Gemini CLI**๏ผˆGoogle OAuth๏ผ‰ | gemini-3-flashใ€gemini-2.5-pro โ€” **180K/ๆœˆๅ…่ดน** | -| 5 | `/dashboard/combos` โ†’ **Free Stack ($0)** ๆจกๆฟ | ่‡ชๅŠจ่ฝฎ่ฏขๆ‰€ๆœ‰ๅ…่ดนๆไพ›ๅ•† | +| Step | Action | Providers Unlocked | +| ---- | -------------------------------------------------- | ------------------------------------------------------------------ | +| 1 | Connect **Kiro** (AWS Builder ID OAuth) | Claude Sonnet 4.5, Haiku 4.5 โ€” **unlimited** | +| 2 | Connect **Qoder** (Google OAuth) | kimi-k2-thinking, qwen3-coder-plus, deepseek-r1... โ€” **unlimited** | +| 3 | Connect **Qwen** (Device Code) | qwen3-coder-plus, qwen3-coder-flash... โ€” **unlimited** | +| 4 | Connect **Gemini CLI** (Google OAuth) | gemini-3-flash, gemini-2.5-pro โ€” **180K/mo free** | +| 5 | `/dashboard/combos` โ†’ **Free Stack ($0)** template | Round-robin all free providers automatically | -**ๅฐ†ไปปไฝ• IDE/CLI ๆŒ‡ๅ‘๏ผš** `http://localhost:20128/v1` ยท API Key: `any-string` ยท ๅฎŒๆˆใ€‚ +**Point any IDE/CLI to:** `http://localhost:20128/v1` ยท API Key: `any-string` ยท Done. -> **ๅฏ้€‰้ขๅค–่ฆ†็›–๏ผˆไนŸๅ…่ดน๏ผ‰๏ผš** Groq API ๅฏ†้’ฅ๏ผˆ30 RPM ๅ…่ดน๏ผ‰ใ€NVIDIA NIM๏ผˆ40 RPM ๅ…่ดน๏ผŒ70+ ไธชๆจกๅž‹๏ผ‰ใ€Cerebras๏ผˆ1M token/ๅคฉ๏ผ‰ใ€LongCat API ๅฏ†้’ฅ๏ผˆ50M tokens/ๅคฉ๏ผ๏ผ‰ใ€Cloudflare Workers AI๏ผˆ10K Neurons/ๅคฉ๏ผŒ50+ ไธชๆจกๅž‹๏ผ‰ใ€‚ +> **Optional extra coverage (also free):** Groq API key (30 RPM free), NVIDIA NIM (40 RPM free, 70+ models), Cerebras (1M tok/day), LongCat API key (50M tokens/day!), Cloudflare Workers AI (10K Neurons/day, 50+ models). ## ๅฟซ้€Ÿๅผ€ๅง‹ -### 1) ๅฎ‰่ฃ…ๅนถ่ฟ่กŒ +### 1) Install and run ```bash npm install -g omniroute omniroute ``` -> **pnpm ็”จๆˆท๏ผš** ๅฎ‰่ฃ…ๅŽ่ฟ่กŒ `pnpm approve-builds -g` ไปฅๅฏ็”จ `better-sqlite3` ๅ’Œ `@swc/core` ๆ‰€้œ€็š„ๅŽŸ็”Ÿๆž„ๅปบ่„šๆœฌ๏ผš +> **pnpm users:** Run `pnpm approve-builds -g` after install to enable native build scripts required by `better-sqlite3` and `@swc/core`: > > ```bash > pnpm install -g omniroute -> pnpm approve-builds -g # ้€‰ๆ‹ฉๆ‰€ๆœ‰ๅŒ… โ†’ ๆ‰นๅ‡† +> pnpm approve-builds -g # Select all packages โ†’ approve > omniroute > ``` -Dashboard ๅœจ `http://localhost:20128` ๆ‰“ๅผ€๏ผŒAPI ๅŸบ็ก€ URL ๆ˜ฏ `http://localhost:20128/v1`ใ€‚ +Dashboard opens at `http://localhost:20128` and API base URL is `http://localhost:20128/v1`. -| ๅ‘ฝไปค | ๆ่ฟฐ | -| ----------------------- | ------------------------------------------------------- | -| `omniroute` | ๅฏๅŠจๆœๅŠกๅ™จ๏ผˆ`PORT=20128`๏ผŒAPI ๅ’Œ Dashboard ๅœจๅŒไธ€็ซฏๅฃ๏ผ‰ | -| `omniroute --port 3000` | ๅฐ†่ง„่Œƒ/API ็ซฏๅฃ่ฎพ็ฝฎไธบ 3000 | -| `omniroute --mcp` | ๅฏๅŠจ MCP ๆœๅŠกๅ™จ๏ผˆstdio ไผ ่พ“๏ผ‰ | -| `omniroute --no-open` | ไธ่‡ชๅŠจๆ‰“ๅผ€ๆต่งˆๅ™จ | -| `omniroute --help` | ๆ˜พ็คบๅธฎๅŠฉ | +| Command | Description | +| ----------------------- | ----------------------------------------------------------- | +| `omniroute` | Start server (`PORT=20128`, API and dashboard on same port) | +| `omniroute --port 3000` | Set canonical/API port to 3000 | +| `omniroute --mcp` | Start MCP server (stdio transport) | +| `omniroute --no-open` | Don't auto-open browser | +| `omniroute --help` | Show help | -ๅฏ้€‰็š„ๅˆ†็ฆป็ซฏๅฃๆจกๅผ๏ผš +Optional split-port mode: ```bash PORT=20128 DASHBOARD_PORT=20129 omniroute @@ -805,36 +807,36 @@ PORT=20128 DASHBOARD_PORT=20129 omniroute # Dashboard: http://localhost:20129 ``` -### 2) ่ฟžๆŽฅๆไพ›ๅ•†ๅนถๅˆ›ๅปบไฝ ็š„ API ๅฏ†้’ฅ +### 2) Connect providers and create your API key -1. ๆ‰“ๅผ€ Dashboard โ†’ `Providers` ๅนถ่ฟžๆŽฅ่‡ณๅฐ‘ไธ€ไธชๆไพ›ๅ•†๏ผˆOAuth ๆˆ– API ๅฏ†้’ฅ๏ผ‰ใ€‚ -2. ๆ‰“ๅผ€ Dashboard โ†’ `Endpoints` ๅนถๅˆ›ๅปบไธ€ไธช API ๅฏ†้’ฅใ€‚ -3. ๏ผˆๅฏ้€‰๏ผ‰ๆ‰“ๅผ€ Dashboard โ†’ `Combos` ๅนถ่ฎพ็ฝฎไฝ ็š„ๅŽๅค‡้“พใ€‚ +1. Open Dashboard โ†’ `Providers` and connect at least one provider (OAuth or API key). +2. Open Dashboard โ†’ `Endpoints` and create an API key. +3. (Optional) Open Dashboard โ†’ `Combos` and set your fallback chain. -### 3) ๅฐ†ไฝ ็š„็ผ–็ ๅทฅๅ…ทๆŒ‡ๅ‘ OmniRoute +### 3) Point your coding tool to OmniRoute ```txt Base URL: http://localhost:20128/v1 -API Key: [ไปŽ็ซฏ็‚น้กต้ขๅคๅˆถ] -Model: if/kimi-k2-thinking๏ผˆๆˆ–ไปปไฝ• provider/model ๅ‰็ผ€๏ผ‰ +API Key: [copy from Endpoint page] +Model: if/kimi-k2-thinking (or any provider/model prefix) ``` -้€‚็”จไบŽ Claude Codeใ€Codex CLIใ€Gemini CLIใ€Cursorใ€Clineใ€OpenClawใ€OpenCode ๅ’Œ OpenAI ๅ…ผๅฎน็š„ SDKใ€‚ +Works with Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, OpenClaw, OpenCode, and OpenAI-compatible SDKs. -### 4) ๅฏ็”จๅนถ้ชŒ่ฏๅ่ฎฎ๏ผˆv2.0๏ผ‰ +### 4) Enable and validate protocols (v2.0) -**MCP๏ผˆ็”จไบŽๅทฅๅ…ท้ฉฑๅŠจ็š„ๆ“ไฝœ๏ผ‰๏ผš** +**MCP (for tool-driven operations):** ```bash omniroute --mcp ``` -็„ถๅŽ้€š่ฟ‡ `stdio` ่ฟžๆŽฅไฝ ็š„ MCP ๅฎขๆˆท็ซฏๅนถๆต‹่ฏ•ๅทฅๅ…ท๏ผŒไพ‹ๅฆ‚๏ผš +Then connect your MCP client over `stdio` and test tools like: - `omniroute_get_health` - `omniroute_list_combos` -**A2A๏ผˆ็”จไบŽไปฃ็†ๅˆฐไปฃ็†ๅทฅไฝœๆต๏ผ‰๏ผš** +**A2A (for agent-to-agent workflows):** ```bash curl http://localhost:20128/.well-known/agent.json @@ -846,15 +848,15 @@ curl -X POST http://localhost:20128/a2a \ -d '{"jsonrpc":"2.0","id":"quickstart","method":"message/send","params":{"skill":"quota-management","messages":[{"role":"user","content":"Give me a short quota summary."}]}}' ``` -### 5) ็ซฏๅˆฐ็ซฏ้ชŒ่ฏไธ€ๅˆ‡๏ผˆๆŽจ่๏ผ‰ +### 5) Validate everything end-to-end (recommended) ```bash npm run test:protocols:e2e ``` -ๆญคๅฅ—ไปถ้’ˆๅฏนๆญฃๅœจ่ฟ่กŒ็š„ๅบ”็”จ้ชŒ่ฏ็œŸๅฎž็š„ MCP ๅ’Œ A2A ๅฎขๆˆท็ซฏๆต็จ‹ใ€‚ +This suite validates real MCP and A2A client flows against a running app. -### ๆ›ฟไปฃๆ–นๆกˆ๏ผšไปŽๆบ็ ่ฟ่กŒ +### Alternative: run from source ```bash cp .env.example .env @@ -862,13 +864,120 @@ npm install PORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev ``` +
+Void Linux (`xbps-src` template) + +For Void Linux users, you can build a native package using `xbps-src`. Save this block as `srcpkgs/omniroute/template`: + +```bash +# Template file for 'omniroute' +pkgname=omniroute +version=3.4.1 +revision=1 +hostmakedepends="nodejs python3 make" +depends="openssl" +short_desc="Universal AI gateway with smart routing for multiple LLM providers" +maintainer="zenobit " +license="MIT" +homepage="https://github.com/diegosouzapw/OmniRoute" +distfiles="https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz" +checksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b +system_accounts="_omniroute" +omniroute_homedir="/var/lib/omniroute" +export NODE_ENV=production +export npm_config_engine_strict=false +export npm_config_loglevel=error +export npm_config_fund=false +export npm_config_audit=false + +do_build() { + # Determine target CPU arch for node-gyp + local _gyp_arch + case "$XBPS_TARGET_MACHINE" in + aarch64*) _gyp_arch=arm64 ;; + armv7*|armv6*) _gyp_arch=arm ;; + i686*) _gyp_arch=ia32 ;; + *) _gyp_arch=x64 ;; + esac + + # 1) Install all deps โ€“ skip scripts (no network in do_build, native modules + # compiled separately below; better-sqlite3 is serverExternalPackage so + # Next.js does not execute it during next build) + NODE_ENV=development npm ci --ignore-scripts + + # 2) Build the Next.js standalone bundle + npm run build + + # 3) Copy static assets into standalone + cp -r .next/static .next/standalone/.next/static + [ -d public ] && cp -r public .next/standalone/public || true + + # 4) Compile better-sqlite3 native binding for the target architecture. + # Use node-gyp directly so CC/CXX from xbps-src cross-toolchain are used + # without npm altering them. + local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js + (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch") + + # 5) Place the compiled binding into the standalone bundle + local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release + mkdir -p "$_bs3_release" + cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/" + + # 6) Remove arch-specific sharp bundles โ€“ upstream sets images.unoptimized=true + # so sharp is not used at runtime; x64 .so files would break aarch64 strip + rm -rf .next/standalone/node_modules/@img + + # 7) Copy pino runtime deps omitted by Next.js static analysis: + # pino-abstract-transport โ€“ required by pino's worker thread + # split2 โ€“ dep of pino-abstract-transport + # process-warning โ€“ dep of pino itself + for _mod in pino-abstract-transport split2 process-warning; do + cp -r "node_modules/$_mod" .next/standalone/node_modules/ + done +} + +do_check() { + npm run test:unit +} + +do_install() { + vmkdir usr/lib/omniroute/.next + + vcopy .next/standalone/. usr/lib/omniroute/.next/standalone + + # Prevent removal of empty Next.js app router dirs by the post-install hook + for _d in \ + .next/standalone/.next/server/app/dashboard \ + .next/standalone/.next/server/app/dashboard/settings \ + .next/standalone/.next/server/app/dashboard/providers; do + touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep" + done + + cat > "${WRKDIR}/omniroute" <<'EOF' +#!/bin/sh +export PORT="${PORT:-20128}" +export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}" +export LOG_TO_FILE="${LOG_TO_FILE:-false}" +mkdir -p "${DATA_DIR}" +exec node /usr/lib/omniroute/.next/standalone/server.js "$@" +EOF + vbin "${WRKDIR}/omniroute" +} + +post_install() { + vlicense LICENSE +} +``` + +
+ --- ## ๐Ÿณ Docker -OmniRoute ๅœจ [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute) ไธŠไฝœไธบๅ…ฌๅ…ฑ Docker ้•œๅƒๆไพ›ใ€‚ +OmniRoute is available as a public Docker image on [Docker Hub](https://hub.docker.com/r/diegosouzapw/omniroute). -**ๅฟซ้€Ÿ่ฟ่กŒ๏ผš** +**Quick run:** ```bash docker run -d \ @@ -879,10 +988,10 @@ docker run -d \ diegosouzapw/omniroute:latest ``` -**ไฝฟ็”จ็Žฏๅขƒๅ˜้‡ๆ–‡ไปถ๏ผš** +**With environment file:** ```bash -# ๅ…ˆๅคๅˆถๅนถ็ผ–่พ‘ .env +# Copy and edit .env first cp .env.example .env docker run -d \ @@ -894,28 +1003,28 @@ docker run -d \ diegosouzapw/omniroute:latest ``` -**ไฝฟ็”จ Docker Compose๏ผš** +**Using Docker Compose:** ```bash -# ๅŸบ็ก€ profile๏ผˆไธๅซ CLI ๅทฅๅ…ท๏ผ‰ +# Base profile (no CLI tools) docker compose --profile base up -d -# CLI profile๏ผˆๅ†…็ฝฎ Claude Codeใ€Codexใ€OpenClaw๏ผ‰ +# CLI profile (Claude Code, Codex, OpenClaw built-in) docker compose --profile cli up -d ``` -้ขๅ‘ Docker ้ƒจ็ฝฒ็š„ Dashboard ็Žฐๅทฒๅœจ `Dashboard โ†’ Endpoints` ไธญๅ†…็ฝฎไธ€้”ฎๅผ **Cloudflare Quick Tunnel**ใ€‚้ฆ–ๆฌกๅฏ็”จๆ—ถไป…ไผšๅœจ้œ€่ฆๆ—ถไธ‹่ฝฝ `cloudflared`๏ผŒ้šๅŽไธบๅฝ“ๅ‰ `/v1` ็ซฏ็‚นๅฏๅŠจไธ€ไธชไธดๆ—ถ้šง้“๏ผŒๅนถๅฐ†็”Ÿๆˆ็š„ `https://*.trycloudflare.com/v1` URL ๆ˜พ็คบๅœจๆ™ฎ้€šๅ…ฌ็ฝ‘ URL ไธ‹ๆ–นใ€‚ +Dashboard support for Docker deployments now includes a one-click **Cloudflare Quick Tunnel** on `Dashboard โ†’ Endpoints`. The first enable downloads `cloudflared` only when needed, starts a temporary tunnel to your current `/v1` endpoint, and shows the generated `https://*.trycloudflare.com/v1` URL directly below your normal public URL. -่ฏดๆ˜Ž๏ผš +Notes: -- Quick Tunnel URL ๆ˜ฏไธดๆ—ถ็š„๏ผŒๆฏๆฌก้‡ๅฏๅŽ้ƒฝไผšๅ˜ๅŒ–ใ€‚ -- ๆ‰˜็ฎกๅฎ‰่ฃ…ๅฝ“ๅ‰ๆ”ฏๆŒ Linuxใ€macOS ๅ’Œ Windows ็š„ `x64` / `arm64`ใ€‚ -- Docker ้•œๅƒๅ†…็ฝฎไบ†็ณป็ปŸ CA ๆ น่ฏไนฆๅนถๅฐ†ๅ…ถไผ ้€’็ป™ๆ‰˜็ฎก็š„ `cloudflared`๏ผŒ้ฟๅ…ไบ†้šง้“ๅœจๅฎนๅ™จๅ†…ๅฏๅŠจๆ—ถ็š„ TLS ไฟกไปปๅคฑ่ดฅ้—ฎ้ข˜ใ€‚ -- ๅฆ‚ๆžœไฝ ๅธŒๆœ› OmniRoute ็›ดๆŽฅไฝฟ็”จ็Žฐๆœ‰ไบŒ่ฟ›ๅˆถ่€Œไธๆ˜ฏไธ‹่ฝฝ๏ผŒๅฏไปฅ่ฎพ็ฝฎ `CLOUDFLARED_BIN=/absolute/path/to/cloudflared`ใ€‚ +- Quick Tunnel URLs are temporary and change after every restart. +- Managed install currently supports Linux, macOS, and Windows on `x64` / `arm64`. +- Docker images bundle system CA roots and pass them to managed `cloudflared`, which avoids TLS trust failures when the tunnel bootstraps inside the container. +- Set `CLOUDFLARED_BIN=/absolute/path/to/cloudflared` if you want OmniRoute to use an existing binary instead of downloading one. -**็ป“ๅˆ Caddy ไฝฟ็”จ Docker Compose๏ผˆHTTPS ่‡ชๅŠจ TLS๏ผ‰๏ผš** +**Using Docker Compose with Caddy (HTTPS Auto-TLS):** -OmniRoute ๅฏไปฅ้€š่ฟ‡ Caddy ็š„่‡ชๅŠจ SSL ้…็ฝฎๅฎ‰ๅ…จๅฏนๅค–ๆšด้œฒใ€‚่ฏท็กฎไฟไฝ ็š„ๅŸŸๅ DNS A ่ฎฐๅฝ•ๅทฒๆŒ‡ๅ‘ๆœๅŠกๅ™จ IPใ€‚ +OmniRoute can be securely exposed using Caddy's automatic SSL provisioning. Ensure your domain's DNS A record points to your server's IP. ```yaml services: @@ -942,388 +1051,388 @@ volumes: omniroute-data: ``` -| ้•œๅƒ | ๆ ‡็ญพ | ๅคงๅฐ | ่ฏดๆ˜Ž | -| ------------------------ | -------- | ------ | ------------ | -| `diegosouzapw/omniroute` | `latest` | ~250MB | ๆœ€ๆ–ฐ็จณๅฎš็‰ˆๆœฌ | -| `diegosouzapw/omniroute` | `1.0.3` | ~250MB | ๅฝ“ๅ‰็‰ˆๆœฌ | +| Image | Tag | Size | Description | +| ------------------------ | -------- | ------ | --------------------- | +| `diegosouzapw/omniroute` | `latest` | ~250MB | Latest stable release | +| `diegosouzapw/omniroute` | `1.0.3` | ~250MB | Current version | --- -## ๐Ÿ–ฅ๏ธ Desktop App โ€” ็ฆป็บฟไธ”ๅธธ้ฉป่ฟ่กŒ +## ๐Ÿ–ฅ๏ธ Desktop App โ€” Offline & Always-On -> ๐Ÿ†• **ๆ–ฐๅŠŸ่ƒฝ๏ผ** OmniRoute ็Žฐๅทฒๆไพ›้€‚็”จไบŽ Windowsใ€macOS ๅ’Œ Linux ็š„**ๅŽŸ็”ŸๆกŒ้ขๅบ”็”จ**ใ€‚ +> ๐Ÿ†• **NEW!** OmniRoute is now available as a **native desktop application** for Windows, macOS, and Linux. -ๅฐ† OmniRoute ไฝœไธบ็‹ฌ็ซ‹ๆกŒ้ขๅบ”็”จ่ฟ่กŒ๏ผŒๆ— ้œ€็ปˆ็ซฏใ€ๆ— ้œ€ๆต่งˆๅ™จ๏ผ›ๅฏนไบŽๆœฌๅœฐๆจกๅž‹ไนŸๆ— ้œ€่”็ฝ‘ใ€‚ๅŸบไบŽ Electron ็š„ๅบ”็”จๅŒ…ๅซ๏ผš +Run OmniRoute as a standalone desktop app โ€” no terminal, no browser, no internet required for local models. The Electron-based app includes: -- ๐Ÿ–ฅ๏ธ **Native Window** โ€” ๅธฆ็ณป็ปŸๆ‰˜็›˜้›†ๆˆ็š„ไธ“็”จๅบ”็”จ็ช—ๅฃ -- ๐Ÿ”„ **Auto-Start** โ€” ๅœจ็ณป็ปŸ็™ปๅฝ•ๆ—ถๅฏๅŠจ OmniRoute -- ๐Ÿ”” **Native Notifications** โ€” ๅœจ้…้ข่€—ๅฐฝๆˆ–ๆไพ›ๅ•†ๅ‡บ็Žฐ้—ฎ้ข˜ๆ—ถๆ”ถๅˆฐๆ้†’ -- โšก **One-Click Install** โ€” NSIS๏ผˆWindows๏ผ‰ใ€DMG๏ผˆmacOS๏ผ‰ใ€AppImage๏ผˆLinux๏ผ‰ -- ๐ŸŒ **Offline Mode** โ€” ไฝฟ็”จๅ†…็ฝฎๆœๅŠกๅ™จๅณๅฏๅฎŒๅ…จ็ฆป็บฟ่ฟ่กŒ +- ๐Ÿ–ฅ๏ธ **Native Window** โ€” Dedicated app window with system tray integration +- ๐Ÿ”„ **Auto-Start** โ€” Launch OmniRoute on system login +- ๐Ÿ”” **Native Notifications** โ€” Get alerts for quota exhaustion or provider issues +- โšก **One-Click Install** โ€” NSIS (Windows), DMG (macOS), AppImage (Linux) +- ๐ŸŒ **Offline Mode** โ€” Works fully offline with bundled server ### ๅฟซ้€Ÿๅผ€ๅง‹ ```bash -# ๅผ€ๅ‘ๆจกๅผ +# Development mode npm run electron:dev -# ๆž„ๅปบๅฝ“ๅ‰ๅนณๅฐๅฎ‰่ฃ…ๅŒ… -npm run electron:build # ๅฝ“ๅ‰ๅนณๅฐ +# Build for your platform +npm run electron:build # Current platform npm run electron:build:win # Windows (.exe) npm run electron:build:mac # macOS (.dmg) โ€” x64 & arm64 npm run electron:build:linux # Linux (.AppImage) ``` -### ็ณป็ปŸๆ‰˜็›˜ +### System Tray -ๆœ€ๅฐๅŒ–ๅŽ๏ผŒOmniRoute ไผš้ฉป็•™ๅœจ็ณป็ปŸๆ‰˜็›˜๏ผŒๅนถๆไพ›ไปฅไธ‹ๅฟซๆทๆ“ไฝœ๏ผš +When minimized, OmniRoute lives in your system tray with quick actions: -- ๆ‰“ๅผ€ dashboard -- ไฟฎๆ”นๆœๅŠก็ซฏ็ซฏๅฃ -- ้€€ๅ‡บๅบ”็”จ +- Open dashboard +- Change server port +- Quit application -๐Ÿ“– ๅฎŒๆ•ดๆ–‡ๆกฃ๏ผš[`electron/README.md`](../../../electron/README.md) +๐Ÿ“– Full documentation: [`electron/README.md`](electron/README.md) --- -## ๐Ÿ’ฐ ๅฎšไปทไธ€่งˆ +## ๐Ÿ’ฐ Pricing at a Glance -| ๅฑ‚็บง | ๆไพ›ๅ•† | ๆˆๆœฌ | ้…้ข้‡็ฝฎ | ้€‚็”จๅœบๆ™ฏ | -| ------------------- | --------------------------- | ---------------------------- | ---------------- | ---------------------------------- | -| **๐Ÿ’ณ SUBSCRIPTION** | 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 | **ๅ…่ดน**๏ผˆๅผ€ๅ‘ๆœŸๆฐธไน…๏ผ‰ | ็บฆ 40 RPM | 70+ ไธชๅผ€ๆบๆจกๅž‹ | -| | Cerebras | **ๅ…่ดน**๏ผˆ100 ไธ‡ tok/ๅคฉ๏ผ‰ | 60K TPM / 30 RPM | ๅ…จ็ƒๆœ€ๅฟซไน‹ไธ€ | -| | Groq | **ๅ…่ดน**๏ผˆ30 RPM๏ผ‰ | 14.4K RPD | ่ถ…้ซ˜้€Ÿ Llama/Gemma | -| | DeepSeek V3.2 | ๆฏ 100 ไธ‡ $0.27/$1.10 | ๆ—  | ๆ€งไปทๆฏ”ๆœ€ไฝณ็š„ๆŽจ็† | -| | xAI Grok-4 Fast | **ๆฏ 100 ไธ‡ $0.20/$0.50** ๐Ÿ†• | ๆ—  | ๆœ€ๅฟซ้€Ÿๅบฆ + tool calling๏ผŒ่ถ…ไฝŽไปท | -| | xAI Grok-4๏ผˆstandard๏ผ‰ | ๆฏ 100 ไธ‡ $0.20/$1.50 ๐Ÿ†• | ๆ—  | xAI ็š„ๆ——่ˆฐๆŽจ็†ๆจกๅž‹ | -| | Mistral | ๅ…่ดน่ฏ•็”จ + ไป˜่ดน | ๆœ‰้€Ÿ็Ž‡้™ๅˆถ | ๆฌงๆดฒ AI | -| | OpenRouter | ๆŒ‰้‡ไป˜่ดน | ๆ—  | ่šๅˆ 100+ ไธชๆจกๅž‹ | -| **๐Ÿ’ฐ CHEAP** | GLM-5๏ผˆvia Z.AI๏ผ‰๐Ÿ†• | $0.5/100 ไธ‡ | ๆฏๅคฉ 10:00 | 128K ่พ“ๅ‡บ๏ผŒๆœ€ๆ–ฐๆ——่ˆฐ | -| | GLM-4.7 | $0.6/100 ไธ‡ | ๆฏๅคฉ 10:00 | ้ข„็ฎ—ๅž‹ๅค‡้€‰ | -| | MiniMax M2.5 ๐Ÿ†• | ่พ“ๅ…ฅ $0.3/100 ไธ‡ | ๆปšๅŠจ 5 ๅฐๆ—ถ | ๆŽจ็† + agentic tasks | -| | MiniMax M2.1 | $0.2/100 ไธ‡ | ๆปšๅŠจ 5 ๅฐๆ—ถ | ๆœ€ไพฟๅฎœ็š„้€‰ๆ‹ฉ | -| | Kimi K2.5 (Moonshot API) ๐Ÿ†• | ๆŒ‰้‡ไป˜่ดน | ๆ—  | ็›ด่ฟž Moonshot API | -| | Kimi K2 | $9/ๆœˆๅ›บๅฎš | 1000 ไธ‡ tok/ๆœˆ | ๆˆๆœฌๅฏ้ข„ๆต‹ | -| **๐Ÿ†“ FREE** | Qoder | **$0** | ๆ— ้™ๅˆถ | 5 ไธชๆจกๅž‹ๆ— ้™็”จ | -| | Qwen | **$0** | ๆ— ้™ๅˆถ | 4 ไธชๆจกๅž‹ๆ— ้™็”จ | -| | Kiro | **$0** | ๆ— ้™ๅˆถ | Claude Sonnet/Haiku๏ผˆAWS Builder๏ผ‰ | -| | LongCat Flash-Lite ๐Ÿ†• | **$0**๏ผˆ5000 ไธ‡ tok/ๅคฉ ๐Ÿ”ฅ๏ผ‰ | 1 RPS | ๅœฐ็ƒไธŠๆœ€ๅคง็š„ๅ…่ดน้…้ข | -| | Pollinations AI ๐Ÿ†• | **$0**๏ผˆๆ— ้œ€ key๏ผ‰ | 1 ๆฌก่ฏทๆฑ‚/15 ็ง’ | GPT-5ใ€Claudeใ€DeepSeekใ€Llama 4 | -| | Cloudflare Workers AI ๐Ÿ†• | **$0**๏ผˆ10K Neurons/ๅคฉ๏ผ‰ | ็บฆ 150 ๆฌกๅ“ๅบ”/ๅคฉ | 50+ ไธชๆจกๅž‹๏ผŒๅ…จ็ƒ่พน็ผ˜ | -| | Scaleway AI ๐Ÿ†• | **$0**๏ผˆๆ€ป่ฎก 100 ไธ‡ tokens๏ผ‰ | ๆœ‰้€Ÿ็Ž‡้™ๅˆถ | EU/GDPR๏ผŒQwen3 235B๏ผŒLlama 70B | +| 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** | NVIDIA NIM | **FREE** (dev forever) | ~40 RPM | 70+ open models | +| | Cerebras | **FREE** (1M tok/day) | 60K TPM / 30 RPM | World's fastest | +| | Groq | **FREE** (30 RPM) | 14.4K RPD | Ultra-fast Llama/Gemma | +| | DeepSeek V3.2 | $0.27/$1.10 per 1M | None | Best price/quality reasoning | +| | xAI Grok-4 Fast | **$0.20/$0.50 per 1M** ๐Ÿ†• | None | Fastest + tool calling, ultralow | +| | xAI Grok-4 (standard) | $0.20/$1.50 per 1M ๐Ÿ†• | None | Reasoning flagship from xAI | +| | Mistral | Free trial + paid | Rate limited | European AI | +| | OpenRouter | Pay-per-use | None | 100+ models aggr. | +| **๐Ÿ’ฐ CHEAP** | GLM-5 (via Z.AI) ๐Ÿ†• | $0.5/1M | Daily 10AM | 128K output, newest flagship | +| | GLM-4.7 | $0.6/1M | Daily 10AM | Budget backup | +| | MiniMax M2.5 ๐Ÿ†• | $0.3/1M input | 5-hour rolling | Reasoning + agentic tasks | +| | MiniMax M2.1 | $0.2/1M | 5-hour rolling | Cheapest option | +| | Kimi K2.5 (Moonshot API) ๐Ÿ†• | Pay-per-use | None | Direct Moonshot API access | +| | Kimi K2 | $9/mo flat | 10M tokens/mo | Predictable cost | +| **๐Ÿ†“ FREE** | Qoder | **$0** | Unlimited | 5 models unlimited | +| | Qwen | **$0** | Unlimited | 4 models unlimited | +| | Kiro | **$0** | Unlimited | Claude Sonnet/Haiku (AWS Builder) | +| | LongCat Flash-Lite ๐Ÿ†• | **$0** (50M tok/day ๐Ÿ”ฅ) | 1 RPS | Largest free quota on Earth | +| | Pollinations AI ๐Ÿ†• | **$0** (no key needed) | 1 req/15s | GPT-5, Claude, DeepSeek, Llama 4 | +| | Cloudflare Workers AI ๐Ÿ†• | **$0** (10K Neurons/day) | ~150 resp/day | 50+ models, global edge | +| | Scaleway AI ๐Ÿ†• | **$0** (1M tokens total) | Rate limited | EU/GDPR, Qwen3 235B, Llama 70B | -> ๐Ÿ†• **ๆ–ฐๅขžๆจกๅž‹๏ผˆ2026 ๅนด 3 ๆœˆ๏ผ‰๏ผš** Grok-4 Fast ็ณปๅˆ—ไปทๆ ผไฝŽ่‡ณ $0.20/$0.50 ๆฏ็™พไธ‡ token๏ผˆๅŸบๅ‡†ๅปถ่ฟŸ 1143ms๏ผŒๆฏ” Gemini 2.5 Flash ๅฟซ็บฆ 30%๏ผ‰๏ผŒไปฅๅŠ้€š่ฟ‡ Z.AI ๆไพ›ใ€ๆ‹ฅๆœ‰ 128K ่พ“ๅ‡บ่ƒฝๅŠ›็š„ GLM-5๏ผŒ้ขๅ‘ๆŽจ็†็š„ๆ–ฐ MiniMax M2.5๏ผŒๆ›ดๆ–ฐๅฎšไปทๅŽ็š„ DeepSeek V3.2๏ผŒไปฅๅŠ้€š่ฟ‡ Moonshot ็›ด่ฟž API ไฝฟ็”จ็š„ Kimi K2.5ใ€‚ +> ๐Ÿ†• **New models added (Mar 2026):** Grok-4 Fast family at $0.20/$0.50/M (benchmarked at 1143ms โ€” 30% faster than Gemini 2.5 Flash), GLM-5 via Z.AI with 128K output, MiniMax M2.5 reasoning, DeepSeek V3.2 updated pricing, Kimi K2.5 via Moonshot direct API. -**๐Ÿ’ก $0 Combo ๆ ˆ๏ผšๅฎŒๆ•ดๅ…่ดน้…็ฝฎ** +**๐Ÿ’ก $0 Combo Stack โ€” The Complete Free Setup:** ``` -# ๐Ÿ†“ Ultimate Free Stack 2026 โ€” 11 ๅฎถๆไพ›ๅ•†๏ผŒๆฐธไน…ๅ…่ดน -Kiro (kr/) โ†’ Claude Sonnet/Haiku ๆ— ้™ไฝฟ็”จ -Qoder (if/) โ†’ kimi-k2-thinkingใ€qwen3-coder-plusใ€deepseek-r1 ๆ— ้™ไฝฟ็”จ -LongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” ๆฏๅคฉ 5000 ไธ‡ tokens ๐Ÿ”ฅ -Pollinations (pol/) โ†’ GPT-5ใ€Claudeใ€DeepSeekใ€Llama 4 โ€” ๆ— ้œ€ key -Qwen (qw/) โ†’ qwen3-coder-plusใ€qwen3-coder-flashใ€qwen3-coder-next ๆ— ้™ไฝฟ็”จ -Gemini (gemini/) โ†’ Gemini 2.5 Flash โ€” ๆฏๅคฉๅ…่ดน 1500 ๆฌก่ฏทๆฑ‚ -Cloudflare AI (cf/) โ†’ Llama 70Bใ€Gemma 3ใ€Mistral โ€” ๆฏๅคฉ 10K Neurons -Scaleway (scw/) โ†’ Qwen3 235Bใ€Llama 70B โ€” 100 ไธ‡ๅ…่ดน tokens๏ผˆEU๏ผ‰ -Groq (groq/) โ†’ ่ถ…้ซ˜้€Ÿ Llama/Gemma โ€” ๆฏๅคฉ 14.4K ๆฌก่ฏทๆฑ‚ -NVIDIA NIM (nvidia/) โ†’ 70+ ๅผ€ๆบๆจกๅž‹ โ€” ๆฐธไน… 40 RPM -Cerebras (cerebras/) โ†’ ่ถ…้ซ˜้€Ÿ Llama/Qwen โ€” ๆฏๅคฉ 100 ไธ‡ tokens +# ๐Ÿ†“ Ultimate Free Stack 2026 โ€” 11 Providers, $0 Forever +Kiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED +Qoder (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED +LongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ +Pollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed +Qwen (qw/) โ†’ qwen3-coder-plus, qwen3-coder-flash, qwen3-coder-next UNLIMITED +Gemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free API key +Cloudflare AI (cf/) โ†’ Llama 70B, Gemma 3, Mistral โ€” 10K Neurons/day +Scaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU) +Groq (groq/) โ†’ Llama/Gemma ultra-fast โ€” 14.4K req/day +NVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever +Cerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day ``` -**้›ถๆˆๆœฌ๏ผŒๆฐธไธไธญๆ–ญ็ผ–็ ใ€‚** ๅฐ†่ฟ™ไบ›ๆจกๅž‹้…็ฝฎไธบไธ€ไธช OmniRoute combo ๅŽ๏ผŒๆ‰€ๆœ‰ๅ›ž้€€้ƒฝไผš่‡ชๅŠจ่ฟ›่กŒ๏ผŒๆ— ้œ€ๆ‰‹ๅŠจๅˆ‡ๆขใ€‚ +**Zero cost. Never stops coding.** Configure this as one OmniRoute combo and all fallbacks happen automatically โ€” no manual switching ever. --- --- -## ๐Ÿ†“ ๅ…่ดนๆจกๅž‹๏ผšไฝ ็œŸๆญฃ่ƒฝ็”จๅˆฐ็š„ๅ†…ๅฎน +## ๐Ÿ†“ Free Models โ€” What You Actually Get -> ไปฅไธ‹ๆ‰€ๆœ‰ๆจกๅž‹้ƒฝ**100% ๅ…่ดน๏ผŒไธ”ไธ้œ€่ฆไฟก็”จๅก**ใ€‚ๅฝ“ๆŸไธช้…้ข่€—ๅฐฝๆ—ถ๏ผŒOmniRoute ไผš่‡ชๅŠจๅœจๅฎƒไปฌไน‹้—ดๅˆ‡ๆข่ทฏ็”ฑ๏ผŒๆŠŠๅฎƒไปฌ็ป„ๅˆ่ตทๆฅๅฐฑ่ƒฝๅพ—ๅˆฐไธ€ไธชๅ‡ ไนŽไธไผšไธญๆ–ญ็š„ $0 comboใ€‚ +> All models below are **100% free with zero credit card required**. OmniRoute auto-routes between them when one quota runs out โ€” combine them all for an unbreakable $0 combo. -### ๐Ÿ”ต CLAUDE MODELS๏ผˆ้€š่ฟ‡ Kiro ๅ’Œ AWS Builder ID๏ผ‰ +### ๐Ÿ”ต CLAUDE MODELS (via Kiro โ€” AWS Builder ID) -| ๆจกๅž‹ | ๅ‰็ผ€ | ้™้ข | ้€Ÿ็Ž‡้™ๅˆถ | -| ------------------- | ----- | ---------- | ------------------------- | -| `claude-sonnet-4.5` | `kr/` | **ๆ— ้™ๅˆถ** | ๆœชๆŠฅๅ‘Šๆฏๆ—ฅไธŠ้™ | -| `claude-haiku-4.5` | `kr/` | **ๆ— ้™ๅˆถ** | ๆœชๆŠฅๅ‘Šๆฏๆ—ฅไธŠ้™ | -| `claude-opus-4.6` | `kr/` | **ๆ— ้™ๅˆถ** | ้€š่ฟ‡ Kiro ไฝฟ็”จๆœ€ๆ–ฐ็š„ Opus | +| Model | Prefix | Limit | Rate Limit | +| ------------------- | ------ | ------------- | --------------------- | +| `claude-sonnet-4.5` | `kr/` | **Unlimited** | No reported daily cap | +| `claude-haiku-4.5` | `kr/` | **Unlimited** | No reported daily cap | +| `claude-opus-4.6` | `kr/` | **Unlimited** | Latest Opus via Kiro | -### ๐ŸŸข QODER MODELS๏ผˆๅ…่ดน OAuth โ€” ๆ— ้œ€ไฟก็”จๅก๏ผ‰ +### ๐ŸŸข QODER MODELS (Free OAuth โ€” No Credit Card) -| ๆจกๅž‹ | ๅ‰็ผ€ | ้™้ข | ้€Ÿ็Ž‡้™ๅˆถ | -| ------------------ | ----- | ---------- | ---------- | -| `kimi-k2-thinking` | `if/` | **ๆ— ้™ๅˆถ** | ๆœชๆŠฅๅ‘ŠไธŠ้™ | -| `qwen3-coder-plus` | `if/` | **ๆ— ้™ๅˆถ** | ๆœชๆŠฅๅ‘ŠไธŠ้™ | -| `deepseek-r1` | `if/` | **ๆ— ้™ๅˆถ** | ๆœชๆŠฅๅ‘ŠไธŠ้™ | -| `minimax-m2.1` | `if/` | **ๆ— ้™ๅˆถ** | ๆœชๆŠฅๅ‘ŠไธŠ้™ | -| `kimi-k2` | `if/` | **ๆ— ้™ๅˆถ** | ๆœชๆŠฅๅ‘ŠไธŠ้™ | +| Model | Prefix | Limit | Rate Limit | +| ------------------ | ------ | ------------- | --------------- | +| `kimi-k2-thinking` | `if/` | **Unlimited** | No reported cap | +| `qwen3-coder-plus` | `if/` | **Unlimited** | No reported cap | +| `deepseek-r1` | `if/` | **Unlimited** | No reported cap | +| `minimax-m2.1` | `if/` | **Unlimited** | No reported cap | +| `kimi-k2` | `if/` | **Unlimited** | No reported cap | -### ๐ŸŸก QWEN MODELS๏ผˆ่ฎพๅค‡็ ่ฎค่ฏ๏ผ‰ +### ๐ŸŸก QWEN MODELS (Device Code Auth) -| ๆจกๅž‹ | ๅ‰็ผ€ | ้™้ข | ้€Ÿ็Ž‡้™ๅˆถ | -| ------------------- | ----- | ---------- | -------------- | -| `qwen3-coder-plus` | `qw/` | **ๆ— ้™ๅˆถ** | ๆœชๆŠฅๅ‘ŠไธŠ้™ | -| `qwen3-coder-flash` | `qw/` | **ๆ— ้™ๅˆถ** | ๆœชๆŠฅๅ‘ŠไธŠ้™ | -| `qwen3-coder-next` | `qw/` | **ๆ— ้™ๅˆถ** | ๆœชๆŠฅๅ‘ŠไธŠ้™ | -| `vision-model` | `qw/` | **ๆ— ้™ๅˆถ** | ๅคšๆจกๆ€๏ผˆๅ›พๅƒ๏ผ‰ | +| Model | Prefix | Limit | Rate Limit | +| ------------------- | ------ | ------------- | ------------------- | +| `qwen3-coder-plus` | `qw/` | **Unlimited** | No reported cap | +| `qwen3-coder-flash` | `qw/` | **Unlimited** | No reported cap | +| `qwen3-coder-next` | `qw/` | **Unlimited** | No reported cap | +| `vision-model` | `qw/` | **Unlimited** | Multimodal (images) | -### ๐ŸŸฃ GEMINI CLI๏ผˆGoogle OAuth๏ผ‰ +### ๐ŸŸฃ GEMINI CLI (Google OAuth) -| ๆจกๅž‹ | ๅ‰็ผ€ | ้™้ข | ้€Ÿ็Ž‡้™ๅˆถ | -| ------------------------ | ----- | --------------------------- | ---------- | -| `gemini-3-flash-preview` | `gc/` | **ๆฏๆœˆ 180K tok** + ๆฏๅคฉ 1K | ๆŒ‰ๆœˆ้‡็ฝฎ | -| `gemini-2.5-pro` | `gc/` | ๆฏๆœˆ 180K๏ผˆๅ…ฑไบซๆฑ ๏ผ‰ | ้ซ˜่ดจ้‡ๆจกๅž‹ | +| Model | Prefix | Limit | Rate Limit | +| ------------------------ | ------ | --------------------------- | ------------- | +| `gemini-3-flash-preview` | `gc/` | **180K tok/month** + 1K/day | Monthly reset | +| `gemini-2.5-pro` | `gc/` | 180K/month (shared pool) | High quality | -### โšซ NVIDIA NIM๏ผˆๅ…่ดน API Key โ€” build.nvidia.com๏ผ‰ +### โšซ NVIDIA NIM (Free API Key โ€” build.nvidia.com) -| ๅฑ‚็บง | ๆฏๆ—ฅ้™้ข | ้€Ÿ็Ž‡้™ๅˆถ | ่ฏดๆ˜Ž | -| ----------- | ------------- | ------------- | ------------------------------------------ | -| Free๏ผˆDev๏ผ‰ | ๆ—  token ไธŠ้™ | **็บฆ 40 RPM** | 70+ ไธชๆจกๅž‹๏ผ›่ฎกๅˆ’ๅœจ 2025 ๅนดไธญ่ฝฌไธบ็บฏ้€Ÿ็Ž‡้™ๅˆถ | +| Tier | Daily Limit | Rate Limit | Notes | +| ---------- | ------------ | ----------- | ------------------------------------------------------ | +| Free (Dev) | No token cap | **~40 RPM** | 70+ models; transitioning to pure rate limits mid-2025 | -็ƒญ้—จๅ…่ดนๆจกๅž‹๏ผš`moonshotai/kimi-k2.5`๏ผˆKimi K2.5๏ผ‰ใ€`z-ai/glm4.7`๏ผˆGLM 4.7๏ผ‰ใ€`deepseek-ai/deepseek-v3.2`๏ผˆDeepSeek V3.2๏ผ‰ใ€`nvidia/llama-3.3-70b-instruct`ใ€`deepseek/deepseek-r1` +Popular free models: `moonshotai/kimi-k2.5` (Kimi K2.5), `z-ai/glm4.7` (GLM 4.7), `deepseek-ai/deepseek-v3.2` (DeepSeek V3.2), `nvidia/llama-3.3-70b-instruct`, `deepseek/deepseek-r1` -### โšช CEREBRAS๏ผˆๅ…่ดน API Key โ€” inference.cerebras.ai๏ผ‰ +### โšช CEREBRAS (Free API Key โ€” inference.cerebras.ai) -| ๅฑ‚็บง | ๆฏๆ—ฅ้™้ข | ้€Ÿ็Ž‡้™ๅˆถ | ่ฏดๆ˜Ž | -| ---- | ---------------------- | ---------------- | --------------------------------- | -| Free | **ๆฏๅคฉ 100 ไธ‡ tokens** | 60K TPM / 30 RPM | ๅ…จ็ƒๆœ€ๅฟซ็š„ LLM ๆŽจ็†ไน‹ไธ€๏ผ›ๆฏๆ—ฅ้‡็ฝฎ | +| Tier | Daily Limit | Rate Limit | Notes | +| ---- | ----------------- | ---------------- | ------------------------------------------- | +| Free | **1M tokens/day** | 60K TPM / 30 RPM | World's fastest LLM inference; resets daily | -ๅฏ็”จๅ…่ดนๆจกๅž‹๏ผš`llama-3.3-70b`ใ€`llama-3.1-8b`ใ€`deepseek-r1-distill-llama-70b` +Available free: `llama-3.3-70b`, `llama-3.1-8b`, `deepseek-r1-distill-llama-70b` -### ๐Ÿ”ด GROQ๏ผˆๅ…่ดน API Key โ€” console.groq.com๏ผ‰ +### ๐Ÿ”ด GROQ (Free API Key โ€” console.groq.com) -| ๅฑ‚็บง | ๆฏๆ—ฅ้™้ข | ้€Ÿ็Ž‡้™ๅˆถ | ่ฏดๆ˜Ž | -| ---- | ------------- | ------------- | ------------------------------------ | -| Free | **14.4K RPD** | ๆฏๆจกๅž‹ 30 RPM | ๆ— ้œ€ไฟก็”จๅก๏ผ›่ถ…้™ๆ—ถ่ฟ”ๅ›ž 429๏ผŒไธไผšๆ‰ฃ่ดน | +| Tier | Daily Limit | Rate Limit | Notes | +| ---- | ------------- | ---------------- | ----------------------------------------- | +| Free | **14.4K RPD** | 30 RPM per model | No credit card; 429 on limit, not charged | -ๅฏ็”จๅ…่ดนๆจกๅž‹๏ผš`llama-3.3-70b-versatile`ใ€`gemma2-9b-it`ใ€`mixtral-8x7b`ใ€`whisper-large-v3` +Available free: `llama-3.3-70b-versatile`, `gemma2-9b-it`, `mixtral-8x7b`, `whisper-large-v3` -### ๐Ÿ”ด LONGCAT AI๏ผˆๅ…่ดน API Key โ€” longcat.chat๏ผ‰๐Ÿ†• +### ๐Ÿ”ด LONGCAT AI (Free API Key โ€” longcat.chat) ๐Ÿ†• -| ๆจกๅž‹ | ๅ‰็ผ€ | ๆฏๆ—ฅๅ…่ดน้ขๅบฆ | ่ฏดๆ˜Ž | -| ----------------------------- | ----- | --------------------- | ------------------ | -| `LongCat-Flash-Lite` | `lc/` | **5000 ไธ‡ tokens** ๐Ÿ’ฅ | ๅฒไธŠๆœ€ๅคง็š„ๅ…่ดน้ขๅบฆ | -| `LongCat-Flash-Chat` | `lc/` | 500K tokens | ๅคš่ฝฎๅฏน่ฏ | -| `LongCat-Flash-Thinking` | `lc/` | 500K tokens | ๆŽจ็† / CoT | -| `LongCat-Flash-Thinking-2601` | `lc/` | 500K tokens | 2026 ๅนด 1 ๆœˆ็‰ˆๆœฌ | -| `LongCat-Flash-Omni-2603` | `lc/` | 500K tokens | ๅคšๆจกๆ€ | +| Model | Prefix | Daily Free Quota | Notes | +| ----------------------------- | ------ | ----------------- | ----------------------- | +| `LongCat-Flash-Lite` | `lc/` | **50M tokens** ๐Ÿ’ฅ | Largest free quota ever | +| `LongCat-Flash-Chat` | `lc/` | 500K tokens | Multi-turn chat | +| `LongCat-Flash-Thinking` | `lc/` | 500K tokens | Reasoning / CoT | +| `LongCat-Flash-Thinking-2601` | `lc/` | 500K tokens | Jan 2026 version | +| `LongCat-Flash-Omni-2603` | `lc/` | 500K tokens | Multimodal | -> ๅ…ฌๆต‹ๆœŸ้—ด 100% ๅ…่ดนใ€‚ๅฏๅœจ [longcat.chat](https://longcat.chat) ไฝฟ็”จ้‚ฎ็ฎฑๆˆ–ๆ‰‹ๆœบๅทๆณจๅ†Œใ€‚ๆฏๆ—ฅ UTC 00:00 ้‡็ฝฎใ€‚ +> 100% free while in public beta. Sign up at [longcat.chat](https://longcat.chat) with email or phone. Resets daily 00:00 UTC. -### ๐ŸŸข POLLINATIONS AI๏ผˆๆ— ้œ€ API Key๏ผ‰๐Ÿ†• +### ๐ŸŸข POLLINATIONS AI (No API Key Required) ๐Ÿ†• -| ๆจกๅž‹ | ๅ‰็ผ€ | ้€Ÿ็Ž‡้™ๅˆถ | ่ƒŒๅŽๆไพ›ๅ•† | +| Model | Prefix | Rate Limit | Provider Behind | | ---------- | ------ | ---------- | ------------------ | -| `openai` | `pol/` | 1 ๆฌก/15 ็ง’ | GPT-5 | -| `claude` | `pol/` | 1 ๆฌก/15 ็ง’ | Anthropic Claude | -| `gemini` | `pol/` | 1 ๆฌก/15 ็ง’ | Google Gemini | -| `deepseek` | `pol/` | 1 ๆฌก/15 ็ง’ | DeepSeek V3 | -| `llama` | `pol/` | 1 ๆฌก/15 ็ง’ | Meta Llama 4 Scout | -| `mistral` | `pol/` | 1 ๆฌก/15 ็ง’ | Mistral AI | +| `openai` | `pol/` | 1 req/15s | GPT-5 | +| `claude` | `pol/` | 1 req/15s | Anthropic Claude | +| `gemini` | `pol/` | 1 req/15s | Google Gemini | +| `deepseek` | `pol/` | 1 req/15s | DeepSeek V3 | +| `llama` | `pol/` | 1 req/15s | Meta Llama 4 Scout | +| `mistral` | `pol/` | 1 req/15s | Mistral AI | -> โœจ **้›ถ้—จๆง›๏ผš** ๆ— ้œ€ๆณจๅ†Œใ€ๆ— ้œ€ API keyใ€‚ๆทปๅŠ  Pollinations ๆไพ›ๅ•†ๆ—ถๆŠŠ key ๅญ—ๆฎต็•™็ฉบๅณๅฏ็ซ‹ๅณไฝฟ็”จใ€‚ +> โœจ **Zero friction:** No signup, no API key. Add the Pollinations provider with an empty key field and it works immediately. -### ๐ŸŸ  CLOUDFLARE WORKERS AI๏ผˆๅ…่ดน API Key โ€” cloudflare.com๏ผ‰๐Ÿ†• +### ๐ŸŸ  CLOUDFLARE WORKERS AI (Free API Key โ€” cloudflare.com) ๐Ÿ†• -| ๅฑ‚็บง | ๆฏๆ—ฅ Neurons | ๆŠ˜็ฎ—็”จ้‡ | ่ฏดๆ˜Ž | -| ---- | ------------ | -------------------------------------------- | ---------------------- | -| Free | **10,000** | ็บฆ 150 ๆฌก LLM ๅ“ๅบ” / 500 ็ง’้Ÿณ้ข‘ / 15K embeds | ๅ…จ็ƒ่พน็ผ˜็ฝ‘็ปœ๏ผŒ50+ ๆจกๅž‹ | +| Tier | Daily Neurons | Equivalent Usage | Notes | +| ---- | ------------- | --------------------------------------- | ----------------------- | +| Free | **10,000** | ~150 LLM resp / 500s audio / 15K embeds | Global edge, 50+ models | -็ƒญ้—จๅ…่ดนๆจกๅž‹๏ผš`@cf/meta/llama-3.3-70b-instruct`ใ€`@cf/google/gemma-3-12b-it`ใ€`@cf/openai/whisper-large-v3-turbo`๏ผˆๅ…่ดน้Ÿณ้ข‘๏ผ๏ผ‰ใ€`@cf/qwen/qwen2.5-coder-15b-instruct` +Popular free models: `@cf/meta/llama-3.3-70b-instruct`, `@cf/google/gemma-3-12b-it`, `@cf/openai/whisper-large-v3-turbo` (free audio!), `@cf/qwen/qwen2.5-coder-15b-instruct` -> ้œ€่ฆๆฅ่‡ช [dash.cloudflare.com](https://dash.cloudflare.com) ็š„ API Token ๅ’Œ Account IDใ€‚่ฏทๅœจ provider settings ไธญไฟๅญ˜ Account IDใ€‚ +> Requires API Token + Account ID from [dash.cloudflare.com](https://dash.cloudflare.com). Store Account ID in provider settings. -### ๐ŸŸฃ SCALEWAY AI๏ผˆ100 ไธ‡ๅ…่ดน Tokens โ€” scaleway.com๏ผ‰๐Ÿ†• +### ๐ŸŸฃ SCALEWAY AI (1M Free Tokens โ€” scaleway.com) ๐Ÿ†• -| ๅฑ‚็บง | ๅ…่ดน้ขๅบฆ | ๅœฐๅŒบ | ่ฏดๆ˜Ž | -| ---- | ----------------- | ------------ | ------------------ | -| Free | **100 ไธ‡ tokens** | ๐Ÿ‡ซ๐Ÿ‡ท Paris, EU | ๅœจ้™้ขๅ†…ๆ— ้œ€ไฟก็”จๅก | +| Tier | Free Quota | Location | Notes | +| ---- | ------------- | ------------ | ----------------------------------- | +| Free | **1M tokens** | ๐Ÿ‡ซ๐Ÿ‡ท Paris, EU | No credit card needed within limits | -ๅฏ็”จๅ…่ดนๆจกๅž‹๏ผš`qwen3-235b-a22b-instruct-2507`๏ผˆQwen3 235B๏ผ๏ผ‰ใ€`llama-3.1-70b-instruct`ใ€`mistral-small-3.2-24b-instruct-2506`ใ€`deepseek-v3-0324` +Available free: `qwen3-235b-a22b-instruct-2507` (Qwen3 235B!), `llama-3.1-70b-instruct`, `mistral-small-3.2-24b-instruct-2506`, `deepseek-v3-0324` -> ็ฌฆๅˆ EU/GDPRใ€‚ๅฏๅœจ [console.scaleway.com](https://console.scaleway.com) ่Žทๅ– API keyใ€‚ +> EU/GDPR compliant. Get API key at [console.scaleway.com](https://console.scaleway.com). -> **๐Ÿ’ก Ultimate Free Stack๏ผˆ11 ๅฎถๆไพ›ๅ•†๏ผŒๆฐธไน…ๅ…่ดน๏ผ‰๏ผš** +> **๐Ÿ’ก The Ultimate Free Stack (11 Providers, $0 Forever):** > > ``` -> Kiro (kr/) โ†’ Claude Sonnet/Haiku ๆ— ้™ไฝฟ็”จ -> Qoder (if/) โ†’ kimi-k2-thinkingใ€qwen3-coder-plusใ€deepseek-r1 ๆ— ้™ไฝฟ็”จ -> LongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” ๆฏๅคฉ 5000 ไธ‡ tokens ๐Ÿ”ฅ -> Pollinations (pol/) โ†’ GPT-5ใ€Claudeใ€DeepSeekใ€Llama 4 โ€” ๆ— ้œ€ key -> Qwen (qw/) โ†’ qwen3-coder ็ณปๅˆ—ๆจกๅž‹ๆ— ้™ไฝฟ็”จ -> Gemini (gemini/) โ†’ Gemini 2.5 Flash โ€” ๆฏๅคฉๅ…่ดน 1500 ๆฌก -> Cloudflare AI (cf/) โ†’ 50+ ๆจกๅž‹ โ€” ๆฏๅคฉ 10K Neurons -> Scaleway (scw/) โ†’ Qwen3 235Bใ€Llama 70B โ€” 100 ไธ‡ๅ…่ดน tokens๏ผˆEU๏ผ‰ -> Groq (groq/) โ†’ Llama/Gemma โ€” ๆฏๅคฉ 14.4K ๆฌก่ถ…้ซ˜้€Ÿ่ฏทๆฑ‚ -> NVIDIA NIM (nvidia/) โ†’ 70+ ๅผ€ๆบๆจกๅž‹ โ€” ๆฐธไน… 40 RPM -> Cerebras (cerebras/) โ†’ ่ถ…้ซ˜้€Ÿ Llama/Qwen โ€” ๆฏๅคฉ 100 ไธ‡ tokens +> Kiro (kr/) โ†’ Claude Sonnet/Haiku UNLIMITED +> Qoder (if/) โ†’ kimi-k2-thinking, qwen3-coder-plus, deepseek-r1 UNLIMITED +> LongCat Lite (lc/) โ†’ LongCat-Flash-Lite โ€” 50M tokens/day ๐Ÿ”ฅ +> Pollinations (pol/) โ†’ GPT-5, Claude, DeepSeek, Llama 4 โ€” no key needed +> Qwen (qw/) โ†’ qwen3-coder models UNLIMITED +> Gemini (gemini/) โ†’ Gemini 2.5 Flash โ€” 1,500 req/day free +> Cloudflare AI (cf/) โ†’ 50+ models โ€” 10K Neurons/day +> Scaleway (scw/) โ†’ Qwen3 235B, Llama 70B โ€” 1M free tokens (EU) +> Groq (groq/) โ†’ Llama/Gemma โ€” 14.4K req/day ultra-fast +> NVIDIA NIM (nvidia/) โ†’ 70+ open models โ€” 40 RPM forever +> Cerebras (cerebras/) โ†’ Llama/Qwen world-fastest โ€” 1M tok/day > ``` -## ๐ŸŽ™๏ธ ๅ…่ดน่ฝฌๅฝ• Combo +## ๐ŸŽ™๏ธ Free Transcription Combo -> ๅฐ†ไปปๆ„้Ÿณ้ข‘/่ง†้ข‘่ฝฌๅฝ•ไธบๆ–‡ๆœฌ๏ผŒๆˆๆœฌ **$0**ใ€‚Deepgram ๆไพ› $200 ๅ…่ดน้ขๅบฆไฝœไธบไธปๅŠ›๏ผŒAssemblyAI ๆไพ› $50 ไฝœไธบๅ›ž้€€๏ผŒGroq Whisper ๅˆ™ไฝœไธบๆ— ้™ๅˆถ็š„็ดงๆ€ฅๅค‡็”จใ€‚ +> Transcribe any audio/video for **$0** โ€” Deepgram leads with $200 free, AssemblyAI $50 fallback, Groq Whisper as unlimited emergency backup. -| ๆไพ›ๅ•† | ๅ…่ดน้ขๅบฆ | ๆœ€ไฝณๆจกๅž‹ | ้€Ÿ็Ž‡้™ๅˆถ | -| ----------------- | --------------------- | ------------------------------------ | --------------------- | -| ๐ŸŸข **Deepgram** | **ๅ…่ดน $200**๏ผˆๆณจๅ†Œ๏ผ‰ | `nova-3` โ€” ็ฒพๅบฆๆœ€ไฝณ๏ผŒๆ”ฏๆŒ 30+ ็ง่ฏญ่จ€ | ๅ…่ดน้ขๅบฆไธ‹ๆ—  RPM ้™ๅˆถ | -| ๐Ÿ”ต **AssemblyAI** | **ๅ…่ดน $50**๏ผˆๆณจๅ†Œ๏ผ‰ | `universal-3-pro` โ€” ็ซ ่Š‚ใ€ๆƒ…็ปชใ€PII | ๅ…่ดน้ขๅบฆไธ‹ๆ—  RPM ้™ๅˆถ | -| ๐Ÿ”ด **Groq** | **ๆฐธไน…ๅ…่ดน** | `whisper-large-v3` โ€” OpenAI Whisper | 30 RPM๏ผˆๆœ‰้€Ÿ็Ž‡้™ๅˆถ๏ผ‰ | +| Provider | Free Credits | Best Model | Rate Limit | +| ----------------- | ---------------------- | -------------------------------------------- | ---------------------------- | +| ๐ŸŸข **Deepgram** | **$200 free** (signup) | `nova-3` โ€” best accuracy, 30+ languages | No RPM limit on free credits | +| ๐Ÿ”ต **AssemblyAI** | **$50 free** (signup) | `universal-3-pro` โ€” chapters, sentiment, PII | No RPM limit on free credits | +| ๐Ÿ”ด **Groq** | **Free forever** | `whisper-large-v3` โ€” OpenAI Whisper | 30 RPM (rate limited) | -**ๅœจ `/dashboard/combos` ไธญๅปบ่ฎฎ่ฟ™ๆ ท้…็ฝฎ combo๏ผš** +**Suggested combo in `/dashboard/combos`:** ``` Name: free-transcription Strategy: Priority Nodes: - [1] deepgram/nova-3 โ†’ ไผ˜ๅ…ˆไฝฟ็”จ $200 ๅ…่ดน้ขๅบฆ - [2] assemblyai/universal-3-pro โ†’ Deepgram ้ขๅบฆ็”จๅฐฝๆ—ถๅ›ž้€€ - [3] groq/whisper-large-v3 โ†’ ๆฐธไน…ๅ…่ดน๏ผŒไฝœไธบ็ดงๆ€ฅๅค‡็”จ + [1] deepgram/nova-3 โ†’ uses $200 free first + [2] assemblyai/universal-3-pro โ†’ fallback when Deepgram credits run out + [3] groq/whisper-large-v3 โ†’ free forever, emergency fallback ``` -็„ถๅŽๅœจ `/dashboard/media` โ†’ **Transcription** ๆ ‡็ญพ้กตไธญไธŠไผ ้Ÿณ้ข‘ๆˆ–่ง†้ข‘ๆ–‡ไปถ๏ผŒ้€‰ๆ‹ฉไฝ ็š„ combo ็ซฏ็‚น๏ผŒๅณๅฏ่Žทๅพ—ๆ”ฏๆŒๆ ผๅผ็š„่ฝฌๅฝ•็ป“ๆžœใ€‚ +Then in `/dashboard/media` โ†’ **Transcription** tab: upload any audio or video file โ†’ select your combo endpoint โ†’ get transcription in supported formats. -## ๐Ÿ’ก ไธป่ฆๅŠŸ่ƒฝ +## ๐Ÿ’ก Key Features -OmniRoute v2.0 ็š„ๅฎšไฝๆ˜ฏไธ€ไธชๅฏ่ฟ็ปด็š„ๅนณๅฐ๏ผŒ่€Œไธๅชๆ˜ฏไธ€ไธช่ฝฌๅ‘ไปฃ็†ใ€‚ +OmniRoute v2.0 is built as an operational platform, not just a relay proxy. -### ๐Ÿ†• ๆ–ฐๅขž๏ผšๅ— ClawRouter ๅฏๅ‘็š„ๆ”น่ฟ›๏ผˆ2026 ๅนด 3 ๆœˆ๏ผ‰ +### ๐Ÿ†• New โ€” ClawRouter-Inspired Improvements (Mar 2026) -| ๅŠŸ่ƒฝ | ไฝœ็”จ | -| ---------------------------------- | -------------------------------------------------------------------------------------------- | -| โšก **Grok-4 Fast Family** | xAI ๆจกๅž‹ไปทๆ ผไฝŽ่‡ณ $0.20/$0.50 ๆฏ็™พไธ‡ token๏ผŒๅŸบๅ‡†ๅปถ่ฟŸ 1143ms๏ผŒๆฏ” Gemini 2.5 Flash ๅฟซ็บฆ 30% | -| ๐Ÿง  **GLM-5 via Z.AI** | 128K ่พ“ๅ‡บไธŠไธ‹ๆ–‡๏ผŒ$0.5/1M๏ผŒๆ˜ฏ GLM ็ณปๅˆ—็š„ๆ–ฐๆ——่ˆฐ | -| ๐Ÿ”ฎ **MiniMax M2.5** | ๆŽจ็†ไธŽ agentic ไปปๅŠกไป…้œ€ $0.30/1M๏ผŒ็›ธๆฏ” M2.1 ๆœ‰ๆ˜Žๆ˜พๅ‡็บง | -| ๐ŸŽฏ **ๆŒ‰ๆจกๅž‹้…็ฝฎ toolCalling ๆ ‡ๅฟ—** | ๅœจๆณจๅ†Œ่กจไธญไธบๆฏไธชๆจกๅž‹ๅ•็‹ฌ่ฎพ็ฝฎ `toolCalling: true/false`๏ผŒAutoCombo ไผš่ทณ่ฟ‡ไธๆ”ฏๆŒๅทฅๅ…ท่ฐƒ็”จ็š„ๆจกๅž‹ | -| ๐ŸŒ **ๅคš่ฏญ่จ€ๆ„ๅ›พๆฃ€ๆต‹** | ๅœจ AutoCombo ๆ‰“ๅˆ†ไธญๅŠ ๅ…ฅ PT/ZH/ES/AR ๅ…ณ้”ฎ่ฏ๏ผŒๆๅ‡้ž่‹ฑๆ–‡ๅ†…ๅฎน็š„ๆจกๅž‹้€‰ๆ‹ฉๆ•ˆๆžœ | -| ๐Ÿ“Š **ๅŸบๅ‡†้ฉฑๅŠจ็š„ๅ›ž้€€** | ไฝฟ็”จ็œŸๅฎž่ฏทๆฑ‚ๅพ—ๅˆฐ็š„ p95 ๅปถ่ฟŸๅ‚ไธŽ combo ๆ‰“ๅˆ†๏ผŒAutoCombo ไผšไปŽ็œŸๅฎžๆ•ฐๆฎไธญๅญฆไน  | -| ๐Ÿ” **่ฏทๆฑ‚ๅŽป้‡** | ๅŸบไบŽๅ†…ๅฎนๅ“ˆๅธŒ็š„ๅŽป้‡็ช—ๅฃ๏ผŒๅคšๆ™บ่ƒฝไฝ“ๅฎ‰ๅ…จ๏ผŒ้ฟๅ…้‡ๅค่ฎก่ดน | -| ๐Ÿ”Œ **ๅฏๆ’ๆ‹” RouterStrategy** | ๅฏๆ‰ฉๅฑ•็š„ `RouterStrategy` ๆŽฅๅฃ๏ผŒๅฏ้€š่ฟ‡ๆ’ไปถๅŠ ๅ…ฅ่‡ชๅฎšไน‰่ทฏ็”ฑ้€ป่พ‘ | +| Feature | What It Does | +| ------------------------------------ | ------------------------------------------------------------------------------------------- | +| โšก **Grok-4 Fast Family** | xAI models at $0.20/$0.50/M โ€” benchmarked 1143ms (30% faster than Gemini 2.5 Flash) | +| ๐Ÿง  **GLM-5 via Z.AI** | 128K output context, $0.5/1M โ€” newest flagship from the GLM family | +| ๐Ÿ”ฎ **MiniMax M2.5** | Reasoning + agentic tasks at $0.30/1M โ€” significant upgrade from M2.1 | +| ๐ŸŽฏ **toolCalling Flag per Model** | Per-model `toolCalling: true/false` in registry โ€” AutoCombo skips non-tool-capable models | +| ๐ŸŒ **Multilingual Intent Detection** | PT/ZH/ES/AR keywords in AutoCombo scoring โ€” better model selection for non-English content | +| ๐Ÿ“Š **Benchmark-Driven Fallbacks** | Real p95 latency from live requests feeds combo scoring โ€” AutoCombo learns from actual data | +| ๐Ÿ” **Request Deduplication** | Content-hash based dedup window โ€” multi-agent safe, prevents duplicate charges | +| ๐Ÿ”Œ **Pluggable RouterStrategy** | Extensible `RouterStrategy` interface โ€” add custom routing logic as plugins | -### ๐Ÿš€ ๆญคๅ‰ v2.0.9+ ็š„่ƒฝๅŠ›๏ผšPlaygroundใ€CLI ๆŒ‡็บนไธŽ ACP +### ๐Ÿš€ Previous v2.0.9+ โ€” Playground, CLI Fingerprints & ACP -| ๅŠŸ่ƒฝ | ไฝœ็”จ | -| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| ๐ŸŽฎ **Model Playground** | ๅœจ Dashboard ไธญ็›ดๆŽฅๆต‹่ฏ•ไปปๆ„ๆจกๅž‹๏ผŒๆ”ฏๆŒ provider/model/endpoint ้€‰ๆ‹ฉๅ™จใ€Monaco Editorใ€ๆตๅผ่พ“ๅ‡บใ€็ปˆๆญข่ฏทๆฑ‚ๅ’Œ่€—ๆ—ถๆ˜พ็คบ | -| ๐Ÿ” **CLI Fingerprint Matching** | ๆŒ‰ๆไพ›ๅ•†ๅŒน้…ๅŽŸ็”Ÿ CLI ็š„่ฏทๆฑ‚ๅคดๅ’Œ่ฏทๆฑ‚ไฝ“้กบๅบ๏ผŒๅฏๅœจ Settings > Security ไธญๆŒ‰ๆไพ›ๅ•†ๅผ€ๅ…ณ๏ผŒไธ”**ไฟ็•™ไฝ ็š„ไปฃ็† IP** | -| ๐Ÿค **ACP Support (Agent Client Protocol)** | ๆ”ฏๆŒ CLI agent ๅ‘็Žฐ๏ผˆCodexใ€Claudeใ€Gooseใ€Gemini CLIใ€OpenClaw ็ญ‰ๅ…ฑ 10+๏ผ‰ใ€่ฟ›็จ‹ๅฏๅŠจๅ™จไปฅๅŠ `/api/acp/agents` ็ซฏ็‚น | -| ๐Ÿค– **ACP Agents Dashboard** | Debug โ€บ Agents ้กต้ขไผšไปฅ็ฝ‘ๆ ผๅฑ•็คบ 14 ไธช agents ็š„ๅฎ‰่ฃ…็Šถๆ€ใ€็‰ˆๆœฌๅ’Œ่‡ชๅฎšไน‰ agent ่กจๅ•ใ€‚**OpenCode** ็”จๆˆท่ฟ˜ไผš่Žทๅพ—โ€œDownload opencode.jsonโ€ๆŒ‰้’ฎ๏ผŒๅฏ่‡ชๅŠจ็”ŸๆˆๅŒ…ๅซๅ…จ้ƒจๅฏ็”จๆจกๅž‹็š„ๅณ็”จ้…็ฝฎใ€‚ | -| ๐Ÿ”ง **่‡ชๅฎšไน‰ๆจกๅž‹ `apiFormat` ่ทฏ็”ฑ** | ๅธฆๆœ‰ `apiFormat: "responses"` ็š„่‡ชๅฎšไน‰ๆจกๅž‹็Žฐๅœจๅฏๆญฃ็กฎ่ทฏ็”ฑๅˆฐ Responses API ็ฟป่ฏ‘ๅ™จ | -| ๐Ÿข **Codex ๅทฅไฝœๅŒบ้š”็ฆป** | ๅŒไธ€้‚ฎ็ฎฑไธ‹ๆ”ฏๆŒๅคšไธช Codex workspace๏ผŒOAuth ไผšๆŒ‰ workspace ID ๆญฃ็กฎๅŒบๅˆ†่ฟžๆŽฅ | -| ๐Ÿ”„ **Electron ่‡ชๅŠจๆ›ดๆ–ฐ** | ๆกŒ้ขๅบ”็”จไผšๆฃ€ๆŸฅๆ›ดๆ–ฐ๏ผŒๅนถๅœจ้‡ๅฏๆ—ถ่‡ชๅŠจๅฎ‰่ฃ… | +| Feature | What It Does | +| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| ๐ŸŽฎ **Model Playground** | Dashboard page to test any model directly โ€” provider/model/endpoint selectors, Monaco Editor, streaming, abort, timing | +| ๐Ÿ” **CLI Fingerprint Matching** | Per-provider header/body ordering to match native CLI signatures โ€” toggle per provider in Settings > Security. **Your proxy IP is preserved** | +| ๐Ÿค **ACP Support (Agent Client Protocol)** | CLI agent discovery (Codex, Claude, Goose, Gemini CLI, OpenClaw + 9 more), process spawner, `/api/acp/agents` endpoint | +| ๐Ÿค– **ACP Agents Dashboard** | Debug โ€บ Agents page โ€” grid of 14 agents with install status, version, custom agent form for any CLI tool. **OpenCode** users get a "Download opencode.json" button that auto-generates a ready-to-use config with all available models. | +| ๐Ÿ”ง **Custom Model `apiFormat` Routing** | Custom models with `apiFormat: "responses"` now correctly route to the Responses API translator | +| ๐Ÿข **Codex Workspace Isolation** | Multiple Codex workspaces per email โ€” OAuth correctly separates connections by workspace ID | +| ๐Ÿ”„ **Electron Auto-Update** | Desktop app checks for updates + auto-install on restart | -### ๐Ÿค– Agent ไธŽๅ่ฎฎ่ฟ็ปด๏ผˆv2.0๏ผ‰ +### ๐Ÿค– Agent & Protocol Operations (v2.0) -| ๅŠŸ่ƒฝ | ไฝœ็”จ | -| ---------------------------------- | ---------------------------------------------------------------------------------------------------------- | -| ๐Ÿ”ง **MCP Server (16 tools)** | ้€š่ฟ‡ 3 ็งไผ ่พ“ๆ–นๅผไธบ IDE/agent ๆไพ›ๅทฅๅ…ท๏ผšstdioใ€SSE๏ผˆ`/api/mcp/sse`๏ผ‰ใ€Streamable HTTP๏ผˆ`/api/mcp/stream`๏ผ‰ | -| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | ๆ”ฏๆŒๅŒๆญฅไธŽๆตๅผๆต็จ‹็š„ agent-to-agent ไปปๅŠกๆ‰ง่กŒ | -| ๐Ÿงญ **็ปŸไธ€ Endpoints ้กต้ข** | ไปฅๆ ‡็ญพ้กตๅฝขๅผ็ฎก็† Endpoint Proxyใ€MCPใ€A2A ๅ’Œ API Endpoints | -| ๐ŸŽš๏ธ **ๆœๅŠกๅฏ็”จ/ๅœ็”จๅผ€ๅ…ณ** | ไธบ MCP ๅ’Œ A2A ๆไพ› ON/OFF ๅผ€ๅ…ณๅนถๆŒไน…ๅŒ–่ฎพ็ฝฎ๏ผˆ้ป˜่ฎค๏ผšOFF๏ผ‰ | -| ๐Ÿ›ฐ๏ธ **MCP ่ฟ่กŒๆ—ถๅฟƒ่ทณ** | ๅฑ•็คบ็œŸๅฎž่ฟ›็จ‹็Šถๆ€๏ผˆpidใ€่ฟ่กŒๆ—ถ้•ฟใ€ๅฟƒ่ทณๅนด้พ„ใ€ไผ ่พ“ๆ–นๅผใ€scope ๆจกๅผ๏ผ‰ | -| ๐Ÿ“‹ **MCP ๅฎก่ฎก่ฝจ่ฟน** | ๅฏ่ฟ‡ๆปค็š„ๅฎก่ฎกๆ—ฅๅฟ—๏ผŒๅŒ…ๅซๆˆๅŠŸ/ๅคฑ่ดฅ็ป“ๆžœไธŽ key ๅฝ’ๅฑžไฟกๆฏ | -| ๐Ÿ” **MCP Scope ๅผบๅˆถๆŽงๅˆถ** | 9 ไธช็ป†็ฒ’ๅบฆ scope ๆƒ้™๏ผŒ็”จไบŽๅ—ๆŽงๅทฅๅ…ท่ฎฟ้—ฎ | -| ๐Ÿ“ก **A2A ไปปๅŠก็”Ÿๅ‘ฝๅ‘จๆœŸ็ฎก็†** | ๅˆ—ๅ‡บ/่ฟ‡ๆปคไปปๅŠก๏ผŒๆŸฅ็œ‹ไบ‹ไปถไธŽ artifact๏ผŒๅ–ๆถˆ่ฟ่กŒไธญ็š„ไปปๅŠก | -| ๐Ÿ“‹ **Agent Card ๅ‘็Žฐ** | ้€š่ฟ‡ `/.well-known/agent.json` ๆ”ฏๆŒๅฎขๆˆท็ซฏ่‡ชๅŠจๅ‘็Žฐ | -| ๐Ÿงช **ๅ่ฎฎ E2E ๆต‹่ฏ•ๆก†ๆžถ** | ๅœจ `test:protocols:e2e` ไธญ่ฟ่กŒ็œŸๅฎž MCP SDK + A2A ๅฎขๆˆท็ซฏๆต็จ‹ | -| โš™๏ธ **่ฟ็ปดๆŽงๅˆถ** | ๅœจไธ€ไธชๆŽงๅˆถ้ข็ปŸไธ€ๅˆ‡ๆข comboใ€ๅบ”็”จ resilience profileใ€้‡็ฝฎ breaker | +| Feature | What It Does | +| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| ๐Ÿ”ง **MCP Server (25 tools)** | IDE/agent tools via 3 transports: stdio, SSE (`/api/mcp/sse`), Streamable HTTP (`/api/mcp/stream`). 18 core + 3 memory + 4 skill tools | +| ๐Ÿค **A2A Server (JSON-RPC + SSE)** | Agent-to-agent task execution with sync and streaming flows | +| ๐Ÿงญ **Consolidated Endpoints Page** | Tabbed management page with Endpoint Proxy, MCP, A2A, and API Endpoints tabs | +| ๐ŸŽš๏ธ **Service Enable/Disable Toggles** | ON/OFF switches for MCP and A2A with settings persistence (default: OFF) | +| ๐Ÿ›ฐ๏ธ **MCP Runtime Heartbeat** | Real process status (pid, uptime, heartbeat age, transport, scope mode) | +| ๐Ÿ“‹ **MCP Audit Trail** | Filterable audit logs with success/failure and key attribution | +| ๐Ÿ” **MCP Scope Enforcement** | 10 granular scope permissions for controlled tool access | +| ๐Ÿ“ก **A2A Task Lifecycle Management** | List/filter tasks, inspect events/artifacts, cancel running tasks | +| ๐Ÿ“‹ **Agent Card Discovery** | `/.well-known/agent.json` for client auto-discovery | +| ๐Ÿงช **Protocol E2E Test Harness** | Real MCP SDK + A2A client flows in `test:protocols:e2e` | +| โš™๏ธ **Operational Controls** | Switch combo, apply resilience profiles, reset breakers from one control surface | -### ๐Ÿง  ่ทฏ็”ฑไธŽๆ™บ่ƒฝ +### ๐Ÿง  Routing & Intelligence -| ๅŠŸ่ƒฝ | ไฝœ็”จ | -| --------------------------- | -------------------------------------------------------------- | -| ๐ŸŽฏ **ๆ™บ่ƒฝ 4 ๅฑ‚ๅŽๅค‡** | ่‡ชๅŠจ่ทฏ็”ฑ๏ผšSubscription โ†’ API Key โ†’ Cheap โ†’ Free | -| ๐Ÿ“Š **ๅฎžๆ—ถ้…้ข่ทŸ่ธช** | ๆŒ‰ๆไพ›ๅ•†ๅฑ•็คบๅฎžๆ—ถ token ่ฎกๆ•ฐไธŽ้‡็ฝฎๅ€’่ฎกๆ—ถ | -| ๐Ÿ”„ **ๆ ผๅผ็ฟป่ฏ‘** | OpenAI โ†” Claude โ†” Gemini โ†” Responses๏ผŒๅธฆ schema-safe ่ฝฌๆข | -| ๐Ÿ‘ฅ **ๅคš่ดฆๆˆทๆ”ฏๆŒ** | ๆฏไธชๆไพ›ๅ•†ๆ”ฏๆŒๅคšไธช่ดฆๆˆทๅนถ่ฟ›่กŒๆ™บ่ƒฝ้€‰ๆ‹ฉ | -| ๐Ÿ”„ **่‡ชๅŠจ Token ๅˆทๆ–ฐ** | OAuth token ่‡ชๅŠจๅˆทๆ–ฐๅนถๆ”ฏๆŒ้‡่ฏ• | -| ๐ŸŽจ **่‡ชๅฎšไน‰ Combo** | 6 ็งๅ‡่กก็ญ–็•ฅ + ๅŽๅค‡้“พๆŽงๅˆถ | -| ๐ŸŒ **้€š้…็ฌฆ่ทฏ็”ฑๅ™จ** | ๆ”ฏๆŒ `provider/*` ๅŠจๆ€่ทฏ็”ฑ | -| ๐Ÿง  **Thinking ้ข„็ฎ—ๆŽงๅˆถ** | ๆ”ฏๆŒ passthroughใ€autoใ€custom ๅ’Œ adaptive ๆŽจ็†้™ๅˆถ | -| ๐Ÿ”€ **ๆจกๅž‹ๅˆซๅ** | ๅ†…็ฝฎ + ่‡ชๅฎšไน‰ๆจกๅž‹ๅˆซๅไธŽๅฎ‰ๅ…จ่ฟ็งป | -| โšก **ๅŽๅฐ้™็บง** | ๅฐ†ไฝŽไผ˜ๅ…ˆ็บงๅŽๅฐไปปๅŠก่ทฏ็”ฑๅˆฐๆ›ดไพฟๅฎœ็š„ๆจกๅž‹ | -| ๐Ÿงช **ไปปๅŠกๆ„Ÿ็Ÿฅๆ™บ่ƒฝ่ทฏ็”ฑ** | ๆŒ‰ๅ†…ๅฎน็ฑปๅž‹่‡ชๅŠจ้€‰ๆ‹ฉๆจกๅž‹๏ผˆcoding/vision/analysis/summarization๏ผ‰ | -| ๐Ÿ”„ **A2A Agent ๅทฅไฝœๆต** | ้ขๅ‘ๆœ‰็Šถๆ€ๅคšๆญฅ้ชค agent ๆ‰ง่กŒ็š„็กฎๅฎšๆ€ง FSM orchestrator | -| ๐Ÿ”€ **่‡ช้€‚ๅบ”่ทฏ็”ฑ** | ๆ นๆฎ token ไฝ“้‡ไธŽๆ็คบ่ฏๅคๆ‚ๅบฆๅŠจๆ€่ฆ†็›–็ญ–็•ฅ | -| ๐ŸŽฒ **ๆไพ›ๅ•†ๅคšๆ ทๆ€ง** | ไฝฟ็”จ Shannon entropy ่ฏ„ๅˆ†ๅนณ่กก auto-combo ๆต้‡ๅˆ†ๅธƒ | -| ๐Ÿ’ฌ **System Prompt ๆณจๅ…ฅ** | ็ปŸไธ€ๅบ”็”จๅ…จๅฑ€่กŒไธบๆŽงๅˆถ | -| ๐Ÿ“„ **Responses API ๅ…ผๅฎนๆ€ง** | ไธบ Codex ๅ’Œ้ซ˜็บง agentic workflow ๆไพ›ๅฎŒๆ•ด `/v1/responses` ๆ”ฏๆŒ | +| Feature | What It Does | +| ---------------------------------- | ------------------------------------------------------------------------ | +| ๐ŸŽฏ **Smart 4-Tier Fallback** | Auto-route: Subscription โ†’ API Key โ†’ Cheap โ†’ Free | +| ๐Ÿ“Š **Real-Time Quota Tracking** | Live token count + reset countdown per provider | +| ๐Ÿ”„ **Format Translation** | OpenAI โ†” Claude โ†” Gemini โ†” Responses with schema-safe conversions | +| ๐Ÿ‘ฅ **Multi-Account Support** | Multiple accounts per provider with intelligent selection | +| ๐Ÿ”„ **Auto Token Refresh** | OAuth tokens refresh automatically with retry | +| ๐ŸŽจ **Custom Combos** | 9 balancing strategies + fallback chain control | +| ๐ŸŒ **Wildcard Router** | `provider/*` dynamic routing | +| ๐Ÿง  **Thinking Budget Controls** | Passthrough, auto, custom, and adaptive reasoning limits | +| ๐Ÿ”€ **Model Aliases** | Built-in + custom model aliasing and migration safety | +| โšก **Background Degradation** | Route low-priority background tasks to cheaper models | +| ๐Ÿงช **Task-Aware Smart Routing** | Auto-select model by content type (coding/vision/analysis/summarization) | +| ๐Ÿ”„ **A2A Agent Workflows** | Deterministic FSM orchestrator for stateful multi-step agent executions | +| ๐Ÿ”€ **Adaptive Routing** | Dynamic strategy override based on token volume and prompt complexity | +| ๐ŸŽฒ **Provider Diversity** | Shannon entropy scoring balancing auto-combo traffic distribution | +| ๐Ÿ’ฌ **System Prompt Injection** | Global behavior controls applied consistently | +| ๐Ÿ“„ **Responses API Compatibility** | Full `/v1/responses` support for Codex and advanced agentic workflows | -### ๐ŸŽต ๅคšๆจกๆ€ API +### ๐ŸŽต Multi-Modal APIs -| ๅŠŸ่ƒฝ | ไฝœ็”จ | -| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| ๐Ÿ–ผ๏ธ **ๅ›พๅƒ็”Ÿๆˆ** | `/v1/images/generations`๏ผŒๆ”ฏๆŒ cloud ๅ’ŒๆœฌๅœฐๅŽ็ซฏ | -| ๐Ÿ“ **Embeddings** | `/v1/embeddings`๏ผŒ้€‚็”จไบŽๆœ็ดขๅ’Œ RAG pipeline | -| ๐ŸŽค **้Ÿณ้ข‘่ฝฌๅฝ•** | `/v1/audio/transcriptions`๏ผŒๆ”ฏๆŒ 7 ๅฎถๆไพ›ๅ•†๏ผˆDeepgram Nova 3ใ€AssemblyAIใ€Groq Whisperใ€HuggingFaceใ€ElevenLabsใ€OpenAIใ€Azure๏ผ‰๏ผŒ่‡ชๅŠจ่ฏญ่จ€ๆฃ€ๆต‹๏ผŒๆ”ฏๆŒ MP4/MP3/WAV | -| ๐Ÿ”Š **Text-to-Speech** | `/v1/audio/speech`๏ผŒๆ”ฏๆŒ 10 ๅฎถๆไพ›ๅ•†๏ผˆElevenLabsใ€OpenAIใ€Deepgramใ€Cartesiaใ€PlayHTใ€HuggingFaceใ€Nvidia NIMใ€Inworldใ€Coquiใ€Tortoise๏ผ‰๏ผŒๅนถ่ฟ”ๅ›žๆญฃ็กฎ้”™่ฏฏไฟกๆฏ | -| ๐ŸŽฌ **่ง†้ข‘็”Ÿๆˆ** | `/v1/videos/generations`๏ผˆComfyUI + SD WebUI workflows๏ผ‰ | -| ๐ŸŽต **้Ÿณไน็”Ÿๆˆ** | `/v1/music/generations`๏ผˆComfyUI workflows๏ผ‰ | -| ๐Ÿ›ก๏ธ **Moderations** | `/v1/moderations` ๅฎ‰ๅ…จๆฃ€ๆŸฅ | -| ๐Ÿ”€ **้‡ๆŽ’ๅบ** | `/v1/rerank` ็”จไบŽ็›ธๅ…ณๆ€ง่ฏ„ๅˆ† | -| ๐Ÿ” **Web Search** ๐Ÿ†• | `/v1/search`๏ผŒๆ”ฏๆŒ 5 ๅฎถๆไพ›ๅ•†๏ผˆSerperใ€Braveใ€Perplexityใ€Exaใ€Tavily๏ผ‰๏ผŒๆฏๆœˆ 6,500+ ๅ…่ดน้ขๅบฆ๏ผŒๆ”ฏๆŒ่‡ชๅŠจๆ•…้šœ่ฝฌ็งปไธŽ็ผ“ๅญ˜ | +| Feature | What It Does | +| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| ๐Ÿ–ผ๏ธ **Image Generation** | `/v1/images/generations` with cloud and local backends | +| ๐Ÿ“ **Embeddings** | `/v1/embeddings` for search and RAG pipelines | +| ๐ŸŽค **Audio Transcription** | `/v1/audio/transcriptions` โ€” 7 providers (Deepgram Nova 3, AssemblyAI, Groq Whisper, HuggingFace, ElevenLabs, OpenAI, Azure), auto-language detection, MP4/MP3/WAV support | +| ๐Ÿ”Š **Text-to-Speech** | `/v1/audio/speech` โ€” 10 providers (ElevenLabs, OpenAI, Deepgram, Cartesia, PlayHT, HuggingFace, Nvidia NIM, Inworld, Coqui, Tortoise) with correct error messages | +| ๐ŸŽฌ **Video Generation** | `/v1/videos/generations` (ComfyUI + SD WebUI workflows) | +| ๐ŸŽต **Music Generation** | `/v1/music/generations` (ComfyUI workflows) | +| ๐Ÿ›ก๏ธ **Moderations** | `/v1/moderations` safety checks | +| ๐Ÿ”€ **Reranking** | `/v1/rerank` for relevance scoring | +| ๐Ÿ” **Web Search** ๐Ÿ†• | `/v1/search` โ€” 5 providers (Serper, Brave, Perplexity, Exa, Tavily), 6,500+ free/month, auto-failover, cache | -### ๐Ÿ›ก๏ธ ๅผนๆ€งใ€ๅฎ‰ๅ…จไธŽๆฒป็† +### ๐Ÿ›ก๏ธ Resilience, Security & Governance -| ๅŠŸ่ƒฝ | ไฝœ็”จ | -| ------------------------------ | ----------------------------------------------------------- | -| ๐Ÿ”Œ **็†”ๆ–ญๅ™จ** | ๆŒ‰ๆจกๅž‹่ฟ›่กŒ็†”ๆ–ญ/ๆขๅค๏ผŒๅนถๆ”ฏๆŒ้˜ˆๅ€ผๆŽงๅˆถ | -| ๐ŸŽฏ **็ซฏ็‚นๆ„Ÿ็Ÿฅๆจกๅž‹** | ่‡ชๅฎšไน‰ๆจกๅž‹ๅฏๅฃฐๆ˜Žๆ”ฏๆŒ็š„็ซฏ็‚นไธŽ API ๆ ผๅผ | -| ๐Ÿ›ก๏ธ **้˜ฒๆƒŠ็พค** | ๅœจ้‡่ฏ•/้™ๆตไบ‹ไปถไธญไฝฟ็”จ mutex + semaphore ไฟๆŠค | -| ๐Ÿง  **่ฏญไน‰ + ็ญพๅ็ผ“ๅญ˜** | ้€š่ฟ‡ไธคๅฑ‚็ผ“ๅญ˜้™ไฝŽๆˆๆœฌไธŽๅปถ่ฟŸ | -| โšก **่ฏทๆฑ‚ๅน‚็ญ‰ๆ€ง** | ๆไพ›้‡ๅค่ฏทๆฑ‚ไฟๆŠค็ช—ๅฃ | -| ๐Ÿ”’ **TLS ๆŒ‡็บนไผช่ฃ…** | ็ฑปๆต่งˆๅ™จ TLS ๆŒ‡็บน๏ผŒ**้™ไฝŽ bot detection ไธŽ่ดฆๆˆทๆ ‡่ฎฐ้ฃŽ้™ฉ** | -| ๐Ÿ” **CLI ๆŒ‡็บนๅŒน้…** | ๅŒน้…ๅŽŸ็”Ÿ CLI ่ฏทๆฑ‚็ญพๅ๏ผŒ**ๅœจไฟ็•™ไปฃ็† IP ็š„ๅŒๆ—ถ้™ไฝŽๅฐ็ฆ้ฃŽ้™ฉ** | -| ๐ŸŒ **IP ่ฟ‡ๆปค** | ไธบๆšด้œฒ้ƒจ็ฝฒๆไพ› allowlist/blocklist ๆŽงๅˆถ | -| ๐Ÿ“Š **ๅฏ็ผ–่พ‘้€Ÿ็Ž‡้™ๅˆถ** | ๆ”ฏๆŒๅ…จๅฑ€/ๆไพ›ๅ•†็บง้™ๅˆถๅนถๆŒไน…ๅŒ– | -| ๐Ÿ“‰ **ไผ˜้›…้™็บง** | ๅคšๅฑ‚่ƒฝๅŠ›ๅŽๅค‡๏ผŒไฟๆŠคๆ ธๅฟƒ็ฝ‘ๅ…ณๆ“ไฝœ | -| ๐Ÿ“œ **้…็ฝฎๅฎก่ฎก่ฝจ่ฟน** | ๅŸบไบŽ diff ็š„ๅ˜ๆ›ด่ทŸ่ธช๏ผŒ้˜ฒๆญข่ฟ็ปดๆผ‚็งปๅนถๆ”ฏๆŒ็ฎ€ๅ•ๅ›žๆปš | -| โณ **ๆไพ›ๅ•†ๅฅๅบทๅŒๆญฅ** | ไธปๅŠจ็›‘ๆŽง token ่ฟ‡ๆœŸ๏ผŒๅœจ่ฎค่ฏๅคฑ่ดฅๅ‰่งฆๅ‘ๅ‘Š่ญฆ | -| ๐Ÿšช **่‡ชๅŠจ็ฆ็”จ่ขซๅฐ่ดฆๆˆท** | ้€š่ฟ‡่ฟ็ปด็†”ๆ–ญๅ™จ่‡ชๅŠจๅฐๅญ˜่ขซๆฐธไน…้˜ปๆญข็š„ token ่ดฆๆˆท | -| ๐Ÿ”‘ **API ๅฏ†้’ฅ็ฎก็† + ่Œƒๅ›ดๆŽงๅˆถ** | ๅฎ‰ๅ…จๅœฐ็ญพๅ‘/่ฝฎๆขๅฏ†้’ฅ๏ผŒๅนถๆŽงๅˆถๆจกๅž‹/ๆไพ›ๅ•†่Œƒๅ›ด | -| ๐Ÿ‘๏ธ **ๅฎšๅ‘ API ๅฏ†้’ฅๆ˜พ็คบ** ๐Ÿ†• | ้€š่ฟ‡ `ALLOW_API_KEY_REVEAL` ่ฟ›่กŒๅฏ้€‰็š„ API ๅฏ†้’ฅๆขๅค | -| ๐Ÿ›ก๏ธ **ๅ—ไฟๆŠค็š„ `/models`** | ไธบๆจกๅž‹็›ฎๅฝ•ๆไพ›ๅฏ้€‰่ฎค่ฏ้—จๆŽงไธŽๆไพ›ๅ•†้š่— | +| Feature | What It Does | +| ----------------------------------- | -------------------------------------------------------------------------------------- | +| ๐Ÿ”Œ **Circuit Breakers** | Per-model trip/recover with threshold controls | +| ๐ŸŽฏ **Endpoint-Aware Models** | Custom models declare supported endpoints + API format | +| ๐Ÿ›ก๏ธ **Anti-Thundering Herd** | Mutex + semaphore protections on retry/rate events | +| ๐Ÿง  **Semantic + Signature Cache** | Cost/latency reduction with two cache layers | +| โšก **Request Idempotency** | Duplicate protection window | +| ๐Ÿ”’ **TLS Fingerprint Spoofing** | Browser-like TLS fingerprint โ€” **reduces bot detection and account flagging** | +| ๐Ÿ” **CLI Fingerprint Matching** | Matches native CLI request signatures โ€” **reduces ban risk while preserving proxy IP** | +| ๐ŸŒ **IP Filtering** | Allowlist/blocklist control for exposed deployments | +| ๐Ÿ“Š **Editable Rate Limits** | Configurable global/provider-level limits with persistence | +| ๐Ÿ“‰ **Graceful Degradation** | Multi-layer capability fallbacks protecting core gateway operations | +| ๐Ÿ“œ **Config Audit Trail** | Diff-based change tracking preventing operational drift with simple rollbacks | +| โณ **Provider Health Sync** | Proactive token expiration monitoring triggering alerts before authorization failures | +| ๐Ÿšช **Auto-Disable Banned Accounts** | Operational circuit breaker sealing permanently blocked token accounts automatically | +| ๐Ÿ”‘ **API Key Management + Scoping** | Secure key issuance/rotation and model/provider controls | +| ๐Ÿ‘๏ธ **Scoped API Key Reveal** ๐Ÿ†• | Opt-in recovery of API keys via `ALLOW_API_KEY_REVEAL` | +| ๐Ÿ›ก๏ธ **Protected `/models`** | Optional auth gating and provider hiding for model catalog | -### ๐Ÿ“Š ๅฏ่ง‚ๆต‹ๆ€งไธŽๅˆ†ๆž +### ๐Ÿ“Š Observability & Analytics -| ๅŠŸ่ƒฝ | ไฝœ็”จ | -| ---------------------- | ------------------------------------------- | -| ๐Ÿ“ **่ฏทๆฑ‚ + ไปฃ็†ๆ—ฅๅฟ—** | ๅฎŒๆ•ด็š„่ฏทๆฑ‚/ๅ“ๅบ”ไธŽไปฃ็†ๆ—ฅๅฟ— | -| ๐Ÿ“‰ **ๆตๅผ่ฏฆ็ป†ๆ—ฅๅฟ—** ๐Ÿ†• | ๅฐ† SSE payload ๆตๅœจ UI ไธญๅนฒๅ‡€ๅœฐ้‡ๅปบๅ‡บๆฅ | -| ๐Ÿ“‹ **็ปŸไธ€ๆ—ฅๅฟ—ไปช่กจ็›˜** | ๅœจๅŒไธ€้กต้ขๆŸฅ็œ‹่ฏทๆฑ‚ใ€ไปฃ็†ใ€ๅฎก่ฎกไธŽๆŽงๅˆถๅฐ่ง†ๅ›พ | -| ๐Ÿ” **่ฏทๆฑ‚้ฅๆต‹** | p50/p95/p99 ๅปถ่ฟŸไธŽ่ฏทๆฑ‚่ฟฝ่ธช | -| ๐Ÿฅ **ๅฅๅบทไปช่กจ็›˜** | ่ฟ่กŒๆ—ถ้•ฟใ€breaker ็Šถๆ€ใ€้”ๅฎšใ€็ผ“ๅญ˜็ปŸ่ฎก | -| ๐Ÿ’ฐ **ๆˆๆœฌ่ทŸ่ธช** | ้ข„็ฎ—ๆŽงๅˆถไธŽๆŒ‰ๆจกๅž‹ๅฎšไปทๅฏ่งๆ€ง | -| ๐Ÿ“ˆ **ๅˆ†ๆžๅฏ่ง†ๅŒ–** | ๆจกๅž‹/ๆไพ›ๅ•†็”จ้‡ๆดžๅฏŸไธŽ่ถ‹ๅŠฟ่ง†ๅ›พ | -| ๐Ÿงช **่ฏ„ไผฐๆก†ๆžถ** | ๆ”ฏๆŒๅฏ้…็ฝฎๅŒน้…็ญ–็•ฅ็š„ Golden Set ๆต‹่ฏ• | -| ๐Ÿ“ก **ๅฎžๆ—ถ่ฏŠๆ–ญ** ๐Ÿ†• | ้€š่ฟ‡็ป•่ฟ‡่ฏญไน‰็ผ“ๅญ˜ๆฅ่ฟ›่กŒๅ‡†็กฎ็š„ combo ๅฎžๆ—ถๆต‹่ฏ• | +| Feature | What It Does | +| -------------------------------- | ----------------------------------------------------- | +| ๐Ÿ“ **Request + Proxy Logging** | Full request/response and proxy logging | +| ๐Ÿ“‰ **Streamed Detailed Logs** ๐Ÿ†• | Reconstructs SSE payload streams cleanly into the UI | +| ๐Ÿ“‹ **Unified Logs Dashboard** | Request, proxy, audit, and console views in one page | +| ๐Ÿ” **Request Telemetry** | p50/p95/p99 latency and request tracing | +| ๐Ÿฅ **Health Dashboard** | Uptime, breaker states, lockouts, cache stats | +| ๐Ÿ’ฐ **Cost Tracking** | Budget controls and per-model pricing visibility | +| ๐Ÿ“ˆ **Analytics Visualizations** | Model/provider usage insights and trend views | +| ๐Ÿงช **Evaluation Framework** | Golden set testing with configurable match strategies | +| ๐Ÿ“ก **Live Diagnostics** ๐Ÿ†• | Semantic cache bypass for accurate combo live testing | -### โ˜๏ธ ้ƒจ็ฝฒไธŽๅนณๅฐ +### โ˜๏ธ Deployment & Platform -| ๅŠŸ่ƒฝ | ไฝœ็”จ | -| --------------------------- | ---------------------------------------------------- | -| ๐ŸŒ **ๅฏ้ƒจ็ฝฒๅˆฐไปปๆ„็Žฏๅขƒ** | ๆ”ฏๆŒ Localhostใ€VPSใ€Dockerใ€Cloud ็Žฏๅขƒ | -| ๐Ÿš‡ **Cloudflare Tunnel** ๐Ÿ†• | ไปŽไปช่กจ็›˜ไธ€้”ฎ้›†ๆˆ Quick Tunnel | -| ๐Ÿ”‘ **API ๅฏ†้’ฅๆจกๅž‹่ฟ‡ๆปค** | ๅŽŸ็”ŸๆŒ‰ๅˆ†้…็š„ Bearer ไธŠไธ‹ๆ–‡่ง’่‰ฒ่ฟ‡ๆปค `/v1/models` ๅ“ๅบ” | -| โšก **ๆ™บ่ƒฝ็ผ“ๅญ˜็ป•่ฟ‡** | ๆ”ฏๆŒๅฏ้…็ฝฎ TTL ๅฏๅ‘ๅผไธŽๅผบๅˆถ้‡ๆ–ฐๆŠ“ๅ–ๆŽงๅˆถ | -| ๐Ÿ”„ **ๅค‡ไปฝ/ๆขๅค** | ๆ”ฏๆŒๅฏผๅ‡บ/ๅฏผๅ…ฅไธŽ็พ้šพๆขๅคๆต็จ‹ | -| ๐Ÿง™ **ๅ…ฅ้—จๅ‘ๅฏผ** | ้ฆ–ๆฌก่ฟ่กŒๅผ•ๅฏผ้…็ฝฎ | -| ๐Ÿ”ง **CLI Tools ไปช่กจ็›˜** | ไธบๅธธ่ง็ผ–็จ‹ๅทฅๅ…ทๆไพ›ไธ€้”ฎ่ฎพ็ฝฎ | -| ๐ŸŽฎ **ๆจกๅž‹ Playground** | ็›ดๆŽฅไปŽไปช่กจ็›˜ๆต‹่ฏ•ไปปๆ„ provider/model/endpoint | -| ๐Ÿ” **CLI ๆŒ‡็บนๅผ€ๅ…ณ** | ๅœจ Settings > Security ไธญๆŒ‰ๆไพ›ๅ•†ๅผ€ๅฏๆŒ‡็บนๅŒน้… | -| ๐ŸŒ **i18n๏ผˆ30 ็ง่ฏญ่จ€๏ผ‰** | ๅฎŒๆ•ดๆ”ฏๆŒ Dashboard + docs ๅคš่ฏญ่จ€๏ผŒๅนถ่ฆ†็›– RTL | -| ๐Ÿงน **ๆธ…็ฉบๅ…จ้ƒจๆจกๅž‹** | ๅœจๆไพ›ๅ•†่ฏฆๆƒ…ไธญไธ€้”ฎๆธ…็ฉบๆจกๅž‹ๅˆ—่กจ | -| ๐Ÿ‘๏ธ **ไพง่พนๆ ๆŽงๅˆถ** ๐Ÿ†• | ไปŽ Appearance Settings ้š่—็ป„ไปถไธŽ้›†ๆˆ | -| ๐Ÿ“‹ **Issue ๆจกๆฟ** | ไธบ bug ๅ’ŒๅŠŸ่ƒฝ่ฏทๆฑ‚ๆไพ›ๆ ‡ๅ‡†ๅŒ– GitHub ๆจกๆฟ | -| ๐Ÿ“‚ **่‡ชๅฎšไน‰ๆ•ฐๆฎ็›ฎๅฝ•** | ไฝฟ็”จ `DATA_DIR` ่ฆ†็›–ๅญ˜ๅ‚จไฝ็ฝฎ | +| Feature | What It Does | +| ------------------------------ | --------------------------------------------------------------------- | +| ๐ŸŒ **Deploy Anywhere** | Localhost, VPS, Docker, Cloud environments | +| ๐Ÿš‡ **Cloudflare Tunnel** ๐Ÿ†• | One-click Quick Tunnel integration from the dashboard | +| ๐Ÿ”‘ **API Key Model Filtering** | Native /v1/models response filtered via assigned Bearer context roles | +| โšก **Smart Cache Bypass** | Configurable TTL heuristics and forced refetch controls | +| ๐Ÿ”„ **Backup/Restore** | Export/import and disaster recovery flows | +| ๐Ÿง™ **Onboarding Wizard** | First-run guided setup | +| ๐Ÿ”ง **CLI Tools Dashboard** | One-click setup for popular coding tools | +| ๐ŸŽฎ **Model Playground** | Test any provider/model/endpoint from the dashboard | +| ๐Ÿ” **CLI Fingerprint Toggle** | Per-provider fingerprint matching in Settings > Security | +| ๐ŸŒ **i18n (30 languages)** | Full dashboard + docs language support with RTL coverage | +| ๐Ÿงน **Clear All Models** | One-click model list clearing in provider details | +| ๐Ÿ‘๏ธ **Sidebar Controls** ๐Ÿ†• | Hide components and integrations from Appearance Settings | +| ๐Ÿ“‹ **Issue Templates** | Standardized GitHub templates for bugs and features | +| ๐Ÿ“‚ **Custom Data Directory** | `DATA_DIR` override for storage location | -### ๅŠŸ่ƒฝๆทฑๅบฆ่งฃๆž +### Feature Deep Dive -#### ๅธฆๅฎž้™…ๆˆๆœฌๆŽงๅˆถ็š„ๆ™บ่ƒฝๅ›ž้€€ +#### Smart fallback with practical cost control ```txt Combo: "my-coding-stack" @@ -1333,73 +1442,73 @@ Combo: "my-coding-stack" 4. if/kimi-k2-thinking ``` -ๅฝ“้…้ขใ€้€Ÿ็Ž‡้™ๅˆถๆˆ–ๅฅๅบท็Šถๆ€ๅ‡บ็Žฐ้—ฎ้ข˜ๆ—ถ๏ผŒOmniRoute ไผš่‡ชๅŠจๅˆ‡ๆขๅˆฐไธ‹ไธ€ไธชๅ€™้€‰ๆจกๅž‹๏ผŒๆ— ้œ€ๆ‰‹ๅŠจๅนฒ้ข„ใ€‚ +When quota, rate, or health fails, OmniRoute automatically moves to the next candidate without manual switching. -#### ๅฏ่งไธ”ๅฏๆ“ไฝœ็š„ๅ่ฎฎ็ฎก็† +#### Protocol management that is visible and operable -- MCP + A2A ไผšๅœจ UI ๅ’Œๆ–‡ๆกฃไธญๆ˜Ž็กฎๅฑ•็คบ๏ผŒ่€Œไธๆ˜ฏ้š่—ๅŠŸ่ƒฝ -- ๅ่ฎฎ็Šถๆ€ API ไผšๆšด้œฒๅฎžๆ—ถ่ฟ่กŒๆ•ฐๆฎ๏ผˆ`/api/mcp/*`ใ€`/api/a2a/*`๏ผ‰ -- Dashboard ๅ†…ๅŒ…ๅซ่ฟ็ปดๅธธ็”จๆ“ไฝœ๏ผŒๅฆ‚ combo ๅผ€ๅ…ณใ€็†”ๆ–ญๅ™จ้‡็ฝฎใ€ไปปๅŠกๅ–ๆถˆ +- MCP + A2A are discoverable in UI and docs (not hidden) +- Protocol status APIs expose live operational data (`/api/mcp/*`, `/api/a2a/*`) +- Dashboards include actions for day-2 ops (combo toggles, breaker resets, task cancellation) -#### ็ฟป่ฏ‘ๅ™จไธŽ้ชŒ่ฏๅทฅไฝœๆต +#### Translator + validation workflow -Translator ๅŒบๅŸŸๅŒ…ๅซ๏ผš +The Translator area includes: -- **Playground**๏ผšๆฃ€ๆŸฅ่ฏทๆฑ‚่ฝฌๆขๆ•ˆๆžœ -- **Chat Tester**๏ผš้ชŒ่ฏๅฎŒๆ•ด่ฏทๆฑ‚/ๅ“ๅบ”ๅพ€่ฟ” -- **Test Bench**๏ผšไธ€ๆฌก่ฟ่กŒๅคš็ป„ๆต‹่ฏ•็”จไพ‹ -- **Live Monitor**๏ผšๅฎžๆ—ถๆŸฅ็œ‹ๆต้‡ +- **Playground**: request transformation checks +- **Chat Tester**: full request/response round-trip +- **Test Bench**: multiple cases in one run +- **Live Monitor**: real-time traffic view -ๆญคๅค–๏ผŒ่ฟ˜ๅฏไปฅ้€š่ฟ‡ `npm run test:protocols:e2e` ไฝฟ็”จ็œŸๅฎžๅฎขๆˆท็ซฏ่ฟ›่กŒๅ่ฎฎ้ชŒ่ฏใ€‚ +Plus protocol validation with real clients via `npm run test:protocols:e2e`. -> ๐Ÿ“– **[MCP Server README](../../../open-sse/mcp-server/README.md)** โ€” ๅทฅๅ…ทๅ‚่€ƒใ€IDE ้…็ฝฎๅ’Œๅฎขๆˆท็ซฏ็คบไพ‹ +> ๐Ÿ“– **[MCP Server README](open-sse/mcp-server/README.md)** โ€” Tool reference, IDE configs, and client examples > -> ๐Ÿ“– **[A2A Server README](../../../src/lib/a2a/README.md)** โ€” Skillsใ€JSON-RPC ๆ–นๆณ•ใ€ๆตๅผไผ ่พ“ไธŽไปปๅŠก็”Ÿๅ‘ฝๅ‘จๆœŸ +> ๐Ÿ“– **[A2A Server README](src/lib/a2a/README.md)** โ€” Skills, JSON-RPC methods, streaming, and task lifecycle -## ๐Ÿงช ่ฏ„ไผฐ๏ผˆEvals๏ผ‰ +## ๐Ÿงช Evaluations (Evals) -OmniRoute ๅ†…็ฝฎไบ†ไธ€ไธช่ฏ„ไผฐๆก†ๆžถ๏ผŒๅฏๅŸบไบŽ golden set ๆต‹่ฏ• LLM ๅ“ๅบ”่ดจ้‡ใ€‚ๅฏๅœจ Dashboard ็š„ **Analytics โ†’ Evals** ไธญ่ฎฟ้—ฎใ€‚ +OmniRoute includes a built-in evaluation framework to test LLM response quality against a golden set. Access it via **Analytics โ†’ Evals** in the dashboard. -### ๅ†…็ฝฎ Golden Set +### Built-in Golden Set -้ข„็ฝฎ็š„ โ€œOmniRoute Golden Setโ€ ๅŒ…ๅซไปฅไธ‹ๆต‹่ฏ•็”จไพ‹๏ผš +The pre-loaded "OmniRoute Golden Set" contains test cases for: -- ้—ฎๅ€™่ฏญใ€ๆ•ฐๅญฆใ€ๅœฐ็†ใ€ไปฃ็ ็”Ÿๆˆ -- JSON ๆ ผๅผๅˆ่ง„ๆ€งใ€็ฟป่ฏ‘ใ€Markdown ็”Ÿๆˆ -- ๅฎ‰ๅ…จๆ‹’็ญ”๏ผˆๆœ‰ๅฎณๅ†…ๅฎน๏ผ‰ใ€่ฎกๆ•ฐใ€ๅธƒๅฐ”้€ป่พ‘ +- Greetings, math, geography, code generation +- JSON format compliance, translation, markdown generation +- Safety refusal (harmful content), counting, boolean logic -### ่ฏ„ไผฐ็ญ–็•ฅ +### Evaluation Strategies -| ็ญ–็•ฅ | ๆ่ฟฐ | ็คบไพ‹ | -| ---------- | ------------------------------------ | -------------------------------- | -| `exact` | ่พ“ๅ‡บๅฟ…้กปๅฎŒๅ…จไธ€่‡ด | `"4"` | -| `contains` | ่พ“ๅ‡บๅฟ…้กปๅŒ…ๅซๆŸไธชๅญไธฒ๏ผˆไธๅŒบๅˆ†ๅคงๅฐๅ†™๏ผ‰ | `"Paris"` | -| `regex` | ่พ“ๅ‡บๅฟ…้กปๅŒน้…ๆŸไธชๆญฃๅˆ™่กจ่พพๅผ | `"1.*2.*3"` | -| `custom` | ่‡ชๅฎšไน‰ JS ๅ‡ฝๆ•ฐ่ฟ”ๅ›ž true/false | `(output) => output.length > 10` | +| Strategy | Description | Example | +| ---------- | ------------------------------------------------ | -------------------------------- | +| `exact` | Output must match exactly | `"4"` | +| `contains` | Output must contain substring (case-insensitive) | `"Paris"` | +| `regex` | Output must match regex pattern | `"1.*2.*3"` | +| `custom` | Custom JS function returns true/false | `(output) => output.length > 10` | --- -## ๐Ÿ“– ้…็ฝฎๆŒ‡ๅ— +## ๐Ÿ“– Setup Guide -### ๅ่ฎฎ้…็ฝฎ๏ผˆMCP + A2A๏ผ‰ +### Protocol Setup (MCP + A2A)
-๐Ÿงฉ MCP ้…็ฝฎ๏ผˆModel Context Protocol๏ผ‰ +๐Ÿงฉ MCP Setup (Model Context Protocol) -ไปฅ stdio ๆจกๅผๅฏๅŠจ MCP transport๏ผš +Start MCP transport in stdio mode: ```bash omniroute --mcp ``` -ๆŽจ่้ชŒ่ฏๆต็จ‹๏ผš +Recommended validation flow: -1. ้€š่ฟ‡ stdio ่ฟžๆŽฅไฝ ็š„ MCP clientใ€‚ -2. ่ฟ่กŒ `omniroute_get_health`ใ€‚ -3. ่ฟ่กŒ `omniroute_list_combos`ใ€‚ -4. ๆ‰“ๅผ€ `/dashboard/endpoint`๏ผŒ็กฎ่ฎคๅฟƒ่ทณใ€ๆดปๅŠจๅ’Œๅฎก่ฎกไฟกๆฏใ€‚ +1. Connect your MCP client over stdio. +2. Run `omniroute_get_health`. +3. Run `omniroute_list_combos`. +4. Open `/dashboard/mcp` to confirm heartbeat, activity, and audit. -้€‚ๅˆ่‡ชๅŠจๅŒ–็š„ API๏ผš +Useful APIs for automation: - `GET /api/mcp/status` - `GET /api/mcp/tools` @@ -1409,15 +1518,15 @@ omniroute --mcp
-๐Ÿค A2A ้…็ฝฎ๏ผˆAgent2Agent๏ผ‰ +๐Ÿค A2A Setup (Agent2Agent) -ๅ‘็Žฐ agent๏ผš +Discover the agent: ```bash curl http://localhost:20128/.well-known/agent.json ``` -ๅ‘้€ไปปๅŠก๏ผš +Send a task: ```bash curl -X POST http://localhost:20128/a2a \ @@ -1425,105 +1534,105 @@ curl -X POST http://localhost:20128/a2a \ -d '{"jsonrpc":"2.0","id":"setup-a2a","method":"message/send","params":{"skill":"quota-management","messages":[{"role":"user","content":"Summarize quota status."}]}}' ``` -็ฎก็†็”Ÿๅ‘ฝๅ‘จๆœŸ๏ผš +Manage lifecycle: - `GET /api/a2a/status` - `GET /api/a2a/tasks` - `GET /api/a2a/tasks/:id` - `POST /api/a2a/tasks/:id/cancel` -่ฟ็ปด UI๏ผš +Operational UI: -- `/dashboard/a2a`๏ผš็”จไบŽไปปๅŠก/็Šถๆ€/ๆต็š„ๅฏ่ง‚ๆต‹ๆ€งไปฅๅŠๅŸบ็ก€ smoke ๆ“ไฝœ +- `/dashboard/a2a` for task/state/stream observability and smoke actions
-๐Ÿงช ็ซฏๅˆฐ็ซฏๅ่ฎฎ้ชŒ่ฏ +๐Ÿงช End-to-end protocol validation -ไฝฟ็”จ็œŸๅฎžๅฎขๆˆท็ซฏ้ชŒ่ฏ่ฟ™ไธค็งๅ่ฎฎ๏ผš +Validate both protocols with real clients: ```bash npm run test:protocols:e2e ``` -่ฟ™ไผš้ชŒ่ฏ๏ผš +This verifies: -- MCP SDK ๅฎขๆˆท็ซฏ็š„ connect/list/call -- A2A ็š„ discovery/send/stream/get/cancel -- ไบคๅ‰ๆ ธๅฏน MCP ๅฎก่ฎกๅ’Œ A2A ไปปๅŠก็ฎก็† API ไธญ็š„ๆ•ฐๆฎ +- MCP SDK client connect/list/call +- A2A discovery/send/stream/get/cancel +- Cross-check data in MCP audit and A2A task management APIs
-๐Ÿ’ณ ่ฎข้˜…ๅž‹ๆไพ›ๅ•† +๐Ÿ’ณ Subscription Providers ### Claude Code (Pro/Max) ```bash Dashboard โ†’ Providers โ†’ Connect Claude Code -โ†’ OAuth ็™ปๅฝ• โ†’ ่‡ชๅŠจๅˆทๆ–ฐ token -โ†’ ่ทŸ่ธช 5 ๅฐๆ—ถ + ๆฏๅ‘จ้…้ข +โ†’ 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 ``` -**ไธ“ไธšๆ็คบ๏ผš** ๅคๆ‚ไปปๅŠก็”จ Opus๏ผŒ่ฟฝๆฑ‚้€Ÿๅบฆ็”จ Sonnetใ€‚OmniRoute ไผšๆŒ‰ๆจกๅž‹่ทŸ่ธช้…้ขใ€‚ +**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 ็™ปๅฝ•๏ผˆ็ซฏๅฃ 1455๏ผ‰ -โ†’ ๆฏ 5 ๅฐๆ—ถ + ๆฏๅ‘จ้‡็ฝฎ +โ†’ OAuth login (port 1455) +โ†’ 5-hour + weekly reset -ๆจกๅž‹๏ผš +Models: cx/gpt-5.2-codex cx/gpt-5.1-codex-max ``` -#### Codex ่ดฆๆˆท้™้ข็ฎก็†๏ผˆ5 ๅฐๆ—ถ + ๆฏๅ‘จ๏ผ‰ +#### Codex Account Limit Management (5h + Weekly) -็Žฐๅœจๆฏไธช Codex ่ดฆๆˆทๅœจ `Dashboard -> Providers` ไธญ้ƒฝๆœ‰็ญ–็•ฅๅผ€ๅ…ณ๏ผš +Each Codex account now has policy toggles in `Dashboard -> Providers`: -- `5h`๏ผˆๅผ€/ๅ…ณ๏ผ‰๏ผšๅฏ็”จ 5 ๅฐๆ—ถ็ช—ๅฃ้˜ˆๅ€ผ็ญ–็•ฅใ€‚ -- `Weekly`๏ผˆๅผ€/ๅ…ณ๏ผ‰๏ผšๅฏ็”จๆฏๅ‘จ็ช—ๅฃ้˜ˆๅ€ผ็ญ–็•ฅใ€‚ -- ้˜ˆๅ€ผ่กŒไธบ๏ผšๅฝ“ๅทฒๅฏ็”จ็ช—ๅฃ็š„ไฝฟ็”จ้‡่พพๅˆฐ >=90% ๆ—ถ๏ผŒ่ฏฅ่ดฆๆˆทไผš่ขซ่ทณ่ฟ‡ใ€‚ -- ่ฝฎๆข่กŒไธบ๏ผšOmniRoute ไผš่‡ชๅŠจ่ทฏ็”ฑๅˆฐไธ‹ไธ€ไธช็ฌฆๅˆๆกไปถ็š„ Codex ่ดฆๆˆทใ€‚ -- ้‡็ฝฎ่กŒไธบ๏ผšๅฝ“ๆไพ›ๅ•†็š„ `resetAt` ๆ—ถ้—ดๅˆฐ่พพๅŽ๏ผŒ่ฏฅ่ดฆๆˆทไผš่‡ชๅŠจ้‡ๆ–ฐๅ˜ไธบๅฏ็”จใ€‚ +- `5h` (ON/OFF): enforce the 5-hour window threshold policy. +- `Weekly` (ON/OFF): enforce the weekly window threshold policy. +- Threshold behavior: when an enabled window reaches >=90% usage, that account is skipped. +- Rotation behavior: OmniRoute routes to the next eligible Codex account automatically. +- Reset behavior: when the provider `resetAt` time passes, the account becomes eligible again automatically. -ๅœบๆ™ฏ๏ผš +Scenarios: -- `5h ON` + `Weekly ON`๏ผšไปปไธ€็ช—ๅฃ่พพๅˆฐ้˜ˆๅ€ผๆ—ถ๏ผŒ่ดฆๆˆท้ƒฝไผš่ขซ่ทณ่ฟ‡ใ€‚ -- `5h OFF` + `Weekly ON`๏ผšๅชๆœ‰ๆฏๅ‘จไฝฟ็”จ้‡ไผš้˜ปๆญข่ฏฅ่ดฆๆˆทใ€‚ -- `5h ON` + `Weekly OFF`๏ผšๅชๆœ‰ 5 ๅฐๆ—ถไฝฟ็”จ้‡ไผš้˜ปๆญข่ฏฅ่ดฆๆˆทใ€‚ -- `resetAt` ๅทฒ่ฟ‡๏ผš่ดฆๆˆทไผš่‡ชๅŠจ้‡ๆ–ฐ่ฟ›ๅ…ฅ่ฝฎๆข๏ผŒๆ— ้œ€ๆ‰‹ๅŠจ้‡ๆ–ฐๅฏ็”จใ€‚ +- `5h ON` + `Weekly ON`: account is skipped when either window reaches threshold. +- `5h OFF` + `Weekly ON`: only weekly usage can block the account. +- `5h ON` + `Weekly OFF`: only 5-hour usage can block the account. +- `resetAt` passed: account re-enters rotation automatically (no manual re-enable). -### Gemini CLI๏ผˆๆฏๆœˆๅ…่ดน 180K๏ผ๏ผ‰ +### Gemini CLI (FREE 180K/month!) ```bash Dashboard โ†’ Providers โ†’ Connect Gemini CLI โ†’ Google OAuth -โ†’ ๆฏๆœˆ 180K completions + ๆฏๅคฉ 1K +โ†’ 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 -โ†’ ้€š่ฟ‡ GitHub OAuth -โ†’ ๆฏๆœˆ้‡็ฝฎ๏ผˆๆฏๆœˆ 1 ๆ—ฅ๏ผ‰ +โ†’ OAuth via GitHub +โ†’ Monthly reset (1st of month) -ๆจกๅž‹๏ผš +Models: gh/gpt-5 gh/claude-4.5-sonnet gh/gemini-3-pro @@ -1532,97 +1641,97 @@ Dashboard โ†’ Providers โ†’ Connect GitHub
-๐Ÿ”‘ API Key ๆไพ›ๅ•† +๐Ÿ”‘ API Key Providers -### NVIDIA NIM๏ผˆๅ…่ดนๅผ€ๅ‘่€…่ฎฟ้—ฎ โ€” 70+ ไธชๆจกๅž‹๏ผ‰ +### NVIDIA NIM (FREE developer access โ€” 70+ models) -1. ๆณจๅ†Œ๏ผš[build.nvidia.com](https://build.nvidia.com) -2. ่Žทๅ–ๅ…่ดน API key๏ผˆๅŒ…ๅซ 1000 ไธช inference credits๏ผ‰ -3. Dashboard โ†’ Add Provider โ†’ NVIDIA NIM๏ผš - - API Key๏ผš`nvapi-your-key` +1. Sign up: [build.nvidia.com](https://build.nvidia.com) +2. Get free API key (1000 inference credits included) +3. Dashboard โ†’ Add Provider โ†’ NVIDIA NIM: + - API Key: `nvapi-your-key` -**ๆจกๅž‹๏ผš** `nvidia/llama-3.3-70b-instruct`ใ€`nvidia/mistral-7b-instruct`๏ผŒไปฅๅŠๅฆๅค– 50+ ไธชๆจกๅž‹ +**Models:** `nvidia/llama-3.3-70b-instruct`, `nvidia/mistral-7b-instruct`, and 50+ more -**ไธ“ไธšๆ็คบ๏ผš** ่ฟ™ๆ˜ฏ OpenAI-compatible API๏ผŒๅฏไธŽ OmniRoute ็š„ๆ ผๅผ็ฟป่ฏ‘ๆ— ็ผ้…ๅˆใ€‚ +**Pro Tip:** OpenAI-compatible API โ€” works seamlessly with OmniRoute's format translation! ### DeepSeek -1. ๆณจๅ†Œ๏ผš[platform.deepseek.com](https://platform.deepseek.com) -2. ่Žทๅ– API key +1. Sign up: [platform.deepseek.com](https://platform.deepseek.com) +2. Get API key 3. Dashboard โ†’ Add Provider โ†’ DeepSeek -**ๆจกๅž‹๏ผš** `deepseek/deepseek-chat`ใ€`deepseek/deepseek-coder` +**Models:** `deepseek/deepseek-chat`, `deepseek/deepseek-coder` -### Groq๏ผˆๆไพ›ๅ…่ดนๅฑ‚๏ผ๏ผ‰ +### Groq (Free Tier Available!) -1. ๆณจๅ†Œ๏ผš[console.groq.com](https://console.groq.com) -2. ่Žทๅ– API key๏ผˆๅŒ…ๅซๅ…่ดนๅฑ‚๏ผ‰ +1. Sign up: [console.groq.com](https://console.groq.com) +2. Get API key (free tier included) 3. Dashboard โ†’ Add Provider โ†’ Groq -**ๆจกๅž‹๏ผš** `groq/llama-3.3-70b`ใ€`groq/mixtral-8x7b` +**Models:** `groq/llama-3.3-70b`, `groq/mixtral-8x7b` -**ไธ“ไธšๆ็คบ๏ผš** ๆŽจ็†้€Ÿๅบฆๆžๅฟซ๏ผŒ้žๅธธ้€‚ๅˆๅฎžๆ—ถ็ผ–็ ใ€‚ +**Pro Tip:** Ultra-fast inference โ€” best for real-time coding! -### OpenRouter๏ผˆ100+ ไธชๆจกๅž‹๏ผ‰ +### OpenRouter (100+ Models) -1. ๆณจๅ†Œ๏ผš[openrouter.ai](https://openrouter.ai) -2. ่Žทๅ– API key +1. Sign up: [openrouter.ai](https://openrouter.ai) +2. Get API key 3. Dashboard โ†’ Add Provider โ†’ OpenRouter -**ๆจกๅž‹๏ผš** ้€š่ฟ‡ไธ€ไธช API key ๅณๅฏ่ฎฟ้—ฎๆ‰€ๆœ‰ไธปๆตๆไพ›ๅ•†็š„ 100+ ไธชๆจกๅž‹ใ€‚ +**Models:** Access 100+ models from all major providers through a single API key. -**Dashboard ่กŒไธบ๏ผš** OpenRouter ๆจกๅž‹็”ฑ **Available Models** ็ปŸไธ€็ฎก็†ใ€‚ๆ‰‹ๅŠจๆทปๅŠ ใ€ๅฏผๅ…ฅๅ’Œ่‡ชๅŠจๅŒๆญฅ้ƒฝไผšๆ›ดๆ–ฐๅŒไธ€ไปฝๅˆ—่กจใ€‚ +**Dashboard behavior:** OpenRouter models are managed from **Available Models**. Manual add, import, and auto-sync all update the same list.
-๐Ÿ’ฐ ไฝŽไปทๆไพ›ๅ•†๏ผˆๅ›ž้€€ๅค‡็”จ๏ผ‰ +๐Ÿ’ฐ Cheap Providers (Backup) -### GLM-4.7๏ผˆๆฏๆ—ฅ้‡็ฝฎ๏ผŒ$0.6/100 ไธ‡๏ผ‰ +### GLM-4.7 (Daily reset, $0.6/1M) -1. ๆณจๅ†Œ๏ผš[Zhipu AI](https://open.bigmodel.cn/) -2. ไปŽ Coding Plan ่Žทๅ– API key -3. Dashboard โ†’ Add API Key๏ผš - - Provider๏ผš`glm` - - API Key๏ผš`your-key` +1. Sign up: [Zhipu AI](https://open.bigmodel.cn/) +2. Get API key from Coding Plan +3. Dashboard โ†’ Add API Key: + - Provider: `glm` + - API Key: `your-key` -**ไฝฟ็”จ๏ผš** `glm/glm-4.7` +**Use:** `glm/glm-4.7` -**ไธ“ไธšๆ็คบ๏ผš** Coding Plan ่ƒฝไปฅ 1/7 ็š„ๆˆๆœฌๆไพ› 3 ๅ€้…้ข๏ผๆฏๅคฉ 10:00 ้‡็ฝฎใ€‚ +**Pro Tip:** Coding Plan offers 3ร— quota at 1/7 cost! Reset daily 10:00 AM. -### MiniMax M2.1๏ผˆ5 ๅฐๆ—ถ้‡็ฝฎ๏ผŒ$0.20/100 ไธ‡๏ผ‰ +### MiniMax M2.1 (5h reset, $0.20/1M) -1. ๆณจๅ†Œ๏ผš[MiniMax](https://www.minimax.io/) -2. ่Žทๅ– API key +1. Sign up: [MiniMax](https://www.minimax.io/) +2. Get API key 3. Dashboard โ†’ Add API Key -**ไฝฟ็”จ๏ผš** `minimax/MiniMax-M2.1` +**Use:** `minimax/MiniMax-M2.1` -**ไธ“ไธšๆ็คบ๏ผš** ่ฟ™ๆ˜ฏ้•ฟไธŠไธ‹ๆ–‡๏ผˆ100 ไธ‡ tokens๏ผ‰ๅœบๆ™ฏไธญๆœ€ไพฟๅฎœ็š„้€‰ๆ‹ฉ๏ผ +**Pro Tip:** Cheapest option for long context (1M tokens)! -### Kimi K2๏ผˆๅ›บๅฎš $9/ๆœˆ๏ผ‰ +### Kimi K2 ($9/month flat) -1. ่ฎข้˜…๏ผš[Moonshot AI](https://platform.moonshot.ai/) -2. ่Žทๅ– API key +1. Subscribe: [Moonshot AI](https://platform.moonshot.ai/) +2. Get API key 3. Dashboard โ†’ Add API Key -**ไฝฟ็”จ๏ผš** `kimi/kimi-latest` +**Use:** `kimi/kimi-latest` -**ไธ“ไธšๆ็คบ๏ผš** ๅ›บๅฎš $9/ๆœˆๅณๅฏ่Žทๅพ— 1000 ไธ‡ tokens๏ผŒ็›ธๅฝ“ไบŽๆฏ 100 ไธ‡ tokens ไป… $0.90๏ผ +**Pro Tip:** Fixed $9/month for 10M tokens = $0.90/1M effective cost!
-๐Ÿ†“ ๅ…่ดนๆไพ›ๅ•†๏ผˆ็ดงๆ€ฅๅค‡็”จ๏ผ‰ +๐Ÿ†“ FREE Providers (Emergency Backup) -### Qoder๏ผˆ้€š่ฟ‡ OAuth ๆไพ› 5 ไธชๅ…่ดนๆจกๅž‹๏ผ‰ +### Qoder (5 FREE models via OAuth) ```bash Dashboard โ†’ Connect Qoder -โ†’ Qoder OAuth ็™ปๅฝ• -โ†’ ๆ— ้™ไฝฟ็”จ +โ†’ Qoder OAuth login +โ†’ Unlimited usage -ๆจกๅž‹๏ผš +Models: if/kimi-k2-thinking if/qwen3-coder-plus if/glm-4.7 @@ -1630,26 +1739,26 @@ Dashboard โ†’ Connect Qoder if/deepseek-r1 ``` -### Qwen๏ผˆ้€š่ฟ‡่ฎพๅค‡็ ๆไพ› 4 ไธชๅ…่ดนๆจกๅž‹๏ผ‰ +### Qwen (4 FREE models via Device Code) ```bash Dashboard โ†’ Connect Qwen -โ†’ ่ฎพๅค‡็ ๆŽˆๆƒ -โ†’ ๆ— ้™ไฝฟ็”จ +โ†’ Device code authorization +โ†’ Unlimited usage -ๆจกๅž‹๏ผš +Models: qw/qwen3-coder-plus qw/qwen3-coder-flash ``` -### Kiro๏ผˆๅ…่ดน Claude๏ผ‰ +### Kiro (Claude FREE) ```bash Dashboard โ†’ Connect Kiro -โ†’ AWS Builder ID ๆˆ– Google/GitHub -โ†’ ๆ— ้™ไฝฟ็”จ +โ†’ AWS Builder ID or Google/GitHub +โ†’ Unlimited usage -ๆจกๅž‹๏ผš +Models: kr/claude-sonnet-4.5 kr/claude-haiku-4.5 ``` @@ -1657,51 +1766,51 @@ Dashboard โ†’ Connect Kiro
-๐ŸŽจ ๅˆ›ๅปบ Combos +๐ŸŽจ Create Combos -### ็คบไพ‹ 1๏ผšๆœ€ๅคงๅŒ–่ฎข้˜… โ†’ ๅป‰ไปทๅค‡็”จ +### Example 1: Maximize Subscription โ†’ Cheap Backup ``` Dashboard โ†’ Combos โ†’ Create New Name: premium-coding -ๆจกๅž‹๏ผš - 1. cc/claude-opus-4-6๏ผˆ่ฎข้˜…ไธปๅŠ›๏ผ‰ - 2. glm/glm-4.7๏ผˆๅป‰ไปทๅค‡็”จ๏ผŒ$0.6/1M๏ผ‰ - 3. minimax/MiniMax-M2.1๏ผˆๆœ€ไพฟๅฎœ็š„ๅ›ž้€€๏ผŒ$0.20/1M๏ผ‰ +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) -ๅœจ CLI ไธญไฝฟ็”จ๏ผšpremium-coding +Use in CLI: premium-coding ``` -### ็คบไพ‹ 2๏ผšไป…ๅ…่ดน๏ผˆ้›ถๆˆๆœฌ๏ผ‰ +### Example 2: Free-Only (Zero Cost) ``` Name: free-combo -ๆจกๅž‹๏ผš - 1. gc/gemini-3-flash-preview๏ผˆๆฏๆœˆๅ…่ดน 180K๏ผ‰ - 2. if/kimi-k2-thinking๏ผˆๆ— ้™๏ผ‰ - 3. qw/qwen3-coder-plus๏ผˆๆ— ้™๏ผ‰ +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 ้›†ๆˆ +๐Ÿ”ง CLI Integration ### Cursor IDE ``` Settings โ†’ Models โ†’ Advanced: OpenAI API Base URL: http://localhost:20128/v1 - OpenAI API Key: [ไปŽ OmniRoute Dashboard ่Žทๅ–] + OpenAI API Key: [from OmniRoute dashboard] Model: cc/claude-opus-4-6 ``` ### Claude Code -ไฝฟ็”จ Dashboard ไธญ็š„ **CLI Tools** ้กต้ข่ฟ›่กŒไธ€้”ฎ้…็ฝฎ๏ผŒๆˆ–ๆ‰‹ๅŠจ็ผ–่พ‘ `~/.claude/settings.json`ใ€‚ +Use the **CLI Tools** page in the dashboard for one-click configuration, or edit `~/.claude/settings.json` manually. ### Codex CLI @@ -1714,13 +1823,13 @@ codex "your prompt" ### OpenClaw -**ๆ–นๅผ 1๏ผš้€š่ฟ‡ Dashboard๏ผˆๆŽจ่๏ผ‰** +**Option 1 โ€” Dashboard (recommended):** ``` Dashboard โ†’ CLI Tools โ†’ OpenClaw โ†’ Select Model โ†’ Apply ``` -**ๆ–นๅผ 2๏ผšๆ‰‹ๅŠจ้…็ฝฎ** ็ผ–่พ‘ `~/.openclaw/openclaw.json`๏ผš +**Option 2 โ€” Manual:** Edit `~/.openclaw/openclaw.json`: ```json { @@ -1736,7 +1845,7 @@ Dashboard โ†’ CLI Tools โ†’ OpenClaw โ†’ Select Model โ†’ Apply } ``` -> **ๆณจๆ„๏ผš** OpenClaw ไป…้€‚็”จไบŽๆœฌๅœฐ OmniRouteใ€‚่ฏทไฝฟ็”จ `127.0.0.1` ่€Œไธๆ˜ฏ `localhost`๏ผŒไปฅ้ฟๅ… IPv6 ่งฃๆž้—ฎ้ข˜ใ€‚ +> **Note:** OpenClaw only works with local OmniRoute. Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues. ### Cline / Continue / RooCode @@ -1744,21 +1853,21 @@ Dashboard โ†’ CLI Tools โ†’ OpenClaw โ†’ Select Model โ†’ Apply Settings โ†’ API Configuration: Provider: OpenAI Compatible Base URL: http://localhost:20128/v1 - API Key: [ไปŽ OmniRoute Dashboard ่Žทๅ–] + API Key: [from OmniRoute dashboard] Model: if/kimi-k2-thinking ``` ### OpenCode -**ๆญฅ้ชค 1๏ผš** ๅฐ† OmniRoute ๆทปๅŠ ไธบ่‡ชๅฎšไน‰ provider๏ผš +**Step 1:** Add OmniRoute as a custom provider: ```bash opencode /connect -# ้€‰ๆ‹ฉ โ€œOtherโ€ โ†’ ่พ“ๅ…ฅ ID๏ผšโ€œomnirouteโ€ โ†’ ่พ“ๅ…ฅไฝ ็š„ OmniRoute API key +# Select "Other" โ†’ Enter ID: "omniroute" โ†’ Enter your OmniRoute API key ``` -**ๆญฅ้ชค 2๏ผš** ๅœจ้กน็›ฎๆ น็›ฎๅฝ•ไธญๅˆ›ๅปบๆˆ–็ผ–่พ‘ `opencode.json`๏ผš +**Step 2:** Create/edit `opencode.json` in your project root: ```json { @@ -1780,14 +1889,14 @@ opencode } ``` -**ๆญฅ้ชค 3๏ผš** ๅœจ OpenCode ไธญ้€‰ๆ‹ฉๆจกๅž‹๏ผš +**Step 3:** Select the model in OpenCode: ```bash /models -# ไปŽๅˆ—่กจไธญ้€‰ๆ‹ฉไปปๆ„ OmniRoute ๆจกๅž‹ +# Select any OmniRoute model from the list ``` -> **ๆ็คบ๏ผš** ๅฏๅฐ† OmniRoute `/v1/models` ็ซฏ็‚นไธญๅฏ่ง็š„ไปปๆ„ๆจกๅž‹ๆทปๅŠ ๅˆฐ `models` ๆฎตใ€‚่ฏทไฝฟ็”จ OmniRoute Dashboard ไธญ็š„ `provider/model-id` ๆ ผๅผใ€‚ +> **Tip:** Add any model available in your OmniRoute `/v1/models` endpoint to the `models` section. Use the format `provider/model-id` from your OmniRoute dashboard.
@@ -1796,240 +1905,241 @@ opencode ## ๆ•…้šœๆŽ’้™ค
-็‚นๅ‡ปๅฑ•ๅผ€ๆ•…้šœๆŽ’้™คๆŒ‡ๅ— +Click to expand troubleshooting guide -**โ€œLanguage model did not provide messagesโ€** +**"Language model did not provide messages"** -- ๆไพ›ๅ•†้…้ขๅทฒ่€—ๅฐฝ โ†’ ๆฃ€ๆŸฅ Dashboard ไธญ็š„้…้ข่ทŸ่ธชๅ™จ -- ่งฃๅ†ณๆ–นๆกˆ๏ผšไฝฟ็”จ combo ๅ›ž้€€ๆˆ–ๅˆ‡ๆขๅˆฐๆ›ดไพฟๅฎœ็š„ๅฑ‚็บง +- Provider quota exhausted โ†’ Check dashboard quota tracker +- Solution: Use combo fallback or switch to cheaper tier -**้€Ÿ็Ž‡้™ๅˆถ** +**Rate limiting** -- ่ฎข้˜…้…้ข็”จๅฐฝ โ†’ ๅ›ž้€€ๅˆฐ GLM/MiniMax -- ๆทปๅŠ  combo๏ผš`cc/claude-opus-4-6 โ†’ glm/glm-4.7 โ†’ if/kimi-k2-thinking` +- Subscription quota out โ†’ Fallback to GLM/MiniMax +- Add combo: `cc/claude-opus-4-6 โ†’ glm/glm-4.7 โ†’ if/kimi-k2-thinking` -**OAuth token ๅทฒ่ฟ‡ๆœŸ** +**OAuth token expired** -- OmniRoute ไผš่‡ชๅŠจๅˆทๆ–ฐ -- ๅฆ‚ๆžœ้—ฎ้ข˜ๆŒ็ปญ๏ผšDashboard โ†’ Provider โ†’ Reconnect +- Auto-refreshed by OmniRoute +- If issues persist: Dashboard โ†’ Provider โ†’ Reconnect -**ๆˆๆœฌ่ฟ‡้ซ˜** +**High costs** -- ๆฃ€ๆŸฅ Dashboard โ†’ Costs ไธญ็š„็”จ้‡็ปŸ่ฎก -- ๅฐ†ไธปๆจกๅž‹ๅˆ‡ๆขๅˆฐ GLM/MiniMax -- ๅฏน้žๅ…ณ้”ฎไปปๅŠกไฝฟ็”จๅ…่ดนๅฑ‚๏ผˆGemini CLIใ€Qoder๏ผ‰ +- Check usage stats in Dashboard โ†’ Costs +- Switch primary model to GLM/MiniMax +- Use free tier (Gemini CLI, Qoder) for non-critical tasks -**Dashboard/API ็ซฏๅฃไธๆญฃ็กฎ** +**Dashboard/API ports are wrong** -- `PORT` ๆ˜ฏ่ง„่ŒƒๅŸบ็ก€็ซฏๅฃ๏ผˆ้ป˜่ฎคไนŸไฝœไธบ API ็ซฏๅฃ๏ผ‰ -- `API_PORT` ไป…่ฆ†็›– OpenAI-compatible API ็›‘ๅฌๅ™จ -- `DASHBOARD_PORT` ไป…่ฆ†็›– dashboard/Next.js ็›‘ๅฌๅ™จ -- ๅฐ† `NEXT_PUBLIC_BASE_URL` ่ฎพ็ฝฎไธบไฝ ็š„ Dashboard/ๅ…ฌๅ…ฑ URL๏ผˆ็”จไบŽ OAuth ๅ›ž่ฐƒ๏ผ‰ +- `PORT` is the canonical base port (and API port by default) +- `API_PORT` overrides only OpenAI-compatible API listener +- `DASHBOARD_PORT` overrides only dashboard/Next.js listener +- Set `NEXT_PUBLIC_BASE_URL` to your dashboard/public URL (for OAuth callbacks) -**Cloud sync ้”™่ฏฏ** +**Cloud sync errors** -- ็กฎ่ฎค `BASE_URL` ๆŒ‡ๅ‘ๆญฃๅœจ่ฟ่กŒ็š„ๅฎžไพ‹ -- ็กฎ่ฎค `CLOUD_URL` ๆŒ‡ๅ‘ไฝ ๆœŸๆœ›็š„ cloud endpoint -- ไฟๆŒ `NEXT_PUBLIC_*` ็š„ๅ€ผไธŽๆœๅŠก็ซฏ้…็ฝฎไธ€่‡ด +- Verify `BASE_URL` points to your running instance +- Verify `CLOUD_URL` points to your expected cloud endpoint +- Keep `NEXT_PUBLIC_*` values aligned with server-side values -**้ฆ–ๆฌก็™ปๅฝ•ๆ— ๆณ•ไฝฟ็”จ** +**First login not working** -- ๆฃ€ๆŸฅ `.env` ไธญ็š„ `INITIAL_PASSWORD` -- ๅฆ‚ๆžœๆœช่ฎพ็ฝฎ๏ผŒๅŽๅค‡ๅฏ†็ ไธบ `123456` +- Check `INITIAL_PASSWORD` in `.env` +- If unset, fallback password is `123456` -**ๆฒกๆœ‰่ฏทๆฑ‚ๆ—ฅๅฟ—** +**No request logs** -- ่ฏทๆฑ‚ artifact ไผšไปฅๆฏ่ฏทๆฑ‚ไธ€ไธช JSON ๆ–‡ไปถ็š„ๅฝขๅผๅ†™ๅ…ฅ `DATA_DIR/call_logs/` -- ๅฆ‚ๆžœไฝ ้œ€่ฆๆŒ‰้˜ถๆฎตๆŸฅ็œ‹่ฏฆ็ป† payload๏ผŒ่ฏทๅœจ Dashboard โ†’ Logs โ†’ Request Logs ไธญๅฏ็”จ pipeline capture -- ๅฆ‚ๆžœ่ฟ˜้œ€่ฆๅบ”็”จๆŽงๅˆถๅฐๆ—ฅๅฟ—๏ผŒ่ฏท่ฎพ็ฝฎ `APP_LOG_TO_FILE=true`๏ผŒๆ—ฅๅฟ—ไผšๅ†™ๅ…ฅ `logs/application/app.log` +- Request artifacts are written to `DATA_DIR/call_logs/` as one JSON file per request +- Enable pipeline capture from Dashboard โ†’ Logs โ†’ Request Logs if you need detailed per-stage payloads +- Set `APP_LOG_TO_FILE=true` if you also want application console logs in `logs/application/app.log` +- Adjust `APP_LOG_MAX_FILE_SIZE`, `APP_LOG_RETENTION_DAYS`, `APP_LOG_MAX_FILES`, and `CALL_LOG_MAX_ENTRIES` as needed -**OpenAI-compatible ๆไพ›ๅ•†็š„่ฟžๆŽฅๆต‹่ฏ•ๆ˜พ็คบ โ€œInvalidโ€** +**Connection test shows "Invalid" for OpenAI-compatible providers** -- ่ฎธๅคšๆไพ›ๅ•†ๅนถไธๆšด้œฒ `/models` ็ซฏ็‚น -- OmniRoute v1.0.6+ ๅทฒๅŒ…ๅซๅŸบไบŽ chat completions ็š„ๅŽๅค‡ๆ ก้ชŒ -- ็กฎไฟ base URL ๅŒ…ๅซ `/v1` ๅŽ็ผ€ +- Many providers don't expose a `/models` endpoint +- OmniRoute v1.0.6+ includes fallback validation via chat completions +- Ensure base URL includes `/v1` suffix -### ๐Ÿ” ่ฟœ็จ‹ๆœๅŠกๅ™จไธŠ็š„ OAuth +### ๐Ÿ” OAuth on a Remote Server -> **โš ๏ธ ้€‚็”จไบŽๅœจ VPSใ€Docker ๆˆ–ไปปๆ„่ฟœ็จ‹ๆœๅŠกๅ™จไธŠ่ฟ่กŒ OmniRoute ็š„็”จๆˆท** +> **โš ๏ธ Important for users running OmniRoute on a VPS, Docker, or any remote server** -#### ไธบไป€ไนˆ Antigravity / Gemini CLI ็š„ OAuth ไผšๅœจ่ฟœ็จ‹ๆœๅŠกๅ™จไธŠๅคฑ่ดฅ๏ผŸ +#### Why does Antigravity / Gemini CLI OAuth fail on remote servers? -**Antigravity** ๅ’Œ **Gemini CLI** ๆไพ›ๅ•†ไฝฟ็”จ **Google OAuth 2.0**ใ€‚Google ่ฆๆฑ‚ OAuth ๆต็จ‹ไธญ็š„ `redirect_uri` ๅฟ…้กปไธŽๅบ”็”จๅœจ Google Cloud Console ไธญ้ข„ๅ…ˆๆณจๅ†Œ็š„ๆŸไธช URI **ๅฎŒๅ…จไธ€่‡ด**ใ€‚ +The **Antigravity** and **Gemini CLI** providers use **Google OAuth 2.0**. Google requires the `redirect_uri` in the OAuth flow to exactly match one of the pre-registered URIs in the app's Google Cloud Console. -OmniRoute ๅ†…็ฝฎ็š„ OAuth ๅ‡ญ่ฏ**ไป…ไธบ `localhost` ๆณจๅ†Œ**ใ€‚ๅฝ“ไฝ ้€š่ฟ‡่ฟœ็จ‹ๆœๅŠกๅ™จ่ฎฟ้—ฎ OmniRoute๏ผˆไพ‹ๅฆ‚ `https://omniroute.myserver.com`๏ผ‰ๆ—ถ๏ผŒGoogle ไผšๆ‹’็ป่ฎค่ฏ๏ผŒๅนถ่ฟ”ๅ›ž๏ผš +The OAuth credentials bundled in OmniRoute are registered **for `localhost` only**. When you access OmniRoute on a remote server (e.g. `https://omniroute.myserver.com`), Google rejects the authentication with: ``` Error 400: redirect_uri_mismatch ``` -#### ่งฃๅ†ณๆ–นๆกˆ๏ผš้…็ฝฎไฝ ่‡ชๅทฑ็š„ OAuth ๅ‡ญ่ฏ +#### Solution: Configure your own OAuth credentials -ไฝ ้œ€่ฆๅœจ Google Cloud Console ไธญๅˆ›ๅปบไธ€ไธชๅธฆๆœ‰ไฝ ๆœๅŠกๅ™จ URI ็š„ **OAuth 2.0 Client ID**ใ€‚ +You need to create an **OAuth 2.0 Client ID** in Google Cloud Console with your server's URI. -#### ๆ“ไฝœๆญฅ้ชค +#### Step-by-step -**1. ๆ‰“ๅผ€ Google Cloud Console** +**1. Open Google Cloud Console** -่ฎฟ้—ฎ๏ผš[https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) +Go to: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) -**2. ๅˆ›ๅปบๆ–ฐ็š„ OAuth 2.0 Client ID** +**2. Create a new OAuth 2.0 Client ID** -- ็‚นๅ‡ป **"+ Create Credentials"** โ†’ **"OAuth client ID"** -- ๅบ”็”จ็ฑปๅž‹๏ผš**"Web application"** -- ๅ็งฐ๏ผšๅฏ่‡ชๅฎšไน‰๏ผˆไพ‹ๅฆ‚ `OmniRoute Remote`๏ผ‰ +- Click **"+ Create Credentials"** โ†’ **"OAuth client ID"** +- Application type: **"Web application"** +- Name: anything you like (e.g. `OmniRoute Remote`) -**3. ๆทปๅŠ  Authorized Redirect URIs** +**3. Add Authorized Redirect URIs** -ๅœจ **"Authorized redirect URIs"** ๅญ—ๆฎตไธญๆทปๅŠ ๏ผš +In the **"Authorized redirect URIs"** field, add: ``` https://your-server.com/callback ``` -> ๅฐ† `your-server.com` ๆ›ฟๆขไธบไฝ ็š„ๆœๅŠกๅ™จๅŸŸๅๆˆ– IP๏ผˆๅฆ‚ๆœ‰้œ€่ฆ่ฏทๅŒ…ๅซ็ซฏๅฃ๏ผŒไพ‹ๅฆ‚ `http://45.33.32.156:20128/callback`๏ผ‰ใ€‚ +> Replace `your-server.com` with your server's domain or IP (include the port if needed, e.g. `http://45.33.32.156:20128/callback`). -**4. ไฟๅญ˜ๅนถๅคๅˆถๅ‡ญ่ฏ** +**4. Save and copy the credentials** -ๅˆ›ๅปบๅฎŒๆˆๅŽ๏ผŒGoogle ไผšๆ˜พ็คบ **Client ID** ๅ’Œ **Client Secret**ใ€‚ +After creating, Google will show the **Client ID** and **Client Secret**. -**5. ่ฎพ็ฝฎ็Žฏๅขƒๅ˜้‡** +**5. Set environment variables** -ๅœจ `.env`๏ผˆๆˆ– Docker ็Žฏๅขƒๅ˜้‡๏ผ‰ไธญๆทปๅŠ ๏ผš +In your `.env` (or Docker environment variables): ```bash -# ็”จไบŽ Antigravity๏ผš +# For Antigravity: ANTIGRAVITY_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com ANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-your-secret -# ็”จไบŽ Gemini CLI๏ผš +# For Gemini CLI: GEMINI_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-your-secret ``` -**6. ้‡ๅฏ OmniRoute** +**6. Restart OmniRoute** ```bash -# npm๏ผš +# npm: npm run dev -# Docker๏ผš +# Docker: docker restart omniroute ``` -**7. ๅ†ๆฌกๅฐ่ฏ•่ฟžๆŽฅ** +**7. Try connecting again** -Dashboard โ†’ Providers โ†’ Antigravity๏ผˆๆˆ– Gemini CLI๏ผ‰โ†’ OAuth +Dashboard โ†’ Providers โ†’ Antigravity (or Gemini CLI) โ†’ OAuth -ๆญคๆ—ถ Google ๅฐฑไผšๆญฃ็กฎ้‡ๅฎšๅ‘ๅˆฐ `https://your-server.com/callback`ใ€‚ +Google will now redirect correctly to `https://your-server.com/callback`. --- -#### ไธดๆ—ถ็ป•่ฟ‡ๆ–นๆกˆ๏ผˆไธ้…็ฝฎ่‡ชๆœ‰ๅ‡ญ่ฏ๏ผ‰ +#### Temporary workaround (without custom credentials) -ๅฆ‚ๆžœไฝ ๆš‚ๆ—ถไธๆƒณ้…็ฝฎ่‡ชๅทฑ็š„ๅ‡ญ่ฏ๏ผŒไป็„ถๅฏไปฅไฝฟ็”จ**ๆ‰‹ๅŠจ URL ๆต็จ‹**๏ผš +If you don't want to set up your own credentials right now, you can still use the **manual URL flow**: -1. OmniRoute ๆ‰“ๅผ€ Google ๆŽˆๆƒ URL -2. ๆŽˆๆƒๅŽ๏ผŒGoogle ไผšๅฐ่ฏ•้‡ๅฎšๅ‘ๅˆฐ `localhost`๏ผˆๅœจ่ฟœ็จ‹ๆœๅŠกๅ™จไธŠ่ฟ™ไผšๅคฑ่ดฅ๏ผ‰ -3. ๅณไฝฟ้กต้ขๆ‰“ไธๅผ€๏ผŒไนŸ่ฏทไปŽๆต่งˆๅ™จๅœฐๅ€ๆ **ๅคๅˆถๅฎŒๆ•ด URL** -4. ๅฐ†่ฏฅ URL ็ฒ˜่ดดๅˆฐ OmniRoute ่ฟžๆŽฅๅผน็ช—ไธญ็š„่พ“ๅ…ฅๆก† -5. ็‚นๅ‡ป **"Connect"** +1. OmniRoute opens the Google authorization URL +2. After authorizing, Google tries to redirect to `localhost` (which fails on the remote server) +3. **Copy the full URL** from your browser's address bar (even if the page doesn't load) +4. Paste that URL into the field shown in the OmniRoute connection modal +5. Click **"Connect"** -> ไน‹ๆ‰€ไปฅๅฏ่กŒ๏ผŒๆ˜ฏๅ› ไธบ URL ไธญ็š„ๆŽˆๆƒ็ ๆ— ่ฎบ้‡ๅฎšๅ‘้กต้ขๆ˜ฏๅฆๆˆๅŠŸๅŠ ่ฝฝ๏ผŒ้ƒฝๆ˜ฏๆœ‰ๆ•ˆ็š„ใ€‚ +> This works because the authorization code in the URL is valid regardless of whether the redirect page loaded. ---
-๐Ÿ‡ง๐Ÿ‡ท ่‘ก่„็‰™่ฏญ็‰ˆๆœฌ +๐Ÿ‡ง๐Ÿ‡ท Versรฃo em Portuguรชs -#### ไธบไป€ไนˆ Antigravity / Gemini CLI ็š„ OAuth ไผšๅœจ่ฟœ็จ‹ๆœๅŠกๅ™จไธŠๅคฑ่ดฅ๏ผŸ +#### Por que o OAuth do Antigravity / Gemini CLI falha em servidores remotos? -**Antigravity** ๅ’Œ **Gemini CLI** ๆไพ›ๅ•†ไฝฟ็”จ **Google OAuth 2.0**ใ€‚Google ่ฆๆฑ‚ OAuth ๆต็จ‹ไธญไฝฟ็”จ็š„ `redirect_uri` ๅฟ…้กปไธŽๅบ”็”จๅœจ Google Cloud Console ไธญ้ข„ๅ…ˆๆณจๅ†Œ็š„ URI **ๅฎŒๅ…จไธ€่‡ด**ใ€‚ +Os provedores **Antigravity** e **Gemini CLI** usam **Google OAuth 2.0** para autenticaรงรฃo. O Google exige que a `redirect_uri` usada no fluxo OAuth seja **exatamente** uma das URIs prรฉ-cadastradas no Google Cloud Console do aplicativo. -OmniRoute ๅ†…็ฝฎ็š„ OAuth ๅ‡ญ่ฏ**ไป…ไธบ `localhost` ๆณจๅ†Œ**ใ€‚ๅฝ“ไฝ ๅœจ่ฟœ็จ‹ๆœๅŠกๅ™จไธŠ่ฎฟ้—ฎ OmniRoute๏ผˆไพ‹ๅฆ‚ `https://omniroute.meuservidor.com`๏ผ‰ๆ—ถ๏ผŒGoogle ไผšๆ‹’็ป่ฎค่ฏ๏ผŒๅนถ่ฟ”ๅ›ž๏ผš +As credenciais OAuth embutidas no OmniRoute estรฃo cadastradas **apenas para `localhost`**. Quando vocรช acessa o OmniRoute em um servidor remoto (ex: `https://omniroute.meuservidor.com`), o Google rejeita a autenticaรงรฃo com: ``` Error 400: redirect_uri_mismatch ``` -#### ่งฃๅ†ณๆ–นๆกˆ๏ผš้…็ฝฎไฝ ่‡ชๅทฑ็š„ OAuth ๅ‡ญ่ฏ +#### Soluรงรฃo: Configure suas prรณprias credenciais OAuth -ไฝ ้œ€่ฆๅœจ Google Cloud Console ไธญๅˆ›ๅปบไธ€ไธชๅธฆๆœ‰ไฝ ๆœๅŠกๅ™จ URI ็š„ **OAuth 2.0 Client ID**ใ€‚ +Vocรช precisa criar um **OAuth 2.0 Client ID** no Google Cloud Console com a URI do seu servidor. -#### ๆ“ไฝœๆญฅ้ชค +#### Passo a passo -**1. ๆ‰“ๅผ€ Google Cloud Console** +**1. Acesse o Google Cloud Console** -่ฎฟ้—ฎ๏ผš[https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) +Abra: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) -**2. ๅˆ›ๅปบๆ–ฐ็š„ OAuth 2.0 Client ID** +**2. Crie um novo OAuth 2.0 Client ID** -- ็‚นๅ‡ป **"+ Create Credentials"** โ†’ **"OAuth client ID"** -- ๅบ”็”จ็ฑปๅž‹๏ผš**"Web application"** -- ๅ็งฐ๏ผšๅฏ่‡ชๅฎšไน‰๏ผˆไพ‹ๅฆ‚ `OmniRoute Remote`๏ผ‰ +- Clique em **"+ Create Credentials"** โ†’ **"OAuth client ID"** +- Tipo de aplicativo: **"Web application"** +- Nome: escolha qualquer nome (ex: `OmniRoute Remote`) -**3. ๆทปๅŠ  Authorized Redirect URIs** +**3. Adicione as Authorized Redirect URIs** -ๅœจ **"Authorized redirect URIs"** ๅญ—ๆฎตไธญๆทปๅŠ ๏ผš +No campo **"Authorized redirect URIs"**, adicione: ``` https://seu-servidor.com/callback ``` -> ๅฐ† `seu-servidor.com` ๆ›ฟๆขไธบไฝ ็š„ๆœๅŠกๅ™จๅŸŸๅๆˆ– IP๏ผˆๅฆ‚ๆœ‰้œ€่ฆ่ฏทๅŒ…ๅซ็ซฏๅฃ๏ผŒไพ‹ๅฆ‚ `http://45.33.32.156:20128/callback`๏ผ‰ใ€‚ +> Substitua `seu-servidor.com` pelo domรญnio ou IP do seu servidor (inclua a porta se necessรกrio, ex: `http://45.33.32.156:20128/callback`). -**4. ไฟๅญ˜ๅนถๅคๅˆถๅ‡ญ่ฏ** +**4. Salve e copie as credenciais** -ๅˆ›ๅปบๅฎŒๆˆๅŽ๏ผŒGoogle ไผšๆ˜พ็คบ **Client ID** ๅ’Œ **Client Secret**ใ€‚ +Apรณs criar, o Google mostrarรก o **Client ID** e o **Client Secret**. -**5. ้…็ฝฎ็Žฏๅขƒๅ˜้‡** +**5. Configure as variรกveis de ambiente** -ๅœจ `.env`๏ผˆๆˆ– Docker ็Žฏๅขƒๅ˜้‡๏ผ‰ไธญๆทปๅŠ ๏ผš +No seu `.env` (ou nas variรกveis de ambiente do Docker): ```bash -# ็”จไบŽ Antigravity๏ผš +# Para Antigravity: ANTIGRAVITY_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com ANTIGRAVITY_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret -# ็”จไบŽ Gemini CLI๏ผš +# Para Gemini CLI: GEMINI_OAUTH_CLIENT_ID=seu-client-id.apps.googleusercontent.com GEMINI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret GEMINI_CLI_OAUTH_CLIENT_SECRET=GOCSPX-seu-secret ``` -**6. ้‡ๅฏ OmniRoute** +**6. Reinicie o OmniRoute** ```bash -# npm๏ผš +# Se usando npm: npm run dev -# Docker๏ผš +# Se usando Docker: docker restart omniroute ``` -**7. ๅ†ๆฌกๅฐ่ฏ•่ฟžๆŽฅ** +**7. Tente conectar novamente** -Dashboard โ†’ Providers โ†’ Antigravity๏ผˆๆˆ– Gemini CLI๏ผ‰โ†’ OAuth +Dashboard โ†’ Providers โ†’ Antigravity (ou Gemini CLI) โ†’ OAuth -ๆญคๆ—ถ Google ๅฐฑไผšๆญฃ็กฎ้‡ๅฎšๅ‘ๅˆฐ `https://seu-servidor.com/callback`ใ€‚ +Agora o Google redirecionarรก corretamente para `https://seu-servidor.com/callback` e a autenticaรงรฃo funcionarรก. --- -#### ไธดๆ—ถ็ป•่ฟ‡ๆ–นๆกˆ๏ผˆไธ้…็ฝฎ่‡ชๆœ‰ๅ‡ญ่ฏ๏ผ‰ +#### Workaround temporรกrio (sem configurar credenciais prรณprias) -ๅฆ‚ๆžœไฝ ๆš‚ๆ—ถไธๆƒณ้…็ฝฎ่‡ชๅทฑ็š„ๅ‡ญ่ฏ๏ผŒไป็„ถๅฏไปฅไฝฟ็”จ**ๆ‰‹ๅŠจ URL ๆต็จ‹**๏ผš +Se nรฃo quiser criar credenciais prรณprias agora, ainda รฉ possรญvel usar o fluxo **manual de URL**: -1. OmniRoute ไผšๆ‰“ๅผ€ Google ๆŽˆๆƒ URL -2. ๅœจไฝ ๆŽˆๆƒไน‹ๅŽ๏ผŒGoogle ไผšๅฐ่ฏ•้‡ๅฎšๅ‘ๅˆฐ `localhost`๏ผˆ่ฟ™ๅœจ่ฟœ็จ‹ๆœๅŠกๅ™จไธŠไผšๅคฑ่ดฅ๏ผ‰ -3. ๅณไฝฟ้กต้ขๆœชๅŠ ่ฝฝ๏ผŒไนŸ่ฏทไปŽๆต่งˆๅ™จๅœฐๅ€ๆ **ๅคๅˆถๅฎŒๆ•ด URL** -4. ๅฐ†่ฏฅ URL ็ฒ˜่ดดๅˆฐ OmniRoute ่ฟžๆŽฅๅผน็ช—ไธญ็š„่พ“ๅ…ฅๆก† -5. ็‚นๅ‡ป **"Connect"** +1. O OmniRoute abrirรก a URL de autorizaรงรฃo do Google +2. Apรณs vocรช autorizar, o Google tentarรก redirecionar para `localhost` (que falha no servidor remoto) +3. **Copie a URL completa** da barra de endereรงo do seu browser (mesmo que a pรกgina nรฃo carregue) +4. Cole essa URL no campo que aparece no modal de conexรฃo do OmniRoute +5. Clique em **"Connect"** -> ไน‹ๆ‰€ไปฅๅฏ่กŒ๏ผŒๆ˜ฏๅ› ไธบ URL ไธญ็š„ๆŽˆๆƒ็ ๆ— ่ฎบ้‡ๅฎšๅ‘้กต้ขๆ˜ฏๅฆๆˆๅŠŸๅŠ ่ฝฝ๏ผŒ้ƒฝๆ˜ฏๆœ‰ๆ•ˆ็š„ใ€‚ +> Este workaround funciona porque o cรณdigo de autorizaรงรฃo na URL รฉ vรกlido independente do redirect ter carregado ou nรฃo.
@@ -2037,25 +2147,25 @@ Dashboard โ†’ Providers โ†’ Antigravity๏ผˆๆˆ– Gemini CLI๏ผ‰โ†’ OAuth
-## ๐Ÿ› ๏ธ ๆŠ€ๆœฏๆ ˆ +## ๐Ÿ› ๏ธ Tech Stack
-็‚นๅ‡ปๅฑ•ๅผ€ๆŠ€ๆœฏๆ ˆ่ฏฆๆƒ… +Click to expand tech stack details -- **Runtime**: Node.js 18โ€“22 LTS๏ผˆโš ๏ธ **ไธๆ”ฏๆŒ** Node.js 24+๏ผŒๅ› ไธบ `better-sqlite3` ๅŽŸ็”ŸไบŒ่ฟ›ๅˆถไธๅ…ผๅฎน๏ผ‰ -- **Language**: TypeScript 5.9๏ผŒ`src/` ไธŽ `open-sse/` ๅ…จ้ข้‡‡็”จ **100% TypeScript**๏ผˆ่‡ช v2.0 ่ตทๆ ธๅฟƒๆจกๅ—ไธญๆ—  `any`๏ผ‰ +- **Runtime**: Node.js 18โ€“22 LTS (โš ๏ธ Node.js 24+ is **not supported** โ€” `better-sqlite3` native binaries are incompatible) +- **Language**: TypeScript 5.9 โ€” **100% TypeScript** across `src/` and `open-sse/` (zero `any` in core modules since v2.0) - **Framework**: Next.js 16 + React 19 + Tailwind CSS 4 -- **Database**: LowDB๏ผˆJSON๏ผ‰+ SQLite๏ผˆdomain state + proxy logs + MCP audit + routing decisions๏ผ‰ -- **Schemas**: Zod๏ผˆMCP tool I/O validationใ€API contracts๏ผ‰ -- **Protocols**: MCP๏ผˆstdio/HTTP๏ผ‰+ A2A v0.3๏ผˆJSON-RPC 2.0 + SSE๏ผ‰ -- **Streaming**: Server-Sent Events๏ผˆSSE๏ผ‰ -- **Auth**: OAuth 2.0๏ผˆPKCE๏ผ‰+ JWT + API Keys + MCP Scoped Authorization -- **Testing**: Node.js test runner + Vitest๏ผˆ900+ ้กนๆต‹่ฏ•๏ผŒๆถต็›– unitใ€integrationใ€E2E๏ผ‰ -- **CI/CD**: GitHub Actions๏ผˆrelease ๆ—ถ่‡ชๅŠจ npm publish + Docker Hub๏ผ‰ +- **Database**: LowDB (JSON) + SQLite (domain state + proxy logs + MCP audit + routing decisions) +- **Schemas**: Zod (MCP tool I/O validation, API contracts) +- **Protocols**: MCP (stdio/HTTP) + A2A v0.3 (JSON-RPC 2.0 + SSE) +- **Streaming**: Server-Sent Events (SSE) +- **Auth**: OAuth 2.0 (PKCE) + JWT + API Keys + MCP Scoped Authorization +- **Testing**: Node.js test runner + Vitest (900+ tests including unit, integration, E2E) +- **CI/CD**: GitHub Actions (auto npm publish + Docker Hub on release) - **Website**: [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) -- **Resilience**: circuit breakerใ€exponential backoffใ€anti-thundering herdใ€TLS spoofingใ€auto-combo self-healing +- **Resilience**: Circuit breaker, exponential backoff, anti-thundering herd, TLS spoofing, auto-combo self-healing
@@ -2063,94 +2173,94 @@ Dashboard โ†’ Providers โ†’ Antigravity๏ผˆๆˆ– Gemini CLI๏ผ‰โ†’ OAuth ## ๆ–‡ๆกฃ -| ๆ–‡ๆกฃ | ่ฏดๆ˜Ž | -| ---------------------------------------------------- | --------------------------------------------- | -| [็”จๆˆทๆŒ‡ๅ—](USER_GUIDE.md) | ๆไพ›ๅ•†ใ€comboใ€CLI ้›†ๆˆใ€้ƒจ็ฝฒ | -| [API ๅ‚่€ƒ](API_REFERENCE.md) | ๆ‰€ๆœ‰็ซฏ็‚นๅŠไฝฟ็”จ็คบไพ‹ | -| [MCP Server](../../../open-sse/mcp-server/README.md) | 16 ไธช MCP ๅทฅๅ…ทใ€IDE ้…็ฝฎใ€Python/TS/Go ๅฎขๆˆท็ซฏ | -| [A2A Server](../../../src/lib/a2a/README.md) | JSON-RPC 2.0 ๅ่ฎฎใ€Skillsใ€ๆตๅผไผ ่พ“ใ€ไปปๅŠก็ฎก็† | -| [Auto-Combo ๅผ•ๆ“Ž](AUTO-COMBO.md) | 6 ๅ› ๅญ่ฏ„ๅˆ†ใ€ๆจกๅผๅŒ…ใ€่‡ชๆ„ˆ | -| [ๆ•…้šœๆŽ’้™ค](TROUBLESHOOTING.md) | ๅธธ่ง้—ฎ้ข˜ๅŠ่งฃๅ†ณๆ–นๆกˆ | -| [ๆžถๆž„](ARCHITECTURE.md) | ็ณป็ปŸๆžถๆž„ไธŽๅ†…้ƒจๅฎž็Žฐ | -| [่ดก็ŒฎๆŒ‡ๅ—](../../../CONTRIBUTING.md) | ๅผ€ๅ‘็ŽฏๅขƒไธŽ่ดก็Œฎ่ง„่Œƒ | -| [OpenAPI ่ง„่Œƒ](../../../docs/openapi.yaml) | OpenAPI 3.0 ่ง„่Œƒ | -| [ๅฎ‰ๅ…จ็ญ–็•ฅ](../../../SECURITY.md) | ๆผๆดžๆŠฅๅ‘ŠไธŽๅฎ‰ๅ…จๅฎž่ทต | -| [VM ้ƒจ็ฝฒๆŒ‡ๅ—](VM_DEPLOYMENT_GUIDE.md) | ๅฎŒๆ•ดๆŒ‡ๅ—๏ผšVM + nginx + Cloudflare ้…็ฝฎ | -| [ๅŠŸ่ƒฝ็”ปๅปŠ](FEATURES.md) | ๅธฆๆˆชๅ›พ็š„ไปช่กจ็›˜ๅŠŸ่ƒฝๅฏผ่งˆ | -| [ๅ‘ๅธƒๆฃ€ๆŸฅๆธ…ๅ•](RELEASE_CHECKLIST.md) | ๅ‘ๅธƒๅ‰้ชŒ่ฏๆญฅ้ชค | +| Document | Description | +| ---------------------------------------------- | --------------------------------------------------- | +| [User Guide](docs/USER_GUIDE.md) | Providers, combos, CLI integration, deployment | +| [API Reference](docs/API_REFERENCE.md) | All endpoints with examples | +| [MCP Server](open-sse/mcp-server/README.md) | 16 MCP tools, IDE configs, Python/TS/Go clients | +| [A2A Server](src/lib/a2a/README.md) | JSON-RPC 2.0 protocol, skills, streaming, task mgmt | +| [Auto-Combo Engine](docs/auto-combo.md) | 6-factor scoring, mode packs, self-healing | +| [Troubleshooting](docs/TROUBLESHOOTING.md) | Common problems and solutions | +| [Architecture](docs/ARCHITECTURE.md) | System architecture and internals | +| [Contributing](CONTRIBUTING.md) | Development setup and guidelines | +| [OpenAPI Spec](docs/openapi.yaml) | OpenAPI 3.0 specification | +| [Security Policy](SECURITY.md) | Vulnerability reporting and security practices | +| [VM Deployment](docs/VM_DEPLOYMENT_GUIDE.md) | Complete guide: VM + nginx + Cloudflare setup | +| [Features Gallery](docs/FEATURES.md) | Visual dashboard tour with screenshots | +| [Release Checklist](docs/RELEASE_CHECKLIST.md) | Pre-release validation steps | --- -## ๐Ÿ—บ๏ธ ่ทฏ็บฟๅ›พ +## ๐Ÿ—บ๏ธ Roadmap -OmniRoute ๅœจๅคšไธชๅผ€ๅ‘้˜ถๆฎต่ฎกๅˆ’ไบ† **210+ ไธชๅŠŸ่ƒฝ**ใ€‚ไปฅไธ‹ๆ˜ฏๅ…ณ้”ฎ้ข†ๅŸŸ๏ผš +OmniRoute has **210+ features planned** across multiple development phases. Here are the key areas: -| ็ฑปๅˆซ | ่ฎกๅˆ’ๅŠŸ่ƒฝ | ไบฎ็‚น | -| ----------------- | -------- | ---------------------------------------------------------- | -| ๐Ÿง  **่ทฏ็”ฑไธŽๆ™บ่ƒฝ** | 25+ | ๆœ€ไฝŽๅปถ่ฟŸ่ทฏ็”ฑใ€ๅŸบไบŽๆ ‡็ญพ่ทฏ็”ฑใ€้…้ข้ข„ๆฃ€ใ€P2C ่ดฆๆˆท้€‰ๆ‹ฉ | -| ๐Ÿ”’ **ๅฎ‰ๅ…จไธŽๅˆ่ง„** | 20+ | SSRF ๅŠ ๅ›บใ€ๅ‡ญ่ฏ้š่—ใ€ๆฏ็ซฏ็‚น้€Ÿ็Ž‡้™ๅˆถใ€็ฎก็†ๅฏ†้’ฅ่Œƒๅ›ด | -| ๐Ÿ“Š **ๅฏ่ง‚ๆต‹ๆ€ง** | 15+ | OpenTelemetry ้›†ๆˆใ€ๅฎžๆ—ถ้…้ข็›‘ๆŽงใ€ๆฏๆจกๅž‹ๆˆๆœฌ่ฟฝ่ธช | -| ๐Ÿ”„ **ๆไพ›ๅ•†้›†ๆˆ** | 20+ | ๅŠจๆ€ๆจกๅž‹ๆณจๅ†Œ่กจใ€ๆไพ›ๅ•†ๅ†ทๅดใ€ๅคš่ดฆๆˆท Codexใ€Copilot ้…้ข่งฃๆž | -| โšก **ๆ€ง่ƒฝ** | 15+ | ๅŒๅฑ‚็ผ“ๅญ˜ใ€ๆ็คบ่ฏ็ผ“ๅญ˜ใ€ๅ“ๅบ”็ผ“ๅญ˜ใ€ๆตๅผ keepaliveใ€ๆ‰น้‡ API | -| ๐ŸŒ **็”Ÿๆ€็ณป็ปŸ** | 10+ | WebSocket APIใ€้…็ฝฎ็ƒญ้‡่ฝฝใ€ๅˆ†ๅธƒๅผ้…็ฝฎๅญ˜ๅ‚จใ€ๅ•†ไธšๆจกๅผ | +| Category | Planned Features | Highlights | +| ----------------------------- | ---------------- | -------------------------------------------------------------------------------------- | +| ๐Ÿง  **Routing & Intelligence** | 25+ | Lowest-latency routing, tag-based routing, quota preflight, P2C account selection | +| ๐Ÿ”’ **Security & Compliance** | 20+ | SSRF hardening, credential cloaking, rate-limit per endpoint, management key scoping | +| ๐Ÿ“Š **Observability** | 15+ | OpenTelemetry integration, real-time quota monitoring, cost tracking per model | +| ๐Ÿ”„ **Provider Integrations** | 20+ | Dynamic model registry, provider cooldowns, multi-account Codex, Copilot quota parsing | +| โšก **Performance** | 15+ | Dual cache layer, prompt cache, response cache, streaming keepalive, batch API | +| ๐ŸŒ **Ecosystem** | 10+ | WebSocket API, config hot-reload, distributed config store, commercial mode | -### ๐Ÿ”œ ๅณๅฐ†ๆŽจๅ‡บ +### ๐Ÿ”œ Coming Soon -- ๐Ÿ”— **OpenCode ้›†ๆˆ** โ€” OpenCode AI ็ผ–็  IDE ็š„ๅŽŸ็”Ÿๆไพ›ๅ•†ๆ”ฏๆŒ -- ๐Ÿ”— **TRAE ้›†ๆˆ** โ€” TRAE AI ๅผ€ๅ‘ๆก†ๆžถ็š„ๅฎŒๆ•ดๆ”ฏๆŒ -- ๐Ÿ“ฆ **ๆ‰น้‡ API** โ€” ๆ‰น้‡่ฏทๆฑ‚็š„ๅผ‚ๆญฅๆ‰นๅค„็† -- ๐ŸŽฏ **ๅŸบไบŽๆ ‡็ญพ่ทฏ็”ฑ** โ€” ๅŸบไบŽ่‡ชๅฎšไน‰ๆ ‡็ญพๅ’Œๅ…ƒๆ•ฐๆฎ่ทฏ็”ฑ่ฏทๆฑ‚ -- ๐Ÿ’ฐ **ๆœ€ไฝŽๆˆๆœฌ็ญ–็•ฅ** โ€” ่‡ชๅŠจ้€‰ๆ‹ฉๆœ€ไพฟๅฎœ็š„ๅฏ็”จๆไพ›ๅ•† +- ๐Ÿ”— **OpenCode Integration** โ€” Native provider support for the OpenCode AI coding IDE +- ๐Ÿ”— **TRAE Integration** โ€” Full support for the TRAE AI development framework +- ๐Ÿ“ฆ **Batch API** โ€” Asynchronous batch processing for bulk requests +- ๐ŸŽฏ **Tag-Based Routing** โ€” Route requests based on custom tags and metadata +- ๐Ÿ’ฐ **Lowest-Cost Strategy** โ€” Automatically select the cheapest available provider -> ๐Ÿ“ ๅฎŒๆ•ดๅŠŸ่ƒฝ่ง„ๆ ผๅœจ [`docs/new-features/`](../../../docs/new-features/) ไธญๅฏ็”จ๏ผˆ217 ไธช่ฏฆ็ป†่ง„ๆ ผ๏ผ‰ +> ๐Ÿ“ Full feature specifications available in [`docs/new-features/`](docs/new-features/) (217 detailed specs) --- -## ๐Ÿ‘ฅ ่ดก็Œฎ่€… +## ๐Ÿ‘ฅ Contributors -[![่ดก็Œฎ่€…](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors) +[![Contributors](https://contrib.rocks/image?repo=diegosouzapw/OmniRoute&max=100&columns=20&anon=1)](https://github.com/diegosouzapw/OmniRoute/graphs/contributors) -### ๅฆ‚ไฝ•่ดก็Œฎ +### How to Contribute -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 +1. Fork the repository +2. Create your feature branch (`git checkout -b feature/amazing-feature`) +3. Commit your changes (`git commit -m 'Add amazing feature'`) +4. Push to the branch (`git push origin feature/amazing-feature`) +5. Open a Pull Request -่ฏฆ็ป†ๆŒ‡ๅ—่ฏทๆŸฅ็œ‹ [CONTRIBUTING.md](../../../CONTRIBUTING.md)ใ€‚ +See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines. -### ๅ‘ๅธƒๆ–ฐ็‰ˆๆœฌ +### Releasing a New Version ```bash -# ๅˆ›ๅปบๅ‘ๅธƒ โ€” npm ๅ‘ๅธƒ่‡ชๅŠจ่ฟ›่กŒ +# Create a release โ€” npm publish happens automatically gh release create v2.0.0 --title "v2.0.0" --generate-notes ``` --- -## ๐Ÿ“Š Star ๅŽ†ๅฒ +## ๐Ÿ“Š Star History -## ้šๆ—ถ้—ดๅ˜ๅŒ–็š„ Stargazers +## Stargazers over time -## [![้šๆ—ถ้—ดๅ˜ๅŒ–็š„ Stargazers](https://starchart.cc/diegosouzapw/OmniRoute.svg?variant=adaptive)](https://starchart.cc/diegosouzapw/OmniRoute) +## [![Stargazers over time](https://starchart.cc/diegosouzapw/OmniRoute.svg?variant=adaptive)](https://starchart.cc/diegosouzapw/OmniRoute) -## ๐Ÿ™ ่‡ด่ฐข +## ๐Ÿ™ Acknowledgments -็‰นๅˆซๆ„Ÿ่ฐข **[decolua](https://github.com/decolua)** ็š„ **[9router](https://github.com/decolua/9router)** โ€” ๅฏๅ‘่ฟ™ไธช fork ็š„ๅŽŸๅง‹้กน็›ฎใ€‚OmniRoute ๅœจ่ฟ™ไธชไปคไบบ้šพไปฅ็ฝฎไฟก็š„ๅŸบ็ก€ไธŠๆž„ๅปบ๏ผŒๅขžๅŠ ไบ†้ขๅค–ๅŠŸ่ƒฝใ€ๅคšๆจกๆ€ API ๅ’ŒๅฎŒๆ•ด็š„ TypeScript ้‡ๅ†™ใ€‚ +Special thanks to **[9router](https://github.com/decolua/9router)** by **[decolua](https://github.com/decolua)** โ€” the original project that inspired this fork. OmniRoute builds upon that incredible foundation with additional features, multi-modal APIs, and a full TypeScript rewrite. -็‰นๅˆซๆ„Ÿ่ฐข **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** โ€” ๅฏๅ‘่ฟ™ไธช JavaScript ็งปๆค็š„ๅŽŸๅง‹ Go ๅฎž็Žฐใ€‚ +Special thanks to **[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** โ€” the original Go implementation that inspired this JavaScript port. --- -## ๐Ÿ“ ่ฎธๅฏ่ฏ +## ่ฎธๅฏ่ฏ -MIT ่ฎธๅฏ่ฏ - ่ฏฆๆƒ…่ฏทๆŸฅ็œ‹ [LICENSE](../../../LICENSE)ใ€‚ +MIT License - see [LICENSE](LICENSE) for details. ---
- ไธบ 24/7 ็ผ–็ ็š„ๅผ€ๅ‘่€…็”จ โค๏ธ ๆž„ๅปบ + Built with โค๏ธ for developers who code 24/7
omniroute.online
diff --git a/docs/i18n/zh-CN/RELEASE_CHECKLIST.md b/docs/i18n/zh-CN/RELEASE_CHECKLIST.md deleted file mode 100644 index a73eac8be9..0000000000 --- a/docs/i18n/zh-CN/RELEASE_CHECKLIST.md +++ /dev/null @@ -1,37 +0,0 @@ -๐ŸŒ **่ฏญ่จ€:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/RELEASE_CHECKLIST.md) - ---- - -# ๅ‘ๅธƒๆฃ€ๆŸฅๆธ…ๅ• - -ๅœจๆ‰“ๆ ‡็ญพๆˆ–ๅ‘ๅธƒๆ–ฐ็š„ OmniRoute ็‰ˆๆœฌไน‹ๅ‰๏ผŒ่ฏทไฝฟ็”จๆญคๆฃ€ๆŸฅๆธ…ๅ•ใ€‚ - -## ็‰ˆๆœฌๅ’Œๅ˜ๆ›ดๆ—ฅๅฟ— - -1. ๅœจๅ‘ๅธƒๅˆ†ๆ”ฏไธญๆ›ดๆ–ฐ `package.json` ็š„็‰ˆๆœฌๅท๏ผˆ`x.y.z`๏ผ‰ใ€‚ -2. ๅฐ†ๅ‘ๅธƒ่ฏดๆ˜ŽไปŽ `CHANGELOG.md` ไธญ็š„ `## [Unreleased]` ็งปๅŠจๅˆฐๅธฆๆ—ฅๆœŸ็š„็ซ ่Š‚๏ผš - - `## [x.y.z] โ€” YYYY-MM-DD` -3. ไฟ็•™ `## [Unreleased]` ไฝœไธบๅ˜ๆ›ดๆ—ฅๅฟ—็š„็ฌฌไธ€ไธช็ซ ่Š‚๏ผŒ็”จไบŽๅŽ็ปญๅทฅไฝœใ€‚ -4. ็กฎไฟ `CHANGELOG.md` ไธญๆœ€ๆ–ฐ็š„่ฏญไน‰ๅŒ–็‰ˆๆœฌ็ซ ่Š‚ไธŽ `package.json` ็š„็‰ˆๆœฌๅทไธ€่‡ดใ€‚ - -## API ๆ–‡ๆกฃ - -1. ๆ›ดๆ–ฐ `docs/openapi.yaml`๏ผš - - `info.version` ๅฟ…้กปไธŽ `package.json` ็š„็‰ˆๆœฌๅทไธ€่‡ดใ€‚ -2. ๅฆ‚ๆžœ API ๅฅ‘็บฆๅ‘็”Ÿๅ˜ๅŒ–๏ผŒ่ฏท้ชŒ่ฏ็ซฏ็‚น็คบไพ‹ใ€‚ - -## ่ฟ่กŒๆ—ถๆ–‡ๆกฃ - -1. ๆฃ€ๆŸฅ `docs/ARCHITECTURE.md` ๆ˜ฏๅฆๅญ˜ๅœจๅญ˜ๅ‚จ/่ฟ่กŒๆ—ถๅ็งปใ€‚ -2. ๆฃ€ๆŸฅ `docs/TROUBLESHOOTING.md` ๆ˜ฏๅฆๅญ˜ๅœจ็Žฏๅขƒๅ˜้‡ๅ’Œๆ“ไฝœๅ็งปใ€‚ -3. ๅฆ‚ๆžœๆบๆ–‡ๆกฃๅ‘็”Ÿ้‡ๅคงๅ˜ๆ›ด๏ผŒ่ฏทๆ›ดๆ–ฐๆœฌๅœฐๅŒ–ๆ–‡ๆกฃใ€‚ - -## ่‡ชๅŠจๅŒ–ๆฃ€ๆŸฅ - -ๅœจๅผ€ๅฏ PR ไน‹ๅ‰๏ผŒๅœจๆœฌๅœฐ่ฟ่กŒๅŒๆญฅๆฃ€ๆŸฅ๏ผš - -```bash -npm run check:docs-sync -``` - -CI ไนŸไผšๅœจ `.github/workflows/ci.yml`๏ผˆlint ไฝœไธš๏ผ‰ไธญ่ฟ่กŒๆญคๆฃ€ๆŸฅใ€‚ diff --git a/docs/i18n/zh-CN/SECURITY.md b/docs/i18n/zh-CN/SECURITY.md new file mode 100644 index 0000000000..c274d543a8 --- /dev/null +++ b/docs/i18n/zh-CN/SECURITY.md @@ -0,0 +1,179 @@ +# Security Policy (ไธญๆ–‡๏ผˆ็ฎ€ไฝ“๏ผ‰) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../SECURITY.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/SECURITY.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/SECURITY.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/SECURITY.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/SECURITY.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/SECURITY.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/SECURITY.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/SECURITY.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/SECURITY.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/SECURITY.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/SECURITY.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/SECURITY.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/SECURITY.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/SECURITY.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/SECURITY.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/SECURITY.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/SECURITY.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../cs/SECURITY.md) + +--- + +## 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 | +| ------- | -------------- | +| 3.4.x | โœ… Active | +| 3.0.x | โœ… Security | +| < 3.0.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 | +| **MCP Scopes** | 10 granular scopes for MCP tool access control | + +### ๐Ÿ›ก๏ธ 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:::` +- 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** | Allowlist/blocklist IP ranges in dashboard | +| **Rate Limiting** | Per-provider rate limits with automatic backoff | +| **Anti-Thundering Herd** | Mutex + per-connection locking prevents cascading 502s | +| **TLS Fingerprint** | Browser-like TLS fingerprint spoofing to reduce bot detection | +| **CLI Fingerprint** | Per-provider header/body ordering to match native CLI signatures | + +### ๐Ÿ”Œ Resilience & Availability + +| 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 `CALL_LOG_RETENTION_DAYS` | +| **No-Log Opt-out** | Per API key `noLog` flag disables request logging | +| **Audit Log** | Administrative actions tracked in `audit_log` table | +| **MCP Audit** | SQLite-backed audit logging for all MCP tool calls | +| **Zod Validation** | All API inputs validated with Zod v4 schemas at module load | + +--- + +## 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 +- Provider constants validated at module load via Zod (`src/shared/validation/providerSchema.ts`) diff --git a/docs/i18n/zh-CN/TROUBLESHOOTING.md b/docs/i18n/zh-CN/TROUBLESHOOTING.md deleted file mode 100644 index a5600a5075..0000000000 --- a/docs/i18n/zh-CN/TROUBLESHOOTING.md +++ /dev/null @@ -1,256 +0,0 @@ -๐ŸŒ **่ฏญ่จ€:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../pt-BR/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../es/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../fr/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../de/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../it/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../ru/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../zh-CN/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../ja/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../ko/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../ar/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../in/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../th/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../vi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../id/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../ms/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../nl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../pl/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../sv/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../no/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../da/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../fi/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../pt/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../ro/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../hu/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../bg/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../sk/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../uk-UA/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../he/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../phi/TROUBLESHOOTING.md) - ---- - -# ๆ•…้šœๆŽ’้™ค - -OmniRoute ๅธธ่ง้—ฎ้ข˜ๅŠ่งฃๅ†ณๆ–นๆกˆใ€‚ - ---- - -## ๅฟซ้€Ÿไฟฎๅค - -| ้—ฎ้ข˜ | ่งฃๅ†ณๆ–นๆกˆ | -| --------------------------- | ------------------------------------------------------------------ | -| ้ฆ–ๆฌก็™ปๅฝ•ๆ— ๆณ•ไฝฟ็”จ | ๅœจ `.env` ไธญ่ฎพ็ฝฎ `INITIAL_PASSWORD`๏ผˆๆ— ็กฌ็ผ–็ ้ป˜่ฎคๅ€ผ๏ผ‰ | -| ไปช่กจ็›˜ๅœจ้”™่ฏฏ็ซฏๅฃๆ‰“ๅผ€ | ่ฎพ็ฝฎ `PORT=20128` ๅ’Œ `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | -| `logs/` ไธ‹ๆ— ่ฏทๆฑ‚ๆ—ฅๅฟ— | ่ฎพ็ฝฎ `ENABLE_REQUEST_LOGS=true` | -| EACCES: ๆƒ้™่ขซๆ‹’็ป | ่ฎพ็ฝฎ `DATA_DIR=/path/to/writable/dir` ไปฅ่ฆ†็›– `~/.omniroute` | -| ่ทฏ็”ฑ็ญ–็•ฅๆœชไฟๅญ˜ | ๆ›ดๆ–ฐๅˆฐ v1.4.11+๏ผˆZod schema ่ฎพ็ฝฎๆŒไน…ๅŒ–ไฟฎๅค๏ผ‰ | - ---- - -## ๆœๅŠกๅ•†้—ฎ้ข˜ - -### "Language model did not provide messages" - -**ๅŽŸๅ› :** ๆœๅŠกๅ•†้…้ข่€—ๅฐฝใ€‚ - -**่งฃๅ†ณๆ–นๆกˆ:** - -1. ๆฃ€ๆŸฅไปช่กจ็›˜้…้ข่ทŸ่ธชๅ™จ -2. ไฝฟ็”จๅธฆๆœ‰ๅ›ž้€€ๅฑ‚็บง็š„็ป„ๅˆ -3. ๅˆ‡ๆขๅˆฐๆ›ดไพฟๅฎœ/ๅ…่ดน็š„ๅฑ‚็บง - -### ้€Ÿ็Ž‡้™ๅˆถ - -**ๅŽŸๅ› :** ่ฎข้˜…้…้ข่€—ๅฐฝใ€‚ - -**่งฃๅ†ณๆ–นๆกˆ:** - -- ๆทปๅŠ ๅ›ž้€€๏ผš`cc/claude-opus-4-6 โ†’ glm/glm-4.7 โ†’ if/kimi-k2-thinking` -- ไฝฟ็”จ GLM/MiniMax ไฝœไธบๅป‰ไปทๅค‡ไปฝ - -### OAuth Token ่ฟ‡ๆœŸ - -OmniRoute ไผš่‡ชๅŠจๅˆทๆ–ฐ tokenใ€‚ๅฆ‚ๆžœ้—ฎ้ข˜ๆŒ็ปญ๏ผš - -1. ไปช่กจ็›˜ โ†’ Provider โ†’ Reconnect -2. ๅˆ ้™คๅนถ้‡ๆ–ฐๆทปๅŠ ๆœๅŠกๅ•†่ฟžๆŽฅ - ---- - -## ไบ‘็ซฏ้—ฎ้ข˜ - -### ไบ‘ๅŒๆญฅ้”™่ฏฏ - -1. ้ชŒ่ฏ `BASE_URL` ๆŒ‡ๅ‘ๆ‚จ็š„่ฟ่กŒๅฎžไพ‹๏ผˆไพ‹ๅฆ‚ `http://localhost:20128`๏ผ‰ -2. ้ชŒ่ฏ `CLOUD_URL` ๆŒ‡ๅ‘ๆ‚จ็š„ไบ‘็ซฏ็‚น๏ผˆไพ‹ๅฆ‚ `https://omniroute.dev`๏ผ‰ -3. ไฟๆŒ `NEXT_PUBLIC_*` ๅ€ผไธŽๆœๅŠกๅ™จ็ซฏๅ€ผไธ€่‡ด - -### ไบ‘็ซฏ `stream=false` ่ฟ”ๅ›ž 500 - -**็—‡็Šถ:** ้žๆตๅผ่ฐƒ็”จๅœจไบ‘็ซฏ็‚น่ฟ”ๅ›ž `Unexpected token 'd'...`ใ€‚ - -**ๅŽŸๅ› :** ไธŠๆธธ่ฟ”ๅ›ž SSE ่ดŸ่ฝฝ๏ผŒ่€Œๅฎขๆˆท็ซฏๆœŸๆœ› JSONใ€‚ - -**่งฃๅ†ณๆ–นๆณ•:** ๅฏนไบ‘็ซฏ็›ดๆŽฅ่ฐƒ็”จไฝฟ็”จ `stream=true`ใ€‚ๆœฌๅœฐ่ฟ่กŒๆ—ถๅŒ…ๅซ SSEโ†’JSON ๅ›ž้€€ใ€‚ - -### ไบ‘็ซฏๆ˜พ็คบๅทฒ่ฟžๆŽฅไฝ† "Invalid API key" - -1. ไปŽๆœฌๅœฐไปช่กจ็›˜ๅˆ›ๅปบๆ–ฐๅฏ†้’ฅ (`/api/keys`) -2. ่ฟ่กŒไบ‘ๅŒๆญฅ๏ผšๅฏ็”จไบ‘ โ†’ ็ซ‹ๅณๅŒๆญฅ -3. ๆ—ง็š„/ๆœชๅŒๆญฅ็š„ๅฏ†้’ฅๅœจไบ‘็ซฏไปๅฏ่ƒฝ่ฟ”ๅ›ž `401` - ---- - -## Docker ้—ฎ้ข˜ - -### CLI ๅทฅๅ…ทๆ˜พ็คบๆœชๅฎ‰่ฃ… - -1. ๆฃ€ๆŸฅ่ฟ่กŒๆ—ถๅญ—ๆฎต๏ผš`curl http://localhost:20128/api/cli-tools/runtime/codex | jq` -2. ไพฟๆบๆจกๅผ๏ผšไฝฟ็”จ้•œๅƒ็›ฎๆ ‡ `runner-cli`๏ผˆๆ†็ป‘ CLI๏ผ‰ -3. ไธปๆœบๆŒ‚่ฝฝๆจกๅผ๏ผš่ฎพ็ฝฎ `CLI_EXTRA_PATHS` ๅนถไปฅๅช่ฏปๆ–นๅผๆŒ‚่ฝฝไธปๆœบ bin ็›ฎๅฝ• -4. ๅฆ‚ๆžœ `installed=true` ไธ” `runnable=false`๏ผšๆ‰พๅˆฐไบŒ่ฟ›ๅˆถๆ–‡ไปถไฝ†ๅฅๅบทๆฃ€ๆŸฅๅคฑ่ดฅ - -### ๅฟซ้€Ÿ่ฟ่กŒๆ—ถ้ชŒ่ฏ - -```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}' -``` - ---- - -## ๆˆๆœฌ้—ฎ้ข˜ - -### ้ซ˜ๆˆๆœฌ - -1. ๅœจ Dashboard โ†’ Usage ๆฃ€ๆŸฅไฝฟ็”จ็ปŸ่ฎก -2. ๅฐ†ไธป่ฆๆจกๅž‹ๅˆ‡ๆขๅˆฐ GLM/MiniMax -3. ๅฏน้žๅ…ณ้”ฎไปปๅŠกไฝฟ็”จๅ…่ดนๅฑ‚๏ผˆGemini CLIใ€Qoder๏ผ‰ -4. ไธบๆฏไธช API ๅฏ†้’ฅ่ฎพ็ฝฎๆˆๆœฌ้ข„็ฎ—๏ผšDashboard โ†’ API Keys โ†’ Budget - ---- - -## ่ฐƒ่ฏ• - -### ๅฏ็”จ่ฏทๆฑ‚ๆ—ฅๅฟ— - -ๅœจ `.env` ๆ–‡ไปถไธญ่ฎพ็ฝฎ `ENABLE_REQUEST_LOGS=true`ใ€‚ๆ—ฅๅฟ—ๅ‡บ็Žฐๅœจ `logs/` ็›ฎๅฝ•ไธ‹ใ€‚ - -### ๆฃ€ๆŸฅๆœๅŠกๅ•†ๅฅๅบท็Šถๆ€ - -```bash -# ๅฅๅบทไปช่กจ็›˜ -http://localhost:20128/dashboard/health - -# API ๅฅๅบทๆฃ€ๆŸฅ -curl http://localhost:20128/api/monitoring/health -``` - -### ่ฟ่กŒๆ—ถๅญ˜ๅ‚จ - -- ไธป่ฆ็Šถๆ€๏ผš`${DATA_DIR}/storage.sqlite`๏ผˆๆœๅŠกๅ•†ใ€็ป„ๅˆใ€ๅˆซๅใ€ๅฏ†้’ฅใ€่ฎพ็ฝฎ๏ผ‰ -- ไฝฟ็”จ้‡๏ผš`storage.sqlite` ไธญ็š„ SQLite ่กจ๏ผˆ`usage_history`ใ€`call_logs`ใ€`proxy_logs`๏ผ‰+ ๅฏ้€‰ `${DATA_DIR}/log.txt` ๅ’Œ `${DATA_DIR}/call_logs/` -- ่ฏทๆฑ‚ๆ—ฅๅฟ—๏ผš`/logs/...`๏ผˆๅฝ“ `ENABLE_REQUEST_LOGS=true` ๆ—ถ๏ผ‰ - ---- - -## ็†”ๆ–ญๅ™จ้—ฎ้ข˜ - -### ๆœๅŠกๅ•†ๅกๅœจ OPEN ็Šถๆ€ - -ๅฝ“ๆœๅŠกๅ•†็š„็†”ๆ–ญๅ™จๅค„ไบŽ OPEN ็Šถๆ€ๆ—ถ๏ผŒ่ฏทๆฑ‚ไผš่ขซ้˜ปๆญข็›ดๅˆฐๅ†ทๅดๆœŸ็ป“ๆŸใ€‚ - -**่งฃๅ†ณๆ–นๆกˆ:** - -1. ๅ‰ๅพ€ **Dashboard โ†’ Settings โ†’ Resilience** -2. ๆฃ€ๆŸฅๅ—ๅฝฑๅ“ๆœๅŠกๅ•†็š„็†”ๆ–ญๅ™จๅก็‰‡ -3. ็‚นๅ‡ป **Reset All** ๆธ…้™คๆ‰€ๆœ‰็†”ๆ–ญๅ™จ๏ผŒๆˆ–็ญ‰ๅพ…ๅ†ทๅดๆœŸ็ป“ๆŸ -4. ้‡็ฝฎๅ‰้ชŒ่ฏๆœๅŠกๅ•†็กฎๅฎžๅฏ็”จ - -### ๆœๅŠกๅ•†ๅๅค่งฆๅ‘็†”ๆ–ญๅ™จ - -ๅฆ‚ๆžœๆœๅŠกๅ•†ๅๅค่ฟ›ๅ…ฅ OPEN ็Šถๆ€๏ผš - -1. ๆฃ€ๆŸฅ **Dashboard โ†’ Health โ†’ Provider Health** ไบ†่งฃๆ•…้šœๆจกๅผ -2. ๅ‰ๅพ€ **Settings โ†’ Resilience โ†’ Provider Profiles** ๅขžๅŠ ๆ•…้šœ้˜ˆๅ€ผ -3. ๆฃ€ๆŸฅๆœๅŠกๅ•†ๆ˜ฏๅฆๆ›ดๆ”นไบ† API ้™ๅˆถๆˆ–้œ€่ฆ้‡ๆ–ฐ่ฎค่ฏ -4. ๆŸฅ็œ‹ๅปถ่ฟŸ้ฅๆต‹ โ€” ้ซ˜ๅปถ่ฟŸๅฏ่ƒฝๅฏผ่‡ดๅŸบไบŽ่ถ…ๆ—ถ็š„ๆ•…้šœ - ---- - -## ้Ÿณ้ข‘่ฝฌๅฝ•้—ฎ้ข˜ - -### "Unsupported model" ้”™่ฏฏ - -- ็กฎไฟไฝฟ็”จๆญฃ็กฎ็š„ๅ‰็ผ€๏ผš`deepgram/nova-3` ๆˆ– `assemblyai/best` -- ๅœจ **Dashboard โ†’ Providers** ้ชŒ่ฏๆœๅŠกๅ•†ๅทฒ่ฟžๆŽฅ - -### ่ฝฌๅฝ•่ฟ”ๅ›ž็ฉบๆˆ–ๅคฑ่ดฅ - -- ๆฃ€ๆŸฅๆ”ฏๆŒ็š„้Ÿณ้ข‘ๆ ผๅผ๏ผš`mp3`ใ€`wav`ใ€`m4a`ใ€`flac`ใ€`ogg`ใ€`webm` -- ้ชŒ่ฏๆ–‡ไปถๅคงๅฐๅœจๆœๅŠกๅ•†้™ๅˆถๅ†…๏ผˆ้€šๅธธ < 25MB๏ผ‰ -- ๅœจๆœๅŠกๅ•†ๅก็‰‡ไธญๆฃ€ๆŸฅ API ๅฏ†้’ฅๆœ‰ๆ•ˆๆ€ง - ---- - -## ็ฟป่ฏ‘ๅ™จ่ฐƒ่ฏ• - -ไฝฟ็”จ **Dashboard โ†’ Translator** ่ฐƒ่ฏ•ๆ ผๅผ็ฟป่ฏ‘้—ฎ้ข˜๏ผš - -| ๆจกๅผ | ไฝฟ็”จๅœบๆ™ฏ | -| ----------------- | ------------------------------------------------------------------------------- | -| **Playground** | ๅนถๆŽ’ๆฏ”่พƒ่พ“ๅ…ฅ/่พ“ๅ‡บๆ ผๅผ โ€” ็ฒ˜่ดดๅคฑ่ดฅ็š„่ฏทๆฑ‚ๆŸฅ็œ‹ๅ…ถ็ฟป่ฏ‘็ป“ๆžœ | -| **Chat Tester** | ๅ‘้€ๅฎžๆ—ถๆถˆๆฏๅนถๆฃ€ๆŸฅๅฎŒๆ•ด็š„่ฏทๆฑ‚/ๅ“ๅบ”่ดŸ่ฝฝ๏ผˆๅŒ…ๆ‹ฌๅคด้ƒจ๏ผ‰ | -| **Test Bench** | ่ทจๆ ผๅผ็ป„ๅˆ่ฟ่กŒๆ‰น้‡ๆต‹่ฏ•ไปฅๆ‰พๅ‡บๅ“ชไบ›็ฟป่ฏ‘ๆœ‰้—ฎ้ข˜ | -| **Live Monitor** | ่ง‚ๅฏŸๅฎžๆ—ถ่ฏทๆฑ‚ๆตไปฅๆ•่Žท้—ดๆญ‡ๆ€ง็ฟป่ฏ‘้—ฎ้ข˜ | - -### ๅธธ่งๆ ผๅผ้—ฎ้ข˜ - -- **Thinking ๆ ‡็ญพๆœชๆ˜พ็คบ** โ€” ๆฃ€ๆŸฅ็›ฎๆ ‡ๆœๅŠกๅ•†ๆ˜ฏๅฆๆ”ฏๆŒ thinking ๅŠ thinking budget ่ฎพ็ฝฎ -- **ๅทฅๅ…ท่ฐƒ็”จไธขๅคฑ** โ€” ๆŸไบ›ๆ ผๅผ็ฟป่ฏ‘ๅฏ่ƒฝๅ‰ฅ็ฆปไธๆ”ฏๆŒ็š„ๅญ—ๆฎต๏ผ›ๅœจ Playground ๆจกๅผ้ชŒ่ฏ -- **็ณป็ปŸๆ็คบ็ผบๅคฑ** โ€” Claude ๅ’Œ Gemini ๅค„็†็ณป็ปŸๆ็คบ็š„ๆ–นๅผไธๅŒ๏ผ›ๆฃ€ๆŸฅ็ฟป่ฏ‘่พ“ๅ‡บ -- **SDK ่ฟ”ๅ›žๅŽŸๅง‹ๅญ—็ฌฆไธฒ่€Œ้žๅฏน่ฑก** โ€” v1.1.0 ๅทฒไฟฎๅค๏ผšๅ“ๅบ”ๆธ…็†ๅ™จ็Žฐๅœจไผšๅ‰ฅ็ฆปๅฏผ่‡ด OpenAI SDK Pydantic ้ชŒ่ฏๅคฑ่ดฅ็š„้žๆ ‡ๅ‡†ๅญ—ๆฎต๏ผˆ`x_groq`ใ€`usage_breakdown` ็ญ‰๏ผ‰ -- **GLM/ERNIE ๆ‹’็ป `system` ่ง’่‰ฒ** โ€” v1.1.0 ๅทฒไฟฎๅค๏ผš่ง’่‰ฒๅฝ’ไธ€ๅŒ–ๅ™จ่‡ชๅŠจๅฐ†็ณป็ปŸๆถˆๆฏๅˆๅนถๅˆฐไธๅ…ผๅฎนๆจกๅž‹็š„็”จๆˆทๆถˆๆฏไธญ -- **`developer` ่ง’่‰ฒไธ่ขซ่ฏ†ๅˆซ** โ€” v1.1.0 ๅทฒไฟฎๅค๏ผšๅฏน้ž OpenAI ๆœๅŠกๅ•†่‡ชๅŠจ่ฝฌๆขไธบ `system` -- **`json_schema` ๅฏน Gemini ไธ่ตทไฝœ็”จ** โ€” v1.1.0 ๅทฒไฟฎๅค๏ผš`response_format` ็Žฐๅœจไผš่ฝฌๆขไธบ Gemini ็š„ `responseMimeType` + `responseSchema` - ---- - -## ๅผนๆ€ง่ฎพ็ฝฎ - -### ่‡ชๅŠจ้€Ÿ็Ž‡้™ๅˆถๆœช่งฆๅ‘ - -- ่‡ชๅŠจ้€Ÿ็Ž‡้™ๅˆถไป…้€‚็”จไบŽ API ๅฏ†้’ฅๆœๅŠกๅ•†๏ผˆไธ้€‚็”จไบŽ OAuth/่ฎข้˜…๏ผ‰ -- ้ชŒ่ฏ **Settings โ†’ Resilience โ†’ Provider Profiles** ๅทฒๅฏ็”จ่‡ชๅŠจ้€Ÿ็Ž‡้™ๅˆถ -- ๆฃ€ๆŸฅๆœๅŠกๅ•†ๆ˜ฏๅฆ่ฟ”ๅ›ž `429` ็Šถๆ€็ ๆˆ– `Retry-After` ๅคด้ƒจ - -### ่ฐƒๆ•ดๆŒ‡ๆ•ฐ้€€้ฟ - -ๆœๅŠกๅ•†้…็ฝฎๆ–‡ไปถๆ”ฏๆŒไปฅไธ‹่ฎพ็ฝฎ๏ผš - -- **Base delay** โ€” ้ฆ–ๆฌกๅคฑ่ดฅๅŽ็š„ๅˆๅง‹็ญ‰ๅพ…ๆ—ถ้—ด๏ผˆ้ป˜่ฎค๏ผš1s๏ผ‰ -- **Max delay** โ€” ๆœ€ๅคง็ญ‰ๅพ…ๆ—ถ้—ดไธŠ้™๏ผˆ้ป˜่ฎค๏ผš30s๏ผ‰ -- **Multiplier** โ€” ๆฏๆฌก่ฟž็ปญๅคฑ่ดฅๅŽๅปถ่ฟŸๅขžๅŠ ็š„ๅ€ๆ•ฐ๏ผˆ้ป˜่ฎค๏ผš2x๏ผ‰ - -### ้˜ฒๆƒŠ็พคๆ•ˆๅบ” - -ๅฝ“ๅคšไธชๅนถๅ‘่ฏทๆฑ‚ๅ‘ฝไธญ้€Ÿ็Ž‡ๅ—้™็š„ๆœๅŠกๅ•†ๆ—ถ๏ผŒOmniRoute ไฝฟ็”จไบ’ๆ–ฅ้” + ่‡ชๅŠจ้€Ÿ็Ž‡้™ๅˆถๆฅๅบๅˆ—ๅŒ–่ฏทๆฑ‚ๅนถ้˜ฒๆญข็บง่”ๆ•…้šœใ€‚่ฟ™ๅฏน API ๅฏ†้’ฅๆœๅŠกๅ•†ๆ˜ฏ่‡ชๅŠจ็š„ใ€‚ - ---- - -## ๅฏ้€‰ RAG / LLM ๆ•…้šœๅˆ†็ฑป๏ผˆ16 ไธช้—ฎ้ข˜๏ผ‰ - -ไธ€ไบ› OmniRoute ็”จๆˆทๅฐ†็ฝ‘ๅ…ณๆ”พๅœจ RAG ๆˆ–ไปฃ็†ๅ †ๆ ˆๅ‰้ขใ€‚ๅœจ่ฟ™ไบ›่ฎพ็ฝฎไธญ๏ผŒๅธธ่งไธ€็งๅฅ‡ๆ€ช็š„ๆจกๅผ๏ผšOmniRoute ็œ‹่ตทๆฅๅฅๅบท๏ผˆๆœๅŠกๅ•†่ฟ่กŒไธญใ€่ทฏ็”ฑ้…็ฝฎๆญฃๅธธใ€ๆ— ้€Ÿ็Ž‡้™ๅˆถๅ‘Š่ญฆ๏ผ‰๏ผŒไฝ†ๆœ€็ปˆ็ญ”ๆกˆไป็„ถๆ˜ฏ้”™่ฏฏ็š„ใ€‚ - -ๅฎž้™…ไธŠ๏ผŒ่ฟ™ไบ›ไบ‹ไปถ้€šๅธธๆฅ่‡ชไธ‹ๆธธ RAG ็ฎก้“๏ผŒ่€Œ้ž็ฝ‘ๅ…ณๆœฌ่บซใ€‚ - -ๅฆ‚ๆžœๆ‚จๆƒณ่ฆๆ่ฟฐ่ฟ™ไบ›ๆ•…้šœ็š„ๅ…ฑไบซ่ฏๆฑ‡๏ผŒๅฏไปฅไฝฟ็”จ WFGY ProblemMap๏ผŒ่ฟ™ๆ˜ฏไธ€ไธชๅค–้ƒจ MIT ่ฎธๅฏ็š„ๆ–‡ๆœฌ่ต„ๆบ๏ผŒๅฎšไน‰ไบ†ๅๅ…ญ็งๅๅคๅ‡บ็Žฐ็š„ RAG / LLM ๆ•…้šœๆจกๅผใ€‚ๅœจ้ซ˜ๅฑ‚ๆฌกไธŠ๏ผŒๅฎƒๆถต็›–๏ผš - -- ๆฃ€็ดขๆผ‚็งปๅ’Œๆ–ญ่ฃ‚็š„ไธŠไธ‹ๆ–‡่พน็•Œ -- ็ฉบ็š„ๆˆ–่ฟ‡ๆ—ถ็š„็ดขๅผ•ๅ’Œๅ‘้‡ๅญ˜ๅ‚จ -- ๅตŒๅ…ฅไธŽ่ฏญไน‰ไธๅŒน้… -- ๆ็คบ็ป„่ฃ…ๅ’ŒไธŠไธ‹ๆ–‡็ช—ๅฃ้—ฎ้ข˜ -- ้€ป่พ‘ๅดฉๆบƒๅ’Œ่ฟ‡ๅบฆ่‡ชไฟก็š„็ญ”ๆกˆ -- ้•ฟ้“พๅ’Œไปฃ็†ๅ่ฐƒๆ•…้šœ -- ๅคšไปฃ็†่ฎฐๅฟ†ๅ’Œ่ง’่‰ฒๆผ‚็งป -- ้ƒจ็ฝฒๅ’ŒๅฏๅŠจ้กบๅบ้—ฎ้ข˜ - -ๆƒณๆณ•ๅพˆ็ฎ€ๅ•๏ผš - -1. ๅฝ“ๆ‚จ่ฐƒๆŸฅ้”™่ฏฏๅ“ๅบ”ๆ—ถ๏ผŒ่ฎฐๅฝ•๏ผš - - ็”จๆˆทไปปๅŠกๅ’Œ่ฏทๆฑ‚ - - OmniRoute ไธญ็š„่ทฏ็”ฑๆˆ–ๆœๅŠกๅ•†็ป„ๅˆ - - ไธ‹ๆธธไฝฟ็”จ็š„ไปปไฝ• RAG ไธŠไธ‹ๆ–‡๏ผˆๆฃ€็ดข็š„ๆ–‡ๆกฃใ€ๅทฅๅ…ท่ฐƒ็”จ็ญ‰๏ผ‰ -2. ๅฐ†ไบ‹ไปถๆ˜ ๅฐ„ๅˆฐไธ€ไธชๆˆ–ไธคไธช WFGY ProblemMap ็ผ–ๅท๏ผˆ`No.1` โ€ฆ `No.16`๏ผ‰ใ€‚ -3. ๅœจๆ‚จ่‡ชๅทฑ็š„ไปช่กจ็›˜ใ€่ฟ่กŒๆ‰‹ๅ†Œๆˆ–ไบ‹ไปถ่ทŸ่ธชๅ™จไธญๅฐ†่ฏฅ็ผ–ๅทๅญ˜ๅ‚จๅœจ OmniRoute ๆ—ฅๅฟ—ๆ—่พนใ€‚ -4. ไฝฟ็”จ็›ธๅบ”็š„ WFGY ้กต้ขๆฅๅ†ณๅฎšๆ˜ฏๅฆ้œ€่ฆๆ›ดๆ”นๆ‚จ็š„ RAG ๅ †ๆ ˆใ€ๆฃ€็ดขๅ™จๆˆ–่ทฏ็”ฑ็ญ–็•ฅใ€‚ - -ๅฎŒๆ•ดๆ–‡ๆœฌๅ’Œๅ…ทไฝ“ๆ–นๆกˆๅœจๆญคๅค„๏ผˆMIT ่ฎธๅฏ๏ผŒไป…ๆ–‡ๆœฌ๏ผ‰๏ผš - -[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) - -ๅฆ‚ๆžœๆ‚จไธๅœจ OmniRoute ๅŽ้ข่ฟ่กŒ RAG ๆˆ–ไปฃ็†็ฎก้“๏ผŒๅฏไปฅๅฟฝ็•ฅๆญค้ƒจๅˆ†ใ€‚ - ---- - -## ไป็„ถๅกไฝ๏ผŸ - -- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) -- **ๆžถๆž„**: ๅ‚่ง [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) ไบ†่งฃๅ†…้ƒจ็ป†่Š‚ -- **API ๅ‚่€ƒ**: ๅ‚่ง [`docs/API_REFERENCE.md`](API_REFERENCE.md) ไบ†่งฃๆ‰€ๆœ‰็ซฏ็‚น -- **ๅฅๅบทไปช่กจ็›˜**: ๆฃ€ๆŸฅ **Dashboard โ†’ Health** ไบ†่งฃๅฎžๆ—ถ็ณป็ปŸ็Šถๆ€ -- **็ฟป่ฏ‘ๅ™จ**: ไฝฟ็”จ **Dashboard โ†’ Translator** ่ฐƒ่ฏ•ๆ ผๅผ้—ฎ้ข˜ diff --git a/docs/i18n/zh-CN/USER_GUIDE.md b/docs/i18n/zh-CN/USER_GUIDE.md deleted file mode 100644 index 7a5275817e..0000000000 --- a/docs/i18n/zh-CN/USER_GUIDE.md +++ /dev/null @@ -1,942 +0,0 @@ -# ็”จๆˆทๆŒ‡ๅ— - -๐ŸŒ **่ฏญ่จ€:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../USER_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](../pt-BR/USER_GUIDE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](../es/USER_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](../fr/USER_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](../it/USER_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](../ru/USER_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](../zh-CN/USER_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](../de/USER_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](../in/USER_GUIDE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](../th/USER_GUIDE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](../uk-UA/USER_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](../ar/USER_GUIDE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](../ja/USER_GUIDE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](../vi/USER_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](../bg/USER_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](../da/USER_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](../fi/USER_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](../he/USER_GUIDE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](../hu/USER_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](../id/USER_GUIDE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](../ko/USER_GUIDE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](../ms/USER_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](../nl/USER_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](../no/USER_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](../pt/USER_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](../ro/USER_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](../pl/USER_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](../sk/USER_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](../sv/USER_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](../phi/USER_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](../cs/USER_GUIDE.md) - -้…็ฝฎๆไพ›ๅ•†ใ€ๅˆ›ๅปบ Comboใ€้›†ๆˆ CLI ๅทฅๅ…ทไปฅๅŠ้ƒจ็ฝฒ OmniRoute ็š„ๅฎŒๆ•ดๆŒ‡ๅ—ใ€‚ - ---- - -## ็›ฎๅฝ• - -- [ไปทๆ ผๆฆ‚่งˆ](#-ไปทๆ ผๆฆ‚่งˆ) -- [ไฝฟ็”จๅœบๆ™ฏ](#-ไฝฟ็”จๅœบๆ™ฏ) -- [ๆไพ›ๅ•†้…็ฝฎ](#-ๆไพ›ๅ•†้…็ฝฎ) -- [CLI ้›†ๆˆ](#-cli-้›†ๆˆ) -- [้ƒจ็ฝฒ](#-้ƒจ็ฝฒ) -- [ๅฏ็”จๆจกๅž‹](#-ๅฏ็”จๆจกๅž‹) -- [้ซ˜็บงๅŠŸ่ƒฝ](#-้ซ˜็บงๅŠŸ่ƒฝ) - ---- - -## ๐Ÿ’ฐ ไปทๆ ผๆฆ‚่งˆ - -| ๅฑ‚็บง | ๆไพ›ๅ•† | ่ดน็”จ | ้…้ข้‡็ฝฎ | ้€‚็”จไบบ็พค | -| ------------------- | ----------------- | ----------- | ---------------- | -------------------- | -| **๐Ÿ’ณ ่ฎข้˜…** | Claude Code (Pro) | $20/ๆœˆ | 5ๅฐๆ—ถ + ๆฏๅ‘จ | ๅทฒ่ฎข้˜…็”จๆˆท | -| | Codex (Plus/Pro) | $20-200/ๆœˆ | 5ๅฐๆ—ถ + ๆฏๅ‘จ | OpenAI ็”จๆˆท | -| | Gemini CLI | **ๅ…่ดน** | 18ไธ‡/ๆœˆ + 1ๅƒ/ๅคฉ | ๆ‰€ๆœ‰ไบบ๏ผ | -| | GitHub Copilot | $10-19/ๆœˆ | ๆฏๆœˆ | GitHub ็”จๆˆท | -| **๐Ÿ”‘ API ๅฏ†้’ฅ** | DeepSeek | ๆŒ‰้‡ไป˜่ดน | ๆ—  | ไฝŽๆˆๆœฌๆŽจ็† | -| | Groq | ๆŒ‰้‡ไป˜่ดน | ๆ—  | ่ถ…ๅฟซๆŽจ็† | -| | xAI (Grok) | ๆŒ‰้‡ไป˜่ดน | ๆ—  | Grok 4 ๆŽจ็† | -| | Mistral | ๆŒ‰้‡ไป˜่ดน | ๆ—  | ๆฌง็›Ÿๆ‰˜็ฎกๆจกๅž‹ | -| | Perplexity | ๆŒ‰้‡ไป˜่ดน | ๆ—  | ๆœ็ดขๅขžๅผบ | -| | Together AI | ๆŒ‰้‡ไป˜่ดน | ๆ—  | ๅผ€ๆบๆจกๅž‹ | -| | Fireworks AI | ๆŒ‰้‡ไป˜่ดน | ๆ—  | ๅฟซ้€Ÿ FLUX ๅ›พๅƒ | -| | Cerebras | ๆŒ‰้‡ไป˜่ดน | ๆ—  | ๆ™ถๅœ†็บง้€Ÿๅบฆ | -| | Cohere | ๆŒ‰้‡ไป˜่ดน | ๆ—  | Command R+ RAG | -| | NVIDIA NIM | ๆŒ‰้‡ไป˜่ดน | ๆ—  | ไผไธš็บงๆจกๅž‹ | -| **๐Ÿ’ฐ ไฝŽไปท** | GLM-4.7 | $0.6/1M | ๆฏๆ—ฅไธŠๅˆ10็‚น | ้ข„็ฎ—ๅค‡็”จ | -| | MiniMax M2.1 | $0.2/1M | 5ๅฐๆ—ถๆปšๅŠจ | ๆœ€ไพฟๅฎœ้€‰้กน | -| | Kimi K2 | $9/ๆœˆๅ›บๅฎš | 1000ไธ‡ token/ๆœˆ | ๅฏ้ข„ๆต‹ๆˆๆœฌ | -| **๐Ÿ†“ ๅ…่ดน** | Qoder | $0 | ๆ— ้™ๅˆถ | 8ไธชๅ…่ดนๆจกๅž‹ | -| | Qwen | $0 | ๆ— ้™ๅˆถ | 3ไธชๅ…่ดนๆจกๅž‹ | -| | Kiro | $0 | ๆ— ้™ๅˆถ | Claude ๅ…่ดน | - -**๐Ÿ’ก ไธ“ไธšๆ็คบ๏ผš** ไปŽ Gemini CLI๏ผˆๆฏๆœˆ18ไธ‡ๅ…่ดน๏ผ‰+ Qoder๏ผˆๆ— ้™ๅ…่ดน๏ผ‰็ป„ๅˆๅผ€ๅง‹ = $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 ๏ผˆๆฏๆœˆ 18 ไธ‡ๅ…่ดน๏ผ‰ - 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 ๅฑ‚ๅŽๅค‡ = ้›ถๅœๆœบ -ๆœˆ่ดน็”จ๏ผš$20-200๏ผˆ่ฎข้˜…๏ผ‰+ $10-20๏ผˆๅค‡็”จ๏ผ‰ -``` - -### ๅœบๆ™ฏ 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... -``` - ---- - -## ๐Ÿ“– ๆไพ›ๅ•†้…็ฝฎ - -### ๐Ÿ” ่ฎข้˜…็ฑปๆไพ›ๅ•† - -#### Claude Code (Pro/Max) - -```bash -Dashboard โ†’ Providers โ†’ Connect Claude Code -โ†’ OAuth ็™ปๅฝ• โ†’ ่‡ชๅŠจๅˆทๆ–ฐ Token -โ†’ 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 โ†’ Providers โ†’ Connect Codex -โ†’ OAuth ็™ปๅฝ•๏ผˆ็ซฏๅฃ 1455๏ผ‰ -โ†’ 5 ๅฐๆ—ถ + ๆฏๅ‘จ้‡็ฝฎ - -ๆจกๅž‹๏ผš - cx/gpt-5.2-codex - cx/gpt-5.1-codex-max -``` - -#### Gemini CLI๏ผˆๆฏๆœˆ 18 ไธ‡ๅ…่ดน๏ผ๏ผ‰ - -```bash -Dashboard โ†’ Providers โ†’ Connect Gemini CLI -โ†’ Google OAuth -โ†’ ๆฏๆœˆ 18 ไธ‡ๆฌก่กฅๅ…จ + ๆฏๆ—ฅ 1 ๅƒๆฌก - -ๆจกๅž‹๏ผš - gc/gemini-3-flash-preview - gc/gemini-2.5-pro -``` - -**ๆœ€ไฝณๆ€งไปทๆฏ”๏ผš** ่ถ…ๅคงๅ…่ดน้ขๅบฆ๏ผไผ˜ๅ…ˆไฝฟ็”จๆญคๆไพ›ๅ•†ใ€‚ - -#### GitHub Copilot - -```bash -Dashboard โ†’ Providers โ†’ Connect GitHub -โ†’ ้€š่ฟ‡ GitHub OAuth -โ†’ ๆฏๆœˆ้‡็ฝฎ๏ผˆๆฏๆœˆ 1 ๆ—ฅ๏ผ‰ - -ๆจกๅž‹๏ผš - gh/gpt-5 - gh/claude-4.5-sonnet - gh/gemini-3-pro -``` - -### ๐Ÿ’ฐ ไฝŽไปทๆไพ›ๅ•† - -#### GLM-4.7๏ผˆๆฏๆ—ฅ้‡็ฝฎ๏ผŒ$0.6/1M๏ผ‰ - -1. ๆณจๅ†Œ๏ผš[ๆ™บ่ฐฑ AI](https://open.bigmodel.cn/) -2. ไปŽ Coding Plan ่Žทๅ– API ๅฏ†้’ฅ -3. Dashboard โ†’ Add 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 ๅฏ†้’ฅ โ†’ Dashboard โ†’ Add API Key - -**ไฝฟ็”จ๏ผš** `minimax/MiniMax-M2.1` โ€” **ไธ“ไธšๆ็คบ๏ผš** ้•ฟไธŠไธ‹ๆ–‡๏ผˆ1M tokens๏ผ‰ๆœ€ไพฟๅฎœ็š„้€‰ๆ‹ฉ๏ผ - -#### Kimi K2๏ผˆๅ›บๅฎš $9/ๆœˆ๏ผ‰ - -1. ่ฎข้˜…๏ผš[Moonshot AI](https://platform.moonshot.ai/) -2. ่Žทๅ– API ๅฏ†้’ฅ โ†’ Dashboard โ†’ Add API Key - -**ไฝฟ็”จ๏ผš** `kimi/kimi-latest` โ€” **ไธ“ไธšๆ็คบ๏ผš** ๅ›บๅฎš $9/ๆœˆ่Žทๅพ— 1000 ไธ‡ tokens = ๆœ‰ๆ•ˆๆˆๆœฌ $0.90/1M๏ผ - -### ๐Ÿ†“ ๅ…่ดนๆไพ›ๅ•† - -#### Qoder๏ผˆ8 ไธชๅ…่ดนๆจกๅž‹๏ผ‰ - -```bash -Dashboard โ†’ Connect Qoder โ†’ OAuth ็™ปๅฝ• โ†’ ๆ— ้™ไฝฟ็”จ - -ๆจกๅž‹๏ผšif/kimi-k2-thinking, if/qwen3-coder-plus, if/glm-4.7, if/minimax-m2, if/deepseek-r1 -``` - -#### Qwen๏ผˆ3 ไธชๅ…่ดนๆจกๅž‹๏ผ‰ - -```bash -Dashboard โ†’ Connect Qwen โ†’ ่ฎพๅค‡็ ่ฎค่ฏ โ†’ ๆ— ้™ไฝฟ็”จ - -ๆจกๅž‹๏ผšqw/qwen3-coder-plus, qw/qwen3-coder-flash -``` - -#### Kiro๏ผˆๅ…่ดน Claude๏ผ‰ - -```bash -Dashboard โ†’ Connect Kiro โ†’ AWS Builder ID ๆˆ– Google/GitHub โ†’ ๆ— ้™ - -ๆจกๅž‹๏ผškr/claude-sonnet-4.5, kr/claude-haiku-4.5 -``` - ---- - -## ๐ŸŽจ Combos - -### ็คบไพ‹ 1๏ผšๆœ€ๅคงๅŒ–่ฎข้˜… โ†’ ไฝŽไปทๅค‡็”จ - -``` -Dashboard โ†’ Combos โ†’ Create New - -ๅ็งฐ๏ผš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๏ผˆๆฏๆœˆ 18 ไธ‡ๅ…่ดน๏ผ‰ - 2. if/kimi-k2-thinking๏ผˆๆ— ้™๏ผ‰ - 3. qw/qwen3-coder-plus๏ผˆๆ— ้™๏ผ‰ - -ๆˆๆœฌ๏ผšๆฐธไน… $0๏ผ -``` - ---- - -## ๐Ÿ”ง CLI ้›†ๆˆ - -### Cursor IDE - -``` -Settings โ†’ Models โ†’ Advanced๏ผš - OpenAI API Base URL๏ผšhttp://localhost:20128/v1 - OpenAI API Key๏ผš[ไปŽ omniroute dashboard ่Žทๅ–] - Model๏ผšcc/claude-opus-4-6 -``` - -### Claude Code - -็ผ–่พ‘ `~/.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 - -็ผ–่พ‘ `~/.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" }] - } - } - } -} -``` - -**ๆˆ–ไฝฟ็”จ Dashboard๏ผš** CLI Tools โ†’ OpenClaw โ†’ Auto-config - -### Cline / Continue / RooCode - -``` -Provider๏ผšOpenAI Compatible -Base URL๏ผšhttp://localhost:20128/v1 -API Key๏ผš[ไปŽ dashboard ่Žทๅ–] -Model๏ผšcc/claude-opus-4-6 -``` - ---- - -## ๐Ÿš€ ้ƒจ็ฝฒ - -### ๅ…จๅฑ€ npm ๅฎ‰่ฃ…๏ผˆๆŽจ่๏ผ‰ - -```bash -npm install -g omniroute - -# ๅˆ›ๅปบ้…็ฝฎ็›ฎๅฝ• -mkdir -p ~/.omniroute - -# ๅˆ›ๅปบ .env ๆ–‡ไปถ๏ผˆๅ‚่ง .env.example๏ผ‰ -cp .env.example ~/.omniroute/.env - -# ๅฏๅŠจๆœๅŠกๅ™จ -omniroute -# ๆˆ–ๆŒ‡ๅฎš็ซฏๅฃ๏ผš -omniroute --port 3000 -``` - -CLI ่‡ชๅŠจไปŽ `~/.omniroute/.env` ๆˆ– `./.env` ๅŠ ่ฝฝ้…็ฝฎใ€‚ - -### VPS ้ƒจ็ฝฒ - -```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 -# ๆˆ–๏ผšpm2 start npm --name omniroute -- start -``` - -### PM2 ้ƒจ็ฝฒ๏ผˆไฝŽๅ†…ๅญ˜๏ผ‰ - -ๅฏนไบŽๅ†…ๅญ˜ๆœ‰้™็š„ๆœๅŠกๅ™จ๏ผŒไฝฟ็”จๅ†…ๅญ˜้™ๅˆถ้€‰้กน๏ผš - -```bash -# ้ป˜่ฎค 512MB ้™ๅˆถ -pm2 start npm --name omniroute -- start - -# ๆˆ–่‡ชๅฎšไน‰ๅ†…ๅญ˜้™ๅˆถ -OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start - -# ๆˆ–ไฝฟ็”จ ecosystem.config.js -pm2 start ecosystem.config.js -``` - -ๅˆ›ๅปบ `ecosystem.config.js`๏ผš - -```javascript -module.exports = { - apps: [ - { - name: "omniroute", - script: "npm", - args: "start", - env: { - NODE_ENV: "production", - OMNIROUTE_MEMORY_MB: "512", - JWT_SECRET: "your-secret", - INITIAL_PASSWORD: "your-password", - }, - node_args: "--max-old-space-size=512", - max_memory_restart: "300M", - }, - ], -}; -``` - -### Docker - -```bash -# ๆž„ๅปบ้•œๅƒ๏ผˆ้ป˜่ฎค = runner-cli๏ผŒ้ข„่ฃ… codex/claude/droid๏ผ‰ -docker build -t omniroute:cli . - -# ไพฟๆบๆจกๅผ๏ผˆๆŽจ่๏ผ‰ -docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli -``` - -ๅ…ณไบŽไธŽไธปๆœบ้›†ๆˆ็š„ CLI ไบŒ่ฟ›ๅˆถๆ–‡ไปถๆจกๅผ๏ผŒ่ฏทๅ‚้˜…ไธปๆ–‡ๆกฃไธญ็š„ Docker ้ƒจๅˆ†ใ€‚ - -### Void Linux (xbps-src) - -Void Linux ็”จๆˆทๅฏไปฅไฝฟ็”จ `xbps-src` ไบคๅ‰็ผ–่ฏ‘ๆก†ๆžถๅŽŸ็”Ÿๆ‰“ๅŒ…ๅ’Œๅฎ‰่ฃ… OmniRouteใ€‚่ฟ™ๅฐ†่‡ชๅŠจๅฎŒๆˆ Node.js standalone ๆž„ๅปบไปฅๅŠๆ‰€้œ€็š„ `better-sqlite3` ๅŽŸ็”Ÿ็ป‘ๅฎšใ€‚ - -
-ๆŸฅ็œ‹ xbps-src ๆจกๆฟ - -```bash -# 'omniroute' ๆจกๆฟๆ–‡ไปถ -pkgname=omniroute -version=3.2.4 -revision=1 -hostmakedepends="nodejs python3 make" -depends="openssl" -short_desc="Universal AI gateway with smart routing for multiple LLM providers" -maintainer="zenobit " -license="MIT" -homepage="https://github.com/diegosouzapw/OmniRoute" -distfiles="https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz" -checksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b -system_accounts="_omniroute" -omniroute_homedir="/var/lib/omniroute" -export NODE_ENV=production -export npm_config_engine_strict=false -export npm_config_loglevel=error -export npm_config_fund=false -export npm_config_audit=false - -do_build() { - # Determine target CPU arch for node-gyp - local _gyp_arch - case "$XBPS_TARGET_MACHINE" in - aarch64*) _gyp_arch=arm64 ;; - armv7*|armv6*) _gyp_arch=arm ;; - i686*) _gyp_arch=ia32 ;; - *) _gyp_arch=x64 ;; - esac - - # 1) Install all deps โ€“ skip scripts - NODE_ENV=development npm ci --ignore-scripts - - # 2) Build the Next.js standalone bundle - npm run build - - # 3) Copy static assets into standalone - cp -r .next/static .next/standalone/.next/static - [ -d public ] && cp -r public .next/standalone/public || true - - # 4) Compile better-sqlite3 native binding - local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js - (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch") - - # 5) Place the compiled binding into the standalone bundle - local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release - mkdir -p "$_bs3_release" - cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/" - - # 6) Remove arch-specific sharp bundles - rm -rf .next/standalone/node_modules/@img - - # 7) Copy pino runtime deps omitted by Next.js static analysis: - for _mod in pino-abstract-transport split2 process-warning; do - cp -r "node_modules/$_mod" .next/standalone/node_modules/ - done -} - -do_check() { - npm run test:unit -} - -do_install() { - vmkdir usr/lib/omniroute/.next - vcopy .next/standalone/. usr/lib/omniroute/.next/standalone - - # Prevent removal of empty Next.js app router dirs by the post-install hook - for _d in \ - .next/standalone/.next/server/app/dashboard \ - .next/standalone/.next/server/app/dashboard/settings \ - .next/standalone/.next/server/app/dashboard/providers; do - touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep" - done - - cat > "${WRKDIR}/omniroute" <<'EOF' -#!/bin/sh -export PORT="${PORT:-20128}" -export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}" -export LOG_TO_FILE="${LOG_TO_FILE:-false}" -mkdir -p "${DATA_DIR}" -exec node /usr/lib/omniroute/.next/standalone/server.js "$@" -EOF - vbin "${WRKDIR}/omniroute" -} - -post_install() { - vlicense LICENSE -} -``` - -
- -### ็Žฏๅขƒๅ˜้‡ - -| ๅ˜้‡ | ้ป˜่ฎคๅ€ผ | ๆ่ฟฐ | -| ------------------------- | ------------------------------------ | ------------------------------------------------------- | -| `JWT_SECRET` | `omniroute-default-secret-change-me` | JWT ็ญพๅๅฏ†้’ฅ๏ผˆ**็”Ÿไบง็Žฏๅขƒๅฟ…้กปๆ›ดๆ”น**๏ผ‰ | -| `INITIAL_PASSWORD` | `123456` | ้ฆ–ๆฌก็™ปๅฝ•ๅฏ†็  | -| `DATA_DIR` | `~/.omniroute` | ๆ•ฐๆฎ็›ฎๅฝ•๏ผˆๆ•ฐๆฎๅบ“ใ€็”จ้‡ใ€ๆ—ฅๅฟ—๏ผ‰ | -| `PORT` | ๆก†ๆžถ้ป˜่ฎคๅ€ผ | ๆœๅŠก็ซฏๅฃ๏ผˆ็คบไพ‹ไธญไธบ `20128`๏ผ‰ | -| `HOSTNAME` | ๆก†ๆžถ้ป˜่ฎคๅ€ผ | ็ป‘ๅฎšไธปๆœบ๏ผˆDocker ้ป˜่ฎค `0.0.0.0`๏ผ‰ | -| `NODE_ENV` | ่ฟ่กŒๆ—ถ้ป˜่ฎคๅ€ผ | ้ƒจ็ฝฒๆ—ถ่ฎพไธบ `production` | -| `BASE_URL` | `http://localhost:20128` | ๆœๅŠก็ซฏๅ†…้ƒจๅŸบ็ก€ URL | -| `CLOUD_URL` | `https://omniroute.dev` | ไบ‘ๅŒๆญฅ็ซฏ็‚นๅŸบ็ก€ URL | -| `API_KEY_SECRET` | `endpoint-proxy-api-key-secret` | ็”Ÿๆˆ API ๅฏ†้’ฅ็š„ HMAC ๅฏ†้’ฅ | -| `REQUIRE_API_KEY` | `false` | ๅฏน `/v1/*` ๅผบๅˆถ่ฆๆฑ‚ Bearer API ๅฏ†้’ฅ | -| `ALLOW_API_KEY_REVEAL` | `false` | ๅ…่ฎธ Api Manager ๆŒ‰้œ€ๅคๅˆถๅฎŒๆ•ด API ๅฏ†้’ฅ | -| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | ๅœจๅ†™ๅ…ฅ/ๅฏผๅ…ฅ/ๆขๅคๅ‰็ฆ็”จ่‡ชๅŠจ SQLite ๅฟซ็…ง๏ผ›ๆ‰‹ๅŠจๅค‡ไปฝไปๅฏ็”จ | -| `ENABLE_REQUEST_LOGS` | `false` | ๅฏ็”จ่ฏทๆฑ‚/ๅ“ๅบ”ๆ—ฅๅฟ— | -| `AUTH_COOKIE_SECURE` | `false` | ๅผบๅˆถไฝฟ็”จ `Secure` ่ฎค่ฏ Cookie๏ผˆHTTPS ๅๅ‘ไปฃ็†ๅŽ๏ผ‰ | -| `CLOUDFLARED_BIN` | ๆœช่ฎพ็ฝฎ | ไฝฟ็”จ็Žฐๆœ‰ `cloudflared` ไบŒ่ฟ›ๅˆถ๏ผŒ่€Œไธๆ˜ฏๆ‰˜็ฎกไธ‹่ฝฝ | -| `OMNIROUTE_MEMORY_MB` | `512` | Node.js ๅ †ๅ†…ๅญ˜้™ๅˆถ๏ผˆMB๏ผ‰ | -| `PROMPT_CACHE_MAX_SIZE` | `50` | ๆœ€ๅคงๆ็คบ่ฏ็ผ“ๅญ˜ๆก็›ฎๆ•ฐ | -| `SEMANTIC_CACHE_MAX_SIZE` | `100` | ๆœ€ๅคง่ฏญไน‰็ผ“ๅญ˜ๆก็›ฎๆ•ฐ | - -ๅฎŒๆ•ด็Žฏๅขƒๅ˜้‡ๅ‚่€ƒ่ฏทๅ‚่ง [README](../README.md)ใ€‚ - ---- - -## ๐Ÿ“Š ๅฏ็”จๆจกๅž‹ - -
-ๆŸฅ็œ‹ๆ‰€ๆœ‰ๅฏ็”จๆจกๅž‹ - -**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` - -**GLM (`glm/`)** โ€” $0.6/1M๏ผš`glm/glm-4.7` - -**MiniMax (`minimax/`)** โ€” $0.2/1M๏ผš`minimax/MiniMax-M2.1` - -**Qoder (`if/`)** โ€” ๅ…่ดน๏ผš`if/kimi-k2-thinking`ใ€`if/qwen3-coder-plus`ใ€`if/deepseek-r1` - -**Qwen (`qw/`)** โ€” ๅ…่ดน๏ผš`qw/qwen3-coder-plus`ใ€`qw/qwen3-coder-flash` - -**Kiro (`kr/`)** โ€” ๅ…่ดน๏ผš`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` - -
- ---- - -## ๐Ÿงฉ ้ซ˜็บงๅŠŸ่ƒฝ - -### ่‡ชๅฎšไน‰ๆจกๅž‹ - -ๆ— ้œ€็ญ‰ๅพ…ๅบ”็”จๆ›ดๆ–ฐๅณๅฏไธบไปปไฝ•ๆไพ›ๅ•†ๆทปๅŠ ไปปๆ„ๆจกๅž‹ ID๏ผš - -```bash -# ้€š่ฟ‡ 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"}' - -# ๅˆ—่กจ๏ผšcurl http://localhost:20128/api/provider-models?provider=openai -# ๅˆ ้™ค๏ผšcurl -X DELETE "http://localhost:20128/api/provider-models?provider=openai&model=gpt-4.5-preview" -``` - -ๆˆ–ไฝฟ็”จ Dashboard๏ผš**Providers โ†’ [ๆไพ›ๅ•†] โ†’ Custom Models**ใ€‚ - -่ฏดๆ˜Ž๏ผš - -- OpenRouter ๅ’Œ OpenAI/Anthropic-compatible ๆไพ›ๅ•†ไป…้€š่ฟ‡ **Available Models** ็ฎก็†ใ€‚ๆ‰‹ๅŠจๆทปๅŠ ใ€ๅฏผๅ…ฅๅ’Œ่‡ชๅŠจๅŒๆญฅ้ƒฝไผšๅ†™ๅ…ฅๅŒไธ€ไปฝ available-model ๅˆ—่กจ๏ผŒๅ› ๆญค่ฟ™ไบ›ๆไพ›ๅ•†ๆฒกๆœ‰ๅ•็‹ฌ็š„ Custom Models ๅŒบๅ—ใ€‚ -- **Custom Models** ๅŒบๅ—้ขๅ‘้‚ฃไบ›ไธๆไพ›ๆ‰˜็ฎก available-model ๅฏผๅ…ฅ็š„ๆไพ›ๅ•†ใ€‚ - -### ไธ“็”จๆไพ›ๅ•†่ทฏ็”ฑ - -็›ดๆŽฅๅฐ†่ฏทๆฑ‚่ทฏ็”ฑๅˆฐ็‰นๅฎšๆไพ›ๅ•†ๅนถ่ฟ›่กŒๆจกๅž‹้ชŒ่ฏ๏ผš - -```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 -``` - -ๅฆ‚ๆžœ็ผบๅฐ‘ๆไพ›ๅ•†ๅ‰็ผ€ๅˆ™่‡ชๅŠจๆทปๅŠ ใ€‚ๆจกๅž‹ไธๅŒน้…ๆ—ถ่ฟ”ๅ›ž `400`ใ€‚ - -### ็ฝ‘็ปœไปฃ็†้…็ฝฎ - -```bash -# ่ฎพ็ฝฎๅ…จๅฑ€ไปฃ็† -curl -X PUT http://localhost:20128/api/settings/proxy \ - -d '{"global": {"type":"http","host":"proxy.example.com","port":"8080"}}' - -# ๆŒ‰ๆไพ›ๅ•†ไปฃ็† -curl -X PUT http://localhost:20128/api/settings/proxy \ - -d '{"providers": {"openai": {"type":"socks5","host":"proxy.example.com","port":"1080"}}}' - -# ๆต‹่ฏ•ไปฃ็† -curl -X POST http://localhost:20128/api/settings/proxy/test \ - -d '{"proxy":{"type":"socks5","host":"proxy.example.com","port":"1080"}}' -``` - -**ไผ˜ๅ…ˆ็บง๏ผš** ๅฏ†้’ฅ็บง โ†’ Combo ็บง โ†’ ๆไพ›ๅ•†็บง โ†’ ๅ…จๅฑ€ โ†’ ็Žฏๅขƒๅ˜้‡ใ€‚ - -### ๆจกๅž‹็›ฎๅฝ• API - -```bash -curl http://localhost:20128/api/models/catalog -``` - -่ฟ”ๅ›žๆŒ‰ๆไพ›ๅ•†ๅˆ†็ป„็š„ๆจกๅž‹ๅŠ็ฑปๅž‹๏ผˆ`chat`ใ€`embedding`ใ€`image`๏ผ‰ใ€‚ - -### ไบ‘ๅŒๆญฅ - -- ่ทจ่ฎพๅค‡ๅŒๆญฅๆไพ›ๅ•†ใ€Combo ๅ’Œ่ฎพ็ฝฎ -- ่‡ชๅŠจๅŽๅฐๅŒๆญฅ๏ผŒๅธฆ่ถ…ๆ—ถ + ๅฟซ้€Ÿๅคฑ่ดฅ -- ็”Ÿไบง็Žฏๅขƒไผ˜ๅ…ˆไฝฟ็”จๆœๅŠก็ซฏ `BASE_URL`/`CLOUD_URL` - -### Cloudflare Quick Tunnel - -- ๅฏๅœจ **Dashboard โ†’ Endpoints** ไธญ็”จไบŽ Docker ๅ’Œๅ…ถไป–่‡ชๆ‰˜็ฎก้ƒจ็ฝฒ -- ไผšๅˆ›ๅปบไธ€ไธชไธดๆ—ถ็š„ `https://*.trycloudflare.com` URL๏ผŒๅนถ่ฝฌๅ‘ๅˆฐๅฝ“ๅ‰ OpenAI ๅ…ผๅฎน็š„ `/v1` ็ซฏ็‚น -- ้ฆ–ๆฌกๅฏ็”จๆ—ถไป…ๅœจ้œ€่ฆๆ—ถๅฎ‰่ฃ… `cloudflared`๏ผ›ไน‹ๅŽ้‡ๅฏไผšๅค็”จๅŒไธ€ไธชๆ‰˜็ฎกไบŒ่ฟ›ๅˆถๆ–‡ไปถ -- Tunnel URL ๆ˜ฏไธดๆ—ถ็š„๏ผŒๆฏๆฌกๅœๆญข/ๅฏๅŠจ้šง้“้ƒฝไผšๅ˜ๅŒ– -- ๅฆ‚ๆžœไฝ ๆ›ดๆƒณไฝฟ็”จ้ข„่ฃ…็š„ `cloudflared`๏ผŒๅฏไปฅ่ฎพ็ฝฎ `CLOUDFLARED_BIN` - -### LLM ็ฝ‘ๅ…ณๆ™บ่ƒฝ๏ผˆ็ฌฌ 9 ้˜ถๆฎต๏ผ‰ - -- **่ฏญไน‰็ผ“ๅญ˜** โ€” ่‡ชๅŠจ็ผ“ๅญ˜้žๆตๅผใ€temperature=0 ็š„ๅ“ๅบ”๏ผˆไฝฟ็”จ `X-OmniRoute-No-Cache: true` ็ป•่ฟ‡๏ผ‰ -- **่ฏทๆฑ‚ๅน‚็ญ‰ๆ€ง** โ€” ้€š่ฟ‡ `Idempotency-Key` ๆˆ– `X-Request-Id` ๅคดๅœจ 5 ็ง’ๅ†…ๅŽป้‡่ฏทๆฑ‚ -- **่ฟ›ๅบฆ่ฟฝ่ธช** โ€” ้€š่ฟ‡ `X-OmniRoute-Progress: true` ๅคด้€‰ๆ‹ฉๆ€งๅฏ็”จ SSE `event: progress` ไบ‹ไปถ - ---- - -### ็ฟป่ฏ‘ๅ™จๅฎž้ชŒๅœบ - -้€š่ฟ‡ **Dashboard โ†’ Translator** ่ฎฟ้—ฎใ€‚่ฐƒ่ฏ•ๅ’Œๅฏ่ง†ๅŒ– OmniRoute ๅฆ‚ไฝ•ๅœจๆไพ›ๅ•†ไน‹้—ด็ฟป่ฏ‘ API ่ฏทๆฑ‚ใ€‚ - -| ๆจกๅผ | ็”จ้€” | -| ---------------- | ------------------------------------------------------------------------------ | -| **Playground** | ้€‰ๆ‹ฉๆบ/็›ฎๆ ‡ๆ ผๅผ๏ผŒ็ฒ˜่ดด่ฏทๆฑ‚๏ผŒๅณๆ—ถๆŸฅ็œ‹็ฟป่ฏ‘่พ“ๅ‡บ | -| **Chat Tester** | ้€š่ฟ‡ไปฃ็†ๅ‘้€ๅฎžๆ—ถ่Šๅคฉๆถˆๆฏ๏ผŒๆฃ€ๆŸฅๅฎŒๆ•ด็š„่ฏทๆฑ‚/ๅ“ๅบ”ๅ‘จๆœŸ | -| **Test Bench** | ๅœจๅคš็งๆ ผๅผ็ป„ๅˆไธญ่ฟ่กŒๆ‰น้‡ๆต‹่ฏ•๏ผŒ้ชŒ่ฏ็ฟป่ฏ‘ๆญฃ็กฎๆ€ง | -| **Live Monitor** | ๅฎžๆ—ถ่ง‚ๅฏŸ่ฏทๆฑ‚ๆต็ปไปฃ็†ๆ—ถ็š„็ฟป่ฏ‘่ฟ‡็จ‹ | - -**ไฝฟ็”จๅœบๆ™ฏ๏ผš** - -- ่ฐƒ่ฏ•็‰นๅฎšๅฎขๆˆท็ซฏ/ๆไพ›ๅ•†็ป„ๅˆๅคฑ่ดฅ็š„ๅŽŸๅ›  -- ้ชŒ่ฏ thinking ๆ ‡็ญพใ€ๅทฅๅ…ท่ฐƒ็”จๅ’Œ็ณป็ปŸๆ็คบ่ฏๆ˜ฏๅฆๆญฃ็กฎ็ฟป่ฏ‘ -- ๆฏ”่พƒ OpenAIใ€Claudeใ€Gemini ๅ’Œ Responses API ๆ ผๅผไน‹้—ด็š„ๅทฎๅผ‚ - ---- - -### ่ทฏ็”ฑ็ญ–็•ฅ - -้€š่ฟ‡ **Dashboard โ†’ Settings โ†’ Routing** ้…็ฝฎใ€‚ - -| ็ญ–็•ฅ | ๆ่ฟฐ | -| ------------------------------ | ---------------------------------------------------------------------------------------- | -| **Fill First** | ๆŒ‰ไผ˜ๅ…ˆ็บง้กบๅบไฝฟ็”จ่ดฆๆˆท โ€” ไธป่ดฆๆˆทๅค„็†ๆ‰€ๆœ‰่ฏทๆฑ‚็›ดๅˆฐไธๅฏ็”จ | -| **Round Robin** | ๅพช็Žฏไฝฟ็”จๆ‰€ๆœ‰่ดฆๆˆท๏ผŒๅฏ้…็ฝฎ็ฒ˜ๆ€ง้™ๅˆถ๏ผˆ้ป˜่ฎค๏ผšๆฏ่ดฆๆˆท 3 ๆฌก่ฐƒ็”จ๏ผ‰ | -| **P2C (Power of Two Choices)** | ้šๆœบ้€‰ๆ‹ฉ 2 ไธช่ดฆๆˆทๅนถ่ทฏ็”ฑๅˆฐๆ›ดๅฅๅบท็š„้‚ฃไธช โ€” ๅฅๅบทๆ„Ÿ็Ÿฅ็š„่ดŸ่ฝฝๅ‡่กก | -| **Random** | ไฝฟ็”จ Fisher-Yates ๆด—็‰Œไธบๆฏไธช่ฏทๆฑ‚้šๆœบ้€‰ๆ‹ฉ่ดฆๆˆท | -| **Least Used** | ่ทฏ็”ฑๅˆฐ `lastUsedAt` ๆ—ถ้—ดๆˆณๆœ€ๆ—ง็š„่ดฆๆˆท๏ผŒๅ‡ๅŒ€ๅˆ†้…ๆต้‡ | -| **Cost Optimized** | ่ทฏ็”ฑๅˆฐไผ˜ๅ…ˆ็บงๅ€ผๆœ€ไฝŽ็š„่ดฆๆˆท๏ผŒไผ˜ๅŒ–ๆˆๆœฌๆœ€ไฝŽ็š„ๆไพ›ๅ•† | - -#### ๅค–้ƒจ็ฒ˜ๆ€งไผš่ฏๅคด - -็”จไบŽๅค–้ƒจไผš่ฏไบฒๅ’Œๆ€ง๏ผˆไพ‹ๅฆ‚๏ผŒๅๅ‘ไปฃ็†ๅŽ็š„ Claude Code/Codex ไปฃ็†๏ผ‰๏ผŒๅ‘้€๏ผš - -```http -X-Session-Id: your-session-key -``` - -OmniRoute ไนŸๆŽฅๅ— `x_session_id` ๅนถๅœจ `X-OmniRoute-Session-Id` ไธญ่ฟ”ๅ›žๆœ‰ๆ•ˆ็š„ไผš่ฏๅฏ†้’ฅใ€‚ - -ๅฆ‚ๆžœไฝฟ็”จ Nginx ๅ‘้€ไธ‹ๅˆ’็บฟๅฝขๅผ็š„ๅคด๏ผŒ้œ€ๅฏ็”จ๏ผš - -```nginx -underscores_in_headers on; -``` - -#### ้€š้…็ฌฆๆจกๅž‹ๅˆซๅ - -ๅˆ›ๅปบ้€š้…็ฌฆๆจกๅผไปฅ้‡ๆ˜ ๅฐ„ๆจกๅž‹ๅ็งฐ๏ผš - -``` -Pattern: claude-sonnet-* โ†’ Target: cc/claude-sonnet-4-5-20250929 -Pattern: gpt-* โ†’ Target: gh/gpt-5.1-codex -``` - -้€š้…็ฌฆๆ”ฏๆŒ `*`๏ผˆไปปๆ„ๅญ—็ฌฆ๏ผ‰ๅ’Œ `?`๏ผˆๅ•ไธชๅญ—็ฌฆ๏ผ‰ใ€‚ - -#### ๅŽๅค‡้“พ - -ๅฎšไน‰้€‚็”จไบŽๆ‰€ๆœ‰่ฏทๆฑ‚็š„ๅ…จๅฑ€ๅŽๅค‡้“พ๏ผš - -``` -Chain: production-fallback - 1. cc/claude-opus-4-6 - 2. gh/gpt-5.1-codex - 3. glm/glm-4.7 -``` - ---- - -### ๅผนๆ€งไธŽ็†”ๆ–ญๅ™จ - -้€š่ฟ‡ **Dashboard โ†’ Settings โ†’ Resilience** ้…็ฝฎใ€‚ - -OmniRoute ๅฎž็Žฐไบ†ๆไพ›ๅ•†็บงๅˆซ็š„ๅผนๆ€งไฟๆŠค๏ผŒๅŒ…ๅซๅ››ไธช็ป„ไปถ๏ผš - -1. **ๆไพ›ๅ•†้…็ฝฎๆ–‡ไปถ** โ€” ๆฏไธชๆไพ›ๅ•†็š„้…็ฝฎ๏ผš - - ๅคฑ่ดฅ้˜ˆๅ€ผ๏ผˆๅผ€ๅฏ็†”ๆ–ญๅ‰็š„ๅคฑ่ดฅๆฌกๆ•ฐ๏ผ‰ - - ๅ†ทๅดๆŒ็ปญๆ—ถ้—ด - - ้€Ÿ็Ž‡้™ๅˆถๆฃ€ๆต‹็ตๆ•ๅบฆ - - ๆŒ‡ๆ•ฐ้€€้ฟๅ‚ๆ•ฐ - -2. **ๅฏ็ผ–่พ‘้€Ÿ็Ž‡้™ๅˆถ** โ€” ๅฏๅœจ Dashboard ไธญ้…็ฝฎ็š„็ณป็ปŸ็บง้ป˜่ฎคๅ€ผ๏ผš - - **ๆฏๅˆ†้’Ÿ่ฏทๆฑ‚ๆ•ฐ (RPM)** โ€” ๆฏไธช่ดฆๆˆทๆฏๅˆ†้’Ÿๆœ€ๅคง่ฏทๆฑ‚ๆ•ฐ - - **่ฏทๆฑ‚ๆœ€ๅฐ้—ด้š”** โ€” ่ฏทๆฑ‚ไน‹้—ด็š„ๆœ€ๅฐ้—ด้š”๏ผˆๆฏซ็ง’๏ผ‰ - - **ๆœ€ๅคงๅนถๅ‘่ฏทๆฑ‚ๆ•ฐ** โ€” ๆฏไธช่ดฆๆˆท็š„ๆœ€ๅคงๅนถๅ‘่ฏทๆฑ‚ๆ•ฐ - - ็‚นๅ‡ป **Edit** ไฟฎๆ”น๏ผŒ็„ถๅŽ **Save** ๆˆ– **Cancel**ใ€‚ๅ€ผ้€š่ฟ‡ๅผนๆ€ง API ๆŒไน…ๅŒ–ใ€‚ - -3. **็†”ๆ–ญๅ™จ** โ€” ๆŒ‰ๆไพ›ๅ•†่ฟฝ่ธชๅคฑ่ดฅๆฌกๆ•ฐ๏ผŒ่พพๅˆฐ้˜ˆๅ€ผๆ—ถ่‡ชๅŠจๅผ€ๅฏ็†”ๆ–ญ๏ผš - - **CLOSED**๏ผˆๅฅๅบท๏ผ‰โ€” ่ฏทๆฑ‚ๆญฃๅธธๆตๅŠจ - - **OPEN** โ€” ้‡ๅคๅคฑ่ดฅๅŽๆไพ›ๅ•†่ขซไธดๆ—ถ้˜ปๆญข - - **HALF_OPEN** โ€” ๆต‹่ฏ•ๆไพ›ๅ•†ๆ˜ฏๅฆๅทฒๆขๅค - -4. **็ญ–็•ฅไธŽ้”ๅฎšๆ ‡่ฏ†็ฌฆ** โ€” ๆ˜พ็คบ็†”ๆ–ญๅ™จ็Šถๆ€ๅ’Œ้”ๅฎšๆ ‡่ฏ†็ฌฆ๏ผŒๆ”ฏๆŒๅผบๅˆถ่งฃ้”ใ€‚ - -5. **้€Ÿ็Ž‡้™ๅˆถ่‡ชๅŠจๆฃ€ๆต‹** โ€” ็›‘ๆŽง `429` ๅ’Œ `Retry-After` ๅคด๏ผŒไธปๅŠจ้ฟๅ…่งฆๅŠๆไพ›ๅ•†้€Ÿ็Ž‡้™ๅˆถใ€‚ - -**ไธ“ไธšๆ็คบ๏ผš** ๅฝ“ๆไพ›ๅ•†ไปŽๆ•…้šœไธญๆขๅคๆ—ถ๏ผŒไฝฟ็”จ **Reset All** ๆŒ‰้’ฎๆธ…้™คๆ‰€ๆœ‰็†”ๆ–ญๅ™จๅ’Œๅ†ทๅด็Šถๆ€ใ€‚ - ---- - -### ๆ•ฐๆฎๅบ“ๅฏผๅ‡บ/ๅฏผๅ…ฅ - -ๅœจ **Dashboard โ†’ Settings โ†’ System & Storage** ไธญ็ฎก็†ๆ•ฐๆฎๅบ“ๅค‡ไปฝใ€‚ - -| ๆ“ไฝœ | ๆ่ฟฐ | -| ------------------------ | ------------------------------------------------------------------------------------------------------ | -| **Export Database** | ๅฐ†ๅฝ“ๅ‰ SQLite ๆ•ฐๆฎๅบ“ไธ‹่ฝฝไธบ `.sqlite` ๆ–‡ไปถ | -| **Export All (.tar.gz)** | ไธ‹่ฝฝๅฎŒๆ•ดๅค‡ไปฝๅฝ’ๆกฃ๏ผŒๅŒ…ๆ‹ฌ๏ผšๆ•ฐๆฎๅบ“ใ€่ฎพ็ฝฎใ€Comboใ€ๆไพ›ๅ•†่ฟžๆŽฅ๏ผˆๆ— ๅ‡ญๆฎ๏ผ‰ใ€API ๅฏ†้’ฅๅ…ƒๆ•ฐๆฎ | -| **Import Database** | ไธŠไผ  `.sqlite` ๆ–‡ไปถๆ›ฟๆขๅฝ“ๅ‰ๆ•ฐๆฎๅบ“ใ€‚ๅฏผๅ…ฅๅ‰ไผš่‡ชๅŠจๅˆ›ๅปบๅค‡ไปฝ | - -```bash -# API๏ผšๅฏผๅ‡บๆ•ฐๆฎๅบ“ -curl -o backup.sqlite http://localhost:20128/api/db-backups/export - -# API๏ผšๅฏผๅ‡บๅ…จ้ƒจ๏ผˆๅฎŒๆ•ดๅฝ’ๆกฃ๏ผ‰ -curl -o backup.tar.gz http://localhost:20128/api/db-backups/exportAll - -# API๏ผšๅฏผๅ…ฅๆ•ฐๆฎๅบ“ -curl -X POST http://localhost:20128/api/db-backups/import \ - -F "file=@backup.sqlite" -``` - -**ๅฏผๅ…ฅ้ชŒ่ฏ๏ผš** ๅฏผๅ…ฅ็š„ๆ–‡ไปถไผš้ชŒ่ฏๅฎŒๆ•ดๆ€ง๏ผˆSQLite pragma ๆฃ€ๆŸฅ๏ผ‰ใ€ๅฟ…้œ€่กจ๏ผˆ`provider_connections`ใ€`provider_nodes`ใ€`combos`ใ€`api_keys`๏ผ‰ๅ’Œๅคงๅฐ๏ผˆๆœ€ๅคง 100MB๏ผ‰ใ€‚ - -**ไฝฟ็”จๅœบๆ™ฏ๏ผš** - -- ๅœจๆœบๅ™จไน‹้—ด่ฟ็งป OmniRoute -- ไธบ็พ้šพๆขๅคๅˆ›ๅปบๅค–้ƒจๅค‡ไปฝ -- ๅœจๅ›ข้˜Ÿๆˆๅ‘˜ไน‹้—ดๅ…ฑไบซ้…็ฝฎ๏ผˆๅฏผๅ‡บๅ…จ้ƒจ โ†’ ๅˆ†ไบซๅฝ’ๆกฃ๏ผ‰ - ---- - -### ่ฎพ็ฝฎไปช่กจ็›˜ - -่ฎพ็ฝฎ้กต้ขๅˆ†ไธบ 6 ไธชๆ ‡็ญพ้กตไพฟไบŽๅฏผ่ˆช๏ผš - -| ๆ ‡็ญพ้กต | ๅ†…ๅฎน | -| -------------- | ---------------------------------------------------------------------------------------------- | -| **General** | ็ณป็ปŸๅญ˜ๅ‚จๅทฅๅ…ทใ€ๅค–่ง‚่ฎพ็ฝฎใ€ไธป้ข˜ๆŽงๅˆถ๏ผŒไปฅๅŠไพง่พนๆ ้กน็›ฎ็š„ๅ•้กนๅฏ่งๆ€ง | -| **Security** | ็™ปๅฝ•/ๅฏ†็ ่ฎพ็ฝฎใ€IP ่ฎฟ้—ฎๆŽงๅˆถใ€`/models` API ่ฎค่ฏใ€ๆไพ›ๅ•†้˜ปๆญข | -| **Routing** | ๅ…จๅฑ€่ทฏ็”ฑ็ญ–็•ฅ๏ผˆ6 ็ง้€‰้กน๏ผ‰ใ€้€š้…็ฌฆๆจกๅž‹ๅˆซๅใ€ๅŽๅค‡้“พใ€Combo ้ป˜่ฎคๅ€ผ | -| **Resilience** | ๆไพ›ๅ•†้…็ฝฎๆ–‡ไปถใ€ๅฏ็ผ–่พ‘้€Ÿ็Ž‡้™ๅˆถใ€็†”ๆ–ญๅ™จ็Šถๆ€ใ€็ญ–็•ฅไธŽ้”ๅฎšๆ ‡่ฏ†็ฌฆ | -| **AI** | Thinking ้ข„็ฎ—้…็ฝฎใ€ๅ…จๅฑ€็ณป็ปŸๆ็คบ่ฏๆณจๅ…ฅใ€ๆ็คบ่ฏ็ผ“ๅญ˜็ปŸ่ฎก | -| **Advanced** | ๅ…จๅฑ€ไปฃ็†้…็ฝฎ๏ผˆHTTP/SOCKS5๏ผ‰ | - ---- - -### ๆˆๆœฌไธŽ้ข„็ฎ—็ฎก็† - -้€š่ฟ‡ **Dashboard โ†’ Costs** ่ฎฟ้—ฎใ€‚ - -| ๆ ‡็ญพ้กต | ็”จ้€” | -| ----------- | -------------------------------------------------------------------------------- | -| **Budget** | ไธบๆฏไธช API ๅฏ†้’ฅ่ฎพ็ฝฎๆถˆ่ดน้™้ข๏ผŒๆ”ฏๆŒๆฏๆ—ฅ/ๆฏๅ‘จ/ๆฏๆœˆ้ข„็ฎ—ๅ’Œๅฎžๆ—ถ่ฟฝ่ธช | -| **Pricing** | ๆŸฅ็œ‹ๅ’Œ็ผ–่พ‘ๆจกๅž‹ๅฎšไปทๆก็›ฎ โ€” ๆฏๆไพ›ๅ•†ๆฏ 1K ่พ“ๅ…ฅ/่พ“ๅ‡บ token ็š„ๆˆๆœฌ | - -```bash -# API๏ผš่ฎพ็ฝฎ้ข„็ฎ— -curl -X POST http://localhost:20128/api/usage/budget \ - -H "Content-Type: application/json" \ - -d '{"keyId": "key-123", "limit": 50.00, "period": "monthly"}' - -# API๏ผš่Žทๅ–ๅฝ“ๅ‰้ข„็ฎ—็Šถๆ€ -curl http://localhost:20128/api/usage/budget -``` - -**ๆˆๆœฌ่ฟฝ่ธช๏ผš** ๆฏไธช่ฏทๆฑ‚้ƒฝไผš่ฎฐๅฝ• token ็”จ้‡ๅนถไฝฟ็”จๅฎšไปท่กจ่ฎก็ฎ—ๆˆๆœฌใ€‚ๅœจ **Dashboard โ†’ Usage** ไธญๆŒ‰ๆไพ›ๅ•†ใ€ๆจกๅž‹ๅ’Œ API ๅฏ†้’ฅๆŸฅ็œ‹ๆ˜Ž็ป†ใ€‚ - ---- - -### ้Ÿณ้ข‘่ฝฌๅฝ• - -OmniRoute ้€š่ฟ‡ OpenAI ๅ…ผๅฎน็ซฏ็‚นๆ”ฏๆŒ้Ÿณ้ข‘่ฝฌๅฝ•๏ผš - -```bash -POST /v1/audio/transcriptions -Authorization: Bearer your-api-key -Content-Type: multipart/form-data - -# ไฝฟ็”จ 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" -``` - -ๅฏ็”จๆไพ›ๅ•†๏ผš**Deepgram** (`deepgram/`)ใ€**AssemblyAI** (`assemblyai/`)ใ€‚ - -ๆ”ฏๆŒ็š„้Ÿณ้ข‘ๆ ผๅผ๏ผš`mp3`ใ€`wav`ใ€`m4a`ใ€`flac`ใ€`ogg`ใ€`webm`ใ€‚ - ---- - -### Combo ๅ‡่กก็ญ–็•ฅ - -ๅœจ **Dashboard โ†’ Combos โ†’ Create/Edit โ†’ Strategy** ไธญ้…็ฝฎๆฏไธช Combo ็š„ๅ‡่กก็ญ–็•ฅใ€‚ - -| ็ญ–็•ฅ | ๆ่ฟฐ | -| ------------------ | ---------------------------------------------------------------- | -| **Round-Robin** | ๆŒ‰้กบๅบ่ฝฎๆตไฝฟ็”จๆจกๅž‹ | -| **Priority** | ๆ€ปๆ˜ฏๅ…ˆๅฐ่ฏ•็ฌฌไธ€ไธชๆจกๅž‹๏ผ›ไป…ๅœจๅ‡บ้”™ๆ—ถไฝฟ็”จๅŽๅค‡ | -| **Random** | ไธบๆฏไธช่ฏทๆฑ‚ไปŽ Combo ไธญ้šๆœบ้€‰ๆ‹ฉไธ€ไธชๆจกๅž‹ | -| **Weighted** | ๆ นๆฎๆฏไธชๆจกๅž‹ๅˆ†้…็š„ๆƒ้‡ๆŒ‰ๆฏ”ไพ‹่ทฏ็”ฑ | -| **Least-Used** | ่ทฏ็”ฑๅˆฐๆœ€่ฟ‘่ฏทๆฑ‚ๆœ€ๅฐ‘็š„ๆจกๅž‹๏ผˆไฝฟ็”จ Combo ๆŒ‡ๆ ‡๏ผ‰ | -| **Cost-Optimized** | ่ทฏ็”ฑๅˆฐๆœ€ไพฟๅฎœ็š„ๅฏ็”จๆจกๅž‹๏ผˆไฝฟ็”จๅฎšไปท่กจ๏ผ‰ | - -ๅ…จๅฑ€ Combo ้ป˜่ฎคๅ€ผๅฏๅœจ **Dashboard โ†’ Settings โ†’ Routing โ†’ Combo Defaults** ไธญ่ฎพ็ฝฎใ€‚ - ---- - -### ๅฅๅบทไปช่กจ็›˜ - -้€š่ฟ‡ **Dashboard โ†’ Health** ่ฎฟ้—ฎใ€‚ๅŒ…ๅซ 6 ๅผ ๅก็‰‡็š„ๅฎžๆ—ถ็ณป็ปŸๅฅๅบทๆฆ‚่งˆ๏ผš - -| ๅก็‰‡ | ๆ˜พ็คบๅ†…ๅฎน | -| --------------------- | ----------------------------------------------------------- | -| **System Status** | ่ฟ่กŒๆ—ถ้—ดใ€็‰ˆๆœฌใ€ๅ†…ๅญ˜็”จ้‡ใ€ๆ•ฐๆฎ็›ฎๅฝ• | -| **Provider Health** | ๆฏไธชๆไพ›ๅ•†็š„็†”ๆ–ญๅ™จ็Šถๆ€๏ผˆClosed/Open/Half-Open๏ผ‰ | -| **Rate Limits** | ๆฏไธช่ดฆๆˆท็š„ๆดป่ทƒ้€Ÿ็Ž‡้™ๅˆถๅ†ทๅดๅŠๅ‰ฉไฝ™ๆ—ถ้—ด | -| **Active Lockouts** | ่ขซ้”ๅฎš็ญ–็•ฅไธดๆ—ถ้˜ปๆญข็š„ๆไพ›ๅ•† | -| **Signature Cache** | ๅŽป้‡็ผ“ๅญ˜็ปŸ่ฎก๏ผˆๆดป่ทƒๅฏ†้’ฅๆ•ฐใ€ๅ‘ฝไธญ็Ž‡๏ผ‰ | -| **Latency Telemetry** | ๆฏไธชๆไพ›ๅ•†็š„ p50/p95/p99 ๅปถ่ฟŸ่šๅˆ | - -**ไธ“ไธšๆ็คบ๏ผš** ๅฅๅบท้กต้ขๆฏ 10 ็ง’่‡ชๅŠจๅˆทๆ–ฐใ€‚ไฝฟ็”จ็†”ๆ–ญๅ™จๅก็‰‡่ฏ†ๅˆซๅ“ชไบ›ๆไพ›ๅ•†ๆญฃๅœจ้‡ๅˆฐ้—ฎ้ข˜ใ€‚ - ---- - -## ๐Ÿ–ฅ๏ธ ๆกŒ้ขๅบ”็”จ๏ผˆElectron๏ผ‰ - -OmniRoute ๆไพ›้€‚็”จไบŽ Windowsใ€macOS ๅ’Œ Linux ็š„ๅŽŸ็”ŸๆกŒ้ขๅบ”็”จใ€‚ - -### ๅฎ‰่ฃ… - -```bash -# ๅœจ electron ็›ฎๅฝ•ไธญ๏ผš -cd electron -npm install - -# ๅผ€ๅ‘ๆจกๅผ๏ผˆ่ฟžๆŽฅๅˆฐ่ฟ่กŒไธญ็š„ Next.js ๅผ€ๅ‘ๆœๅŠกๅ™จ๏ผ‰๏ผš -npm run dev - -# ็”Ÿไบงๆจกๅผ๏ผˆไฝฟ็”จ standalone ๆž„ๅปบ๏ผ‰๏ผš -npm start -``` - -### ๆž„ๅปบๅฎ‰่ฃ…็จ‹ๅบ - -```bash -cd electron -npm run build # ๅฝ“ๅ‰ๅนณๅฐ -npm run build:win # Windows (.exe NSIS) -npm run build:mac # macOS (.dmg universal) -npm run build:linux # Linux (.AppImage) -``` - -่พ“ๅ‡บ็›ฎๅฝ• โ†’ `electron/dist-electron/` - -### ไธป่ฆๅŠŸ่ƒฝ - -| ๅŠŸ่ƒฝ | ๆ่ฟฐ | -| --------------------------- | ---------------------------------------------------- | -| **Server Readiness** | ๆ˜พ็คบ็ช—ๅฃๅ‰่ฝฎ่ฏขๆœๅŠกๅ™จ๏ผˆๆ— ็ฉบ็™ฝๅฑๅน•๏ผ‰ | -| **System Tray** | ๆœ€ๅฐๅŒ–ๅˆฐๆ‰˜็›˜ใ€ๆ›ดๆ”น็ซฏๅฃใ€ไปŽๆ‰˜็›˜่œๅ•้€€ๅ‡บ | -| **Port Management** | ไปŽๆ‰˜็›˜ๆ›ดๆ”นๆœๅŠกๅ™จ็ซฏๅฃ๏ผˆ่‡ชๅŠจ้‡ๅฏๆœๅŠกๅ™จ๏ผ‰ | -| **Content Security Policy** | ้€š่ฟ‡ไผš่ฏๅคดๅฎž็Žฐ้™ๅˆถๆ€ง CSP | -| **Single Instance** | ๅŒไธ€ๆ—ถ้—ดๅช่ƒฝ่ฟ่กŒไธ€ไธชๅบ”็”จๅฎžไพ‹ | -| **Offline Mode** | ๆ‰“ๅŒ…็š„ Next.js ๆœๅŠกๅ™จๅฏ็ฆป็บฟๅทฅไฝœ | - -### ็Žฏๅขƒๅ˜้‡ - -| ๅ˜้‡ | ้ป˜่ฎคๅ€ผ | ๆ่ฟฐ | -| --------------------- | ------- | -------------------------------- | -| `OMNIROUTE_PORT` | `20128` | ๆœๅŠกๅ™จ็ซฏๅฃ | -| `OMNIROUTE_MEMORY_MB` | `512` | Node.js ๅ †ๅ†…ๅญ˜้™ๅˆถ๏ผˆ64โ€“16384 MB๏ผ‰| - -๐Ÿ“– ๅฎŒๆ•ดๆ–‡ๆกฃ๏ผš[`electron/README.md`](../electron/README.md) diff --git a/docs/i18n/zh-CN/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/zh-CN/VM_DEPLOYMENT_GUIDE.md deleted file mode 100644 index 60c31aa116..0000000000 --- a/docs/i18n/zh-CN/VM_DEPLOYMENT_GUIDE.md +++ /dev/null @@ -1,401 +0,0 @@ -# OmniRoute โ€” ไฝฟ็”จ Cloudflare ๅœจ่™šๆ‹ŸๆœบไธŠ้ƒจ็ฝฒๆŒ‡ๅ— - -๐ŸŒ **่ฏญ่จ€:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ท [Portuguรชs (Brasil)](../pt-BR/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ช๐Ÿ‡ธ [Espaรฑol](../es/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ท [Franรงais](../fr/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡น [Italiano](../it/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡บ [ะ ัƒััะบะธะน](../ru/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ณ [ไธญๆ–‡ (็ฎ€ไฝ“)](../zh-CN/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ช [Deutsch](../de/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ณ [เคนเคฟเคจเฅเคฆเฅ€](../in/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡น๐Ÿ‡ญ [เน„เธ—เธข](../th/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡บ๐Ÿ‡ฆ [ะฃะบั€ะฐั—ะฝััŒะบะฐ](../uk-UA/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฆ [ุงู„ุนุฑุจูŠุฉ](../ar/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฏ๐Ÿ‡ต [ๆ—ฅๆœฌ่ชž](../ja/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ป๐Ÿ‡ณ [Tiแบฟng Viแป‡t](../vi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ง๐Ÿ‡ฌ [ะ‘ัŠะปะณะฐั€ัะบะธ](../bg/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฉ๐Ÿ‡ฐ [Dansk](../da/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ซ๐Ÿ‡ฎ [Suomi](../fi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฑ [ืขื‘ืจื™ืช](../he/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ญ๐Ÿ‡บ [Magyar](../hu/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Bahasa Indonesia](../id/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฐ๐Ÿ‡ท [ํ•œ๊ตญ์–ด](../ko/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ฒ๐Ÿ‡พ [Bahasa Melayu](../ms/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ฑ [Nederlands](../nl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ณ๐Ÿ‡ด [Norsk](../no/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡น [Portuguรชs (Portugal)](../pt/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ท๐Ÿ‡ด [Romรขnฤƒ](../ro/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ฑ [Polski](../pl/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ฐ [Slovenฤina](../sk/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ธ๐Ÿ‡ช [Svenska](../sv/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡ต๐Ÿ‡ญ [Filipino](../phi/VM_DEPLOYMENT_GUIDE.md) | ๐Ÿ‡จ๐Ÿ‡ฟ [ฤŒeลกtina](../cs/VM_DEPLOYMENT_GUIDE.md) - -ๅœจ้€š่ฟ‡ Cloudflare ็ฎก็†ๅŸŸๅ็š„ VM (VPS) ไธŠๅฎ‰่ฃ…ๅ’Œ้…็ฝฎ OmniRoute ็š„ๅฎŒๆ•ดๆŒ‡ๅ—ใ€‚ - ---- - -## ๅ…ˆๅ†ณๆกไปถ - -| ้กน็›ฎ | ๆœ€ไฝŽ่ฆๆฑ‚ | ๆŽจ่ | -| ------------ | -------------------- | ------------------ | -| **CPU** | 1 vCPU | 2 vCPU | -| **ๅ†…ๅญ˜** | 1 GB | 2 GB | -| **็ฃ็›˜** | 10 GB SSD | 25 GB SSD | -| **ๆ“ไฝœ็ณป็ปŸ** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS | -| **ๅŸŸๅ** | ๅœจ Cloudflare ไธŠๆณจๅ†Œ | โ€” | -| **Docker** | Docker Engine 24+ | Docker 27+ | - -**ๅทฒๆต‹่ฏ•็š„ๆœๅŠกๅ•†**๏ผšAkamai (Linode)ใ€DigitalOceanใ€Vultrใ€Hetznerใ€AWS Lightsailใ€‚ - ---- - -## 1. ้…็ฝฎ่™šๆ‹Ÿๆœบ - -### 1.1 ๅˆ›ๅปบๅฎžไพ‹ - -ๅœจๆ‚จ้ฆ–้€‰็š„ VPS ๆœๅŠกๅ•†ไธŠ๏ผš - -- ้€‰ๆ‹ฉ Ubuntu 24.04 LTS -- ้€‰ๆ‹ฉๆœ€ไฝŽ้…็ฝฎ๏ผˆ1 vCPU / 1 GB RAM๏ผ‰ -- ่ฎพ็ฝฎๅผบ root ๅฏ†็ ๆˆ–้…็ฝฎ SSH ๅฏ†้’ฅ -- ่ฎฐไธ‹**ๅ…ฌ็ฝ‘ IP**๏ผˆไพ‹ๅฆ‚ `203.0.113.10`๏ผ‰ - -### 1.2 ้€š่ฟ‡ SSH ่ฟžๆŽฅ - -```bash -ssh root@203.0.113.10 -``` - -### 1.3 ๆ›ดๆ–ฐ็ณป็ปŸ - -```bash -apt update && apt upgrade -y -``` - -### 1.4 ๅฎ‰่ฃ… Docker - -```bash -# ๅฎ‰่ฃ…ไพ่ต– -apt install -y ca-certificates curl gnupg - -# ๆทปๅŠ ๅฎ˜ๆ–น 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 ๅฎ‰่ฃ… nginx - -```bash -apt install -y nginx -``` - -### 1.6 ้…็ฝฎ้˜ฒ็ซๅข™ (UFW) - -```bash -ufw default deny incoming -ufw default allow outgoing -ufw allow 22/tcp # SSH -ufw allow 80/tcp # HTTP๏ผˆ้‡ๅฎšๅ‘๏ผ‰ -ufw allow 443/tcp # HTTPS -ufw enable -``` - -> **ๆ็คบ**๏ผšไธบ่Žทๅพ—ๆœ€้ซ˜ๅฎ‰ๅ…จๆ€ง๏ผŒ่ฏทๅฐ†็ซฏๅฃ 80 ๅ’Œ 443 ไป…้™ๅˆถไธบ Cloudflare IPใ€‚ๅ‚่ง[้ซ˜็บงๅฎ‰ๅ…จ](#6-้ซ˜็บงๅฎ‰ๅ…จๆ€ง)้ƒจๅˆ†ใ€‚ - ---- - -## 2. ๅฎ‰่ฃ… OmniRoute - -### 2.1 ๅˆ›ๅปบ้…็ฝฎ็›ฎๅฝ• - -```bash -mkdir -p /opt/omniroute -``` - -### 2.2 ๅˆ›ๅปบ็Žฏๅขƒๅ˜้‡ๆ–‡ไปถ - -```bash -cat > /opt/omniroute/.env << โ€˜EOFโ€™ -# === ๅฎ‰ๅ…จ้…็ฝฎ === -JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY -INITIAL_PASSWORD=YourSecurePassword123! -API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY -STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY -STORAGE_ENCRYPTION_KEY_VERSION=v1 -MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT - -# === ๅบ”็”จ้…็ฝฎ === -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 - -# === ๅŸŸๅ๏ผˆไฟฎๆ”นไธบๆ‚จ็š„ๅŸŸๅ๏ผ‰ === -BASE_URL=https://llms.seudominio.com -NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com - -# === ไบ‘ๅŒๆญฅ๏ผˆๅฏ้€‰๏ผ‰ === -# CLOUD_URL=https://cloud.omniroute.online -# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online -EOF -``` - -> โš ๏ธ **้‡่ฆ**๏ผš็”Ÿๆˆๅ”ฏไธ€็š„ๅฏ†้’ฅ๏ผๅฏนๆฏไธชๅฏ†้’ฅไฝฟ็”จ `openssl rand -hex 32`ใ€‚ - -### 2.3 ๅฏๅŠจๅฎนๅ™จ - -```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 ้ชŒ่ฏ่ฟ่กŒ็Šถๆ€ - -```bash -docker ps | grep omniroute -docker logs omniroute --tail 20 -``` - -ๅบ”ๆ˜พ็คบ๏ผš`[DB] SQLite database ready` ๅ’Œ `listening on port 20128`ใ€‚ - ---- - -## 3. ้…็ฝฎ nginx๏ผˆๅๅ‘ไปฃ็†๏ผ‰ - -### 3.1 ็”Ÿๆˆ SSL ่ฏไนฆ๏ผˆCloudflare Origin๏ผ‰ - -ๅœจ Cloudflare ไปช่กจๆฟไธญ๏ผš - -1. ๅ‰ๅพ€ **SSL/TLS โ†’ Origin Server** -2. ็‚นๅ‡ป **Create Certificate** -3. ไฟๆŒ้ป˜่ฎค่ฎพ็ฝฎ๏ผˆ15 ๅนด๏ผŒ\*.yourdomain.com๏ผ‰ -4. ๅคๅˆถ **Origin Certificate** ๅ’Œ **Private Key** - -```bash -mkdir -p /etc/nginx/ssl - -# ็ฒ˜่ดด่ฏไนฆ -nano /etc/nginx/ssl/origin.crt - -# ็ฒ˜่ดด็ง้’ฅ -nano /etc/nginx/ssl/origin.key - -chmod 600 /etc/nginx/ssl/origin.key -``` - -### 3.2 Nginx ้…็ฝฎ - -```bash -cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ -# ้ป˜่ฎคๆœๅŠกๅ™จ โ€” ้˜ปๆญข้€š่ฟ‡ 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.yourdomain.com; # ไฟฎๆ”นไธบๆ‚จ็š„ๅŸŸๅ - - 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 ๆ”ฏๆŒ - proxy_http_version 1.1; - proxy_set_header Upgrade $http_upgrade; - proxy_set_header Connection โ€œupgradeโ€; - - # SSE (Server-Sent Events) โ€” AI ๆตๅผๅ“ๅบ” - proxy_buffering off; - proxy_cache off; - proxy_read_timeout 300s; - proxy_send_timeout 300s; - } -} - -# HTTP โ†’ HTTPS ้‡ๅฎšๅ‘ -server { - listen 80; - listen [::]:80; - server_name llms.yourdomain.com; - return 301 https://$server_name$request_uri; -} -NGINX -``` - -### 3.3 ๅฏ็”จๅ’Œๆต‹่ฏ• - -```bash -# ๅˆ ้™ค้ป˜่ฎค้…็ฝฎ -rm -f /etc/nginx/sites-enabled/default - -# ๅฏ็”จ OmniRoute -ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute - -# ๆต‹่ฏ•ๅนถ้‡่ฝฝ -nginx -t && systemctl reload nginx -``` - ---- - -## 4. ้…็ฝฎ Cloudflare DNS - -### 4.1 ๆทปๅŠ  DNS ่ฎฐๅฝ• - -ๅœจ Cloudflare ไปช่กจๆฟ โ†’ DNS ไธญ๏ผš - -| ็ฑปๅž‹ | ๅ็งฐ | ๅ†…ๅฎน | ไปฃ็† | -| ---- | ------ | ---------------------- | --------- | -| A | `llms` | `203.0.113.10`๏ผˆVM IP๏ผ‰| โœ… Proxied | - -### 4.2 ้…็ฝฎ SSL - -ๅœจ **SSL/TLS โ†’ Overview** ไธ‹๏ผš - -- ๆจกๅผ๏ผš**Full (Strict)** - -ๅœจ **SSL/TLS โ†’ Edge Certificates** ไธ‹๏ผš - -- Always Use HTTPS๏ผšโœ… ๅผ€ๅฏ -- Minimum TLS Version๏ผšTLS 1.2 -- Automatic HTTPS Rewrites๏ผšโœ… ๅผ€ๅฏ - -### 4.3 ๆต‹่ฏ• - -```bash -curl -sI https://llms.seudominio.com/health -# ๅบ”่ฟ”ๅ›ž HTTP/2 200 -``` - ---- - -## 5. ่ฟ็ปดไธŽ็ปดๆŠค - -### ๅ‡็บงๅˆฐๆ–ฐ็‰ˆๆœฌ - -```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 -``` - -### ๆŸฅ็œ‹ๆ—ฅๅฟ— - -```bash -docker logs -f omniroute # ๅฎžๆ—ถๆต -docker logs omniroute --tail 50 # ๆœ€ๅŽ 50 ่กŒ -``` - -### ๆ‰‹ๅŠจๆ•ฐๆฎๅบ“ๅค‡ไปฝ - -```bash -# ไปŽๅทๅคๅˆถๆ•ฐๆฎๅˆฐไธปๆœบ -docker cp omniroute:/app/data ./backup-$(date +%F) - -# ๆˆ–ๅŽ‹็ผฉๆ•ดไธชๅท -docker run --rm -v omniroute-data:/data -v $(pwd):/backup \ - alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data -``` - -### ไปŽๅค‡ไปฝๆขๅค - -```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. ้ซ˜็บงๅฎ‰ๅ…จๆ€ง - -### ๅฐ† nginx ้™ๅˆถไธบ Cloudflare IP - -```bash -cat > /etc/nginx/cloudflare-ips.conf << โ€˜CFโ€™ -# Cloudflare IPv4 ่Œƒๅ›ด โ€” ๅฎšๆœŸๆ›ดๆ–ฐ -# 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 -``` - -ๅฐ†ไปฅไธ‹ๅ†…ๅฎนๆทปๅŠ ๅˆฐ `nginx.conf` ็š„ `http {}` ๅ—ไธญ๏ผš - -```nginx -include /etc/nginx/cloudflare-ips.conf; -``` - -### ๅฎ‰่ฃ… fail2ban - -```bash -apt install -y fail2ban -systemctl enable fail2ban -systemctl start fail2ban - -# ๆฃ€ๆŸฅ็Šถๆ€ -fail2ban-client status sshd -``` - -### ้˜ปๆญข็›ดๆŽฅ่ฎฟ้—ฎ Docker ็ซฏๅฃ - -```bash -# ้˜ฒๆญขๅค–้ƒจ็›ดๆŽฅ่ฎฟ้—ฎ็ซฏๅฃ 20128 -iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP -iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT - -# ๆŒไน…ๅŒ–่ง„ๅˆ™ -apt install -y iptables-persistent -netfilter-persistent save -``` - ---- - -## 7. ้ƒจ็ฝฒๅˆฐ Cloudflare Workers๏ผˆๅฏ้€‰๏ผ‰ - -้€š่ฟ‡ Cloudflare Workers ่ฟ›่กŒ่ฟœ็จ‹่ฎฟ้—ฎ๏ผˆๆ— ้œ€็›ดๆŽฅๆšด้œฒ VM๏ผ‰๏ผš - -```bash -# ๅœจๆœฌๅœฐไป“ๅบ“ไธญ -cd omnirouteCloud -npm install -npx wrangler login -npx wrangler deploy -``` - -ๅฎŒๆ•ดๆ–‡ๆกฃ่ฏทๅ‚่ง [omnirouteCloud/README.md](../omnirouteCloud/README.md)ใ€‚ - ---- - -## ็ซฏๅฃๆฑ‡ๆ€ป - -| ็ซฏๅฃ | ๆœๅŠก | ่ฎฟ้—ฎ | -| ----- | ----------- | -------------------------- | -| 22 | SSH | ๅ…ฌๅผ€๏ผˆ้…ๅˆ fail2ban๏ผ‰ | -| 80 | nginx HTTP | ้‡ๅฎšๅ‘ โ†’ HTTPS | -| 443 | nginx HTTPS | ้€š่ฟ‡ Cloudflare ไปฃ็† | -| 20128 | OmniRoute | ไป…ๆœฌๅœฐ๏ผˆ้€š่ฟ‡ nginx๏ผ‰ | diff --git a/docs/i18n/zh-CN/docs/A2A-SERVER.md b/docs/i18n/zh-CN/docs/A2A-SERVER.md new file mode 100644 index 0000000000..389ca05dd3 --- /dev/null +++ b/docs/i18n/zh-CN/docs/A2A-SERVER.md @@ -0,0 +1,200 @@ +# OmniRoute A2A Server Documentation (ไธญๆ–‡๏ผˆ็ฎ€ไฝ“๏ผ‰) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/A2A-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/A2A-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/A2A-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/A2A-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/A2A-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/A2A-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/A2A-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/A2A-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/A2A-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/A2A-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/A2A-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/A2A-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/A2A-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/A2A-SERVER.md) + +--- + +> Agent-to-Agent Protocol v0.3 โ€” OmniRoute as an intelligent routing agent + +## Agent Discovery + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +Returns the Agent Card describing OmniRoute's capabilities, skills, and authentication requirements. + +--- + +## Authentication + +All `/a2a` requests require an API key via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server, authentication is bypassed. + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Sends a message to a skill and waits for the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a hello world in Python"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "uuid", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "..." }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.003)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"..."}}} + +: heartbeat 2026-03-03T17:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Available Skills + +| Skill | Description | +| :----------------- | :------------------------------------------------------------------------------------------------------------------------------ | +| `smart-routing` | Routes prompts through OmniRoute's intelligent pipeline. Returns response with routing explanation, cost, and resilience trace. | +| `quota-management` | Answers natural-language queries about provider quotas, suggests free combos, and provides quota rankings. | + +--- + +## Task Lifecycle + +``` +submitted โ†’ working โ†’ completed + โ†’ failed + โ†’ cancelled +``` + +- Tasks expire after 5 minutes (configurable) +- Terminal states: `completed`, `failed`, `cancelled` +- Event log tracks every state transition + +--- + +## Error Codes + +| Code | Meaning | +| :----- | :----------------------------- | +| -32700 | Parse error (invalid JSON) | +| -32600 | Invalid request / Unauthorized | +| -32601 | Method or skill not found | +| -32602 | Invalid params | +| -32603 | Internal error | + +--- + +## Integration Examples + +### Python (requests) + +```python +import requests + +resp = requests.post("http://localhost:20128/a2a", json={ + "jsonrpc": "2.0", "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Hello"}] + } +}, headers={"Authorization": "Bearer YOUR_KEY"}) + +result = resp.json()["result"] +print(result["artifacts"][0]["content"]) +print(result["metadata"]["routing_explanation"]) +``` + +### TypeScript (fetch) + +```typescript +const resp = await fetch("http://localhost:20128/a2a", { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: "Bearer YOUR_KEY", + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "1", + method: "message/send", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Hello" }], + }, + }), +}); +const { result } = await resp.json(); +console.log(result.metadata.routing_explanation); +``` diff --git a/docs/i18n/zh-CN/docs/API_REFERENCE.md b/docs/i18n/zh-CN/docs/API_REFERENCE.md new file mode 100644 index 0000000000..70c90df342 --- /dev/null +++ b/docs/i18n/zh-CN/docs/API_REFERENCE.md @@ -0,0 +1,465 @@ +# API Reference (ไธญๆ–‡๏ผˆ็ฎ€ไฝ“๏ผ‰) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/API_REFERENCE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/API_REFERENCE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/API_REFERENCE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/API_REFERENCE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/API_REFERENCE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/API_REFERENCE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/API_REFERENCE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/API_REFERENCE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/API_REFERENCE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/API_REFERENCE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/API_REFERENCE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/API_REFERENCE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/API_REFERENCE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/API_REFERENCE.md) + +--- + +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 | +| `X-Session-Id` | Request | Sticky session key for external session affinity | +| `x_session_id` | Request | Underscore variant also accepted (direct HTTP) | +| `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 | +| `X-OmniRoute-Session-Id` | Response | Effective session ID used by OmniRoute | + +> Nginx note: if you rely on underscore headers (for example `x_session_id`), enable `underscores_in_headers 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/stats + +# Clear all caches +DELETE /api/cache/stats +``` + +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/PATCH | 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 + provider summary (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`) | +| `/api/cache/stats` | 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 | + +### Tunnels + +| Endpoint | Method | Description | +| -------------------------- | ------ | ----------------------------------------------------------------------- | +| `/api/tunnels/cloudflared` | GET | Read Cloudflare Quick Tunnel install/runtime status for the dashboard | +| `/api/tunnels/cloudflared` | POST | Enable or disable the Cloudflare Quick Tunnel (`action=enable/disable`) | + +### 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`. + +### ACP Agents + +| Endpoint | Method | Description | +| ----------------- | ------ | -------------------------------------------------------- | +| `/api/acp/agents` | GET | List all detected agents (built-in + custom) with status | +| `/api/acp/agents` | POST | Add custom agent or refresh detection cache | +| `/api/acp/agents` | DELETE | Remove a custom agent by `id` query param | + +GET response includes `agents[]` (id, name, binary, version, installed, protocol, isCustom) and `summary` (total, installed, notFound, builtIn, custom). + +### Resilience & Rate Limits + +| Endpoint | Method | Description | +| ----------------------- | --------- | ------------------------------- | +| `/api/resilience` | GET/PATCH | 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` diff --git a/docs/i18n/zh-CN/docs/ARCHITECTURE.md b/docs/i18n/zh-CN/docs/ARCHITECTURE.md new file mode 100644 index 0000000000..efd02a4a6d --- /dev/null +++ b/docs/i18n/zh-CN/docs/ARCHITECTURE.md @@ -0,0 +1,814 @@ +# OmniRoute Architecture (ไธญๆ–‡๏ผˆ็ฎ€ไฝ“๏ผ‰) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/ARCHITECTURE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/ARCHITECTURE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/ARCHITECTURE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/ARCHITECTURE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/ARCHITECTURE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/ARCHITECTURE.md) + +--- + +_Last updated: 2026-03-28_ + +## 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 (`...`) for reasoning models +- Response sanitization for strict OpenAI SDK compatibility +- Role normalization (developerโ†’system, systemโ†’user) for cross-provider compatibility +- Structured output conversion (json_schema โ†’ Gemini responseSchema) +- Local persistence for providers, keys, aliases, combos, settings, pricing +- Usage/cost tracking and request logging +- Optional cloud sync for multi-device/state sync +- IP allowlist/blocklist for API access control +- Thinking budget management (passthrough/auto/custom/adaptive) +- Global system prompt injection +- Session tracking and fingerprinting +- Per-account enhanced rate limiting with provider-specific profiles +- Circuit breaker pattern for provider resilience +- Anti-thundering herd protection with mutex locking +- Signature-based request deduplication cache +- Domain layer: model availability, cost rules, fallback policy, lockout policy +- Domain state persistence (SQLite write-through cache for fallbacks, budgets, lockouts, circuit breakers) +- Policy engine for centralized request evaluation (lockout โ†’ budget โ†’ fallback) +- Request telemetry with p50/p95/p99 latency aggregation +- Correlation ID (X-Request-Id) for end-to-end tracing +- Compliance audit logging with opt-out per API key +- Eval framework for LLM quality assurance +- Resilience UI dashboard with real-time circuit breaker status +- Modular OAuth providers (12 individual modules under `src/lib/oauth/providers/`) + +Primary runtime model: + +- Next.js 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.) + +## Dashboard Surface (Current) + +Main pages under `src/app/(dashboard)/dashboard/`: + +- `/dashboard` โ€” quick start + provider overview +- `/dashboard/endpoint` โ€” endpoint proxy + MCP + A2A + API endpoint tabs +- `/dashboard/providers` โ€” provider connections and credentials +- `/dashboard/combos` โ€” combo strategies, templates, model routing rules +- `/dashboard/costs` โ€” cost aggregation and pricing visibility +- `/dashboard/analytics` โ€” usage analytics and evaluations +- `/dashboard/limits` โ€” quota/rate controls +- `/dashboard/cli-tools` โ€” CLI onboarding, runtime detection, config generation +- `/dashboard/agents` โ€” detected ACP agents + custom agent registration +- `/dashboard/media` โ€” image/video/music playground +- `/dashboard/search-tools` โ€” search provider testing and history +- `/dashboard/health` โ€” uptime, circuit breakers, rate limits +- `/dashboard/logs` โ€” request/proxy/audit/console logs +- `/dashboard/settings` โ€” system settings tabs (general, routing, combo defaults, etc.) +- `/dashboard/api-manager` โ€” API key lifecycle and model permissions + +## 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[(storage.sqlite)] + UDB[(usage tables + log artifacts)] + end + + subgraph Upstreams[Upstream Providers] + P1[OAuth Providers\nClaude/Codex/Gemini/Qwen/Qoder/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/route.ts` (GET) +- Proxy config: `src/app/api/settings/proxy` (GET/PUT/DELETE) + `src/app/api/settings/proxy/test` (POST) +- OAuth: `src/app/api/oauth/*` +- Keys/aliases/combos/pricing: `src/app/api/keys*`, `src/app/api/models/alias`, `src/app/api/combos*`, `src/app/api/pricing` +- Usage: `src/app/api/usage/*` +- Sync/cloud: `src/app/api/sync/*`, `src/app/api/cloud/*` +- CLI tooling helpers: `src/app/api/cli-tools/*` +- IP filter: `src/app/api/settings/ip-filter` (GET/PUT) +- Thinking budget: `src/app/api/settings/thinking-budget` (GET/PUT) +- System prompt: `src/app/api/settings/system-prompt` (GET/PUT) +- Sessions: `src/app/api/sessions` (GET) +- Rate limits: `src/app/api/rate-limits` (GET) +- Resilience: `src/app/api/resilience` (GET/PATCH) โ€” provider profiles, circuit breaker, rate limit state +- Resilience reset: `src/app/api/resilience/reset` (POST) โ€” reset breakers + cooldowns +- Cache stats: `src/app/api/cache/stats` (GET/DELETE) +- Model availability: `src/app/api/models/availability` (GET/POST) +- Telemetry: `src/app/api/telemetry/summary` (GET) +- Budget: `src/app/api/usage/budget` (GET/POST) +- Fallback chains: `src/app/api/fallback/chains` (GET/POST/DELETE) +- Compliance audit: `src/app/api/compliance/audit-log` (GET) +- Evals: `src/app/api/evals` (GET/POST), `src/app/api/evals/[suiteId]` (GET) +- Policies: `src/app/api/policies` (GET/POST) + +## 2) SSE + 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` +- Response sanitization: `open-sse/handlers/responseSanitizer.ts` +- Role normalization: `open-sse/services/roleNormalizer.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`, `qoder.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 (SQLite): + +- Core infra: `src/lib/db/core.ts` (better-sqlite3, migrations, WAL) +- Re-export facade: `src/lib/localDb.ts` (thin compatibility layer for callers) +- file: `${DATA_DIR}/storage.sqlite` (or `$XDG_CONFIG_HOME/omniroute/storage.sqlite` when set, else `~/.omniroute/storage.sqlite`) +- entities (tables + KV namespaces): providerConnections, providerNodes, modelAliases, combos, apiKeys, settings, pricing, **customModels**, **proxyConfig**, **ipFilter**, **thinkingBudget**, **systemPrompt** + +Usage persistence: + +- facade: `src/lib/usageDb.ts` (decomposed modules in `src/lib/usage/*`) +- SQLite tables in `storage.sqlite`: `usage_history`, `call_logs`, `proxy_logs` +- optional file artifacts remain for compatibility/debug (`${DATA_DIR}/log.txt`, `${DATA_DIR}/call_logs/`, `/logs/...`) +- legacy JSON files are migrated to SQLite by startup migrations when present + +Domain State DB (SQLite): + +- `src/lib/db/domainState.ts` โ€” CRUD operations 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`, `src/shared/services/modelSyncScheduler.ts` +- Periodic task: `src/shared/services/cloudSyncScheduler.ts` +- Periodic task: `src/shared/services/modelSyncScheduler.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. Combo routing adds one extra guard: provider-scoped 400s such as upstream content-block and role-validation failures are treated as model-local failures so later combo targets can still run. + +## 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: + +- primary runtime DB: `${DATA_DIR}/storage.sqlite` +- request log lines: `${DATA_DIR}/log.txt` (compat/debug artifact) +- structured call payload archives: `${DATA_DIR}/call_logs/` +- optional translator/request debug sessions: `/logs/...` + +## Deployment Topology + +```mermaid +flowchart LR + 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[(storage.sqlite)] + UsageDB[(usage tables + log artifacts)] + end + + subgraph External[External Services] + Providers[AI Providers] + SyncCloud[Cloud Sync Service] + end + + CLI --> Next + Browser --> Next + Next --> Core + Next --> MainDB + Core --> MainDB + Core --> UsageDB + Core --> Providers + Next --> SyncCloud +``` + +## Module Mapping (Decision-Critical) + +### Route and API Modules + +- `src/app/api/v1/*`, `src/app/api/v1beta/*`: compatibility APIs +- `src/app/api/v1/providers/[provider]/*`: dedicated per-provider routes (chat, embeddings, images) +- `src/app/api/providers*`: provider CRUD, validation, testing +- `src/app/api/provider-nodes*`: custom compatible node management +- `src/app/api/provider-models`: custom model management (CRUD) +- `src/app/api/models/route.ts`: model catalog API (aliases + custom models) +- `src/app/api/oauth/*`: OAuth/device-code flows +- `src/app/api/keys*`: local API key lifecycle +- `src/app/api/models/alias`: alias management +- `src/app/api/combos*`: fallback combo management +- `src/app/api/pricing`: pricing overrides for cost calculation +- `src/app/api/settings/proxy`: proxy configuration (GET/PUT/DELETE) +- `src/app/api/settings/proxy/test`: outbound proxy connectivity test (POST) +- `src/app/api/usage/*`: usage and logs APIs +- `src/app/api/sync/*` + `src/app/api/cloud/*`: cloud sync and cloud-facing helpers +- `src/app/api/cli-tools/*`: local CLI config writers/checkers +- `src/app/api/settings/ip-filter`: IP allowlist/blocklist (GET/PUT) +- `src/app/api/settings/thinking-budget`: thinking token budget config (GET/PUT) +- `src/app/api/settings/system-prompt`: global system prompt (GET/PUT) +- `src/app/api/sessions`: active session listing (GET) +- `src/app/api/rate-limits`: per-account rate limit status (GET) + +### Routing and Execution Core + +- `src/sse/handlers/chat.ts`: request parse, combo handling, account selection loop +- `open-sse/handlers/chatCore.ts`: translation, executor dispatch, retry/refresh handling, stream setup +- `open-sse/executors/*`: provider-specific network and format behavior + +### Translation Registry and Format Converters + +- `open-sse/translator/index.ts`: translator registry and orchestration +- Request translators: `open-sse/translator/request/*` +- Response translators: `open-sse/translator/response/*` +- Format constants: `open-sse/translator/formats.ts` + +### Persistence + +- `src/lib/db/*`: persistent config/state and domain persistence on SQLite +- `src/lib/localDb.ts`: compatibility re-export for DB modules +- `src/lib/usageDb.ts`: usage history/call logs facade on top of SQLite tables + +## Provider Executor Coverage (Strategy Pattern) + +Each provider has a specialized executor extending `BaseExecutor` (in `open-sse/executors/base.ts`), which provides URL building, header construction, retry with exponential backoff, credential refresh hooks, and the `execute()` orchestration method. + +| Executor | Provider(s) | Special Handling | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| `DefaultExecutor` | OpenAI, Claude, Gemini, Qwen, Qoder, 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 | +| Qoder | openai | OAuth (Basic) | โœ… | โœ… | โœ… | โš ๏ธ Per request | +| OpenRouter | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| GLM/Kimi/MiniMax | claude | API Key | โœ… | โœ… | โŒ | โŒ | +| DeepSeek | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Groq | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| xAI (Grok) | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Mistral | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Perplexity | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Together AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Fireworks AI | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Cerebras | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| Cohere | openai | API Key | โœ… | โœ… | โŒ | โŒ | +| NVIDIA NIM | openai | API Key | โœ… | โœ… | โŒ | โŒ | + +## Format Translation Coverage + +Detected source formats include: + +- `openai` +- `openai-responses` +- `claude` +- `gemini` + +Target formats include: + +- OpenAI chat/Responses +- Claude +- Gemini/Gemini-CLI/Antigravity envelope +- Kiro +- Cursor + +Translations use **OpenAI as the hub format** โ€” all conversions go through OpenAI as intermediate: + +``` +Source Format โ†’ OpenAI (hub) โ†’ Target Format +``` + +Translations are selected dynamically based on source payload shape and provider target format. + +Additional processing layers in the translation pipeline: + +- **Response sanitization** โ€” Strips non-standard fields from OpenAI-format responses (both streaming and non-streaming) to ensure strict SDK compliance +- **Role normalization** โ€” Converts `developer` โ†’ `system` for non-OpenAI targets; merges `system` โ†’ `user` for models that reject the system role (GLM, ERNIE) +- **Think tag extraction** โ€” Parses `...` blocks from content into `reasoning_content` field +- **Structured output** โ€” Converts OpenAI `response_format.json_schema` to Gemini's `responseMimeType` + `responseSchema` + +## Supported API Endpoints + +| 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` | Provider Models | Provider model metadata backing custom and managed available models | + +## 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 `/logs//` 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 + +- SQLite schema migrations and auto-upgrade hooks at startup +- legacy JSON โ†’ SQLite migration compatibility path + +## Observability and Operational Signals + +Runtime visibility sources: + +- console logs from `src/sse/utils/logger.ts` +- per-request usage aggregates in SQLite (`usage_history`, `call_logs`, `proxy_logs`) +- four-stage detailed payload captures in SQLite (`request_detail_logs`) when `settings.detailed_logs_enabled=true` +- textual request status log in `log.txt` (optional/compat) +- optional deep request/translation logs under `logs/` when `ENABLE_REQUEST_LOGS=true` +- dashboard usage endpoints (`/api/usage/*`) for UI consumption + +Detailed request payload capture stores up to four JSON payload stages per routed call: + +- raw request received from the client +- translated request actually sent upstream +- provider response reconstructed as JSON; streamed responses are compacted to the final summary plus stream metadata +- final client response returned by OmniRoute; streamed responses are stored in the same compact summary form + +## Security-Sensitive Boundaries + +- JWT secret (`JWT_SECRET`) secures dashboard session cookie verification/signing +- Initial password bootstrap (`INITIAL_PASSWORD`) should be explicitly configured for first-run provisioning +- API key HMAC secret (`API_KEY_SECRET`) secures generated local API key format +- Provider secrets (API keys/tokens) are persisted in local DB and should be protected at filesystem level +- Cloud sync endpoints rely on API key auth + machine id semantics + +## Environment and Runtime Matrix + +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` share the same base directory policy (`DATA_DIR` -> `XDG_CONFIG_HOME/omniroute` -> `~/.omniroute`) with legacy file migration. +2. `/api/v1/route.ts` delegates to the same unified catalog builder used by `/api/v1/models` (`src/app/api/v1/models/catalog.ts`) to avoid semantic drift. +3. Request logger writes full headers/body when enabled; treat log directory as sensitive. +4. Cloud behavior depends on correct `NEXT_PUBLIC_BASE_URL` and cloud endpoint reachability. +5. The `open-sse/` directory is published as the `@omniroute/open-sse` **npm workspace package**. Source code imports it via `@omniroute/open-sse/...` (resolved by Next.js `transpilePackages`). File paths in this document still use the directory name `open-sse/` for consistency. +6. Charts in the dashboard use **Recharts** (SVG-based) for accessible, interactive analytics visualizations (model usage bar charts, provider breakdown tables with success rates). +7. E2E tests use **Playwright** (`tests/e2e/`), run via `npm run test:e2e`. Unit tests use **Node.js test runner** (`tests/unit/`), run via `npm run test:unit`. Source code under `src/` is **TypeScript** (`.ts`/`.tsx`); the `open-sse/` workspace remains JavaScript (`.js`). +8. Settings page is organized into 5 tabs: Security, Routing (6 global strategies: fill-first, round-robin, p2c, random, least-used, cost-optimized), Resilience (editable rate limits, circuit breaker, policies), AI (thinking budget, system prompt, prompt cache), Advanced (proxy). + +## Operational Verification Checklist + +- Build from source: `npm run build` +- Build Docker image: `docker build -t omniroute .` +- Start service and verify: +- `GET /api/settings` +- `GET /api/v1/models` +- CLI target base URL should be `http://:20128/v1` when `PORT=20128` diff --git a/docs/i18n/zh-CN/docs/AUTO-COMBO.md b/docs/i18n/zh-CN/docs/AUTO-COMBO.md new file mode 100644 index 0000000000..e5ee28f441 --- /dev/null +++ b/docs/i18n/zh-CN/docs/AUTO-COMBO.md @@ -0,0 +1,67 @@ +# OmniRoute Auto-Combo Engine (ไธญๆ–‡๏ผˆ็ฎ€ไฝ“๏ผ‰) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/AUTO-COMBO.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/AUTO-COMBO.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/AUTO-COMBO.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/AUTO-COMBO.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/AUTO-COMBO.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/AUTO-COMBO.md) + +--- + +> Self-managing model chains with adaptive scoring + +## How It Works + +The Auto-Combo Engine dynamically selects the best provider/model for each request using a **6-factor scoring function**: + +| Factor | Weight | Description | +| :--------- | :----- | :---------------------------------------------- | +| Quota | 0.20 | Remaining capacity [0..1] | +| Health | 0.25 | Circuit breaker: CLOSED=1.0, HALF=0.5, OPEN=0.0 | +| CostInv | 0.20 | Inverse cost (cheaper = higher score) | +| LatencyInv | 0.15 | Inverse p95 latency (faster = higher) | +| TaskFit | 0.10 | Model ร— task type fitness score | +| Stability | 0.10 | Low variance in latency/errors | + +## Mode Packs + +| Pack | Focus | Key Weight | +| :---------------------- | :----------- | :--------------- | +| ๐Ÿš€ **Ship Fast** | Speed | latencyInv: 0.35 | +| ๐Ÿ’ฐ **Cost Saver** | Economy | costInv: 0.40 | +| ๐ŸŽฏ **Quality First** | Best model | taskFit: 0.40 | +| ๐Ÿ“ก **Offline Friendly** | Availability | quota: 0.40 | + +## Self-Healing + +- **Temporary exclusion**: Score < 0.2 โ†’ excluded for 5 min (progressive backoff, max 30 min) +- **Circuit breaker awareness**: OPEN โ†’ auto-excluded; HALF_OPEN โ†’ probe requests +- **Incident mode**: >50% OPEN โ†’ disable exploration, maximize stability +- **Cooldown recovery**: After exclusion, first request is a "probe" with reduced timeout + +## Bandit Exploration + +5% of requests (configurable) are routed to random providers for exploration. Disabled in incident mode. + +## API + +```bash +# Create auto-combo +curl -X POST http://localhost:20128/api/combos/auto \ + -H "Content-Type: application/json" \ + -d '{"id":"my-auto","name":"Auto Coder","candidatePool":["anthropic","google","openai"],"modePack":"ship-fast"}' + +# List auto-combos +curl http://localhost:20128/api/combos/auto +``` + +## Task Fitness + +30+ models scored across 6 task types (`coding`, `review`, `planning`, `analysis`, `debugging`, `documentation`). Supports wildcard patterns (e.g., `*-coder` โ†’ high coding score). + +## Files + +| File | Purpose | +| :------------------------------------------- | :------------------------------------ | +| `open-sse/services/autoCombo/scoring.ts` | Scoring function & pool normalization | +| `open-sse/services/autoCombo/taskFitness.ts` | Model ร— task fitness lookup | +| `open-sse/services/autoCombo/engine.ts` | Selection logic, bandit, budget cap | +| `open-sse/services/autoCombo/selfHealing.ts` | Exclusion, probes, incident mode | +| `open-sse/services/autoCombo/modePacks.ts` | 4 weight profiles | +| `src/app/api/combos/auto/route.ts` | REST API | diff --git a/docs/i18n/zh-CN/docs/CLI-TOOLS.md b/docs/i18n/zh-CN/docs/CLI-TOOLS.md new file mode 100644 index 0000000000..9d7055d0b4 --- /dev/null +++ b/docs/i18n/zh-CN/docs/CLI-TOOLS.md @@ -0,0 +1,348 @@ +# CLI Tools Setup Guide โ€” OmniRoute (ไธญๆ–‡๏ผˆ็ฎ€ไฝ“๏ผ‰) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CLI-TOOLS.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CLI-TOOLS.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CLI-TOOLS.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CLI-TOOLS.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CLI-TOOLS.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CLI-TOOLS.md) + +--- + +This guide explains how to install and configure all supported AI coding CLI tools +to use **OmniRoute** as the unified backend, giving you centralized key management, +cost tracking, model switching, and request logging across every tool. + +--- + +## How It Works + +``` +Claude / Codex / OpenCode / Cline / KiloCode / Continue / Kiro / Cursor / Copilot + โ”‚ + โ–ผ (all point to OmniRoute) + http://YOUR_SERVER:20128/v1 + โ”‚ + โ–ผ (OmniRoute routes to the right provider) + Anthropic / OpenAI / Gemini / DeepSeek / Groq / Mistral / ... +``` + +**Benefits:** + +- One API key to manage all tools +- Cost tracking across all CLIs in the dashboard +- Model switching without reconfiguring every tool +- Works locally and on remote servers (VPS) + +--- + +## Supported Tools (Dashboard Source of Truth) + +The dashboard cards in `/dashboard/cli-tools` are generated from `src/shared/constants/cliTools.ts`. +Current list (v3.0.0-rc.16): + +| Tool | ID | Command | Setup Mode | Install Method | +| ------------------ | ------------- | ---------- | ---------- | -------------- | +| **Claude Code** | `claude` | `claude` | env | npm | +| **OpenAI Codex** | `codex` | `codex` | custom | npm | +| **Factory Droid** | `droid` | `droid` | custom | bundled/CLI | +| **OpenClaw** | `openclaw` | `openclaw` | custom | bundled/CLI | +| **Cursor** | `cursor` | app | guide | desktop app | +| **Cline** | `cline` | `cline` | custom | npm | +| **Kilo Code** | `kilo` | `kilocode` | custom | npm | +| **Continue** | `continue` | extension | guide | VS Code | +| **Antigravity** | `antigravity` | internal | mitm | OmniRoute | +| **GitHub Copilot** | `copilot` | extension | custom | VS Code | +| **OpenCode** | `opencode` | `opencode` | guide | npm | +| **Kiro AI** | `kiro` | app/cli | mitm | desktop/CLI | + +### CLI fingerprint sync (Agents + Settings) + +`/dashboard/agents` and `Settings > CLI Fingerprint` use `src/shared/constants/cliCompatProviders.ts`. +This keeps provider IDs aligned with CLI cards and legacy IDs. + +| CLI ID | Fingerprint Provider ID | +| ---------------------------------------------------------------------------------------------------- | ----------------------- | +| `kilo` | `kilocode` | +| `copilot` | `github` | +| `claude` / `codex` / `antigravity` / `kiro` / `cursor` / `cline` / `opencode` / `droid` / `openclaw` | same ID | + +Legacy IDs still accepted for compatibility: `copilot`, `kimi-coding`, `qwen`. + +--- + +## Step 1 โ€” Get an OmniRoute API Key + +1. Open the OmniRoute dashboard โ†’ **API Manager** (`/dashboard/api-manager`) +2. Click **Create API Key** +3. Give it a name (e.g. `cli-tools`) and select all permissions +4. Copy the key โ€” you'll need it for every CLI below + +> Your key looks like: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` + +--- + +## Step 2 โ€” Install CLI Tools + +All npm-based tools require Node.js 18+: + +```bash +# Claude Code (Anthropic) +npm install -g @anthropic-ai/claude-code + +# OpenAI Codex +npm install -g @openai/codex + +# OpenCode +npm install -g opencode-ai + +# Cline +npm install -g cline + +# KiloCode +npm install -g kilocode + +# Kiro CLI (Amazon โ€” requires curl + unzip) +apt-get install -y unzip # on Debian/Ubuntu +curl -fsSL https://cli.kiro.dev/install | bash +export PATH="$HOME/.local/bin:$PATH" # add to ~/.bashrc +``` + +**Verify:** + +```bash +claude --version # 2.x.x +codex --version # 0.x.x +opencode --version # x.x.x +cline --version # 2.x.x +kilocode --version # x.x.x (or: kilo --version) +kiro-cli --version # 1.x.x +``` + +--- + +## Step 3 โ€” Set Global Environment Variables + +Add to `~/.bashrc` (or `~/.zshrc`), then run `source ~/.bashrc`: + +```bash +# OmniRoute Universal Endpoint +export OPENAI_BASE_URL="http://localhost:20128/v1" +export OPENAI_API_KEY="sk-your-omniroute-key" +export ANTHROPIC_BASE_URL="http://localhost:20128/v1" +export ANTHROPIC_API_KEY="sk-your-omniroute-key" +export GEMINI_BASE_URL="http://localhost:20128/v1" +export GEMINI_API_KEY="sk-your-omniroute-key" +``` + +> For a **remote server** replace `localhost:20128` with the server IP or domain, +> e.g. `http://192.168.0.15:20128`. + +--- + +## Step 4 โ€” Configure Each Tool + +### Claude Code + +```bash +# Via CLI: +claude config set --global api-base-url http://localhost:20128/v1 + +# Or create ~/.claude/settings.json: +mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF +{ + "apiBaseUrl": "http://localhost:20128/v1", + "apiKey": "sk-your-omniroute-key" +} +EOF +``` + +**Test:** `claude "say hello"` + +--- + +### OpenAI Codex + +```bash +mkdir -p ~/.codex && cat > ~/.codex/config.yaml << EOF +model: auto +apiKey: sk-your-omniroute-key +apiBaseUrl: http://localhost:20128/v1 +EOF +``` + +**Test:** `codex "what is 2+2?"` + +--- + +### OpenCode + +```bash +mkdir -p ~/.config/opencode && cat > ~/.config/opencode/config.toml << EOF +[provider.openai] +base_url = "http://localhost:20128/v1" +api_key = "sk-your-omniroute-key" +EOF +``` + +**Test:** `opencode` + +--- + +### Cline (CLI or VS Code) + +**CLI mode:** + +```bash +mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF +{ + "apiProvider": "openai", + "openAiBaseUrl": "http://localhost:20128/v1", + "openAiApiKey": "sk-your-omniroute-key" +} +EOF +``` + +**VS Code mode:** +Cline extension settings โ†’ API Provider: `OpenAI Compatible` โ†’ Base URL: `http://localhost:20128/v1` + +Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ Cline โ†’ Apply Config**. + +--- + +### KiloCode (CLI or VS Code) + +**CLI mode:** + +```bash +kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key +``` + +**VS Code settings:** + +```json +{ + "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", + "kilo-code.apiKey": "sk-your-omniroute-key" +} +``` + +Or use the OmniRoute dashboard โ†’ **CLI Tools โ†’ KiloCode โ†’ Apply Config**. + +--- + +### Continue (VS Code Extension) + +Edit `~/.continue/config.yaml`: + +```yaml +models: + - name: OmniRoute + provider: openai + model: auto + apiBase: http://localhost:20128/v1 + apiKey: sk-your-omniroute-key + default: true +``` + +Restart VS Code after editing. + +--- + +### Kiro CLI (Amazon) + +```bash +# Login to your AWS/Kiro account: +kiro-cli login + +# The CLI uses its own auth โ€” OmniRoute is not needed as backend for Kiro CLI itself. +# Use kiro-cli alongside OmniRoute for other tools. +kiro-cli status +``` + +--- + +### Cursor (Desktop App) + +> **Note:** Cursor routes requests through its cloud. For OmniRoute integration, +> enable **Cloud Endpoint** in OmniRoute Settings and use your public domain URL. + +Via GUI: **Settings โ†’ Models โ†’ OpenAI API Key** + +- Base URL: `https://your-domain.com/v1` +- API Key: your OmniRoute key + +--- + +## Dashboard Auto-Configuration + +The OmniRoute dashboard automates configuration for most tools: + +1. Go to `http://localhost:20128/dashboard/cli-tools` +2. Expand any tool card +3. Select your API key from the dropdown +4. Click **Apply Config** (if tool is detected as installed) +5. Or copy the generated config snippet manually + +--- + +## Built-in Agents: Droid & OpenClaw + +**Droid** and **OpenClaw** are AI agents built directly into OmniRoute โ€” no installation needed. +They run as internal routes and use OmniRoute's model routing automatically. + +- Access: `http://localhost:20128/dashboard/agents` +- Configure: same combos and providers as all other tools +- No API key or CLI install required + +--- + +## Available API Endpoints + +| Endpoint | Description | Use For | +| -------------------------- | ----------------------------- | --------------------------- | +| `/v1/chat/completions` | Standard chat (all providers) | All modern tools | +| `/v1/responses` | Responses API (OpenAI format) | Codex, agentic workflows | +| `/v1/completions` | Legacy text completions | Older tools using `prompt:` | +| `/v1/embeddings` | Text embeddings | RAG, search | +| `/v1/images/generations` | Image generation | DALL-E, Flux, etc. | +| `/v1/audio/speech` | Text-to-speech | ElevenLabs, OpenAI TTS | +| `/v1/audio/transcriptions` | Speech-to-text | Deepgram, AssemblyAI | + +--- + +## ๆ•…้šœๆŽ’้™ค + +| Error | Cause | Fix | +| ------------------------- | ----------------------- | ------------------------------------------ | +| `Connection refused` | OmniRoute not running | `pm2 start omniroute` | +| `401 Unauthorized` | Wrong API key | Check in `/dashboard/api-manager` | +| `No combo configured` | No active routing combo | Set up in `/dashboard/combos` | +| `invalid model` | Model not in catalog | Use `auto` or check `/dashboard/providers` | +| CLI shows "not installed" | Binary not in PATH | Check `which ` | +| `kiro-cli: not found` | Not in PATH | `export PATH="$HOME/.local/bin:$PATH"` | + +--- + +## Quick Setup Script (One Command) + +```bash +# Install all CLIs and configure for OmniRoute (replace with your key and server URL) +OMNIROUTE_URL="http://localhost:20128/v1" +OMNIROUTE_KEY="sk-your-omniroute-key" + +npm install -g @anthropic-ai/claude-code @openai/codex opencode-ai cline kilocode + +# Kiro CLI +apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash + +# Write configs +mkdir -p ~/.claude ~/.codex ~/.config/opencode ~/.continue + +cat > ~/.claude/settings.json <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}" +cat > ~/.codex/config.yaml <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL" +cat >> ~/.bashrc << EOF +export OPENAI_BASE_URL="$OMNIROUTE_URL" +export OPENAI_API_KEY="$OMNIROUTE_KEY" +export ANTHROPIC_BASE_URL="$OMNIROUTE_URL" +export ANTHROPIC_API_KEY="$OMNIROUTE_KEY" +EOF + +source ~/.bashrc +echo "โœ… All CLIs installed and configured for OmniRoute" +``` diff --git a/docs/i18n/zh-CN/docs/CODEBASE_DOCUMENTATION.md b/docs/i18n/zh-CN/docs/CODEBASE_DOCUMENTATION.md new file mode 100644 index 0000000000..c61243bb80 --- /dev/null +++ b/docs/i18n/zh-CN/docs/CODEBASE_DOCUMENTATION.md @@ -0,0 +1,591 @@ +# omniroute โ€” Codebase Documentation (ไธญๆ–‡๏ผˆ็ฎ€ไฝ“๏ผ‰) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/CODEBASE_DOCUMENTATION.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/CODEBASE_DOCUMENTATION.md) + +--- + +> 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
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, Qoder, 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. + +#### ๆžถๆž„ + +```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 | +| Qoder | 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"] +``` diff --git a/docs/i18n/zh-CN/docs/COVERAGE_PLAN.md b/docs/i18n/zh-CN/docs/COVERAGE_PLAN.md new file mode 100644 index 0000000000..75dda26531 --- /dev/null +++ b/docs/i18n/zh-CN/docs/COVERAGE_PLAN.md @@ -0,0 +1,170 @@ +# Test Coverage Plan (ไธญๆ–‡๏ผˆ็ฎ€ไฝ“๏ผ‰) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/COVERAGE_PLAN.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/COVERAGE_PLAN.md) + +--- + +Last updated: 2026-03-28 + +## Baseline + +There are multiple coverage numbers depending on how the report is computed. For planning, only one of them is useful. + +| Metric | Scope | Statements / Lines | Branches | Functions | Notes | +| -------------------- | ----------------------------------------------------- | -----------------: | -------: | --------: | --------------------------------------------------- | +| Legacy | Old `npm run test:coverage` | 79.42% | 75.15% | 67.94% | Inflated: counts test files and excludes `open-sse` | +| Diagnostic | Source-only, excluding tests and excluding `open-sse` | 68.16% | 63.55% | 64.06% | Useful only to isolate `src/**` | +| Recommended baseline | Source-only, excluding tests and including `open-sse` | 56.95% | 66.05% | 57.80% | This is the project-wide baseline to improve | + +The recommended baseline is the number to optimize against. + +## Rules + +- Coverage targets apply to source files, not to `tests/**`. +- `open-sse/**` is part of the product and must remain in scope. +- New code should not reduce coverage in touched areas. +- Prefer testing behavior and branch outcomes over implementation details. +- Prefer temp SQLite databases and small fixtures over broad mocks for `src/lib/db/**`. + +## Current command set + +- `npm run test:coverage` + - Main source coverage gate for the unit test suite + - Generates `text-summary`, `html`, `json-summary`, and `lcov` +- `npm run coverage:report` + - Detailed file-by-file report from the latest run +- `npm run test:coverage:legacy` + - Historical comparison only + +## Milestones + +| Phase | Target | Focus | +| ------- | ---------------------: | ------------------------------------------------- | +| Phase 1 | 60% statements / lines | Quick wins and low-risk utility coverage | +| Phase 2 | 65% statements / lines | DB and route foundations | +| Phase 3 | 70% statements / lines | Provider validation and usage analytics | +| Phase 4 | 75% statements / lines | `open-sse` translators and helpers | +| Phase 5 | 80% statements / lines | `open-sse` handlers and executor branches | +| Phase 6 | 85% statements / lines | Harder edge cases, branch debt, regression suites | +| Phase 7 | 90% statements / lines | Final sweep, gap closure, strict ratchet | + +Branches and functions should ratchet upward with each phase, but the primary hard target is statements / lines. + +## Priority hotspots + +These files or areas offer the best return for the next phases: + +1. `open-sse/handlers` + - `chatCore.ts` at 7.57% + - Overall directory at 29.07% +2. `open-sse/translator/request` + - Overall directory at 36.39% + - Many translators are still near single-digit coverage +3. `open-sse/translator/response` + - Overall directory at 8.07% +4. `open-sse/executors` + - Overall directory at 36.62% +5. `src/lib/db` + - `models.ts` at 20.66% + - `registeredKeys.ts` at 34.46% + - `modelComboMappings.ts` at 36.25% + - `settings.ts` at 46.40% + - `webhooks.ts` at 33.33% +6. `src/lib/usage` + - `usageHistory.ts` at 21.12% + - `usageStats.ts` at 9.56% + - `costCalculator.ts` at 30.00% +7. `src/lib/providers` + - `validation.ts` at 41.16% +8. Low-risk utility and API files for early gains + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/api/errorResponse.ts` + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +## Execution checklist + +### Phase 1: 56.95% -> 60% + +- [x] Fix coverage metric so it reflects source code instead of test files +- [x] Keep a legacy coverage script for comparison +- [x] Record the baseline and hotspots in-repo +- [ ] Add focused tests for low-risk utilities: + - `src/shared/utils/upstreamError.ts` + - `src/shared/utils/fetchTimeout.ts` + - `src/lib/api/errorResponse.ts` + - `src/shared/utils/apiAuth.ts` + - `src/lib/display/names.ts` +- [ ] Add route tests for: + - `src/app/api/settings/require-login/route.ts` + - `src/app/api/providers/[id]/models/route.ts` + +### Phase 2: 60% -> 65% + +- [ ] Add DB-backed tests for: + - `src/lib/db/modelComboMappings.ts` + - `src/lib/db/settings.ts` + - `src/lib/db/registeredKeys.ts` +- [ ] Cover branch behavior in: + - `src/lib/providers/validation.ts` + - `src/app/api/v1/embeddings/route.ts` + - `src/app/api/v1/moderations/route.ts` + +### Phase 3: 65% -> 70% + +- [ ] Add usage analytics tests for: + - `src/lib/usage/usageHistory.ts` + - `src/lib/usage/usageStats.ts` + - `src/lib/usage/costCalculator.ts` +- [ ] Expand route coverage for proxy management and settings branches + +### Phase 4: 70% -> 75% + +- [ ] Cover translator helpers and central translation paths: + - `open-sse/translator/index.ts` + - `open-sse/translator/helpers/*` + - `open-sse/translator/request/*` + - `open-sse/translator/response/*` + +### Phase 5: 75% -> 80% + +- [ ] Add handler-level tests for: + - `open-sse/handlers/chatCore.ts` + - `open-sse/handlers/responsesHandler.js` + - `open-sse/handlers/imageGeneration.js` + - `open-sse/handlers/embeddings.js` +- [ ] Add executor branch coverage for provider-specific auth, retries, and endpoint overrides + +### Phase 6: 80% -> 85% + +- [ ] Merge more edge-case suites into the main coverage path +- [ ] Increase function coverage for DB modules with weak constructor/helper coverage +- [ ] Close branch gaps in `settings.ts`, `registeredKeys.ts`, `validation.ts`, and translator helpers + +### Phase 7: 85% -> 90% + +- [ ] Treat the remaining low-coverage files as blockers +- [ ] Add regression tests for every uncovered production bug fixed during the push to 90% +- [ ] Raise the coverage gate in CI only after the local baseline is stable for at least two consecutive runs + +## Ratchet policy + +Update `npm run test:coverage` thresholds only after the project actually exceeds the next milestone with a comfortable buffer. + +Recommended ratchet sequence: + +1. 55/60/55 +2. 60/62/58 +3. 65/64/62 +4. 70/66/66 +5. 75/70/72 +6. 80/75/78 +7. 85/80/84 +8. 90/85/88 + +Order is `statements-lines / branches / functions`. + +## Known gap + +The current coverage command measures the main Node unit suite and includes source reached from it, including `open-sse`. It does not yet merge Vitest coverage into a single unified report. That merge is worth doing later, but it is not a blocker for starting the 60% -> 80% climb. diff --git a/docs/i18n/zh-CN/docs/FEATURES.md b/docs/i18n/zh-CN/docs/FEATURES.md index 4e02ea41a4..07220dc413 100644 --- a/docs/i18n/zh-CN/docs/FEATURES.md +++ b/docs/i18n/zh-CN/docs/FEATURES.md @@ -1,16 +1,16 @@ -# OmniRoute โ€” Dashboard ๅŠŸ่ƒฝ็”ปๅปŠ +# OmniRoute โ€” Dashboard Features Gallery (ไธญๆ–‡๏ผˆ็ฎ€ไฝ“๏ผ‰) -๐ŸŒ **่ฏญ่จ€๏ผš** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/FEATURES.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/FEATURES.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/FEATURES.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/FEATURES.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/FEATURES.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/FEATURES.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/FEATURES.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/FEATURES.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/FEATURES.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/FEATURES.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/FEATURES.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/FEATURES.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/FEATURES.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/FEATURES.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/FEATURES.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/FEATURES.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/FEATURES.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/FEATURES.md) --- -OmniRoute ไปช่กจ็›˜ๅ„ไธช้กต้ข็š„ๅฏ่ง†ๅŒ–ๅฏผ่งˆใ€‚ +Visual guide to every section of the OmniRoute dashboard. --- -## ๐Ÿ”Œ ๆไพ›ๅ•† +## ๐Ÿ”Œ Providers -็ฎก็† AI ๆไพ›ๅ•†่ฟžๆŽฅ๏ผšๅŒ…ๆ‹ฌ OAuth ๆไพ›ๅ•†๏ผˆClaude Codeใ€Codexใ€Gemini CLI๏ผ‰ใ€API Key ๆไพ›ๅ•†๏ผˆGroqใ€DeepSeekใ€OpenRouter๏ผ‰ไปฅๅŠๅ…่ดนๆไพ›ๅ•†๏ผˆQoderใ€Qwenใ€Kiro๏ผ‰ใ€‚Kiro ่ดฆๆˆท่ฟ˜ๆ”ฏๆŒ้ขๅบฆไฝ™้ข่ทŸ่ธช๏ผŒๅฏๅœจ Dashboard โ†’ Usage ไธญๆŸฅ็œ‹ๅ‰ฉไฝ™้ขๅบฆใ€ๆ€ป้ขๅบฆๅ’Œ็ปญๆœŸๆ—ฅๆœŸใ€‚ +Manage AI provider connections: OAuth providers (Claude Code, Codex, Gemini CLI), API key providers (Groq, DeepSeek, OpenRouter), and free providers (Qoder, Qwen, Kiro). Kiro accounts include credit balance tracking โ€” remaining credits, total allowance, and renewal date visible in Dashboard โ†’ Usage. ![Providers Dashboard](screenshots/01-providers.png) @@ -18,128 +18,128 @@ OmniRoute ไปช่กจ็›˜ๅ„ไธช้กต้ข็š„ๅฏ่ง†ๅŒ–ๅฏผ่งˆใ€‚ ## ๐ŸŽจ Combos -ๅˆ›ๅปบๆจกๅž‹่ทฏ็”ฑ Combo๏ผŒๆ”ฏๆŒ 6 ็ง็ญ–็•ฅ๏ผšpriorityใ€weightedใ€round-robinใ€randomใ€least-used ๅ’Œ cost-optimizedใ€‚ๆฏไธช Combo ้ƒฝๅฏไปฅไธฒ่”ๅคšไธชๆจกๅž‹ๅนถ่‡ชๅŠจๅ›ž้€€๏ผŒๅŒๆ—ถๆไพ›ๅฟซๆทๆจกๆฟๅ’Œๅฐฑ็ปชๆฃ€ๆŸฅใ€‚ +Create model routing combos with 6 strategies: priority, weighted, round-robin, random, least-used, and cost-optimized. Each combo chains multiple models with automatic fallback and includes quick templates and readiness checks. ![Combos Dashboard](screenshots/02-combos.png) --- -## ๐Ÿ“Š ๅˆ†ๆž +## ๐Ÿ“Š Analytics -ๅฎŒๆ•ด็š„็”จ้‡ๅˆ†ๆž่ƒฝๅŠ›๏ผŒๅŒ…ๆ‹ฌ token ๆถˆ่€—ใ€ๆˆๆœฌไผฐ็ฎ—ใ€ๆดปๅŠจ็ƒญๅŠ›ๅ›พใ€ๆฏๅ‘จๅˆ†ๅธƒๅ›พๅ’ŒๆŒ‰ๆไพ›ๅ•†ๆ‹†ๅˆ†็š„ๆ•ฐๆฎใ€‚ +Comprehensive usage analytics with token consumption, cost estimates, activity heatmaps, weekly distribution charts, and per-provider breakdowns. ![Analytics Dashboard](screenshots/03-analytics.png) --- -## ๐Ÿฅ ็ณป็ปŸๅฅๅบท +## ๐Ÿฅ System Health -ๅฎžๆ—ถ็›‘ๆŽง๏ผš่ฟ่กŒๆ—ถ้•ฟใ€ๅ†…ๅญ˜ใ€็‰ˆๆœฌใ€ๅปถ่ฟŸๅˆ†ไฝๆ•ฐ๏ผˆp50/p95/p99๏ผ‰ใ€็ผ“ๅญ˜็ปŸ่ฎกไปฅๅŠๆไพ›ๅ•†็†”ๆ–ญๅ™จ็Šถๆ€ใ€‚ +Real-time monitoring: uptime, memory, version, latency percentiles (p50/p95/p99), cache statistics, and provider circuit breaker states. ![Health Dashboard](screenshots/04-health.png) --- -## ๐Ÿ”ง ็ฟป่ฏ‘ๅ™จๅฎž้ชŒๅœบ +## ๐Ÿ”ง Translator Playground -ๆไพ› 4 ็ง API ็ฟป่ฏ‘่ฐƒ่ฏ•ๆจกๅผ๏ผš**Playground**๏ผˆๆ ผๅผ่ฝฌๆขๅ™จ๏ผ‰ใ€**Chat Tester**๏ผˆๅฎžๆ—ถ่ฏทๆฑ‚๏ผ‰ใ€**Test Bench**๏ผˆๆ‰น้‡ๆต‹่ฏ•๏ผ‰ๅ’Œ **Live Monitor**๏ผˆๅฎžๆ—ถๆต็›‘่ง†๏ผ‰ใ€‚ +Four modes for debugging API translations: **Playground** (format converter), **Chat Tester** (live requests), **Test Bench** (batch tests), and **Live Monitor** (real-time stream). ![Translator Playground](screenshots/05-translator.png) --- -## ๐ŸŽฎ ๆจกๅž‹ๅฎž้ชŒๅœบ _(v2.0.9+)_ +## ๐ŸŽฎ Model Playground _(v2.0.9+)_ -็›ดๆŽฅๅœจไปช่กจ็›˜ไธญๆต‹่ฏ•ไปปๆ„ๆจกๅž‹ใ€‚ๅฏไปฅ้€‰ๆ‹ฉๆไพ›ๅ•†ใ€ๆจกๅž‹ๅ’Œ็ซฏ็‚น๏ผŒไฝฟ็”จ Monaco Editor ็ผ–ๅ†™ๆ็คบ่ฏ๏ผŒๅฎžๆ—ถๆตๅผๆŸฅ็œ‹ๅ“ๅบ”ใ€ไธญ้€”็ปˆๆญข่ฏทๆฑ‚๏ผŒๅนถๆŸฅ็œ‹่€—ๆ—ถๆŒ‡ๆ ‡ใ€‚ +Test any model directly from the dashboard. Select provider, model, and endpoint, write prompts with Monaco Editor, stream responses in real-time, abort mid-stream, and view timing metrics. --- -## ๐ŸŽจ ไธป้ข˜ _(v2.0.5+)_ +## ๐ŸŽจ Themes _(v2.0.5+)_ -ไธบๆ•ดไธชไปช่กจ็›˜่‡ชๅฎšไน‰้ขœ่‰ฒไธป้ข˜ใ€‚ๅฏไปŽ 7 ็ง้ข„่ฎพ้ขœ่‰ฒ๏ผˆCoralใ€Blueใ€Redใ€Greenใ€Violetใ€Orangeใ€Cyan๏ผ‰ไธญ้€‰ๆ‹ฉ๏ผŒไนŸๅฏไปฅ้€š่ฟ‡ไปปๆ„ hex ้ขœ่‰ฒๅˆ›ๅปบ่‡ชๅฎšไน‰ไธป้ข˜ใ€‚ๆ”ฏๆŒๆต…่‰ฒใ€ๆทฑ่‰ฒๅ’Œ่ทŸ้š็ณป็ปŸใ€‚ +Customizable color themes for the entire dashboard. Choose from 7 preset colors (Coral, Blue, Red, Green, Violet, Orange, Cyan) or create a custom theme by picking any hex color. Supports light, dark, and system mode. --- -## โš™๏ธ ่ฎพ็ฝฎ +## โš™๏ธ Settings -ๅฎŒๆ•ด็š„่ฎพ็ฝฎ้ขๆฟ๏ผŒๅŒ…ๅซไปฅไธ‹ๆ ‡็ญพ้กต๏ผš +Comprehensive settings panel with tabs: -- **General** โ€” ็ณป็ปŸๅญ˜ๅ‚จใ€ๅค‡ไปฝ็ฎก็†๏ผˆๅฏผๅ‡บ/ๅฏผๅ…ฅๆ•ฐๆฎๅบ“๏ผ‰ -- **Appearance** โ€” ไธป้ข˜้€‰ๆ‹ฉๅ™จ๏ผˆdark/light/system๏ผ‰ใ€้ขœ่‰ฒไธป้ข˜้ข„่ฎพๅ’Œ่‡ชๅฎšไน‰้ขœ่‰ฒใ€ๅฅๅบทๆ—ฅๅฟ—ๅฏ่งๆ€งใ€ไพง่พนๆ ้กน็›ฎๅฏ่งๆ€งๆŽงๅˆถ -- **Security** โ€” API ็ซฏ็‚นไฟๆŠคใ€่‡ชๅฎšไน‰ๆไพ›ๅ•†ๅฑ่”ฝใ€IP ่ฟ‡ๆปคใ€ไผš่ฏไฟกๆฏ -- **Routing** โ€” ๆจกๅž‹ๅˆซๅใ€ๅŽๅฐไปปๅŠก้™็บง -- **Resilience** โ€” ้€Ÿ็Ž‡้™ๅˆถๆŒไน…ๅŒ–ใ€็†”ๆ–ญๅ™จ่ฐƒไผ˜ใ€่‡ชๅŠจ็ฆ็”จ่ขซๅฐ่ดฆๆˆทใ€ๆไพ›ๅ•†่ฟ‡ๆœŸ็›‘ๆŽง -- **Advanced** โ€” ้…็ฝฎ่ฆ†็›–ใ€้…็ฝฎๅฎก่ฎก่ฝจ่ฟนใ€ๅ›ž้€€้™็บงๆจกๅผ +- **General** โ€” System storage, backup management (export/import database) +- **Appearance** โ€” Theme selector (dark/light/system), color theme presets and custom colors, health log visibility, sidebar item visibility controls +- **Security** โ€” API endpoint protection, custom provider blocking, IP filtering, session info +- **Routing** โ€” Model aliases, background task degradation +- **Resilience** โ€” Rate limit persistence, circuit breaker tuning, auto-disable banned accounts, provider expiration monitoring +- **Advanced** โ€” Configuration overrides, configuration audit trail, fallback degradation mode ![Settings Dashboard](screenshots/06-settings.png) --- -## ๐Ÿ”ง CLI ๅทฅๅ…ท +## ๐Ÿ”ง CLI Tools -ไธบ AI ็ผ–็จ‹ๅทฅๅ…ทๆไพ›ไธ€้”ฎ้…็ฝฎ๏ผšClaude Codeใ€Codex CLIใ€Gemini CLIใ€OpenClawใ€Kilo Codeใ€Antigravityใ€Clineใ€Continueใ€Cursor ๅ’Œ Factory Droidใ€‚ๆ”ฏๆŒ่‡ชๅŠจๅบ”็”จ/้‡็ฝฎ้…็ฝฎใ€่ฟžๆŽฅ้…็ฝฎๆ–‡ไปถๅ’Œๆจกๅž‹ๆ˜ ๅฐ„ใ€‚ +One-click configuration for AI coding tools: Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kilo Code, Antigravity, Cline, Continue, Cursor, and Factory Droid. Features automated config apply/reset, connection profiles, and model mapping. ![CLI Tools Dashboard](screenshots/07-cli-tools.png) --- -## ๐Ÿค– CLI ไปฃ็† _(v2.0.11+)_ +## ๐Ÿค– CLI Agents _(v2.0.11+)_ -็”จไบŽๅ‘็Žฐๅ’Œ็ฎก็† CLI agents ็š„ไปช่กจ็›˜ใ€‚ไผšไปฅ็ฝ‘ๆ ผๅฑ•็คบ 14 ไธชๅ†…็ฝฎ agent๏ผˆCodexใ€Claudeใ€Gooseใ€Gemini CLIใ€OpenClawใ€Aiderใ€OpenCodeใ€Clineใ€Qwen Codeใ€ForgeCodeใ€Amazon Qใ€Open Interpreterใ€Cursor CLIใ€Warp๏ผ‰๏ผŒๅŒ…ๆ‹ฌ๏ผš +Dashboard for discovering and managing CLI agents. Shows a grid of 14 built-in agents (Codex, Claude, Goose, Gemini CLI, OpenClaw, Aider, OpenCode, Cline, Qwen Code, ForgeCode, Amazon Q, Open Interpreter, Cursor CLI, Warp) with: -- **ๅฎ‰่ฃ…็Šถๆ€** โ€” Installed / Not Found๏ผŒๅนถๅธฆ็‰ˆๆœฌๆฃ€ๆต‹ -- **ๅ่ฎฎๅพฝๆ ‡** โ€” stdioใ€HTTP ็ญ‰ -- **่‡ชๅฎšไน‰ agents** โ€” ๅฏ้€š่ฟ‡่กจๅ•ๆณจๅ†Œไปปๆ„ CLI ๅทฅๅ…ท๏ผˆๅ็งฐใ€ไบŒ่ฟ›ๅˆถใ€็‰ˆๆœฌๅ‘ฝไปคใ€ๅฏๅŠจๅ‚ๆ•ฐ๏ผ‰ -- **CLI Fingerprint Matching** โ€” ๆŒ‰ๆไพ›ๅ•†ๅผ€ๅ…ณ๏ผŒไปฅๅŒน้…ๅŽŸ็”Ÿ CLI ่ฏทๆฑ‚็‰นๅพ๏ผŒๅœจไฟ็•™ไปฃ็† IP ็š„ๅŒๆ—ถ้™ไฝŽๅฐ็ฆ้ฃŽ้™ฉ +- **Installation status** โ€” Installed / Not Found with version detection +- **Protocol badges** โ€” stdio, HTTP, etc. +- **Custom agents** โ€” Register any CLI tool via form (name, binary, version command, spawn args) +- **CLI Fingerprint Matching** โ€” Per-provider toggle to match native CLI request signatures, reducing ban risk while preserving proxy IP --- -## ๐Ÿ–ผ๏ธ ๅช’ไฝ“ _(v2.0.3+)_ +## ๐Ÿ–ผ๏ธ Media _(v2.0.3+)_ -ไปŽไปช่กจ็›˜็”Ÿๆˆๅ›พๅƒใ€่ง†้ข‘ๅ’Œ้Ÿณไนใ€‚ๆ”ฏๆŒ OpenAIใ€xAIใ€Togetherใ€Hyperbolicใ€SD WebUIใ€ComfyUIใ€AnimateDiffใ€Stable Audio Open ๅ’Œ MusicGenใ€‚ +Generate images, videos, and music from the dashboard. Supports OpenAI, xAI, Together, Hyperbolic, SD WebUI, ComfyUI, AnimateDiff, Stable Audio Open, and MusicGen. --- -## ๐Ÿ“ ่ฏทๆฑ‚ๆ—ฅๅฟ— +## ๐Ÿ“ Request Logs -ๅฎžๆ—ถ่ฏทๆฑ‚ๆ—ฅๅฟ—๏ผŒๆ”ฏๆŒๆŒ‰ๆไพ›ๅ•†ใ€ๆจกๅž‹ใ€่ดฆๆˆทๅ’Œ API Key ่ฟ‡ๆปคใ€‚ๅฏๆŸฅ็œ‹็Šถๆ€็ ใ€token ็”จ้‡ใ€ๅปถ่ฟŸๅ’Œๅ“ๅบ”่ฏฆๆƒ…ใ€‚ +Real-time request logging with filtering by provider, model, account, and API key. Shows status codes, token usage, latency, and response details. ![Usage Logs](screenshots/08-usage.png) --- -## ๐ŸŒ API ็ซฏ็‚น +## ๐ŸŒ API Endpoint -็ปŸไธ€ API ็ซฏ็‚น้กต้ข๏ผŒๆŒ‰่ƒฝๅŠ›ๆ‹†ๅˆ†ๅฑ•็คบ๏ผšChat Completionsใ€Responses APIใ€Embeddingsใ€Image Generationใ€Rerankingใ€Audio Transcriptionใ€Text-to-Speechใ€Moderations๏ผŒไปฅๅŠๅทฒๆณจๅ†Œ API Keysใ€‚่ฟ˜้›†ๆˆไบ† Cloudflare Quick Tunnel ๅ’Œไบ‘ไปฃ็†ๆ”ฏๆŒ๏ผŒๆ–นไพฟ่ฟœ็จ‹่ฎฟ้—ฎใ€‚ +Your unified API endpoint with capability breakdown: Chat Completions, Responses API, Embeddings, Image Generation, Reranking, Audio Transcription, Text-to-Speech, Moderations, and registered API keys. Cloudflare Quick Tunnel integration and cloud proxy support for remote access. ![Endpoint Dashboard](screenshots/09-endpoint.png) --- -## ๐Ÿ”‘ API ๅฏ†้’ฅ็ฎก็† +## ๐Ÿ”‘ API Key Management -ๅˆ›ๅปบใ€้™ๅฎš่Œƒๅ›ดๅนถๆ’ค้”€ API Keysใ€‚ๆฏไธช key ้ƒฝๅฏไปฅ้™ๅˆถๅˆฐ็‰นๅฎšๆจกๅž‹ๆˆ–ๆไพ›ๅ•†๏ผŒๅนถๆ”ฏๆŒ full access ๆˆ– read-only ๆƒ้™ใ€‚ๆไพ›ๅฏ่ง†ๅŒ–ๅฏ†้’ฅ็ฎก็†ๅ’Œ็”จ้‡่ทŸ่ธชใ€‚ +Create, scope, and revoke API keys. Each key can be restricted to specific models/providers with full access or read-only permissions. Visual key management with usage tracking. --- -## ๐Ÿ“‹ ๅฎก่ฎกๆ—ฅๅฟ— +## ๐Ÿ“‹ Audit Log -็”จไบŽ่ทŸ่ธช็ฎก็†ๆ“ไฝœ๏ผŒๆ”ฏๆŒๆŒ‰ๆ“ไฝœ็ฑปๅž‹ใ€ๆ‰ง่กŒ่€…ใ€็›ฎๆ ‡ใ€IP ๅœฐๅ€ๅ’Œๆ—ถ้—ดๆˆณ่ฟ‡ๆปค๏ผŒๅฏๆŸฅ็œ‹ๅฎŒๆ•ด็š„ๅฎ‰ๅ…จไบ‹ไปถๅŽ†ๅฒใ€‚ +Administrative action tracking with filtering by action type, actor, target, IP address, and timestamp. Full security event history. --- -## ๐Ÿ–ฅ๏ธ ๆกŒ้ขๅบ”็”จ +## ๐Ÿ–ฅ๏ธ Desktop Application -้€‚็”จไบŽ Windowsใ€macOS ๅ’Œ Linux ็š„ๅŽŸ็”Ÿ Electron ๆกŒ้ขๅบ”็”จใ€‚ๅฏไปฅๅฐ† OmniRoute ไฝœไธบ็‹ฌ็ซ‹ๅบ”็”จ่ฟ่กŒ๏ผŒๆ”ฏๆŒ็ณป็ปŸๆ‰˜็›˜ใ€็ฆป็บฟๆจกๅผใ€่‡ชๅŠจๆ›ดๆ–ฐๅ’Œไธ€้”ฎๅฎ‰่ฃ…ใ€‚ +Native Electron desktop app for Windows, macOS, and Linux. Run OmniRoute as a standalone application with system tray integration, offline support, auto-update, and one-click install. -ไธป่ฆ็‰นๆ€ง๏ผš +Key features: -- ๆœๅŠกๅ™จๅฐฑ็ปช่ฝฎ่ฏข๏ผˆๅ†ทๅฏๅŠจๆ—ถไธๅ†็™ฝๅฑ๏ผ‰ -- ๅธฆ็ซฏๅฃ็ฎก็†็š„็ณป็ปŸๆ‰˜็›˜ +- Server readiness polling (no blank screen on cold start) +- System tray with port management - Content Security Policy -- ๅ•ๅฎžไพ‹้” -- ้‡ๅฏๆ—ถ่‡ชๅŠจๆ›ดๆ–ฐ -- ๆŒ‰ๅนณๅฐ้€‚้…็š„็•Œ้ข๏ผˆmacOS traffic lightsใ€Windows/Linux ้ป˜่ฎคๆ ‡้ข˜ๆ ๏ผ‰ -- ๅŠ ๅ›บ็š„ Electron ๆ‰“ๅŒ…ๆต็จ‹๏ผšไผšๅœจๆ‰“ๅŒ…ๅ‰ๆฃ€ๆต‹ๅนถๆ‹’็ป standalone bundle ไธญ็ฌฆๅท้“พๆŽฅ็š„ `node_modules`๏ผŒ้˜ฒๆญข่ฟ่กŒๆ—ถไพ่ต–ๆž„ๅปบๆœบ็Žฏๅขƒ๏ผˆv2.5.5+๏ผ‰ +- Single-instance lock +- Auto-update on restart +- Platform-conditional UI (macOS traffic lights, Windows/Linux default titlebar) +- Hardened Electron build packaging โ€” symlinked `node_modules` in the standalone bundle is detected and rejected before packaging, preventing runtime dependency on the build machine (v2.5.5+) -๐Ÿ“– ๅฎŒๆ•ดๆ–‡ๆกฃ่ง [`electron/README.md`](../electron/README.md)ใ€‚ +๐Ÿ“– See [`electron/README.md`](../electron/README.md) for full documentation. diff --git a/docs/i18n/zh-CN/docs/MCP-SERVER.md b/docs/i18n/zh-CN/docs/MCP-SERVER.md new file mode 100644 index 0000000000..d521c8c256 --- /dev/null +++ b/docs/i18n/zh-CN/docs/MCP-SERVER.md @@ -0,0 +1,87 @@ +# OmniRoute MCP Server Documentation (ไธญๆ–‡๏ผˆ็ฎ€ไฝ“๏ผ‰) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/MCP-SERVER.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/MCP-SERVER.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/MCP-SERVER.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/MCP-SERVER.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/MCP-SERVER.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/MCP-SERVER.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/MCP-SERVER.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/MCP-SERVER.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/MCP-SERVER.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/MCP-SERVER.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/MCP-SERVER.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/MCP-SERVER.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/MCP-SERVER.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/MCP-SERVER.md) + +--- + +> Model Context Protocol server with 16 intelligent tools + +## ๅฎ‰่ฃ… + +OmniRoute MCP is built-in. Start it with: + +```bash +omniroute --mcp +``` + +Or via the open-sse transport: + +```bash +# HTTP streamable transport (port 20130) +omniroute --dev # MCP auto-starts on /mcp endpoint +``` + +## IDE Configuration + +See [IDE Configs](integrations/ide-configs.md) for Antigravity, Cursor, Copilot, and Claude Desktop setup. + +--- + +## Essential Tools (8) + +| Tool | Description | +| :------------------------------ | :--------------------------------------- | +| `omniroute_get_health` | Gateway health, circuit breakers, uptime | +| `omniroute_list_combos` | All configured combos with models | +| `omniroute_get_combo_metrics` | Performance metrics for a specific combo | +| `omniroute_switch_combo` | Switch active combo by ID/name | +| `omniroute_check_quota` | Quota status per provider or all | +| `omniroute_route_request` | Send a chat completion through OmniRoute | +| `omniroute_cost_report` | Cost analytics for a time period | +| `omniroute_list_models_catalog` | Full model catalog with capabilities | + +## Advanced Tools (8) + +| Tool | Description | +| :--------------------------------- | :---------------------------------------------------------- | +| `omniroute_simulate_route` | Dry-run routing simulation with fallback tree | +| `omniroute_set_budget_guard` | Session budget with degrade/block/alert actions | +| `omniroute_set_resilience_profile` | Apply conservative/balanced/aggressive preset | +| `omniroute_test_combo` | Live-test all models in a combo via a real upstream request | +| `omniroute_get_provider_metrics` | Detailed metrics for one provider | +| `omniroute_best_combo_for_task` | Task-fitness recommendation with alternatives | +| `omniroute_explain_route` | Explain a past routing decision | +| `omniroute_get_session_snapshot` | Full session state: costs, tokens, errors | + +## Authentication + +MCP tools are authenticated via API key scopes. Each tool requires specific scopes: + +| Scope | Tools | +| :------------- | :----------------------------------------------- | +| `read:health` | get_health, get_provider_metrics | +| `read:combos` | list_combos, get_combo_metrics | +| `write:combos` | switch_combo | +| `read:quota` | check_quota | +| `write:route` | route_request, simulate_route, test_combo | +| `read:usage` | cost_report, get_session_snapshot, explain_route | +| `write:config` | set_budget_guard, set_resilience_profile | +| `read:models` | list_models_catalog, best_combo_for_task | + +## Audit Logging + +Every tool call is logged to `mcp_tool_audit` with: + +- Tool name, arguments, result +- Duration (ms), success/failure +- API key hash, timestamp + +## Files + +| File | Purpose | +| :------------------------------------------- | :------------------------------------------ | +| `open-sse/mcp-server/server.ts` | MCP server creation + 16 tool registrations | +| `open-sse/mcp-server/transport.ts` | Stdio + HTTP transport | +| `open-sse/mcp-server/auth.ts` | API key + scope validation | +| `open-sse/mcp-server/audit.ts` | Tool call audit logging | +| `open-sse/mcp-server/tools/advancedTools.ts` | 8 advanced tool handlers | diff --git a/docs/i18n/zh-CN/docs/RELEASE_CHECKLIST.md b/docs/i18n/zh-CN/docs/RELEASE_CHECKLIST.md new file mode 100644 index 0000000000..967c7c7d95 --- /dev/null +++ b/docs/i18n/zh-CN/docs/RELEASE_CHECKLIST.md @@ -0,0 +1,37 @@ +# Release Checklist (ไธญๆ–‡๏ผˆ็ฎ€ไฝ“๏ผ‰) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/RELEASE_CHECKLIST.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/RELEASE_CHECKLIST.md) + +--- + +Use this checklist before tagging or publishing a new OmniRoute release. + +## Version and Changelog + +1. Bump `package.json` version (`x.y.z`) in the release branch. +2. Move release notes from `## [Unreleased]` in `CHANGELOG.md` to a dated section: + - `## [x.y.z] โ€” YYYY-MM-DD` +3. Keep `## [Unreleased]` as the first changelog section for upcoming work. +4. Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version. + +## API Docs + +1. Update `docs/openapi.yaml`: + - `info.version` must equal `package.json` version. +2. Validate endpoint examples if API contracts changed. + +## Runtime Docs + +1. Review `docs/ARCHITECTURE.md` for storage/runtime drift. +2. Review `docs/TROUBLESHOOTING.md` for env var and operational drift. +3. Update localized docs if source docs changed significantly. + +## Automated Check + +Run the sync guard locally before opening PR: + +```bash +npm run check:docs-sync +``` + +CI also runs this check in `.github/workflows/ci.yml` (lint job). diff --git a/docs/i18n/zh-CN/docs/TROUBLESHOOTING.md b/docs/i18n/zh-CN/docs/TROUBLESHOOTING.md new file mode 100644 index 0000000000..4999520435 --- /dev/null +++ b/docs/i18n/zh-CN/docs/TROUBLESHOOTING.md @@ -0,0 +1,256 @@ +# Troubleshooting (ไธญๆ–‡๏ผˆ็ฎ€ไฝ“๏ผ‰) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/TROUBLESHOOTING.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/TROUBLESHOOTING.md) + +--- + +Common problems and solutions for OmniRoute. + +--- + +## Quick Fixes + +| Problem | Solution | +| ----------------------------- | ------------------------------------------------------------------ | +| First login not working | Set `INITIAL_PASSWORD` in `.env` (no hardcoded default) | +| Dashboard opens on wrong port | Set `PORT=20128` and `NEXT_PUBLIC_BASE_URL=http://localhost:20128` | +| No request logs under `logs/` | Set `ENABLE_REQUEST_LOGS=true` | +| EACCES: permission denied | Set `DATA_DIR=/path/to/writable/dir` to override `~/.omniroute` | +| Routing strategy not saving | Update to v1.4.11+ (Zod schema fix for settings persistence) | + +--- + +## Provider Issues + +### "Language model did not provide messages" + +**Cause:** Provider quota exhausted. + +**Fix:** + +1. 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, Qoder) 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}/storage.sqlite` (providers, combos, aliases, keys, settings) +- Usage: SQLite tables in `storage.sqlite` (`usage_history`, `call_logs`, `proxy_logs`) + optional `${DATA_DIR}/log.txt` and `${DATA_DIR}/call_logs/` +- Request logs: `/logs/...` (when `ENABLE_REQUEST_LOGS=true`) + +--- + +## Circuit Breaker Issues + +### Provider stuck in OPEN state + +When a provider's circuit breaker is OPEN, requests are blocked until the cooldown expires. + +**Fix:** + +1. 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 +- **SDK returns raw string instead of object** โ€” Fixed in v1.1.0: response sanitizer now strips non-standard fields (`x_groq`, `usage_breakdown`, etc.) that cause OpenAI SDK Pydantic validation failures +- **GLM/ERNIE rejects `system` role** โ€” Fixed in v1.1.0: role normalizer automatically merges system messages into user messages for incompatible models +- **`developer` role not recognized** โ€” Fixed in v1.1.0: automatically converted to `system` for non-OpenAI providers +- **`json_schema` not working with Gemini** โ€” Fixed in v1.1.0: `response_format` is now converted to Gemini's `responseMimeType` + `responseSchema` + +--- + +## Resilience Settings + +### Auto rate-limit not triggering + +- 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. + +--- + +## Optional RAG / LLM failure taxonomy (16 problems) + +Some OmniRoute users place the gateway in front of RAG or agent stacks. In those setups it is common to see a strange pattern: OmniRoute looks healthy (providers up, routing profiles ok, no rate limit alerts) but the final answer is still wrong. + +In practice these incidents usually come from the downstream RAG pipeline, not from the gateway itself. + +If you want a shared vocabulary to describe those failures you can use the WFGY ProblemMap, an external MIT license text resource that defines sixteen recurring RAG / LLM failure patterns. At a high level it covers: + +- retrieval drift and broken context boundaries +- empty or stale indexes and vector stores +- embedding versus semantic mismatch +- prompt assembly and context window issues +- logic collapse and overconfident answers +- long chain and agent coordination failures +- multi agent memory and role drift +- deployment and bootstrap ordering problems + +The idea is simple: + +1. When you investigate a bad response, capture: + - user task and request + - route or provider combo in OmniRoute + - any RAG context used downstream (retrieved documents, tool calls, etc) +2. Map the incident to one or two WFGY ProblemMap numbers (`No.1` โ€ฆ `No.16`). +3. Store the number in your own dashboard, runbook, or incident tracker next to the OmniRoute logs. +4. Use the corresponding WFGY page to decide whether you need to change your RAG stack, retriever, or routing strategy. + +Full text and concrete recipes live here (MIT license, text only): + +[WFGY ProblemMap README](https://github.com/onestardao/WFGY/blob/main/ProblemMap/README.md) + +You can ignore this section if you do not run RAG or agent pipelines behind OmniRoute. + +--- + +## Still Stuck? + +- **GitHub Issues**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues) +- **Architecture**: See [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) for internal details +- **API Reference**: See [`docs/API_REFERENCE.md`](API_REFERENCE.md) for all endpoints +- **Health Dashboard**: Check **Dashboard โ†’ Health** for real-time system status +- **Translator**: Use **Dashboard โ†’ Translator** to debug format issues diff --git a/docs/i18n/zh-CN/docs/USER_GUIDE.md b/docs/i18n/zh-CN/docs/USER_GUIDE.md new file mode 100644 index 0000000000..d98b957a6a --- /dev/null +++ b/docs/i18n/zh-CN/docs/USER_GUIDE.md @@ -0,0 +1,944 @@ +# User Guide (ไธญๆ–‡๏ผˆ็ฎ€ไฝ“๏ผ‰) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/USER_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/USER_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/USER_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/USER_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/USER_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/USER_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/USER_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/USER_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/USER_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/USER_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/USER_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/USER_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/USER_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/USER_GUIDE.md) + +--- + +Complete guide for configuring providers, creating combos, integrating CLI tools, and deploying OmniRoute. + +--- + +## Table of Contents + +- [Pricing at a Glance](#-pricing-at-a-glance) +- [Use Cases](#-use-cases) +- [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** | Qoder | $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) + Qoder (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 + +#### Qoder (8 FREE models) + +```bash +Dashboard โ†’ Connect Qoder โ†’ 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 +``` + +--- + +## ้ƒจ็ฝฒ + +### Global npm install (Recommended) + +```bash +npm install -g omniroute + +# Create config directory +mkdir -p ~/.omniroute + +# Create .env file (see .env.example) +cp .env.example ~/.omniroute/.env + +# Start server +omniroute +# Or with custom port: +omniroute --port 3000 +``` + +The CLI automatically loads `.env` from `~/.omniroute/.env` or `./.env`. + +### VPS Deployment + +```bash +git clone https://github.com/diegosouzapw/OmniRoute.git +cd OmniRoute && npm install && npm run build + +export JWT_SECRET="your-secure-secret-change-this" +export INITIAL_PASSWORD="your-password" +export DATA_DIR="/var/lib/omniroute" +export PORT="20128" +export HOSTNAME="0.0.0.0" +export NODE_ENV="production" +export NEXT_PUBLIC_BASE_URL="http://localhost:20128" +export API_KEY_SECRET="endpoint-proxy-api-key-secret" + +npm run start +# Or: pm2 start npm --name omniroute -- start +``` + +### PM2 Deployment (Low Memory) + +For servers with limited RAM, use the memory limit option: + +```bash +# With 512MB limit (default) +pm2 start npm --name omniroute -- start + +# Or with custom memory limit +OMNIROUTE_MEMORY_MB=512 pm2 start npm --name omniroute -- start + +# Or using ecosystem.config.js +pm2 start ecosystem.config.js +``` + +Create `ecosystem.config.js`: + +```javascript +module.exports = { + apps: [ + { + name: "omniroute", + script: "npm", + args: "start", + env: { + NODE_ENV: "production", + OMNIROUTE_MEMORY_MB: "512", + JWT_SECRET: "your-secret", + INITIAL_PASSWORD: "your-password", + }, + node_args: "--max-old-space-size=512", + max_memory_restart: "300M", + }, + ], +}; +``` + +### Docker + +```bash +# Build image (default = runner-cli with codex/claude/droid preinstalled) +docker build -t omniroute:cli . + +# Portable mode (recommended) +docker run -d --name omniroute -p 20128:20128 --env-file ./.env -v omniroute-data:/app/data omniroute:cli +``` + +For host-integrated mode with CLI binaries, see the Docker section in the main docs. + +### Void Linux (xbps-src) + +Void Linux users can package and install OmniRoute natively using the `xbps-src` cross-compilation framework. This automates the Node.js standalone build along with the required `better-sqlite3` native bindings. + +
+View xbps-src template + +```bash +# Template file for 'omniroute' +pkgname=omniroute +version=3.2.4 +revision=1 +hostmakedepends="nodejs python3 make" +depends="openssl" +short_desc="Universal AI gateway with smart routing for multiple LLM providers" +maintainer="zenobit " +license="MIT" +homepage="https://github.com/diegosouzapw/OmniRoute" +distfiles="https://github.com/diegosouzapw/OmniRoute/archive/refs/tags/v${version}.tar.gz" +checksum=009400afee90a9f32599d8fe734145cfd84098140b7287990183dde45ae2245b +system_accounts="_omniroute" +omniroute_homedir="/var/lib/omniroute" +export NODE_ENV=production +export npm_config_engine_strict=false +export npm_config_loglevel=error +export npm_config_fund=false +export npm_config_audit=false + +do_build() { + # Determine target CPU arch for node-gyp + local _gyp_arch + case "$XBPS_TARGET_MACHINE" in + aarch64*) _gyp_arch=arm64 ;; + armv7*|armv6*) _gyp_arch=arm ;; + i686*) _gyp_arch=ia32 ;; + *) _gyp_arch=x64 ;; + esac + + # 1) Install all deps โ€“ skip scripts + NODE_ENV=development npm ci --ignore-scripts + + # 2) Build the Next.js standalone bundle + npm run build + + # 3) Copy static assets into standalone + cp -r .next/static .next/standalone/.next/static + [ -d public ] && cp -r public .next/standalone/public || true + + # 4) Compile better-sqlite3 native binding + local _node_gyp=/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js + (cd node_modules/better-sqlite3 && node "$_node_gyp" rebuild --arch="$_gyp_arch") + + # 5) Place the compiled binding into the standalone bundle + local _bs3_release=.next/standalone/node_modules/better-sqlite3/build/Release + mkdir -p "$_bs3_release" + cp node_modules/better-sqlite3/build/Release/better_sqlite3.node "$_bs3_release/" + + # 6) Remove arch-specific sharp bundles + rm -rf .next/standalone/node_modules/@img + + # 7) Copy pino runtime deps omitted by Next.js static analysis: + for _mod in pino-abstract-transport split2 process-warning; do + cp -r "node_modules/$_mod" .next/standalone/node_modules/ + done +} + +do_check() { + npm run test:unit +} + +do_install() { + vmkdir usr/lib/omniroute/.next + vcopy .next/standalone/. usr/lib/omniroute/.next/standalone + + # Prevent removal of empty Next.js app router dirs by the post-install hook + for _d in \ + .next/standalone/.next/server/app/dashboard \ + .next/standalone/.next/server/app/dashboard/settings \ + .next/standalone/.next/server/app/dashboard/providers; do + touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep" + done + + cat > "${WRKDIR}/omniroute" <<'EOF' +#!/bin/sh +export PORT="${PORT:-20128}" +export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}" +export LOG_TO_FILE="${LOG_TO_FILE:-false}" +mkdir -p "${DATA_DIR}" +exec node /usr/lib/omniroute/.next/standalone/server.js "$@" +EOF + vbin "${WRKDIR}/omniroute" +} + +post_install() { + vlicense LICENSE +} +``` + +
+ +### 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/*` | +| `ALLOW_API_KEY_REVEAL` | `false` | Allow Api Manager to copy full API keys on demand | +| `DISABLE_SQLITE_AUTO_BACKUP` | `false` | Disable automatic SQLite snapshots before writes/import/restore; manual backups still work | +| `ENABLE_REQUEST_LOGS` | `false` | Enables request/response logs | +| `AUTH_COOKIE_SECURE` | `false` | Force `Secure` auth cookie (behind HTTPS reverse proxy) | +| `CLOUDFLARED_BIN` | unset | Use an existing `cloudflared` binary instead of managed download | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit in MB | +| `PROMPT_CACHE_MAX_SIZE` | `50` | Max prompt cache entries | +| `SEMANTIC_CACHE_MAX_SIZE` | `100` | Max semantic cache entries | + +For the full environment variable reference, see the [README](../README.md). + +--- + +## ๐Ÿ“Š Available Models + +
+View all available models + +**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` + +**Qoder (`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` + +
+ +--- + +## ๐Ÿงฉ 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**. + +Notes: + +- OpenRouter and OpenAI/Anthropic-compatible providers are managed from **Available Models** only. Manual add, import, and auto-sync all land in the same available-model list, so there is no separate Custom Models section for those providers. +- The **Custom Models** section is intended for providers that do not expose managed available-model imports. + +### 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 + +### Cloudflare Quick Tunnel + +- Available in **Dashboard โ†’ Endpoints** for Docker and other self-hosted deployments +- Creates a temporary `https://*.trycloudflare.com` URL that forwards to your current OpenAI-compatible `/v1` endpoint +- First enable installs `cloudflared` only when needed; later restarts reuse the same managed binary +- Tunnel URLs are ephemeral and change every time you stop/start the tunnel +- Set `CLOUDFLARED_BIN` if you prefer using a preinstalled `cloudflared` binary instead of the managed download + +### 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 | + +#### External Sticky Session Header + +For external session affinity (for example, Claude Code/Codex agents behind reverse proxies), send: + +```http +X-Session-Id: your-session-key +``` + +OmniRoute also accepts `x_session_id` and returns the effective session key in `X-OmniRoute-Session-Id`. + +If you use Nginx and send underscore-form headers, enable: + +```nginx +underscores_in_headers on; +``` + +#### 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 unless `DISABLE_SQLITE_AUTO_BACKUP=true` | + +```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 6 tabs for easy navigation: + +| Tab | Contents | +| -------------- | ---------------------------------------------------------------------------------------------- | +| **General** | System storage tools, appearance settings, theme controls, and per-item sidebar visibility | +| **Security** | Login/Password settings, IP Access Control, API auth for `/models`, and Provider Blocking | +| **Routing** | Global routing strategy (6 options), wildcard model aliases, fallback chains, combo defaults | +| **Resilience** | Provider profiles, editable rate limits, circuit breaker status, policies & locked identifiers | +| **AI** | Thinking budget configuration, global system prompt injection, prompt cache stats | +| **Advanced** | Global proxy configuration (HTTP/SOCKS5) | + +--- + +### Costs & Budget Management + +Access via **Dashboard โ†’ Costs**. + +| 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. + +--- + +## ๐Ÿ–ฅ๏ธ Desktop Application (Electron) + +OmniRoute is available as a native desktop application for Windows, macOS, and Linux. + +### ๅฎ‰่ฃ… + +```bash +# From the electron directory: +cd electron +npm install + +# Development mode (connect to running Next.js dev server): +npm run dev + +# Production mode (uses standalone build): +npm start +``` + +### Building Installers + +```bash +cd electron +npm run build # Current platform +npm run build:win # Windows (.exe NSIS) +npm run build:mac # macOS (.dmg universal) +npm run build:linux # Linux (.AppImage) +``` + +Output โ†’ `electron/dist-electron/` + +### Key Features + +| Feature | Description | +| --------------------------- | ---------------------------------------------------- | +| **Server Readiness** | Polls server before showing window (no blank screen) | +| **System Tray** | Minimize to tray, change port, quit from tray menu | +| **Port Management** | Change server port from tray (auto-restarts server) | +| **Content Security Policy** | Restrictive CSP via session headers | +| **Single Instance** | Only one app instance can run at a time | +| **Offline Mode** | Bundled Next.js server works without internet | + +### Environment Variables + +| Variable | Default | Description | +| --------------------- | ------- | -------------------------------- | +| `OMNIROUTE_PORT` | `20128` | Server port | +| `OMNIROUTE_MEMORY_MB` | `512` | Node.js heap limit (64โ€“16384 MB) | + +๐Ÿ“– Full documentation: [`electron/README.md`](../electron/README.md) diff --git a/docs/i18n/zh-CN/docs/VM_DEPLOYMENT_GUIDE.md b/docs/i18n/zh-CN/docs/VM_DEPLOYMENT_GUIDE.md new file mode 100644 index 0000000000..37d94e2a15 --- /dev/null +++ b/docs/i18n/zh-CN/docs/VM_DEPLOYMENT_GUIDE.md @@ -0,0 +1,403 @@ +# OmniRoute โ€” Deployment Guide on VM with Cloudflare (ไธญๆ–‡๏ผˆ็ฎ€ไฝ“๏ผ‰) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../es/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../fr/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../de/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../it/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../ru/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../zh-CN/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../ja/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../ko/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../ar/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../in/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../th/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../vi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../id/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../ms/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../nl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../pl/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../sv/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../no/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../da/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../fi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../pt/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../ro/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../hu/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../bg/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../sk/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../uk-UA/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../he/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../phi/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../pt-BR/docs/VM_DEPLOYMENT_GUIDE.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../cs/docs/VM_DEPLOYMENT_GUIDE.md) + +--- + +Complete guide to install and configure OmniRoute on a VM (VPS) with domain managed via Cloudflare. + +--- + +## Prerequisites + +| Item | Minimum | Recommended | +| ---------- | ------------------------ | ---------------- | +| **CPU** | 1 vCPU | 2 vCPU | +| **RAM** | 1 GB | 2 GB | +| **Disk** | 10 GB SSD | 25 GB SSD | +| **OS** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS | +| **Domain** | Registered on Cloudflare | โ€” | +| **Docker** | Docker Engine 24+ | Docker 27+ | + +**Tested providers**: Akamai (Linode), DigitalOcean, Vultr, Hetzner, AWS Lightsail. + +--- + +## 1. Configure the VM + +### 1.1 Create the instance + +On your preferred VPS provider: + +- Choose Ubuntu 24.04 LTS +- Select the minimum plan (1 vCPU / 1 GB RAM) +- Set a strong root password or configure SSH key +- Note the **public IP** (e.g., `203.0.113.10`) + +### 1.2 Connect via SSH + +```bash +ssh root@203.0.113.10 +``` + +### 1.3 Update the system + +```bash +apt update && apt upgrade -y +``` + +### 1.4 Install Docker + +```bash +# Install dependencies +apt install -y ca-certificates curl gnupg + +# Add official Docker repository +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 Install nginx + +```bash +apt install -y nginx +``` + +### 1.6 Configure 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 +``` + +> **Tip**: For maximum security, restrict ports 80 and 443 to Cloudflare IPs only. See the [Advanced Security](#advanced-security) section. + +--- + +## 2. Install OmniRoute + +### 2.1 Create configuration directory + +```bash +mkdir -p /opt/omniroute +``` + +### 2.2 Create environment variables file + +```bash +cat > /opt/omniroute/.env << โ€˜EOFโ€™ +# === Security === +JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY +INITIAL_PASSWORD=YourSecurePassword123! +API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY +STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY +STORAGE_ENCRYPTION_KEY_VERSION=v1 +MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT + +# === 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 (change to your domain) === +BASE_URL=https://llms.seudominio.com +NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com + +# === Cloud Sync (optional) === +# CLOUD_URL=https://cloud.omniroute.online +# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online +EOF +``` + +> โš ๏ธ **IMPORTANT**: Generate unique secret keys! Use `openssl rand -hex 32` for each key. + +### 2.3 Start the 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 Verify that it is running + +```bash +docker ps | grep omniroute +docker logs omniroute --tail 20 +``` + +It should display: `[DB] SQLite database ready` and `listening on port 20128`. + +--- + +## 3. Configure nginx (Reverse Proxy) + +### 3.1 Generate SSL certificate (Cloudflare Origin) + +In the Cloudflare dashboard: + +1. Go to **SSL/TLS โ†’ Origin Server** +2. Click **Create Certificate** +3. Keep the defaults (15 years, \*.yourdomain.com) +4. Copy the **Origin Certificate** and the **Private Key** + +```bash +mkdir -p /etc/nginx/ssl + +# Paste the certificate +nano /etc/nginx/ssl/origin.crt + +# Paste the private key +nano /etc/nginx/ssl/origin.key + +chmod 600 /etc/nginx/ssl/origin.key +``` + +### 3.2 Nginx Configuration + +```bash +cat > /etc/nginx/sites-available/omniroute << โ€˜NGINXโ€™ +# Default server โ€” blocks direct access via 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.yourdomain.com; # Change to your domain + + 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.yourdomain.com; + return 301 https://$server_name$request_uri; +} +NGINX +``` + +### 3.3 Enable and Test + +```bash +# Remove default configuration +rm -f /etc/nginx/sites-enabled/default + +# Enable OmniRoute +ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute + +# Test and reload +nginx -t && systemctl reload nginx +``` + +--- + +## 4. Configure Cloudflare DNS + +### 4.1 Add DNS record + +In the Cloudflare dashboard โ†’ DNS: + +| Type | Name | Content | Proxy | +| ---- | ------ | ---------------------- | ---------- | +| A | `llms` | `203.0.113.10` (VM IP) | โœ… Proxied | + +### 4.2 Configure SSL + +Under **SSL/TLS โ†’ Overview**: + +- Mode: **Full (Strict)** + +Under **SSL/TLS โ†’ Edge Certificates**: + +- Always Use HTTPS: โœ… On +- Minimum TLS Version: TLS 1.2 +- Automatic HTTPS Rewrites: โœ… On + +### 4.3 Testing + +```bash +curl -sI https://llms.seudominio.com/health +# Should return HTTP/2 200 +``` + +--- + +## 5. Operations and Maintenance + +### Upgrade to a new version + +```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 +``` + +### View logs + +```bash +docker logs -f omniroute # Real-time stream +docker logs omniroute --tail 50 # Last 50 lines +``` + +### Manual database backup + +```bash +# Copy data from the volume to the host +docker cp omniroute:/app/data ./backup-$(date +%F) + +# Or compress the entire volume +docker run --rm -v omniroute-data:/data -v $(pwd):/backup \ + alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data +``` + +### Restore from 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. Advanced Security + +### Restrict nginx to Cloudflare IPs + +```bash +cat > /etc/nginx/cloudflare-ips.conf << โ€˜CFโ€™ +# Cloudflare IPv4 ranges โ€” update periodically +# 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 +``` + +Add the following to `nginx.conf` inside the `http {}` block: + +```nginx +include /etc/nginx/cloudflare-ips.conf; +``` + +### Install fail2ban + +```bash +apt install -y fail2ban +systemctl enable fail2ban +systemctl start fail2ban + +# Check status +fail2ban-client status sshd +``` + +### Block direct access to the Docker port + +```bash +# Prevent direct external access to port 20128 +iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP +iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT + +# Persist the rules +apt install -y iptables-persistent +netfilter-persistent save +``` + +--- + +## 7. Deploy to Cloudflare Workers (Optional) + +For remote access via Cloudflare Workers (without exposing the VM directly): + +```bash +# In the local repository +cd omnirouteCloud +npm install +npx wrangler login +npx wrangler deploy +``` + +See the full documentation at [omnirouteCloud/README.md](../omnirouteCloud/README.md). + +--- + +## Port Summary + +| Port | Service | Access | +| ----- | ----------- | -------------------------- | +| 22 | SSH | Public (with fail2ban) | +| 80 | nginx HTTP | Redirect โ†’ HTTPS | +| 443 | nginx HTTPS | Via Cloudflare Proxy | +| 20128 | OmniRoute | Localhost only (via nginx) | diff --git a/docs/i18n/zh-CN/src/lib/a2a/README.md b/docs/i18n/zh-CN/src/lib/a2a/README.md new file mode 100644 index 0000000000..209d6e928e --- /dev/null +++ b/docs/i18n/zh-CN/src/lib/a2a/README.md @@ -0,0 +1,752 @@ +# OmniRoute A2A Server (ไธญๆ–‡๏ผˆ็ฎ€ไฝ“๏ผ‰) + +๐ŸŒ **Languages:** ๐Ÿ‡บ๐Ÿ‡ธ [English](../../../../../../src/lib/a2a/README.md) ยท ๐Ÿ‡ช๐Ÿ‡ธ [es](../../../../es/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ท [fr](../../../../fr/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ช [de](../../../../de/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡น [it](../../../../it/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡บ [ru](../../../../ru/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ณ [zh-CN](../../../../zh-CN/src/lib/a2a/README.md) ยท ๐Ÿ‡ฏ๐Ÿ‡ต [ja](../../../../ja/src/lib/a2a/README.md) ยท ๐Ÿ‡ฐ๐Ÿ‡ท [ko](../../../../ko/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฆ [ar](../../../../ar/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ณ [in](../../../../in/src/lib/a2a/README.md) ยท ๐Ÿ‡น๐Ÿ‡ญ [th](../../../../th/src/lib/a2a/README.md) ยท ๐Ÿ‡ป๐Ÿ‡ณ [vi](../../../../vi/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฉ [id](../../../../id/src/lib/a2a/README.md) ยท ๐Ÿ‡ฒ๐Ÿ‡พ [ms](../../../../ms/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ฑ [nl](../../../../nl/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ฑ [pl](../../../../pl/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ช [sv](../../../../sv/src/lib/a2a/README.md) ยท ๐Ÿ‡ณ๐Ÿ‡ด [no](../../../../no/src/lib/a2a/README.md) ยท ๐Ÿ‡ฉ๐Ÿ‡ฐ [da](../../../../da/src/lib/a2a/README.md) ยท ๐Ÿ‡ซ๐Ÿ‡ฎ [fi](../../../../fi/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡น [pt](../../../../pt/src/lib/a2a/README.md) ยท ๐Ÿ‡ท๐Ÿ‡ด [ro](../../../../ro/src/lib/a2a/README.md) ยท ๐Ÿ‡ญ๐Ÿ‡บ [hu](../../../../hu/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ฌ [bg](../../../../bg/src/lib/a2a/README.md) ยท ๐Ÿ‡ธ๐Ÿ‡ฐ [sk](../../../../sk/src/lib/a2a/README.md) ยท ๐Ÿ‡บ๐Ÿ‡ฆ [uk-UA](../../../../uk-UA/src/lib/a2a/README.md) ยท ๐Ÿ‡ฎ๐Ÿ‡ฑ [he](../../../../he/src/lib/a2a/README.md) ยท ๐Ÿ‡ต๐Ÿ‡ญ [phi](../../../../phi/src/lib/a2a/README.md) ยท ๐Ÿ‡ง๐Ÿ‡ท [pt-BR](../../../../pt-BR/src/lib/a2a/README.md) ยท ๐Ÿ‡จ๐Ÿ‡ฟ [cs](../../../../cs/src/lib/a2a/README.md) + +--- + +> **Agent-to-Agent Protocol v0.3** โ€” Enables any AI agent to use OmniRoute as an intelligent routing agent via JSON-RPC 2.0. + +The A2A Server exposes OmniRoute as a **first-class agent** that other agents can discover, delegate tasks to, and collaborate with using the [A2A Protocol](https://google.github.io/A2A/). + +--- + +## ๆžถๆž„ + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Orchestrator Agent โ”‚ +โ”‚ (LangChain, CrewAI, AutoGen, Custom Agent) โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ 1. GET /.well-known/agent.json (discover) + โ”‚ 2. POST /a2a (JSON-RPC 2.0) + โ–ผ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ OmniRoute A2A Server โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Task Manager โ”‚ โ”‚ Skill Engine โ”‚ โ”‚ SSE Streaming โ”‚ โ”‚ +โ”‚ โ”‚ (lifecycle) โ”‚โ”€โ”€โ”‚ (registry) โ”‚โ”€โ”€โ”‚ (real-time) โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ +โ”‚ Skills: โ”‚ โ”‚ +โ”‚ โ”œโ”€ smart-routing โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ””โ”€ quota-management โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ Routing Decision Logger โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ + โ–ผ OmniRoute Gateway (internal) + /v1/chat/completions, /api/combos, /api/usage/quota +``` + +--- + +## ๅฟซ้€Ÿๅผ€ๅง‹ + +### Agent Discovery + +Every A2A-compatible agent exposes an **Agent Card** at `/.well-known/agent.json`: + +```bash +curl http://localhost:20128/.well-known/agent.json +``` + +**Response:** + +```json +{ + "name": "OmniRoute", + "description": "Intelligent AI gateway with auto-routing across 50+ providers", + "url": "http://localhost:20128/a2a", + "version": "1.8.1", + "capabilities": { + "streaming": true, + "pushNotifications": false + }, + "skills": [ + { + "id": "smart-routing", + "name": "Smart Routing", + "description": "Routes prompts through OmniRoute intelligent pipeline", + "tags": ["routing", "llm", "multi-provider", "cost-optimization"], + "examples": [ + "Write a hello world in Python", + "Explain quantum computing using the cheapest provider" + ] + }, + { + "id": "quota-management", + "name": "Quota Management", + "description": "Natural-language queries about provider quotas", + "tags": ["quota", "analytics", "cost"], + "examples": [ + "Which provider has the most quota remaining?", + "Suggest a free combo for coding" + ] + } + ], + "authentication": { + "schemes": ["bearer"], + "apiKeyHeader": "Authorization" + } +} +``` + +--- + +## JSON-RPC 2.0 Methods + +### `message/send` โ€” Synchronous Execution + +Send a message to a skill and receive the complete response. + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python hello world"}], + "metadata": {"model": "auto", "combo": "fast-coding"} + } + }' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "task": { "id": "a1b2c3d4-...", "state": "completed" }, + "artifacts": [{ "type": "text", "content": "print('Hello, World!')" }], + "metadata": { + "routing_explanation": "Selected claude-sonnet via provider \"anthropic\" (latency: 1200ms, cost: $0.0030)", + "cost_envelope": { "estimated": 0.005, "actual": 0.003, "currency": "USD" }, + "resilience_trace": [ + { "event": "primary_selected", "provider": "anthropic", "timestamp": "2026-03-04T..." } + ], + "policy_verdict": { "allowed": true, "reason": "within budget and quota limits" } + } + } +} +``` + +### `message/stream` โ€” SSE Streaming + +Same as `message/send` but returns Server-Sent Events for real-time streaming. + +```bash +curl -N -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{ + "jsonrpc": "2.0", + "id": "1", + "method": "message/stream", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Explain quantum computing"}] + } + }' +``` + +**SSE Events:** + +``` +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"working"},"chunk":{"type":"text","content":"Quantum computing..."}}} + +: heartbeat 2026-03-04T21:00:00Z + +data: {"jsonrpc":"2.0","method":"message/stream","params":{"task":{"id":"...","state":"completed"},"metadata":{...}}} +``` + +### `tasks/get` โ€” Query Task Status + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"2","method":"tasks/get","params":{"taskId":"TASK_UUID"}}' +``` + +### `tasks/cancel` โ€” Cancel a Running Task + +```bash +curl -X POST http://localhost:20128/a2a \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_KEY" \ + -d '{"jsonrpc":"2.0","id":"3","method":"tasks/cancel","params":{"taskId":"TASK_UUID"}}' +``` + +--- + +## Skills Reference + +### `smart-routing` + +Routes prompts through OmniRoute's intelligent pipeline with full observability. + +**Parameters (in `metadata`):** + +| Parameter | Type | Default | Description | +| --------- | -------- | ------------ | ---------------------------------------------------------------------------------------- | +| `model` | `string` | `"auto"` | Target model (e.g., `claude-sonnet-4`, `gpt-4o`, `auto`) | +| `combo` | `string` | active combo | Specific combo to route through | +| `budget` | `number` | none | Maximum cost in USD for this request | +| `role` | `string` | none | Task role hint: `coding`, `review`, `planning`, `analysis`, `debugging`, `documentation` | + +**Returns:** + +| Field | Description | +| ------------------------------ | --------------------------------------------------------- | +| `artifacts[].content` | The LLM response text | +| `metadata.routing_explanation` | Human-readable explanation of routing decision | +| `metadata.cost_envelope` | Estimated vs actual cost with currency | +| `metadata.resilience_trace` | Array of events (primary_selected, fallback_needed, etc.) | +| `metadata.policy_verdict` | Whether the request was allowed and why | + +### `quota-management` + +Answers natural-language queries about provider quotas. + +**Query types (inferred from message content):** + +| Query Pattern | Response Type | +| ---------------------------------------------- | -------------------------------------------------------- | +| Contains `"ranking"`, `"most quota"`, `"best"` | Providers ranked by remaining quota | +| Contains `"free"`, `"suggest"` | Lists free combos or suggests free-tier providers | +| Default | Full quota summary with warnings for low-quota providers | + +--- + +## Task Lifecycle + +``` +submitted โ”€โ”€โ†’ working โ”€โ”€โ†’ completed + โ”€โ”€โ†’ failed + โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ†’ cancelled +``` + +| State | Description | +| ----------- | ----------------------------------------------------- | +| `submitted` | Task created, queued for execution | +| `working` | Skill handler is executing | +| `completed` | Execution succeeded, artifacts available | +| `failed` | Execution failed or task expired (TTL: 5 min default) | +| `cancelled` | Cancelled by client via `tasks/cancel` | + +- Terminal states: `completed`, `failed`, `cancelled` (no further transitions) +- Expired tasks in `submitted` or `working` are auto-marked as `failed` +- Tasks are garbage-collected after 2ร— TTL + +--- + +## Client Examples + +### Python โ€” Orchestrator Agent + +```python +""" +A2A Client โ€” Python example. +Discovers OmniRoute agent, sends a task, and processes the result. +""" +import requests +import json + +BASE_URL = "http://localhost:20128" +API_KEY = "your-api-key" +HEADERS = { + "Content-Type": "application/json", + "Authorization": f"Bearer {API_KEY}", +} + +# 1. Discover agent capabilities +agent_card = requests.get(f"{BASE_URL}/.well-known/agent.json").json() +print(f"Agent: {agent_card['name']} v{agent_card['version']}") +print(f"Skills: {[s['id'] for s in agent_card['skills']]}") + +# 2. Send a smart-routing task +response = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": "Write a Python quicksort implementation"}], + "metadata": { + "model": "auto", + "combo": "fast-coding", + "budget": 0.10, + } + } +}) +result = response.json()["result"] +print(f"\n๐Ÿ“ Response: {result['artifacts'][0]['content'][:200]}...") +print(f"๐Ÿ”€ Routing: {result['metadata']['routing_explanation']}") +print(f"๐Ÿ’ฐ Cost: ${result['metadata']['cost_envelope']['actual']}") +print(f"๐Ÿ›ก๏ธ Policy: {result['metadata']['policy_verdict']['reason']}") + +# 3. Query quota status +quota_resp = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "task-2", + "method": "message/send", + "params": { + "skill": "quota-management", + "messages": [{"role": "user", "content": "Which provider has the most quota remaining?"}], + } +}) +quota_result = quota_resp.json()["result"] +print(f"\n๐Ÿ“Š Quota: {quota_result['artifacts'][0]['content']}") +``` + +### TypeScript โ€” Multi-Agent Orchestrator + +```typescript +/** + * A2A Client โ€” TypeScript example. + * Shows agent discovery, task delegation, and streaming. + */ + +const BASE_URL = "http://localhost:20128"; +const API_KEY = "your-api-key"; + +interface JsonRpcResponse { + jsonrpc: "2.0"; + id: string | number; + result?: T; + error?: { code: number; message: string }; +} + +async function a2aCall(method: string, params: Record): Promise { + const resp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: `${method}-${Date.now()}`, + method, + params, + }), + }); + const json: JsonRpcResponse = await resp.json(); + if (json.error) throw new Error(`[${json.error.code}] ${json.error.message}`); + return json.result!; +} + +// โ”€โ”€ Agent Discovery โ”€โ”€ +const agentCard = await fetch(`${BASE_URL}/.well-known/agent.json`).then((r) => r.json()); +console.log(`Connected to: ${agentCard.name} (${agentCard.skills.length} skills)`); + +// โ”€โ”€ Smart Routing: Send a coding task โ”€โ”€ +const routingResult = await a2aCall("message/send", { + skill: "smart-routing", + messages: [{ role: "user", content: "Implement a Redis cache wrapper in TypeScript" }], + metadata: { model: "claude-sonnet-4", role: "coding" }, +}); +console.log("Response:", routingResult.artifacts[0].content); +console.log("Provider:", routingResult.metadata.routing_explanation); + +// โ”€โ”€ Quota Management: Find free alternatives โ”€โ”€ +const quotaResult = await a2aCall("message/send", { + skill: "quota-management", + messages: [{ role: "user", content: "Suggest free combos for documentation" }], +}); +console.log("Free combos:", quotaResult.artifacts[0].content); + +// โ”€โ”€ Streaming: Real-time response โ”€โ”€ +const streamResp = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${API_KEY}`, + }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "stream-1", + method: "message/stream", + params: { + skill: "smart-routing", + messages: [{ role: "user", content: "Explain microservices architecture" }], + }, + }), +}); + +const reader = streamResp.body!.getReader(); +const decoder = new TextDecoder(); +while (true) { + const { done, value } = await reader.read(); + if (done) break; + const chunk = decoder.decode(value); + for (const line of chunk.split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + if (event.params.chunk) { + process.stdout.write(event.params.chunk.content); + } + if (event.params.task.state === "completed") { + console.log("\nโœ… Stream completed"); + } + } + } +} +``` + +### Python โ€” LangChain A2A Integration + +```python +""" +LangChain integration โ€” Use OmniRoute A2A as a custom LLM. +""" +from langchain.llms.base import BaseLLM +from langchain.schema import LLMResult, Generation +import requests +from typing import List, Optional + +class OmniRouteA2A(BaseLLM): + base_url: str = "http://localhost:20128" + api_key: str = "" + model: str = "auto" + combo: Optional[str] = None + + @property + def _llm_type(self) -> str: + return "omniroute-a2a" + + def _call(self, prompt: str, stop: Optional[List[str]] = None, **kwargs) -> str: + response = requests.post( + f"{self.base_url}/a2a", + headers={ + "Content-Type": "application/json", + "Authorization": f"Bearer {self.api_key}", + }, + json={ + "jsonrpc": "2.0", + "id": "langchain-1", + "method": "message/send", + "params": { + "skill": "smart-routing", + "messages": [{"role": "user", "content": prompt}], + "metadata": { + "model": self.model, + **({"combo": self.combo} if self.combo else {}), + }, + }, + }, + ) + result = response.json()["result"] + return result["artifacts"][0]["content"] + + def _generate(self, prompts: List[str], stop=None, **kwargs) -> LLMResult: + return LLMResult( + generations=[[Generation(text=self._call(p, stop))] for p in prompts] + ) + +# Usage +llm = OmniRouteA2A( + base_url="http://localhost:20128", + api_key="your-key", + model="auto", + combo="fast-coding", +) +result = llm("Write a Python function to merge two sorted lists") +print(result) +``` + +### Go โ€” A2A Client + +```go +package main + +import ( + "bytes" + "encoding/json" + "fmt" + "io" + "net/http" +) + +const baseURL = "http://localhost:20128" +const apiKey = "your-api-key" + +type JsonRpcRequest struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Method string `json:"method"` + Params interface{} `json:"params"` +} + +type JsonRpcResponse struct { + Jsonrpc string `json:"jsonrpc"` + ID string `json:"id"` + Result interface{} `json:"result"` + Error *struct { + Code int `json:"code"` + Message string `json:"message"` + } `json:"error"` +} + +func a2aCall(method string, params interface{}) (*JsonRpcResponse, error) { + body, _ := json.Marshal(JsonRpcRequest{ + Jsonrpc: "2.0", + ID: "go-1", + Method: method, + Params: params, + }) + + req, _ := http.NewRequest("POST", baseURL+"/a2a", bytes.NewReader(body)) + req.Header.Set("Content-Type", "application/json") + req.Header.Set("Authorization", "Bearer "+apiKey) + + resp, err := http.DefaultClient.Do(req) + if err != nil { + return nil, err + } + defer resp.Body.Close() + data, _ := io.ReadAll(resp.Body) + + var result JsonRpcResponse + json.Unmarshal(data, &result) + return &result, nil +} + +func main() { + // Discover agent + resp, _ := http.Get(baseURL + "/.well-known/agent.json") + defer resp.Body.Close() + body, _ := io.ReadAll(resp.Body) + fmt.Println("Agent Card:", string(body)) + + // Send smart-routing task + result, _ := a2aCall("message/send", map[string]interface{}{ + "skill": "smart-routing", + "messages": []map[string]string{{"role": "user", "content": "Hello from Go!"}}, + "metadata": map[string]interface{}{"model": "auto"}, + }) + out, _ := json.MarshalIndent(result.Result, "", " ") + fmt.Println("Result:", string(out)) +} +``` + +--- + +## Use Cases + +### ๐Ÿค– Use Case 1: Multi-Agent Coding Pipeline + +An orchestrator agent delegates code generation to OmniRoute, then passes the output to a review agent. + +```python +def coding_pipeline(task: str): + # Step 1: Generate code via OmniRoute A2A + code_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Write production-quality code: {task}"} + ], metadata={"model": "auto", "role": "coding"}) + code = code_result["artifacts"][0]["content"] + + # Step 2: Review the code via OmniRoute A2A (different model) + review_result = a2a_send("smart-routing", [ + {"role": "user", "content": f"Review this code for bugs and improvements:\n\n{code}"} + ], metadata={"model": "auto", "role": "review"}) + review = review_result["artifacts"][0]["content"] + + # Step 3: Check costs + print(f"Code cost: ${code_result['metadata']['cost_envelope']['actual']}") + print(f"Review cost: ${review_result['metadata']['cost_envelope']['actual']}") + + return {"code": code, "review": review} +``` + +### ๐Ÿ’ก Use Case 2: Quota-Aware Agent Swarm + +Multiple agents share quota through OmniRoute, using the quota skill to coordinate. + +```python +async def quota_aware_agent(agent_name: str, task: str): + # Check quota before starting + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Which provider has the most quota remaining?"} + ]) + print(f"[{agent_name}] {quota['artifacts'][0]['content']}") + + # Send request with budget constraint + result = a2a_send("smart-routing", [ + {"role": "user", "content": task} + ], metadata={"budget": 0.05}) + + policy = result["metadata"]["policy_verdict"] + if not policy["allowed"]: + print(f"[{agent_name}] โš ๏ธ Budget exceeded: {policy['reason']}") + # Fall back to free combo + quota = a2a_send("quota-management", [ + {"role": "user", "content": "Suggest free combos"} + ]) + print(f"[{agent_name}] Free alternatives: {quota['artifacts'][0]['content']}") + + return result +``` + +### ๐Ÿ“Š Use Case 3: Real-Time Streaming Dashboard + +A monitoring agent streams responses and displays progress in real-time. + +```typescript +async function streamingDashboard(prompt: string) { + const response = await fetch(`${BASE_URL}/a2a`, { + method: "POST", + headers: { "Content-Type": "application/json", Authorization: `Bearer ${API_KEY}` }, + body: JSON.stringify({ + jsonrpc: "2.0", + id: "dash-1", + method: "message/stream", + params: { skill: "smart-routing", messages: [{ role: "user", content: prompt }] }, + }), + }); + + let totalChunks = 0; + const reader = response.body!.getReader(); + const decoder = new TextDecoder(); + + while (true) { + const { done, value } = await reader.read(); + if (done) break; + + for (const line of decoder.decode(value).split("\n")) { + if (line.startsWith("data: ")) { + const event = JSON.parse(line.slice(6)); + const state = event.params.task.state; + + if (state === "working" && event.params.chunk) { + totalChunks++; + process.stdout.write( + `\r[Chunk ${totalChunks}] ${event.params.chunk.content.slice(0, 50)}...` + ); + } + if (state === "completed") { + const meta = event.params.metadata; + console.log( + `\nโœ… Done | Cost: $${meta?.cost_envelope?.actual || 0} | Route: ${meta?.routing_explanation || "N/A"}` + ); + } + if (state === "failed") { + console.error(`\nโŒ Failed: ${event.params.metadata?.error}`); + } + } + } + } +} +``` + +### ๐Ÿ” Use Case 4: Task Polling Pattern + +For long-running tasks, poll the task status instead of waiting synchronously. + +```python +import time + +def poll_task(task_id: str, timeout: int = 60): + """Poll task status until completion or timeout.""" + start = time.time() + while time.time() - start < timeout: + result = requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "poll-1", + "method": "tasks/get", + "params": {"taskId": task_id}, + }).json() + + task = result["result"]["task"] + state = task["state"] + print(f" Task {task_id[:8]}... state={state}") + + if state in ("completed", "failed", "cancelled"): + return task + time.sleep(2) + + # Timeout โ€” cancel the task + requests.post(f"{BASE_URL}/a2a", headers=HEADERS, json={ + "jsonrpc": "2.0", + "id": "cancel-1", + "method": "tasks/cancel", + "params": {"taskId": task_id}, + }) + raise TimeoutError(f"Task {task_id} timed out after {timeout}s") +``` + +--- + +## Error Codes + +| Code | Constant | Meaning | +| ------ | ------------------------ | ---------------------------------------- | +| -32700 | โ€” | Parse error (invalid JSON) | +| -32600 | `INVALID_REQUEST` | Invalid JSON-RPC request or unauthorized | +| -32601 | `METHOD_NOT_FOUND` | Unknown method or skill | +| -32602 | `INVALID_PARAMS` | Missing or invalid parameters | +| -32603 | `INTERNAL_ERROR` | Skill execution failed | +| -32001 | `TASK_NOT_FOUND` | Task ID not found | +| -32002 | `TASK_ALREADY_COMPLETED` | Cannot modify a completed task | +| -32003 | `UNAUTHORIZED` | Invalid or missing API key | +| -32004 | `BUDGET_EXCEEDED` | Request exceeds configured budget | +| -32005 | `PROVIDER_UNAVAILABLE` | No available providers | + +--- + +## Authentication + +All `/a2a` requests require a Bearer token via the `Authorization` header: + +``` +Authorization: Bearer YOUR_OMNIROUTE_API_KEY +``` + +If no API key is configured on the server (`OMNIROUTE_API_KEY` is empty), authentication is bypassed. + +--- + +## File Structure + +``` +src/lib/a2a/ +โ”œโ”€โ”€ taskManager.ts # Task lifecycle (create/update/cancel/list), TTL, cleanup +โ”œโ”€โ”€ taskExecution.ts # Generic task executor with state management +โ”œโ”€โ”€ streaming.ts # SSE stream formatting, heartbeat, chunk/completion events +โ”œโ”€โ”€ routingLogger.ts # Routing decision logger (stats, history, retention) +โ””โ”€โ”€ skills/ + โ”œโ”€โ”€ smartRouting.ts # Smart routing skill (routes via /v1/chat/completions) + โ””โ”€โ”€ quotaManagement.ts # Quota management skill (natural-language quota queries) + +src/app/a2a/ +โ””โ”€โ”€ route.ts # Next.js API route handler (JSON-RPC 2.0 dispatch) + +open-sse/mcp-server/ +โ””โ”€โ”€ schemas/a2a.ts # Zod schemas (AgentCard, Task, JSON-RPC, SSE events) +``` + +--- + +## Comparison: MCP vs A2A + +| Feature | MCP Server | A2A Server | +| ----------------- | ---------------------------- | ------------------------------------------------- | +| **Protocol** | Model Context Protocol | Agent-to-Agent Protocol v0.3 | +| **Transport** | stdio / HTTP | HTTP (JSON-RPC 2.0) | +| **Discovery** | Tool listing via MCP | `/.well-known/agent.json` | +| **Granularity** | 16 individual tools | 2 high-level skills | +| **Best for** | IDE agents (Cursor, VS Code) | Multi-agent systems (LangChain, CrewAI) | +| **Streaming** | Not supported | SSE via `message/stream` | +| **Task tracking** | No | Full lifecycle (submitted โ†’ completed) | +| **Observability** | Audit log per tool call | Cost envelope + resilience trace + policy verdict | + +--- + +## ่ฎธๅฏ่ฏ + +Part of [OmniRoute](https://github.com/diegosouzapw/OmniRoute) โ€” MIT License. diff --git a/typescript b/typescript deleted file mode 100644 index e69de29bb2..0000000000