diff --git a/README.md b/README.md index cb981b5b..dbc10eb3 100644 --- a/README.md +++ b/README.md @@ -50,6 +50,25 @@ ccs glm ccs ollama ``` +## OpenAI-Compatible Routing + +CCS can now bridge Claude Code into OpenAI-compatible providers through a local +Anthropic-compatible proxy instead of requiring a native Anthropic upstream. + +```bash +ccs api create --preset hf +ccs hf +``` + +Need to manage the proxy manually? + +```bash +ccs proxy start hf +eval "$(ccs proxy activate)" +``` + +Guide: [OpenAI-Compatible Provider Routing](./docs/openai-compatible-providers.md) + Need the full setup path instead of the short version? | Need | Start here | diff --git a/docs/openai-compatible-providers.md b/docs/openai-compatible-providers.md new file mode 100644 index 00000000..9a8a0466 --- /dev/null +++ b/docs/openai-compatible-providers.md @@ -0,0 +1,135 @@ +# OpenAI-Compatible Provider Routing + +CCS can route Claude Code traffic through a local Anthropic-compatible proxy when +your API profile points at an OpenAI-compatible chat completions endpoint. + +This is useful for providers such as: + +- Hugging Face Inference Providers +- OpenRouter +- Ollama +- llama.cpp servers +- OpenAI-compatible self-hosted gateways + +## What CCS Does + +When you launch a compatible settings profile with the Claude target, CCS now: + +1. Starts a local proxy on `127.0.0.1` +2. Accepts Anthropic `/v1/messages` traffic from Claude Code +3. Translates requests into OpenAI chat-completions format +4. Forwards them to your configured upstream provider +5. Translates streaming responses back into Anthropic SSE + +You do not need to rewrite your profile by hand each time. + +## Quick Start + +Create or reuse an API profile that points at an OpenAI-compatible endpoint: + +```bash +ccs api create --preset hf +``` + +Then you can use the profile directly: + +```bash +ccs hf +``` + +CCS detects that the profile is OpenAI-compatible and auto-routes Claude Code +through the local proxy. + +## Manual Proxy Lifecycle + +If you want to manage the proxy explicitly: + +```bash +ccs proxy start hf +eval "$(ccs proxy activate)" +ccs proxy status +ccs proxy stop +``` + +`ccs proxy activate` prints the `ANTHROPIC_*` exports needed for a local +Anthropic-compatible session against the running proxy. + +## One Active Proxy Profile + +The current runtime is a single local proxy daemon. + +- Reusing the same OpenAI-compatible profile is supported +- Starting a different OpenAI-compatible profile while one proxy is already + running is rejected instead of silently replacing the active upstream + +This is intentional to avoid breaking an in-flight Claude session by swapping +its upstream provider out from under it. + +## How Profile Detection Works + +CCS keeps these profiles in the normal API/settings-profile flow. + +Anthropic-compatible endpoints such as: + +- `https://api.anthropic.com` +- `https://api.z.ai/api/anthropic` +- `https://api.deepseek.com/anthropic` + +continue to launch directly. + +OpenAI-compatible endpoints such as: + +- `https://router.huggingface.co/v1` +- `https://api.openai.com/v1` +- `http://localhost:11434` + +are routed through the local proxy for Claude-target launches. + +## Self-Signed TLS + +If your upstream gateway uses a self-signed or privately issued certificate, +set this in the profile settings JSON: + +```json +{ + "env": { + "CCS_OPENAI_PROXY_INSECURE": "1" + } +} +``` + +That flag is respected by both: + +- `ccs ` auto-routing +- `ccs proxy start ` + +## Supported Runtime Paths + +- `ccs ` with Claude target: auto-starts the local proxy when needed +- `ccs proxy start `: starts the proxy explicitly +- `GET /health`: proxy liveness check +- `GET /v1/models`: local view of the configured model mapping +- `POST /v1/messages`: Anthropic-compatible request entrypoint + +## Validation + +The shipped coverage includes: + +- unit tests for OpenAI-compatible profile detection +- unit tests for Anthropic -> OpenAI request translation +- unit tests for multi-line SSE parsing +- integration tests for `/v1/messages` request/response translation +- integration tests for daemon lifecycle and `/health` / `/v1/models` +- e2e tests for `ccs proxy` lifecycle +- e2e tests for `ccs ` auto-routing through a mock upstream + +## Current Scope + +The current implementation focuses on the core routing path: + +- local proxy lifecycle +- Anthropic/OpenAI request-response translation +- Claude-target settings profile auto-routing + +Scenario-based routing and token-count-driven model switching remain follow-up +work if they are needed beyond the base provider-routing flow. diff --git a/docs/project-roadmap.md b/docs/project-roadmap.md index 4f977fdd..3b82689d 100644 --- a/docs/project-roadmap.md +++ b/docs/project-roadmap.md @@ -1,6 +1,6 @@ # CCS Project Roadmap -Last Updated: 2026-04-10 +Last Updated: 2026-04-14 Forward-looking roadmap documenting current priorities, GitHub issues, and future feature plans. @@ -41,6 +41,7 @@ All major modularization work is complete. The codebase evolved from monolithic ### Recent Fixes +- **2026-04-14**: **#991** CCS now auto-routes Claude-target settings profiles that use OpenAI-compatible endpoints through a local Anthropic-compatible proxy instead of sending raw Anthropic `/v1/messages` traffic directly to chat-completions backends. The new `ccs proxy` command supports `start`, `status`, `activate`, and `stop`, the runtime exposes `/health` and `/v1/models`, the shared SSE parser now handles multi-line `data:` payloads, and the feature ships with dedicated unit, integration, and e2e coverage. - **2026-04-10**: **#765** `/providers` now includes a first-class Hugging Face preset for API Profiles. CCS exposes Hugging Face Inference Providers through the existing OpenAI-compatible profile flow with the official router endpoint `https://router.huggingface.co/v1`, a short `hf` default profile name, and `hf` preset alias support for both the dashboard chooser and `ccs api create --preset hf`. - **2026-04-10**: **#944** Image Analysis auth readiness no longer collapses to native Read when merged runtime-status dependency overrides include a missing initializer value. CCS now preserves default dependency functions when override entries are `undefined`, still reads token-backed auth status directly in the local readiness path, and includes regression coverage for the missing-initializer case that previously surfaced as `deps.initializeAccounts is not a function`. - **2026-04-10**: **#945** CCS now normalizes Gemini CLI and Antigravity tier signals around an explicit `free / pro / ultra / unknown` model, preserves raw tier ids such as `g1-pro-tier`, enriches Gemini quota responses with provider entitlement evidence, classifies `MODEL_CAPACITY_EXHAUSTED` separately from auth/entitlement failures, fixes the Antigravity CLI quota table so live quota-derived tiers no longer collapse back to stale `unknown`, adds Gemini tier ids to CLI quota output, extends Gemini Flash Lite grouping to cover `gemini-3.1-flash-lite-preview`, and allows Gemini account surfaces to render the same tier badge semantics as Antigravity.