AIRegulation/nexus-claude-api
7
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2851fa01cf2e60061621641dddf6dfeea51218da
nexus-claude-api/docs/PRD.md
Guangfei.Zhao 2851fa01cf initial commits
2026-06-26 17:02:21 +08:00

3.3 KiB
Raw Blame History

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

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.