Integrate with AI

Integrate only Claude models through HopBase in the current project. Follow this contract exactly; where it differs from the vendor's own API docs, this contract wins.

Scope
- Implement only the Claude API (Anthropic Messages) or Claude Code. Do not add, configure, or test any other model family.
- Keep the existing framework, SDKs, and code style; make the smallest change that works.
- First decide whether this is a local single-user tool, an internal service, or an application serving downstream customers or tenants; that decides key placement and architecture.

Key
- Use only a Claude-family key. Each key is bound to one console group and reaches only that group's models:
  - SDK, HTTP, editors, and Claude Code: "Claude Max (Official, Full Quota)" or "Claude Max (Official, Full Quota) - Limited-Time Offer".
  - "Claude Max (ccmax)" works only inside the Claude Code client; SDK or HTTP calls with that key fail.
- In a multi-model project read HOPBASE_CLAUDE_API_KEY or the existing secret manager; reuse HOPBASE_API_KEY only in an explicitly single-model project.
- Never create a key, read another family's key, or ask me to paste a real key into the conversation. If the key is missing, stop and ask me to create a key for the right group under API Keys in the console and configure it locally or in the secret manager.

Models
- First call GET https://api.hop-base.com/v1/models with this key and use only IDs beginning with claude- from the response, copied verbatim.
- On sale: claude-fable-5-1, claude-sonnet-5, claude-sonnet-5-5, claude-opus-5-5, claude-fable-5, claude-opus-5, claude-opus-4-8, claude-opus-4-7, claude-opus-4-6, claude-sonnet-4-6, claude-haiku-4-5-20251001.
- 404 model_not_found means the ID is not in this key's group: fetch /v1/models again and use a returned ID. Never guess, shorten, or rewrite a model name.

Connection
- Base URL https://api.hop-base.com without /v1 (the SDK appends /v1/messages). A Base URL ending in /v1 produces /v1/v1/messages and a 404.
- Auth: the SDK api_key option, or the x-api-key header for raw HTTP. Keep SDK-native authentication.
- Endpoints: POST /v1/messages and POST /v1/messages/count_tokens. OpenAI paths (/v1/chat/completions, /v1/responses) return 404 with a Claude key; never convert Messages calls to Chat Completions.
- Claude Code: ANTHROPIC_BASE_URL=https://api.hop-base.com and ANTHROPIC_AUTH_TOKEN=<Claude key>. One-click setup writes both into the env block of ~/.claude/settings.json, which overrides shell variables.

Request rules
- Always send max_tokens. When omitted it is filled in as 4096 and long output stops with stop_reason "max_tokens".
- claude-opus-5-5: thinking is always on — thinking {"type":"disabled"} or budget_tokens returns 400; set depth with output_config.effort (default medium). tool_choice any / tool returns 400 (use auto). Assistant prefill is not supported.
- Pass earlier thinking blocks back exactly as received, signature included. Rewriting, merging, or reusing them across models returns 400 "Invalid signature in thinking block".
- Non-streaming calls are capped at 300 s (then 504). Stream long outputs and pass Anthropic SSE through unchanged; count_tokens calls also consume concurrency.

Errors and retries
- Branch on the HTTP status and error.code, never on message text. Log the x-request-id response header for support.
- Retry with backoff (2 s, 5 s, 15 s; at most 3 attempts; honor Retry-After): 429, 502, 503, 504, and interrupted streams.
- Never retry unchanged: 400, 401, 402, 403, 404, 413, 422. Fix the request, key, group, or balance first.
- Anthropic-shape errors carry no code field. Key errors (401, 402, 403) use the OpenAI shape {"error":{"code":…}} even on /v1/messages.
- 404 "This API path is not supported by the current platform" = wrong protocol or an extra /v1 in the Base URL. Fix the configuration; do not retry.
- A stream that has started fails with an event: error line while HTTP stays 200; handle it in the read loop and reissue the whole request.

Implementation
- Put the Base URL, key variable name, and default model into the existing configuration system. Update .env.example without a real key.
- Downstream or multi-tenant calls must keep the key on the server, reuse caller authentication, and add a model allowlist, request limits, timeouts, rate limiting, usage attribution, and redacted logs. A local single-user tool gets none of that extra layer.
- An account runs 5 requests at a time by default; above that the request is rejected at once with 429 and Retry-After: 1, not queued. Throttle on the client.

Validation and handoff
- Send one minimal real request after configuration. Add a streaming test only when the project actually streams.
- Send one Messages request with max_tokens 1024 asking a returned claude- model to reply "ok", and verify content[0].text.
- Report changed files, the key variable name, model ID, endpoint, HTTP status, and a redacted response summary, plus start, verification, and rollback commands.