Phase 1: Additive anthropic provider (unblocker)

[neuromechanist]

Part of epic #155.

Goal: Add native Anthropic (AWS-billable, non-Bedrock direct billing) as an additive provider so standalone runs can use it immediately. This is the unblocker for the word-blurb 1000-image run. It does not flip any shipped default (that is Phase 3) — purely additive and low-risk.

Scope

• New provider branch in the LLM factory (src/utils/openrouter_llm.py, or a small create_llm dispatcher) for native Anthropic: prefix anthropic/<model>, key ANTHROPIC_API_KEY, optional api_base from ANTHROPIC_BASE_URL, optional workspace header from ANTHROPIC_WORKSPACE_ID (exact header name confirmed via smoke test).
• Wire --provider anthropic (CLI) and LLM_PROVIDER=anthropic selection into the standalone path (src/cli/local_executor.py:174-223, 278-290) for annotation + eval + keyword + vision LLMs.
• Preserve annotation prompt caching on the Anthropic path; fix is_cacheable_model() to return True for bare claude- ids (minimal; full universal caching is Phase 2).
• Credentials: read ANTHROPIC_* from env; minimal per-provider storage or env-only for this phase.
• Model overridable to claude-opus-4-8.

Definition of Done

• hedit annotate "<text>" --provider anthropic --model claude-opus-4-8 returns a valid HED annotation billed to AWS.
• One key-gated integration smoke test (skips when ANTHROPIC_API_KEY absent; no mocks per repo policy).
• OpenRouter and Ollama paths unchanged; shipped defaults unchanged.

Prereqs

• ANTHROPIC_API_KEY for the AWS-external account exported (ANTHROPIC_BASE_URL + ANTHROPIC_WORKSPACE_ID already known).

[neuromechanist]

Phase 1 implementation + live-endpoint findings (AWS-external Anthropic)

Branch feature/issue-156-phase1-anthropic-provider (commits d53d2dc, 1809ecd). Additive --backend anthropic / LLM_PROVIDER=anthropic selector, standalone-only, single native model for all roles, reuses CachingLLMWrapper. Lint clean; 3 unit tests pass; 73 existing OpenRouter/CLI tests unaffected.

Verified against the live AWS-external endpoint

• Transport works via both the official anthropic SDK and LiteLLM. Requests reach https://aws-external-anthropic.us-east-2.api.aws and get past client-side param validation; the only failure is auth (below). So HEDit's existing LiteLLM stack can talk to this endpoint — no forced migration to langchain-anthropic.
• Workspace id header name is anthropic-workspace-id (matches the code default), passed via extra_headers (LiteLLM) / default_headers (SDK).
• Base URL must be passed explicitly. LiteLLM's Anthropic provider reads ANTHROPIC_API_BASE, not the SDK's ANTHROPIC_BASE_URL; the factory forwards model_kwargs["api_base"] so the SDK-style env var still works.

Key learning: temperature constraint (fixed in 1809ecd)

LiteLLM: claude-opus-4-8 does not support temperature=0.0. Only temperature=1 is supported. Reasoning-tier Claude models only accept temperature=1. HEDit passes temperature=0.1 everywhere, which errors. Fix: set drop_params=True on the anthropic backend so LiteLLM drops per-model-unsupported params instead of raising (Haiku keeps 0.1; Opus drops it -> uses 1).

Reasoning / extended thinking

Native Anthropic extended thinking is off unless a thinking param is sent; the factory never sends it, so the anthropic backend produces concise HED-tags-only output with no reasoning-token bloat -- matching how annotation behaved on OpenRouter (annotation left at OpenRouter's default = thinking-off for Claude; eval/keyword explicitly disabled via reasoning.enabled=false, #148/#150). Recommendation: keep thinking off for all roles in Phase 1; making annotation thinking an explicit opt-in is a Phase 2/3 decision measured against token cost.

Open blocker: authentication (401)

Sending the full verbatim key (aws-external-anthropic-api-key-<base64>, 163 chars; the base64 decodes to a structured …AeaApiKey-… blob, i.e. an opaque token to send as-is) returns 401 authentication_error: "Invalid bearer token" under both x-api-key and Authorization: Bearer. This is a credential/provisioning issue, not a code issue -- needs the key confirmed active for this workspace + us-east-2, or the exact working invocation from the AWS/Anthropic console. Phase 1 code is validated up to auth; the live smoke test + PR are held until the credential authenticates.

[neuromechanist]

Live validation PASSED (fresh credential)

The earlier 401 was the expired/placeholder key. With a fresh short-lived credential (the key decodes to an AWS SigV4 presigned URL, Action=CallWithBearerToken, sent verbatim), everything is green:

• Auth: works via the standard x-api-key path (LiteLLM default and the SDK's api_key). No Bearer/auth_token needed.
• Full workflow smoke (hedit annotate --backend anthropic --model claude-opus-4-8): annotation + validation + evaluation all run on the native Anthropic AWS backend -> valid HED 8.4.0 (Agent-action, (Human-agent, (Ride, Bicycle)), (Urban, Road)), faithful, ~13s.
• Tests: 4/4 pass including the real-call e2e (tests/test_anthropic_provider.py).
• No reasoning bloat: a 1-word probe returned 4 output tokens; extended thinking stays off (matches OpenRouter behaviour).

Transport confirmed on both the official SDK and LiteLLM, so HEDit keeps its existing LiteLLM stack. Ready for PR.

Operational note: these credentials are ~30-min TTL, so any long batch (e.g. the 1000-image word-blurb run) needs either a longer-lived credential or a resumable runner that refreshes the key per window.

[neuromechanist]

Delivered by #162 (merged into develop 2026-08-19).

The additive-provider shape in this phase's scope was overtaken by the same PR going
further: rather than adding anthropic alongside openrouter/ollama, #162 moved
every role to Anthropic and removed the other two providers. The Definition of Done
holds either way: annotation runs against the Claude Platform on AWS with prompt
caching intact, and tests/test_integration_anthropic.py covers it with key-gated live
tests.

Two deviations worth recording:

• Opus is not offered (claude-opus-4-8 in this issue's DoD). Offered models are
  claude-haiku-4-5 (default) and claude-sonnet-5; the model allowlist rejects
  everything else with HTTP 400.
• The workspace header is anthropic-workspace-id, and the AWS endpoint rejects any
  request without it.