Add opt-in Anthropic (Claude) cloud preparation provider (closes #144) (#148)

acltabontabon · web-flow · commit fc2226c7c15c · 2026-06-27T18:28:26.000+08:00
Ship the first paid/cloud synthesis backend on the PreparationProvider SPI introduced in #143. Until now every provider was local/free (Ollama, OpenAI-compatible, deterministic), so teams wanting higher-quality synthesis from a preferred paid provider could not select one. AnthropicProvider is a single new SPI bean - no router or health-checker changes. Per the philosophy guardrails, local stays the default and the cloud provider is explicit-selection only: autoDetectable() returns false, so auto-detection never routes preparation to a paid API even when a key is set. - Vendor-specific auth: launchpad.ai.anthropic.api-key (bound from LAUNCHPAD_ANTHROPIC_API_KEY), falling back to the shared key; its own cloud base-url and anthropic-version, decoupled from the local-oriented settings. - Graceful degradation: a missing key short-circuits with a clear "API key is not configured" status (no network call), and an unreachable or unauthorized endpoint reports not-ready - both degrade to deterministic-only output before generation runs, never crashing. - Health probe reuses ProviderProbe via a new header-map fetch overload (x-api-key + anthropic-version); model matching is exact with a narrow -latest alias tolerance. Spring AI 2.0.0-M6 wraps the official Anthropic Java SDK (AnthropicClient), so the provider mirrors the OpenAI provider's explicit sync+async client wiring. Adds the Spring AI Anthropic starter, the ANTHROPIC provider vocabulary, a nested Anthropic config record, provider-text status factories with generic default switch arms, docs notes, a CHANGELOG entry, and tests (dedicated provider tests plus registry/health-checker guardrails proving Anthropic is listed/selectable but never chosen by auto-detection).
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 ### Added
+- **Anthropic (Claude) cloud preparation provider**: An opt-in, paid synthesis backend on the `PreparationProvider` SPI (`provider=anthropic`), shipped via the Spring AI Anthropic starter. It is explicit-selection only - `autoDetectable()` is `false`, so auto-detection never routes preparation to a paid API even when a key is present; local AI stays the default. Authentication is vendor-specific (`launchpad.ai.anthropic.api-key`, bound from `LAUNCHPAD_ANTHROPIC_API_KEY`, falling back to the shared key), with its own cloud base URL and `anthropic-version`. A missing key or an unreachable endpoint degrades cleanly to deterministic-only output instead of crashing. Adding it was a single new bean plus its config - no router or health-checker changes (toward #144).
 - **Project readiness evaluator**: `ReadinessEvaluator.evaluate(Path)` returns a read-only `ReadinessResult` (status, structured reason lines, recommended action, last-prepared timestamp) derived from a project's prepared artifacts (`AGENTS.md` and the `.launchpad/*.json` sidecars) and its provenance stamp - the deterministic verdict the readiness dashboard renders. `ProvenanceHeader` gains a `parse(...)` inverse of `render()` (closes #122).
 - **Output contract docs**: `docs/output-contract.adoc` documents every file a scan writes - layout, section structure, provenance stamp, write/merge actions, stable-vs-experimental tiers, and versioning - so downstream tools integrate against a contract instead of snapshot-testing prose. Adds a `docs/index.adoc` landing page (closes #91).
 - **MCP task-interview tools**: `ask_task_question`, `finalize_task`, and `regenerate_section` expose the local `/new-task` interview over MCP so a cloud agent can de-risk a task first. Stateless (the caller carries the `history` transcript), reuses `TaskAdvisorService`, caps at 8 rounds with a critic after round 2 (closes #19).
diff --git a/README.md b/README.md
@@ -77,7 +77,9 @@ Launchpad is:
 
 ## 🔌 AI providers
 
-Providers are pluggable. Local AI is the default -- Ollama, LM Studio, llama.cpp, vLLM, or anything with an OpenAI-compatible endpoint -- and keeps your code on your machine, which makes it a first-class option for privacy-sensitive, offline, air-gapped, or cost-sensitive workflows. Paid and cloud providers are also supported when they produce better results.
+Providers are pluggable. Local AI is the default -- Ollama, LM Studio, llama.cpp, vLLM, or anything with an OpenAI-compatible endpoint -- and keeps your code on your machine, which makes it a first-class option for privacy-sensitive, offline, air-gapped, or cost-sensitive workflows. Paid and cloud providers are also supported when they produce better results: Claude (Anthropic) is the first cloud provider, opt-in and explicitly selected. Local stays the default, and auto-detection never selects a paid provider -- choosing one is always a deliberate choice.
+
+Selecting Anthropic is explicit (`launchpad.ai.provider=anthropic`); its key reads from `LAUNCHPAD_ANTHROPIC_API_KEY` (falling back to the shared `LAUNCHPAD_LLM_API_KEY`). If the key is missing or Anthropic is unreachable, preparation degrades cleanly to deterministic-only output.
 
 Default:
 
diff --git a/docs/architecture.adoc b/docs/architecture.adoc
@@ -12,6 +12,8 @@ image::resources/launchpad-overview.drawio.png[Launchpad architecture overview]
 
 Launchpad works with any AI provider that exposes an OpenAI-compatible endpoint. Local providers (Ollama, LM Studio, llama.cpp) are the default: source code, scan results, and generated context stay on your machine, and no cloud API calls are made during analysis or synthesis. Paid or remote providers are also supported; the choice belongs to the operator, not the tool.
 
+The provider is a pluggable bean, so a paid cloud provider is just another selectable backend - Anthropic (Claude) ships as the first one, chosen for higher-quality synthesis when the operator wants it. It is opt-in and explicitly selected; auto-detection only ever resolves to a local backend, so preparation is never silently routed to a paid API. No vendor is privileged - cloud providers are added on the same provider seam, not as a blessed default.
+
 === Deterministic-first
 
 Repository structure, dependencies, endpoints, and documentation are extracted through structured, deterministic analysis. The local AI model is only used for bounded synthesis -- writing short narrative sections from data the deterministic phase already produced.
diff --git a/pom.xml b/pom.xml
@@ -65,6 +65,15 @@
             <artifactId>spring-ai-starter-model-openai</artifactId>
         </dependency>
 
+        <!-- Spring AI - opt-in cloud provider. Anthropic (Claude) is a paid,
+             explicit-selection synthesis backend on the PreparationProvider SPI;
+             AUTO never selects it. Like the local starters, its autoconfigured
+             bean is shadowed by the router's @Primary ChatModel. -->
+        <dependency>
+            <groupId>org.springframework.ai</groupId>
+            <artifactId>spring-ai-starter-model-anthropic</artifactId>
+        </dependency>
+
         <!-- Spring AI MCP server (stdio transport) - exposes Launchpad's scan / standards /
              audit results as MCP tools and resources so any MCP client (Claude Code, Cursor,
              Cline, Continue, Zed) can query them. -->
diff --git a/src/main/java/com/acltabontabon/launchpad/ai/AnthropicProvider.java b/src/main/java/com/acltabontabon/launchpad/ai/AnthropicProvider.java
@@ -0,0 +1,139 @@
+package com.acltabontabon.launchpad.ai;
+
+import com.acltabontabon.launchpad.config.LaunchpadAiProperties;
+import com.acltabontabon.launchpad.config.LaunchpadSettings.Snapshot;
+import com.anthropic.client.okhttp.AnthropicOkHttpClient;
+import com.anthropic.client.okhttp.AnthropicOkHttpClientAsync;
+import java.util.Map;
+import org.springframework.ai.anthropic.AnthropicChatModel;
+import org.springframework.ai.anthropic.AnthropicChatOptions;
+import org.springframework.ai.chat.model.ChatModel;
+import org.springframework.core.annotation.Order;
+import org.springframework.stereotype.Component;
+
+/**
+ * Anthropic (Claude) {@link PreparationProvider} - the first paid/cloud synthesis
+ * backend on the SPI. Opt-in only: {@link #autoDetectable()} is {@code false}, so
+ * {@link LlmProvider#AUTO} never routes preparation to a paid API even when a key
+ * is present; the user must pin {@code launchpad.ai.provider=anthropic} explicitly.
+ *
+ * <p>Authentication is vendor-specific: it prefers the {@code launchpad.ai.anthropic.api-key}
+ * key (bound from {@code LAUNCHPAD_ANTHROPIC_API_KEY}) and falls back to the shared
+ * snapshot key. A missing key or an unreachable endpoint degrades cleanly to
+ * deterministic-only output - {@link #check(Snapshot)} reports not-ready before any
+ * generation runs, and {@link #build(Snapshot)} stays safe to construct regardless.
+ * Probes {@code /v1/models} with Anthropic's {@code x-api-key} + {@code anthropic-version}
+ * headers for health.
+ */
+@Component
+@Order(30)
+public class AnthropicProvider implements PreparationProvider {
+
+    /**
+     * Substituted when no key is configured so the Anthropic client construction
+     * never fails. The router builds its delegate eagerly, but an unauthenticated
+     * provider reports not-ready, so this placeholder model is never actually called.
+     */
+    private static final String NOT_CONFIGURED_PLACEHOLDER = "not-configured";
+
+    /**
+     * Upper bound on synthesised tokens. Anthropic requires {@code max_tokens}; the
+     * synthesis layer caps each fragment well under this, so it is a guard rail, not
+     * a target.
+     */
+    private static final int MAX_TOKENS = 1024;
+
+    private final LaunchpadAiProperties properties;
+    private final ProviderProbe probe;
+
+    public AnthropicProvider(LaunchpadAiProperties properties, ProviderProbe probe) {
+        this.properties = properties;
+        this.probe = probe;
+    }
+
+    @Override
+    public String id() {
+        return LlmProvider.ANTHROPIC.slug();
+    }
+
+    /** Paid/cloud: never auto-selected. The user must pin it explicitly. */
+    @Override
+    public boolean autoDetectable() {
+        return false;
+    }
+
+    @Override
+    public ChatModel build(Snapshot snap) {
+        var apiKey = resolveApiKey(snap);
+        if (apiKey.isBlank()) apiKey = NOT_CONFIGURED_PLACEHOLDER;
+        var baseUrl = properties.anthropic().baseUrl();
+        var timeout = properties.readTimeout();
+        // The official Anthropic SDK rebuilds an async client from the
+        // environment when one is not supplied, and that rebuild ignores our
+        // base URL / api key. Wire both clients explicitly, mirroring the
+        // OpenAI-compatible provider.
+        var sync = AnthropicOkHttpClient.builder()
+            .baseUrl(baseUrl)
+            .apiKey(apiKey)
+            .timeout(timeout)
+            .build();
+        var async = AnthropicOkHttpClientAsync.builder()
+            .baseUrl(baseUrl)
+            .apiKey(apiKey)
+            .timeout(timeout)
+            .build();
+        var opts = AnthropicChatOptions.builder()
+            .model(snap.model())
+            .maxTokens(MAX_TOKENS)
+            .build();
+        return AnthropicChatModel.builder()
+            .anthropicClient(sync)
+            .anthropicClientAsync(async)
+            .options(opts)
+            .build();
+    }
+
+    @Override
+    public LlmProviderStatus check(Snapshot snap) {
+        var apiKey = resolveApiKey(snap);
+        if (apiKey.isBlank()) {
+            return LlmProviderStatus.unavailable(LlmProvider.ANTHROPIC,
+                "Anthropic API key is not configured",
+                "Set LAUNCHPAD_ANTHROPIC_API_KEY (or launchpad.ai.api-key) and select a Claude model");
+        }
+        var body = probe.fetch(properties.anthropic().baseUrl() + "/v1/models", Map.of(
+            "x-api-key", apiKey,
+            "anthropic-version", properties.anthropic().version()));
+        if (body == null) {
+            return LlmProviderStatus.unavailable(LlmProvider.ANTHROPIC,
+                "Anthropic not reachable - check the API key and network",
+                "Verify the Anthropic API key is valid and api.anthropic.com is reachable");
+        }
+        return probe.matchModel(body, snap.model(), AnthropicProvider::anthropicMatch)
+            ? LlmProviderStatus.ready(LlmProvider.ANTHROPIC, snap.model())
+            : LlmProviderStatus.modelMissing(LlmProvider.ANTHROPIC, snap.model(),
+                "Set an available Claude model id (e.g. claude-sonnet-4-5)");
+    }
+
+    /** Vendor key first, then the shared snapshot key; blank means unconfigured. */
+    private String resolveApiKey(Snapshot snap) {
+        var vendor = properties.anthropic().apiKey();
+        if (vendor != null && !vendor.isBlank()) return vendor;
+        return snap.hasApiKey() ? snap.apiKey() : "";
+    }
+
+    /**
+     * Exact match first. Then a narrow alias tolerance: a configured {@code -latest}
+     * alias matches a listed dated id sharing the same family stem (e.g.
+     * {@code claude-sonnet-4-5-latest} matches {@code claude-sonnet-4-5-20250930}).
+     * Deliberately not a broad substring match.
+     */
+    private static boolean anthropicMatch(String listed, String configured) {
+        if (listed.equals(configured)) return true;
+        if (configured.endsWith("-latest")) {
+            var stem = configured.substring(0, configured.length() - "-latest".length());
+            return listed.startsWith(stem + "-");
+        }
+        return false;
+    }
+}
diff --git a/src/main/java/com/acltabontabon/launchpad/ai/LlmProvider.java b/src/main/java/com/acltabontabon/launchpad/ai/LlmProvider.java
@@ -11,6 +11,7 @@
 public enum LlmProvider {
     OLLAMA("ollama"),
     OPENAI_COMPATIBLE("openai-compatible"),
+    ANTHROPIC("anthropic"),
     DETERMINISTIC("deterministic"),
     AUTO("auto");
 
@@ -39,6 +40,7 @@ public String displayName() {
         return switch (this) {
             case OLLAMA -> "Ollama";
             case OPENAI_COMPATIBLE -> "OpenAI-compatible";
+            case ANTHROPIC -> "Claude (Anthropic)";
             case DETERMINISTIC -> "Deterministic (no AI)";
             case AUTO -> "Auto-detect";
         };
diff --git a/src/main/java/com/acltabontabon/launchpad/ai/LlmProviderStatus.java b/src/main/java/com/acltabontabon/launchpad/ai/LlmProviderStatus.java
@@ -34,24 +34,42 @@ public static LlmProviderStatus daemonDown(LlmProvider attempted, String baseUrl
             case OPENAI_COMPATIBLE -> "Start your OpenAI-compatible server (LM Studio / llama.cpp / vLLM)";
             case AUTO -> "Start Ollama (ollama serve) or an OpenAI-compatible server";
             // The deterministic provider is always reachable, so it never reaches
-            // this path; the arm keeps the switch exhaustive.
-            case DETERMINISTIC -> null;
+            // this path. Other providers (e.g. cloud) carry their own message via
+            // unavailable(); the default arm keeps this switch generic.
+            default -> null;
         };
         String label = attempted == LlmProvider.AUTO
             ? "Local AI not reachable at " + baseUrl
             : attempted.displayName() + " not reachable at " + baseUrl;
         return new LlmProviderStatus(State.DAEMON_DOWN, attempted, label, hint);
     }
 
+    /**
+     * Not-ready status carrying a provider-supplied message and hint, mapped to
+     * {@link State#DAEMON_DOWN} so {@link #isReady()} is false and the runtime
+     * degrades to deterministic output. Lets a provider phrase its own failure
+     * (e.g. "Anthropic API key is not configured") instead of routing through
+     * the generic daemon-down wording.
+     */
+    public static LlmProviderStatus unavailable(LlmProvider provider, String message, String hint) {
+        return new LlmProviderStatus(State.DAEMON_DOWN, provider, message, hint);
+    }
+
     public static LlmProviderStatus modelMissing(LlmProvider provider, String model) {
         String hint = switch (provider) {
             case OLLAMA -> "Run: ollama pull " + model;
             case OPENAI_COMPATIBLE -> "Load model '" + model + "' in your local server";
             case AUTO -> "Load model '" + model + "' in your local server";
-            // The deterministic provider has no model to load; the arm keeps the
-            // switch exhaustive.
-            case DETERMINISTIC -> null;
+            // The deterministic provider has no model to load; other providers
+            // pass an explicit hint via the three-arg overload. The default arm
+            // keeps this switch generic.
+            default -> "Select a model available to this provider";
         };
+        return modelMissing(provider, model, hint);
+    }
+
+    /** Model-missing status with a provider-supplied hint. */
+    public static LlmProviderStatus modelMissing(LlmProvider provider, String model, String hint) {
         return new LlmProviderStatus(
             State.MODEL_MISSING, provider, "Model '" + model + "' is not loaded", hint);
     }
diff --git a/src/main/java/com/acltabontabon/launchpad/ai/OllamaProvider.java b/src/main/java/com/acltabontabon/launchpad/ai/OllamaProvider.java
@@ -53,7 +53,7 @@ public ChatModel build(Snapshot snap) {
 
     @Override
     public LlmProviderStatus check(Snapshot snap) {
-        var body = probe.fetch(snap.baseUrl() + "/api/tags", null);
+        var body = probe.fetch(snap.baseUrl() + "/api/tags", (String) null);
         if (body == null) return LlmProviderStatus.daemonDown(LlmProvider.OLLAMA, snap.baseUrl());
         return probe.matchModel(body, snap.model(), OllamaProvider::ollamaMatch)
             ? LlmProviderStatus.ready(LlmProvider.OLLAMA, snap.model())
diff --git a/src/main/java/com/acltabontabon/launchpad/ai/ProviderProbe.java b/src/main/java/com/acltabontabon/launchpad/ai/ProviderProbe.java
@@ -5,6 +5,7 @@
 import java.net.http.HttpRequest;
 import java.net.http.HttpResponse;
 import java.time.Duration;
+import java.util.Map;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 import org.springframework.stereotype.Component;
@@ -32,14 +33,25 @@ public ProviderProbe() {
 
     /** GET the url (optionally bearer-authed); returns the body on HTTP 200, else null. */
     public String fetch(String url, String apiKey) {
+        Map<String, String> headers = (apiKey != null && !apiKey.isBlank())
+            ? Map.of("Authorization", "Bearer " + apiKey)
+            : Map.of();
+        return fetch(url, headers);
+    }
+
+    /**
+     * GET the url with arbitrary headers; returns the body on HTTP 200, else
+     * null. Lets vendors that authenticate outside the {@code Authorization:
+     * Bearer} convention (Anthropic's {@code x-api-key} + {@code anthropic-version})
+     * reuse the same bounded-timeout probe.
+     */
+    public String fetch(String url, Map<String, String> headers) {
         try {
             var builder = HttpRequest.newBuilder()
                 .uri(URI.create(url))
                 .timeout(TIMEOUT)
                 .GET();
-            if (apiKey != null && !apiKey.isBlank()) {
-                builder.header("Authorization", "Bearer " + apiKey);
-            }
+            headers.forEach(builder::header);
             var response = http.send(builder.build(), HttpResponse.BodyHandlers.ofString());
             return response.statusCode() == 200 ? response.body() : null;
         } catch (Exception e) {
diff --git a/src/main/java/com/acltabontabon/launchpad/config/LaunchpadAiProperties.java b/src/main/java/com/acltabontabon/launchpad/config/LaunchpadAiProperties.java
@@ -20,25 +20,27 @@ public record LaunchpadAiProperties(
     Duration connectTimeout,
     Duration readTimeout,
     Ollama ollama,
+    Anthropic anthropic,
     Synthesis synthesis
 ) {
 
     public LaunchpadAiProperties {
         if (connectTimeout == null) connectTimeout = Duration.ofSeconds(10);
         if (readTimeout == null) readTimeout = Duration.ofMinutes(2);
         if (ollama == null) ollama = new Ollama(null);
+        if (anthropic == null) anthropic = new Anthropic(null, null, null);
         if (synthesis == null) synthesis = new Synthesis(null, null, null);
     }
 
     /**
-     * Builds a properties instance with default Ollama / synthesis settings.
-     * Used by call-sites that only care about HTTP timeouts (tests, code
-     * paths that don't synthesise). Distinct from the canonical 4-arg
+     * Builds a properties instance with default Ollama / Anthropic / synthesis
+     * settings. Used by call-sites that only care about HTTP timeouts (tests,
+     * code paths that don't synthesise). Distinct from the canonical
      * constructor so Spring's @ConfigurationProperties binding stays
      * unambiguous (Spring picks the canonical constructor, not this factory).
      */
     public static LaunchpadAiProperties ofTimeouts(Duration connectTimeout, Duration readTimeout) {
-        return new LaunchpadAiProperties(connectTimeout, readTimeout, null, null);
+        return new LaunchpadAiProperties(connectTimeout, readTimeout, null, null, null);
     }
 
     /**
@@ -53,6 +55,28 @@ public record Ollama(Integer numCtx) {
         }
     }
 
+    /**
+     * Anthropic (Claude) cloud-provider knobs. Decoupled from the shared
+     * {@code launchpad.ai.base-url} / {@code api-key} (which are local-oriented)
+     * so selecting Anthropic does not require re-pointing the local settings.
+     * <ul>
+     *   <li>{@code baseUrl} - Anthropic API host. Defaults to the public cloud
+     *       endpoint.</li>
+     *   <li>{@code version} - the {@code anthropic-version} header sent on every
+     *       request and on the health probe.</li>
+     *   <li>{@code apiKey} - the vendor-specific key. Bound in
+     *       {@code application.properties} from the {@code LAUNCHPAD_ANTHROPIC_API_KEY}
+     *       env var; when blank the provider falls back to the shared snapshot key.</li>
+     * </ul>
+     */
+    public record Anthropic(String baseUrl, String version, String apiKey) {
+        public Anthropic {
+            if (baseUrl == null || baseUrl.isBlank()) baseUrl = "https://api.anthropic.com";
+            if (version == null || version.isBlank()) version = "2023-06-01";
+            if (apiKey == null) apiKey = "";
+        }
+    }
+
     /**
      * Bounded local-AI synthesis. Each fragment job has a strict input and
      * output budget so a runaway prompt can never re-introduce the
diff --git a/src/main/resources/application.properties b/src/main/resources/application.properties
diff --git a/src/test/java/com/acltabontabon/launchpad/ai/AnthropicProviderTest.java b/src/test/java/com/acltabontabon/launchpad/ai/AnthropicProviderTest.java
diff --git a/src/test/java/com/acltabontabon/launchpad/ai/ProviderHealthCheckerTest.java b/src/test/java/com/acltabontabon/launchpad/ai/ProviderHealthCheckerTest.java
diff --git a/src/test/java/com/acltabontabon/launchpad/ai/ProviderRegistryTest.java b/src/test/java/com/acltabontabon/launchpad/ai/ProviderRegistryTest.java
diff --git a/src/test/java/com/acltabontabon/launchpad/template/ContextGenerationVerification.java b/src/test/java/com/acltabontabon/launchpad/template/ContextGenerationVerification.java
