nexus-claude-api/docs/REQUIREMENTS_DESIGN.md

nexus-claude-api Requirements Design

Technical Stack

• Python >=3.11
• Package manager: uv
• Web framework: FastAPI
• ASGI server: Uvicorn
• Nexus client: boto3 Bedrock Runtime client
• Validation: Pydantic
• CLI: standard library argparse
• Tests: pytest

All project dependencies must be managed by uv and the project virtual environment. Do not install global Python dependencies.

Project Structure

nexus-claude-api/
  pyproject.toml
  README.md
  docs/
    AI_NEXUS_CLAUDE.md
    PRD.md
    REQUIREMENTS_DESIGN.md
  src/
    nexus_claude_api/
      __init__.py
      __main__.py
      cli.py
      config.py
      errors.py
      models.py
      nexus_client.py
      server.py
      shell.py
      tokens.py
      routes/
        health.py
        messages.py
        models.py
      translators/
        anthropic_to_bedrock.py
        bedrock_to_anthropic.py
        stream.py
  tests/

CLI Contract

Primary command:

uv run nexus-claude-api start --port 4141 --claude-code

Options:

• --host: default 127.0.0.1
• --port, -p: default 4141
• --endpoint-url: default https://genai-nexus.api.corpinter.net
• --api-key: optional; fallback to ignored local config, NEXUS_API_KEY, then AWS_BEARER_TOKEN_BEDROCK
• --model: default claude-sonnet-4.6
• --small-model: default claude-haiku-4.5
• --claude-code: print Claude Code launch command
• --verbose, -v: debug logging without secrets

When --claude-code is used, print a PowerShell command that sets:

• ANTHROPIC_BASE_URL
• ANTHROPIC_AUTH_TOKEN
• ANTHROPIC_MODEL
• ANTHROPIC_DEFAULT_SONNET_MODEL
• ANTHROPIC_DEFAULT_OPUS_MODEL
• ANTHROPIC_SMALL_FAST_MODEL
• ANTHROPIC_DEFAULT_HAIKU_MODEL
• DISABLE_NON_ESSENTIAL_MODEL_CALLS
• CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC

HTTP API Contract

Expose:

• GET /
• GET /health
• GET /v1/models
• POST /v1/messages
• POST /v1/messages/count_tokens

ANTHROPIC_AUTH_TOKEN is printed as dummy because Claude Code expects an Anthropic auth token variable to exist. This local proxy does not validate that inbound token by default. It is not the Nexus key.

Inbound authentication headers are accepted for compatibility but not validated by default because the service is local. Outbound Nexus authentication uses --api-key, ignored local nexus-claude-api.local.json, NEXUS_API_KEY, or AWS_BEARER_TOKEN_BEDROCK.

Model Mapping

Public local model IDs:

• claude-sonnet-4.6
• claude-opus-4.6
• claude-haiku-4.5

Backend IDs are resolved through a mapping table. The initial default mapping keeps the same IDs, except common short aliases are supported:

• claude-sonnet-4 -> claude-sonnet-4.6
• claude-opus-4 -> claude-opus-4.6
• claude-haiku-4 -> claude-haiku-4.5

If Nexus requires different backend IDs, update the mapping without changing Claude Code-facing model IDs.

Request Translation

Anthropic to Bedrock:

• model -> modelId
• messages[].role -> role
• string content -> { "text": "..." }
• { "type": "text", "text": "..." } -> { "text": "..." }
• Anthropic image block -> Bedrock image block
• assistant tool_use -> Bedrock toolUse
• user tool_result -> Bedrock toolResult
• system -> Bedrock system
• max_tokens, temperature, top_p -> inferenceConfig
• stop_sequences -> stopSequences
• tools and tool_choice -> toolConfig

Unsupported content blocks should return 400 invalid_request_error.

Response Translation

Bedrock to Anthropic:

• Bedrock text content -> Anthropic text block.
• Bedrock toolUse -> Anthropic tool_use.
• Bedrock usage -> Anthropic usage.
• Bedrock stop reason maps to Anthropic stop reason.

Stop reason mapping:

• end_turn -> end_turn
• max_tokens -> max_tokens
• stop_sequence -> stop_sequence
• tool_use -> tool_use
• unknown -> end_turn

Streaming Translation

Use converse_stream.

Translate Bedrock stream events to Anthropic SSE events:

• messageStart -> message_start
• contentBlockStart -> content_block_start
• contentBlockDelta.delta.text -> content_block_delta with text_delta
• tool input deltas -> content_block_delta with input_json_delta
• contentBlockStop -> content_block_stop
• messageStop -> message_delta, then message_stop
• metadata.usage -> usage update on final message_delta
• backend error -> error

SSE frame format:

event: <event_type>
data: <json>

Error Handling

Return Anthropic-compatible errors:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "..."
  }
}

Status mapping:

• invalid request: 400
• missing local Nexus credential: startup failure
• Nexus auth failure: 401 or 403
• Nexus throttling: 429
• Nexus network/timeout: 502 or 504
• unexpected server error: 500

Testing

Unit tests:

• Minimal Anthropic text request -> Bedrock payload.
• System prompt conversion.
• Image block conversion.
• Tool config conversion.
• Tool use and tool result conversion.
• Bedrock text response -> Anthropic response.
• Bedrock tool response -> Anthropic tool response.
• Bedrock streaming events -> Anthropic SSE sequence.
• Token counting approximation.

Route tests:

• GET /health
• GET /v1/models
• POST /v1/messages non-stream
• POST /v1/messages stream
• POST /v1/messages/count_tokens

CLI tests:

• nexus-claude-api --help
• Claude Code command generation.
• Missing API key validation.