87 lines
3.3 KiB
Markdown
87 lines
3.3 KiB
Markdown
# nexus-claude-api PRD
|
|
|
|
## Product Overview
|
|
|
|
`nexus-claude-api` is a local Python API proxy that lets Claude Code use company-approved Claude models through AI Nexus.
|
|
|
|
AI Nexus currently documents that the Anthropic Messages API is temporarily unsupported and recommends AWS Bedrock Converse API as the workaround. Claude Code expects an Anthropic-compatible Messages API. This project bridges that gap locally.
|
|
|
|
Reference: [AI_NEXUS_CLAUDE.md](AI_NEXUS_CLAUDE.md)
|
|
|
|
## Users
|
|
|
|
Target users are internal developers who:
|
|
|
|
- Have an AI Nexus API key.
|
|
- Want to use Claude Code with company-approved Claude models.
|
|
- Work primarily in local development environments.
|
|
- Need Claude Code workflows such as code editing, tool use, and streaming responses.
|
|
|
|
## Goals
|
|
|
|
- Provide a local Anthropic-compatible API for Claude Code.
|
|
- Start locally with a command similar to `copilot-api`.
|
|
- Convert Anthropic Messages requests to AI Nexus Bedrock Converse requests.
|
|
- Convert Nexus responses back to Anthropic Messages responses.
|
|
- Support text, streaming, tools, tool results, and image inputs.
|
|
- Provide model discovery and token-count compatibility endpoints.
|
|
- Keep credentials local and avoid logging secrets.
|
|
|
|
## Non-goals
|
|
|
|
The first version will not include:
|
|
|
|
- OpenAI-compatible `/v1/chat/completions`.
|
|
- A dashboard.
|
|
- Nexus API key provisioning.
|
|
- Multi-user hosted gateway deployment.
|
|
- Database persistence.
|
|
- Direct Anthropic public API forwarding.
|
|
|
|
## Supported Models
|
|
|
|
The local API exposes:
|
|
|
|
- `claude-sonnet-4.6`
|
|
- `claude-opus-4.6`
|
|
- `claude-haiku-4.5`
|
|
|
|
Defaults:
|
|
|
|
- Main model: `claude-sonnet-4.6`
|
|
- Small model: `claude-haiku-4.5`
|
|
|
|
`claude-sonnet-4.6` is the default because the AI Nexus documentation recommends it as the cost-effective default for most use cases.
|
|
|
|
## User Stories
|
|
|
|
- As a developer, I can store my Nexus key in ignored local config or set `NEXUS_API_KEY`, then run `nexus-claude-api start --claude-code` to get a Claude Code launch command.
|
|
- As a Claude Code user, I can run coding workflows through local `http://127.0.0.1:4141`.
|
|
- As a Claude Code user, I can receive streaming model output.
|
|
- As a Claude Code user, I can use tool calls and tool results.
|
|
- As a multimodal user, I can send images through Claude-compatible image content blocks.
|
|
- As a developer debugging setup, I can enable verbose logs without exposing tokens.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- `uv run nexus-claude-api start --port 4141 --claude-code` starts a local server.
|
|
- The server binds to `127.0.0.1` by default.
|
|
- Missing Nexus credentials fail fast with a clear error.
|
|
- `GET /health` returns healthy status.
|
|
- `GET /v1/models` returns the supported Claude models.
|
|
- `POST /v1/messages` works for non-streaming text generation.
|
|
- `POST /v1/messages` works for streaming text generation.
|
|
- Tool use and tool result conversion are covered by tests.
|
|
- Image block conversion is covered by tests.
|
|
- `POST /v1/messages/count_tokens` returns an Anthropic-compatible token count response.
|
|
- Claude Code can be launched with the printed environment command.
|
|
|
|
## Security Requirements
|
|
|
|
- Do not persist API keys automatically.
|
|
- If the user chooses hardcoded local configuration, keep it in ignored `nexus-claude-api.local.json`.
|
|
- Do not print or log API keys.
|
|
- Redact authorization headers in debug logs.
|
|
- Bind locally by default.
|
|
- Allow `0.0.0.0` only when explicitly requested.
|