AIRegulation/nexus-claude-api
7
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4685a0165d033040cb870411ca1d3358635bb122
nexus-claude-api/AGENTS.md
Guangfei.Zhao 0e98ce57d4 Refactor models and logging for nexus-claude-api 
- Update default models in config to use `claude-opus-4.6`.
- Introduce logging configuration to write logs to a file.
- Add correlation ID to error responses for better traceability.
- Implement diagnostics for summarizing message requests.
- Normalize legacy system messages in the API.
- Enhance tests to cover new logging and error handling features.
- Update README and documentation to reflect changes in model defaults and logging behavior.
2026-06-26 22:36:09 +08:00

2.8 KiB
Raw Blame History

AGENTS.md

Repo shape

  • Single Python package repo. Runtime code lives in src/nexus_claude_api/, tests in tests/, design/product docs in docs/.
  • There is no monorepo/workspace layer, no task runner, and no repo-configured lint/typecheck/build command. Do not invent those steps in plans or completion reports.

Commands that are actually supported

  • Install dev dependencies: uv sync --extra dev
  • Start the local proxy and print the Claude Code helper: uv run nexus-claude-api start --port 4141 --claude-code
  • Fast config check without starting the server: uv run nexus-claude-api start --dry-run
  • Run all tests: uv run pytest
  • Run focused tests: uv run pytest tests/test_cli.py or uv run pytest tests/test_routes.py -k messages_stream

Real entrypoints and change boundaries

  • CLI entrypoint is src/nexus_claude_api/cli.py; src/nexus_claude_api/__main__.py just forwards to it.
  • FastAPI app wiring is in src/nexus_claude_api/server.py; it stores settings and nexus_client on app.state.
  • The main HTTP behavior is in src/nexus_claude_api/routes/messages.py. That file owns request validation, Anthropic→Bedrock translation, SSE streaming, and Anthropic-shaped error responses.
  • Translation boundaries live under src/nexus_claude_api/translators/. Upstream Nexus/Bedrock transport lives in src/nexus_claude_api/nexus_client.py.

Runtime/config facts worth preserving

  • Credential lookup order is fixed in Settings.from_values(): --api-key -> nexus-claude-api.local.json -> NEXUS_API_KEY -> AWS_BEARER_TOKEN_BEDROCK.
  • nexus-claude-api.local.json is gitignored and may exist locally; never commit it or overwrite it casually while testing.
  • NexusClient writes settings.api_key back into AWS_BEARER_TOKEN_BEDROCK before building the boto3 Bedrock client. Keep that side effect in mind for tests and env-sensitive refactors.
  • Defaults from src/nexus_claude_api/config.py: host 127.0.0.1, port 4141, endpoint https://genai-nexus.api.corpinter.net, main model claude-opus-4.6, small model claude-opus-4.6. Sonnet and Haiku aliases intentionally resolve to Opus for users who only have Opus access.
  • The Claude Code helper from src/nexus_claude_api/shell.py intentionally sets ANTHROPIC_AUTH_TOKEN='dummy'. That placeholder is only for Claude Code compatibility; it is not the Nexus key.

Repo-specific verification gotchas

  • Tests rely on pytest pythonpath = ["src"] from pyproject.toml; keep the src-layout imports intact.
  • tests/test_cli.py uses per-test temp workspaces under .test-tmp/. Logging writes to logs/nexus-claude-api.log. Both paths are gitignored.
  • If you change request/error/logging behavior, re-run uv run pytest tests/test_routes.py. It covers SSE responses, correlation IDs, and the requirement that logs do not leak API keys, Authorization, or raw payload blobs.