Introduce PreparationProvider SPI and retire provider switches (closes #143) (#147)

Provider selection was hardcoded across an enum and two parallel switch
statements (router + health checker), and "no-AI / deterministic" was a
boolean threaded through the synthesis layer rather than a selectable mode.
Adding a provider meant a multi-file edit.

Replace this with a PreparationProvider SPI (id + build + check), mirroring
the existing RuleChecker pattern: beans are auto-collected into a pure
ProviderRegistry and resolved by id. The router and health checker no longer
switch over the enum.

- Add PreparationProvider SPI and a shared ProviderProbe HTTP helper.
- Reimplement Ollama and OpenAI-compatible factories as provider beans;
  add a first-class deterministic (no-AI) provider that reports ready with
  no network call.
- ProviderRegistry is a pure lookup table; all resolution policy and AUTO
  probing live in ProviderHealthChecker. Only the AUTO path probes.
- Deterministic active yields aiAvailable=false, so synthesis short-circuits
  before the inert model is invoked; synthesis-disabled resolves to
  deterministic regardless of the configured provider.
- SettingsView renders the provider list from the registry instead of the
  enum. launchpad.ai.synthesis.enabled remains the config-time kill switch.

Scope: LlmProvider kept as the built-in vocabulary; arbitrary external
string-id providers deferred to a later migration.

Author: acltabontabon

CHANGELOG.md

@@ -24,6 +24,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Standards-pack schema version**: `standards-pack.yml` requires an integer `schemaVersion`; missing or unsupported versions are rejected on load and surfaced by the MCP standards tools as `incompatible_pack_schema` (closes #84).
 
 ### Changed
+- **Pluggable preparation-provider SPI**: Providers are now `PreparationProvider` beans (`id()` + `build()` + `check()`) auto-collected into a registry, replacing the hardcoded provider switches in the router and health checker; adding a built-in provider is a new bean rather than a multi-file edit. A first-class `deterministic` (no-AI) provider is selectable and produces deterministic-only output with no network calls; when synthesis is disabled globally the runtime resolves to it regardless of the configured provider. `launchpad.ai.synthesis.enabled` remains the config-time kill switch (closes #143).
 - **Preparation-first, provider-pluggable docs**: Rewrote README and docs to frame Launchpad as agent-agnostic and provider-pluggable. "Local-first" is no longer the product identity -- local AI is described as the default option, not the defining trait. Added a Philosophy section to README (agent-agnostic, preparation-first, standards-aware, local-capable not local-limited, complementary to context-aware tools). Renamed "Local-first" architecture principle to "Provider-pluggable", relabeled the pipeline's "Local AI synthesis" stage to "AI synthesis", softened the getting-started AI model prerequisite, and updated the docs index lead sentence (closes #142, supersedes #72).
 - **Uniform MCP argument validation**: Every MCP tool now rejects a missing or blank required argument with a single `missing_argument` error (type `INVALID_ARGUMENT`, `details.field` naming the argument) instead of scattered per-field codes or a misleading default-project fallback. Replaces the prior `missing_query`, `missing_path`, and `missing_task` codes (closes #75).
 - **Repositioned product headline**: README and positioning now lead with the Preparation Engine and standards-first story instead of contested token-savings claims. Launchpad prepares a repository for AI-assisted development by scanning locally, resolving standards, and emitting grounded context artifacts (closes #71).

src/main/java/com/acltabontabon/launchpad/ai/DeterministicProvider.java

@@ -0,0 +1,62 @@
+package com.acltabontabon.launchpad.ai;
+
+import com.acltabontabon.launchpad.config.LaunchpadSettings.Snapshot;
+import java.util.List;
+import org.springframework.ai.chat.model.ChatModel;
+import org.springframework.ai.chat.model.ChatResponse;
+import org.springframework.ai.chat.prompt.Prompt;
+import org.springframework.core.annotation.Order;
+import org.springframework.stereotype.Component;
+import reactor.core.publisher.Flux;
+
+/**
+ * First-class no-AI provider. Selecting it (or disabling synthesis globally)
+ * produces deterministic-only output with no network calls: {@link #check}
+ * always reports ready without probing anything.
+ *
+ * <p>{@link #build} returns a no-op {@link ChatModel} purely as a safety net.
+ * The runtime contract is {@code aiAvailable == false} whenever this provider is
+ * active (see {@code LaunchpadRunner}), so the synthesis layer short-circuits to
+ * its deterministic fallback before this model is ever invoked.
+ */
+@Component
+@Order(100)
+public class DeterministicProvider implements PreparationProvider {
+
+    @Override
+    public String id() {
+        return LlmProvider.DETERMINISTIC.slug();
+    }
+
+    @Override
+    public ChatModel build(Snapshot snap) {
+        return new NoOpChatModel();
+    }
+
+    @Override
+    public LlmProviderStatus check(Snapshot snap) {
+        return LlmProviderStatus.deterministic();
+    }
+
+    /** Excluded from AUTO probing - AUTO should never silently land on no-AI mode. */
+    @Override
+    public boolean autoDetectable() {
+        return false;
+    }
+
+    /**
+     * Inert {@link ChatModel} that yields no content. Never reached on the normal
+     * path; exists so a stray call cannot blow up an assembling document.
+     */
+    private static final class NoOpChatModel implements ChatModel {
+        @Override
+        public ChatResponse call(Prompt prompt) {
+            return new ChatResponse(List.of());
+        }
+
+        @Override
+        public Flux<ChatResponse> stream(Prompt prompt) {
+            return Flux.empty();
+        }
+    }
+}

src/main/java/com/acltabontabon/launchpad/ai/LlmProvider.java

@@ -1,14 +1,17 @@
 package com.acltabontabon.launchpad.ai;
 
 /**
- * Local-AI backend Launchpad talks to. {@link #AUTO} defers the choice to
- * {@link ProviderHealthChecker#resolveAuto(String, String)} at health-check
- * time; the resolved value is surfaced on {@link LlmProviderStatus} so the
- * Welcome badge can show what was actually picked.
+ * Built-in vocabulary of preparation backends Launchpad talks to. Each value's
+ * {@link #slug()} matches the {@code id()} of a {@link PreparationProvider} bean.
+ * {@link #AUTO} defers the choice to {@link ProviderHealthChecker} at
+ * health-check time; the resolved value is surfaced on {@link LlmProviderStatus}
+ * so the Welcome badge can show what was actually picked. {@link #DETERMINISTIC}
+ * selects deterministic, no-AI output.
  */
 public enum LlmProvider {
     OLLAMA("ollama"),
     OPENAI_COMPATIBLE("openai-compatible"),
+    DETERMINISTIC("deterministic"),
     AUTO("auto");
 
     private final String slug;
@@ -36,6 +39,7 @@ public String displayName() {
         return switch (this) {
             case OLLAMA -> "Ollama";
             case OPENAI_COMPATIBLE -> "OpenAI-compatible";
+            case DETERMINISTIC -> "Deterministic (no AI)";
             case AUTO -> "Auto-detect";
         };
     }

src/main/java/com/acltabontabon/launchpad/ai/LlmProviderRouter.java

@@ -1,6 +1,5 @@
 package com.acltabontabon.launchpad.ai;
 
-import com.acltabontabon.launchpad.config.LaunchpadAiProperties;
 import com.acltabontabon.launchpad.config.LaunchpadSettings;
 import com.acltabontabon.launchpad.config.LaunchpadSettings.LlmProviderSettingsChanged;
 import com.acltabontabon.launchpad.config.LaunchpadSettings.Snapshot;
@@ -15,10 +14,10 @@
 
 /**
  * Single {@link ChatModel} the rest of Launchpad sees. Holds a volatile delegate
- * that points at either the Ollama- or OpenAI-compatible-backed model, depending
- * on the current {@link LaunchpadSettings} snapshot. Settings changes published
- * through {@link LlmProviderSettingsChanged} swap the delegate in place so the
- * user can switch providers without restarting the JVM.
+ * built by the {@link PreparationProvider} that {@link ProviderHealthChecker}
+ * resolves for the current {@link LaunchpadSettings} snapshot. Settings changes
+ * published through {@link LlmProviderSettingsChanged} swap the delegate in place
+ * so the user can switch providers without restarting the JVM.
  * <p>
  * The Spring AI autoconfigured {@code ChatClient.Builder} picks up this bean
  * (via {@link Primary}) and wraps it, so every {@code chatClient.prompt()...call()}
@@ -28,16 +27,11 @@
 @Primary
 public class LlmProviderRouter implements ChatModel {
 
-    private final OllamaChatModelFactory ollamaFactory;
-    private final OpenAiCompatibleChatModelFactory openAiFactory;
     private final ProviderHealthChecker healthChecker;
     private volatile ChatModel delegate;
 
     public LlmProviderRouter(LaunchpadSettings settings,
-                             LaunchpadAiProperties properties,
                              ProviderHealthChecker healthChecker) {
-        this.ollamaFactory = new OllamaChatModelFactory(properties);
-        this.openAiFactory = new OpenAiCompatibleChatModelFactory(properties);
         this.healthChecker = healthChecker;
         this.delegate = build(settings.snapshot());
     }
@@ -63,15 +57,8 @@ public ChatOptions getDefaultOptions() {
     }
 
     private ChatModel build(Snapshot snap) {
-        var concrete = snap.provider() == LlmProvider.AUTO
-            ? healthChecker.resolveAuto(snap.baseUrl(), snap.apiKey())
-            : snap.provider();
-        return switch (concrete) {
-            case OLLAMA -> ollamaFactory.build(snap);
-            case OPENAI_COMPATIBLE -> openAiFactory.build(snap);
-            // resolveAuto() never returns AUTO; the fallthrough keeps the
-            // switch exhaustive and routes to Ollama as a last-resort default.
-            case AUTO -> ollamaFactory.build(snap);
-        };
+        // A concrete provider builds with no network; only the AUTO path probes
+        // (inside resolve), exactly as before.
+        return healthChecker.resolve(snap).build(snap);
     }
 }

src/main/java/com/acltabontabon/launchpad/ai/LlmProviderStatus.java

@@ -18,11 +18,24 @@ public static LlmProviderStatus ready(LlmProvider provider, String model) {
             State.READY, provider, provider.displayName() + " ready - " + model, null);
     }
 
+    /**
+     * Ready status for the deterministic (no-AI) provider. Always reachable - it
+     * makes no network call - but yields deterministic-only output, so the
+     * runtime treats it as {@code aiAvailable == false}.
+     */
+    public static LlmProviderStatus deterministic() {
+        return new LlmProviderStatus(
+            State.READY, LlmProvider.DETERMINISTIC, "Deterministic mode - no AI synthesis", null);
+    }
+
     public static LlmProviderStatus daemonDown(LlmProvider attempted, String baseUrl) {
         String hint = switch (attempted) {
             case OLLAMA -> "Run: ollama serve";
             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;
         };
         String label = attempted == LlmProvider.AUTO
             ? "Local AI not reachable at " + baseUrl
@@ -35,6 +48,9 @@ public static LlmProviderStatus modelMissing(LlmProvider provider, String model)
             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;
         };
         return new LlmProviderStatus(
             State.MODEL_MISSING, provider, "Model '" + model + "' is not loaded", hint);

src/main/java/com/acltabontabon/launchpad/ai/OllamaChatModelFactory.java

@@ -0,0 +1,69 @@
+package com.acltabontabon.launchpad.ai;
+
+import com.acltabontabon.launchpad.config.LaunchpadAiProperties;
+import com.acltabontabon.launchpad.config.LaunchpadSettings.Snapshot;
+import org.springframework.ai.chat.model.ChatModel;
+import org.springframework.ai.ollama.OllamaChatModel;
+import org.springframework.ai.ollama.api.OllamaApi;
+import org.springframework.ai.ollama.api.OllamaChatOptions;
+import org.springframework.core.annotation.Order;
+import org.springframework.stereotype.Component;
+
+/**
+ * Ollama-backed {@link PreparationProvider}. Builds an {@link OllamaChatModel}
+ * bound to the configured base URL and model - wrapping every HTTP call with the
+ * configured connect+read timeouts so a hung daemon cannot freeze the calling
+ * thread - and probes {@code /api/tags} for health.
+ */
+@Component
+@Order(10)
+public class OllamaProvider implements PreparationProvider {
+
+    private final HttpTimeouts http;
+    private final int numCtx;
+    private final ProviderProbe probe;
+
+    public OllamaProvider(LaunchpadAiProperties properties, ProviderProbe probe) {
+        this.http = new HttpTimeouts(properties);
+        this.numCtx = properties.ollama().numCtx();
+        this.probe = probe;
+    }
+
+    @Override
+    public String id() {
+        return LlmProvider.OLLAMA.slug();
+    }
+
+    @Override
+    public ChatModel build(Snapshot snap) {
+        var api = OllamaApi.builder()
+            .baseUrl(snap.baseUrl())
+            .restClientBuilder(http.restClient())
+            .webClientBuilder(http.webClient())
+            .build();
+        var opts = OllamaChatOptions.builder()
+            .model(snap.model())
+            .numCtx(numCtx)
+            .build();
+        return OllamaChatModel.builder()
+            .ollamaApi(api)
+            .defaultOptions(opts)
+            .build();
+    }
+
+    @Override
+    public LlmProviderStatus check(Snapshot snap) {
+        var body = probe.fetch(snap.baseUrl() + "/api/tags", 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())
+            : LlmProviderStatus.modelMissing(LlmProvider.OLLAMA, snap.model());
+    }
+
+    /** Ollama returns names like "llama3.2:latest" for a "llama3.2" pull. */
+    private static boolean ollamaMatch(String installed, String configured) {
+        if (installed.equals(configured)) return true;
+        int colon = installed.indexOf(':');
+        return colon > 0 && installed.substring(0, colon).equals(configured);
+    }
+}

src/main/java/com/acltabontabon/launchpad/ai/OllamaProvider.java

@@ -4,16 +4,22 @@
 import com.acltabontabon.launchpad.config.LaunchpadSettings.Snapshot;
 import com.openai.client.okhttp.OpenAIOkHttpClient;
 import com.openai.client.okhttp.OpenAIOkHttpClientAsync;
+import org.springframework.ai.chat.model.ChatModel;
 import org.springframework.ai.openai.OpenAiChatModel;
 import org.springframework.ai.openai.OpenAiChatOptions;
+import org.springframework.core.annotation.Order;
+import org.springframework.stereotype.Component;
 
 /**
- * Builds an {@link OpenAiChatModel} pointed at any OpenAI-compatible local
- * endpoint (LM Studio, llama.cpp server, vLLM, hosted gateways). The api key
- * is optional - local servers typically ignore it but the SDK requires a
- * non-null string, so we substitute a placeholder when the user leaves it blank.
+ * OpenAI-compatible {@link PreparationProvider} for any local endpoint (LM
+ * Studio, llama.cpp server, vLLM, hosted gateways). The api key is optional -
+ * local servers typically ignore it but the SDK requires a non-null string, so a
+ * placeholder is substituted when the user leaves it blank. Probes
+ * {@code /v1/models} for health.
  */
-final class OpenAiCompatibleChatModelFactory {
+@Component
+@Order(20)
+public class OpenAiCompatibleProvider implements PreparationProvider {
 
     /**
      * Placeholder the OpenAI SDK accepts when the local server does not enforce
@@ -22,12 +28,20 @@ final class OpenAiCompatibleChatModelFactory {
     private static final String NO_AUTH_PLACEHOLDER = "not-needed";
 
     private final LaunchpadAiProperties properties;
+    private final ProviderProbe probe;
 
-    OpenAiCompatibleChatModelFactory(LaunchpadAiProperties properties) {
+    public OpenAiCompatibleProvider(LaunchpadAiProperties properties, ProviderProbe probe) {
         this.properties = properties;
+        this.probe = probe;
     }
 
-    OpenAiChatModel build(Snapshot snap) {
+    @Override
+    public String id() {
+        return LlmProvider.OPENAI_COMPATIBLE.slug();
+    }
+
+    @Override
+    public ChatModel build(Snapshot snap) {
         var apiKey = snap.hasApiKey() ? snap.apiKey() : NO_AUTH_PLACEHOLDER;
         var sync = OpenAIOkHttpClient.builder()
             .baseUrl(snap.baseUrl())
@@ -49,4 +63,13 @@ OpenAiChatModel build(Snapshot snap) {
             .options(opts)
             .build();
     }
+
+    @Override
+    public LlmProviderStatus check(Snapshot snap) {
+        var body = probe.fetch(snap.baseUrl() + "/v1/models", snap.apiKey());
+        if (body == null) return LlmProviderStatus.daemonDown(LlmProvider.OPENAI_COMPATIBLE, snap.baseUrl());
+        return probe.matchModel(body, snap.model(), String::equals)
+            ? LlmProviderStatus.ready(LlmProvider.OPENAI_COMPATIBLE, snap.model())
+            : LlmProviderStatus.modelMissing(LlmProvider.OPENAI_COMPATIBLE, snap.model());
+    }
 }