65 lines
3.1 KiB
Markdown
65 lines
3.1 KiB
Markdown
|
# CLAUDE.md
|
||
|
|
|
||
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
|
|
||
|
|
## What This Is
|
||
|
|
|
||
|
|
A local Anthropic-compatible API proxy that lets Claude Code talk to AI Nexus Claude models. It receives Anthropic Messages API requests and translates them to AWS Bedrock Converse API calls targeting the corporate Nexus endpoint.
|
||
|
|
|
||
|
|
## Commands
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# Install dependencies
|
||
|
|
uv sync --extra dev
|
||
|
|
|
||
|
|
# Start the proxy (prints Claude Code env helper)
|
||
|
|
uv run nexus-claude-api start --port 4141 --claude-code
|
||
|
|
|
||
|
|
# Start in dev mode (local config/logs instead of ~/.config)
|
||
|
|
uv run nexus-claude-api start --dev --port 4141 --claude-code
|
||
|
|
|
||
|
|
# Validate config without starting
|
||
|
|
uv run nexus-claude-api start --dry-run
|
||
|
|
|
||
|
|
# Run all tests
|
||
|
|
uv run pytest
|
||
|
|
|
||
|
|
# Run a single test file or focused test
|
||
|
|
uv run pytest tests/test_cli.py
|
||
|
|
uv run pytest tests/test_routes.py -k messages_stream
|
||
|
|
```
|
||
|
|
|
||
|
|
There is no lint, typecheck, or build command configured. Do not invent those steps.
|
||
|
|
|
||
|
|
## Architecture
|
||
|
|
|
||
|
|
```
|
||
|
|
Claude Code → FastAPI (routes/) → NexusClient (boto3) → AI Nexus Bedrock
|
||
|
|
```
|
||
|
|
|
||
|
|
- **cli.py** — CLI entrypoint (argparse). `__main__.py` just forwards to it.
|
||
|
|
- **server.py** — App factory (`create_app`), stores `settings` and `nexus_client` on `app.state`.
|
||
|
|
- **config.py** — `Settings` frozen dataclass, credential resolution, model ID mapping, defaults.
|
||
|
|
- **nexus_client.py** — Wraps boto3 Bedrock `converse` / `converse_stream`.
|
||
|
|
- **routes/messages.py** — `POST /v1/messages` and `/v1/messages/count_tokens`. Owns request validation, translation dispatch, SSE streaming, and error shaping.
|
||
|
|
- **translators/** — `anthropic_to_bedrock.py`, `bedrock_to_anthropic.py`, `stream.py`. Pure conversion logic.
|
||
|
|
- **errors.py** — `NexusClaudeError` exception mapped to Anthropic-shaped JSON errors with correlation IDs.
|
||
|
|
- **diagnostics.py** — Request summarization for logs; deliberately omits secrets, prompt text, base64.
|
||
|
|
- **shell.py** — Generates PowerShell env vars for Claude Code (sets `ANTHROPIC_AUTH_TOKEN='dummy'` as a placeholder).
|
||
|
|
|
||
|
|
## Key Design Decisions
|
||
|
|
|
||
|
|
- **Credential priority:** `--api-key` → `nexus-claude-api.local.json` → `NEXUS_API_KEY` env → `AWS_BEARER_TOKEN_BEDROCK` env (fixed in `Settings.from_values()`).
|
||
|
|
- **Model aliasing:** Sonnet/Haiku aliases resolve to Opus because users only have Opus access.
|
||
|
|
- **Localhost only:** Server binds to `127.0.0.1`.
|
||
|
|
- **No console logging:** App logs go to files only (`~/.config/nexus-claude-api/logs/` or `./logs/` in dev mode).
|
||
|
|
- **`NexusClient` side effect:** Writes `settings.api_key` into `AWS_BEARER_TOKEN_BEDROCK` env var before building the boto3 client.
|
||
|
|
|
||
|
|
## Testing Notes
|
||
|
|
|
||
|
|
- Tests use stub clients (`FakeNexusClient`, `AccessDeniedNexusClient`) — no network calls.
|
||
|
|
- `pythonpath = ["src"]` in pyproject.toml enables src-layout imports; keep this intact.
|
||
|
|
- `tests/test_cli.py` uses per-test temp workspaces under `.test-tmp/`.
|
||
|
|
- `nexus-claude-api.local.json` is gitignored and may exist locally; never overwrite it while testing.
|
||
|
|
- After changing request/error/logging behavior, run `uv run pytest tests/test_routes.py` — it covers SSE responses, correlation IDs, and verifies logs don't leak secrets.
|