nexus-claude-api/docs/PRD.md

# 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-opus-4.6`

Defaults:

- Main model: `claude-opus-4.6`
- Small model: `claude-opus-4.6`

The proxy defaults to Opus because this deployment is intended for users whose Nexus access is limited to `claude-opus-4.6`. Sonnet and Haiku aliases are accepted for compatibility and resolved to Opus before calling Nexus.

## 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.