Fix #215: pluggable LLM + embedding provider abstraction

Adds the vendor-agnostic seam the AI assistant + match-ranking plug into:
- LLMProvider / EmbeddingProvider ABCs (base.py). LLM and embeddings are
  SEPARATE abstractions — Anthropic has no embeddings endpoint, so each is
  configured independently and either can be off.
- NullLLMProvider / NullEmbeddingProvider — the default; fail loud with a clear
  "not configured" error so AI-off deployments don't silently no-op.
- AnthropicLLMProvider — first concrete LLM impl, via the official anthropic SDK
  (default model claude-opus-4-8). A local provider (e.g. Ollama) would be
  another subclass of the same interface.
- Factory in deps.py (get_llm_provider / get_embedding_provider) selects by
  env (MODEL_PROVIDER / EMBEDDING_PROVIDER); documented in .env.example.

Providers are read-only text/vector producers — they never touch the DB, so the
"AI never writes autonomously" invariant (CLAUDE.md #1) holds; writes will go
through ChangeProposal (#214).

Tests: provider selection (null default, anthropic when keyed, fallback without
key) + null providers raise. 81 passed.

Closes #215

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Justin Paul <justin@jpaul.me>

backend/app/api/deps.py

@@ -10,6 +10,8 @@ from app.core.db import get_session
 from app.integrations.mailer.base import Mailer
 from app.integrations.mailer.console import ConsoleMailer
 from app.integrations.mailer.smtp import SMTPMailer
+from app.integrations.models.base import EmbeddingProvider, LLMProvider
+from app.integrations.models.null import NullEmbeddingProvider, NullLLMProvider
 from app.integrations.objectstore.base import ObjectStore
 from app.integrations.objectstore.s3 import S3ObjectStore
 from app.models.user import User
@@ -67,3 +69,28 @@ def get_objectstore() -> ObjectStore:
 
 
 ObjectStoreDep = Annotated[ObjectStore, Depends(get_objectstore)]
+
+
+def get_llm_provider() -> LLMProvider:
+    settings = get_settings()
+    if settings.model_provider == "anthropic" and settings.anthropic_api_key:
+        from app.integrations.models.anthropic_provider import AnthropicLLMProvider
+
+        return AnthropicLLMProvider(
+            api_key=settings.anthropic_api_key,
+            model=settings.llm_model,
+            max_tokens=settings.llm_max_tokens,
+        )
+    return NullLLMProvider()
+
+
+LLMProviderDep = Annotated[LLMProvider, Depends(get_llm_provider)]
+
+
+def get_embedding_provider() -> EmbeddingProvider:
+    # Only the null provider exists today; concrete embedders (Ollama/Voyage)
+    # implement the same interface and are selected here by settings.embedding_provider.
+    return NullEmbeddingProvider()
+
+
+EmbeddingProviderDep = Annotated[EmbeddingProvider, Depends(get_embedding_provider)]

backend/app/core/config.py

@@ -60,6 +60,14 @@ class Settings(BaseSettings):
     smtp_password: str | None = None
     smtp_from: str = "Provenance <no-reply@provenance.local>"
 
+    # --- Model providers (AI assistant + match-ranking embeddings) ---
+    # Separate because Anthropic has no embeddings endpoint; either can be off.
+    model_provider: str = "null"  # null | anthropic
+    anthropic_api_key: str | None = None
+    llm_model: str = "claude-opus-4-8"
+    llm_max_tokens: int = 4096
+    embedding_provider: str = "null"  # null | (future: ollama, voyage, …)
+
 
 @lru_cache
 def get_settings() -> Settings:

backend/app/integrations/models/anthropic_provider.py

@@ -0,0 +1,24 @@
+"""Anthropic LLM provider (official SDK). Self-hosters who want everything to
+stay on their own metal would configure a local provider instead (e.g. Ollama) —
+that's a future implementation of the same LLMProvider interface."""
+
+from anthropic import AsyncAnthropic
+
+from app.integrations.models.base import LLMProvider
+
+
+class AnthropicLLMProvider(LLMProvider):
+    def __init__(self, *, api_key: str, model: str, max_tokens: int = 4096) -> None:
+        self._client = AsyncAnthropic(api_key=api_key)
+        self._model = model
+        self._max_tokens = max_tokens
+
+    async def complete(self, *, prompt: str, system: str | None = None) -> str:
+        resp = await self._client.messages.create(
+            model=self._model,
+            max_tokens=self._max_tokens,
+            system=system or "",
+            messages=[{"role": "user", "content": prompt}],
+        )
+        # content is a list of blocks; concatenate the text ones.
+        return "".join(b.text for b in resp.content if b.type == "text")

backend/app/integrations/models/base.py

@@ -0,0 +1,36 @@
+"""Model-provider interfaces — the seam the AI assistant and match ranking plug
+into. LLM (text) and embeddings are *separate* abstractions: Anthropic offers no
+embeddings endpoint, so the two are configured independently (twelve-factor,
+CLAUDE.md #7) and a deployment may run one without the other.
+
+These providers are read-only text/vector producers. They MUST NOT mutate tree
+data — the assistant's writes go through a ChangeProposal a human approves
+(CLAUDE.md #1). Nothing here touches the database.
+"""
+
+from abc import ABC, abstractmethod
+
+
+class LLMProvider(ABC):
+    """Text in, text out. Implementations wrap a chat/completion model."""
+
+    @abstractmethod
+    async def complete(self, *, prompt: str, system: str | None = None) -> str:
+        """Return the model's text response to a single user prompt."""
+        ...
+
+
+class EmbeddingProvider(ABC):
+    """Text in, vectors out — for pgvector-backed match ranking."""
+
+    #: Dimensionality of the returned vectors (for the pgvector column).
+    dimensions: int
+
+    @abstractmethod
+    async def embed(self, texts: list[str]) -> list[list[float]]:
+        """Return one embedding vector per input text, in order."""
+        ...
+
+
+class ModelProviderNotConfigured(RuntimeError):
+    """Raised when an AI capability is used but no provider is configured."""

backend/app/integrations/models/null.py

@@ -0,0 +1,31 @@
+"""Default providers when no model backend is configured — AI features are off.
+
+They fail loudly (rather than silently doing nothing) so a caller that reaches
+for an unconfigured capability gets a clear, actionable error.
+"""
+
+from app.integrations.models.base import (
+    EmbeddingProvider,
+    LLMProvider,
+    ModelProviderNotConfigured,
+)
+
+_MSG = (
+    "No model provider configured. Set MODEL_PROVIDER (e.g. 'anthropic') and the "
+    "provider's credentials to enable AI features."
+)
+
+
+class NullLLMProvider(LLMProvider):
+    async def complete(self, *, prompt: str, system: str | None = None) -> str:
+        raise ModelProviderNotConfigured(_MSG)
+
+
+class NullEmbeddingProvider(EmbeddingProvider):
+    dimensions = 0
+
+    async def embed(self, texts: list[str]) -> list[list[float]]:
+        raise ModelProviderNotConfigured(
+            "No embedding provider configured. Set EMBEDDING_PROVIDER and its "
+            "credentials to enable match ranking."
+        )