feat(server): pluggable AI providers - any open-standard or commercial AI

Lets the owner point transcription and summarisation at any AI: an open-standard
endpoint (OpenAI-compatible / local faster-whisper / Ollama) or a commercial API
(OpenAI, Anthropic, Gemini). Config-driven, self-hostable, no lock-in.

What changed:
- server/app/providers/: provider layer.
  - base.py: Transcriber/Summariser protocols + shared summary prompt + tolerant JSON
    parser (uniform Summary shape across providers).
  - summary.py: OpenAICompatibleSummariser (any /chat/completions - OpenAI, Groq,
    OpenRouter, LocalAI, LM Studio, vLLM, Ollama /v1) and AnthropicSummariser (Claude
    via the official anthropic SDK; Messages API has no OpenAI-compatible endpoint).
  - transcription.py: OpenAICompatibleTranscriber (/audio/transcriptions - OpenAI,
    Groq, self-hosted whisper server) and LocalWhisperTranscriber (faster-whisper,
    execution wired in M5).
  - factory.py: builds the configured providers with per-provider defaults
    (anthropic -> claude-opus-4-8, openai_compatible -> gpt-4o-mini, ollama -> llama3.1).
- config.py + .env.example: transcription_provider / llm_provider selectors + base_url,
  key, model settings; local faster-whisper and Ollama kept as the self-hosted defaults.
- main.py: /health now reports the resolved provider names (no secrets).
- requirements.txt: httpx drives all HTTP providers; anthropic + faster-whisper are
  optional, only for their respective providers.
- docs/ai-providers.md: config recipes for OpenAI, Groq, Anthropic, Gemini, LocalAI,
  LM Studio, Ollama, self-hosted whisper.
- state/: DECISIONS, ARCHITECTURE, TODO updated.

Why:
- The user asked to connect the device to any open standard AI or commercial one; this
  is also the core differentiator vs Plaud's locked cloud.

Notes:
- Anthropic provider uses the official SDK and defaults to claude-opus-4-8 (per the
  claude-api guidance). AI deps are optional per chosen provider. Modules byte-compile
  cleanly; end-to-end wiring into the ingest pipeline lands with M5.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

server/app/config.py

@@ -28,12 +28,26 @@ class Settings(BaseSettings):
     # Metadata DB (SQLite to start; Postgres URL later)
     database_url: str = "sqlite:///./openscribe.db"
 
-    # Transcription (faster-whisper)
+    # --- AI providers (see docs/ai-providers.md) --------------------------------------
+    # Transcription provider: "local_whisper" (self-hosted) | "openai_compatible"
+    transcription_provider: str = "local_whisper"
+    transcription_base_url: str = ""      # e.g. https://api.openai.com/v1 or a Groq/local URL
+    transcription_api_key: str = ""
+    transcription_model: str = ""         # e.g. whisper-1, whisper-large-v3
+
+    # LLM provider for summaries + Ask-AI:
+    #   "ollama" (default, self-hosted) | "openai_compatible" | "anthropic"
+    llm_provider: str = "ollama"
+    llm_base_url: str = "https://api.openai.com/v1"   # used by openai_compatible
+    llm_api_key: str = ""
+    llm_model: str = ""                   # per-provider default applied if empty
+
+    # Local faster-whisper (used when transcription_provider == local_whisper)
     whisper_model: str = "base"           # tiny|base|small|medium|large-v3
     whisper_device: str = "cpu"           # cpu|cuda
     whisper_compute_type: str = "int8"
 
-    # Summarisation (Ollama, self-hosted)
+    # Local Ollama (used when llm_provider == ollama)
     ollama_url: str = "http://localhost:11434"
     ollama_model: str = "llama3.1"
 

server/app/main.py

@@ -24,11 +24,20 @@ _recordings: dict[str, Recording] = {}
 
 @app.get("/health")
 def health() -> dict:
+    # Report the resolved provider names (never secrets) so operators can confirm config.
+    from .providers import build_summariser, build_transcriber
+
+    try:
+        summariser = build_summariser().name
+    except Exception as exc:  # e.g. anthropic dep not installed
+        summariser = f"unavailable ({type(exc).__name__})"
     return {
         "status": "ok",
         "storage_backend": settings.storage_backend,
-        "whisper_model": settings.whisper_model,
-        "ollama_model": settings.ollama_model,
+        "transcription_provider": settings.transcription_provider,
+        "transcriber": build_transcriber().name,
+        "llm_provider": settings.llm_provider,
+        "summariser": summariser,
     }
 
 

server/app/providers/__init__.py

@@ -0,0 +1,12 @@
+# SPDX-License-Identifier: GPL-3.0-only
+"""Pluggable AI providers for OpenScribe.
+
+Transcription and summarisation each target a provider chosen by config, so the owner can
+point OpenScribe at any open-standard endpoint (OpenAI-compatible, local faster-whisper,
+Ollama) or a commercial API (OpenAI, Anthropic, Gemini via its OpenAI-compatible endpoint),
+self-hosted or not, with no lock-in. See docs/ai-providers.md.
+"""
+
+from .factory import build_summariser, build_transcriber
+
+__all__ = ["build_summariser", "build_transcriber"]

server/app/providers/base.py

@@ -0,0 +1,54 @@
+# SPDX-License-Identifier: GPL-3.0-only
+"""Provider interfaces plus the shared summary prompt and a tolerant JSON parser.
+
+Keeping the prompt and parser here means every LLM provider produces the same Summary
+shape regardless of whether it is OpenAI-compatible, Anthropic, or a local model.
+"""
+from __future__ import annotations
+
+import json
+import re
+from typing import Protocol
+
+from ..models import Summary, Transcript
+
+SUMMARY_SYSTEM = (
+    "You are a meeting-notes assistant. Given a transcript, produce a concise overview, "
+    "the key points, and any action items. Respond with ONLY a JSON object of the form "
+    '{"overview": string, "key_points": [string], "action_items": [string]} and nothing '
+    "else."
+)
+
+
+def summary_user_prompt(transcript_text: str) -> str:
+    return f"Transcript:\n\n{transcript_text}\n\nProduce the JSON summary now."
+
+
+def parse_summary(recording_id: str, model: str, raw: str) -> Summary:
+    """Parse an LLM reply into a Summary, tolerating prose or code-fences around the JSON."""
+    data: dict = {}
+    match = re.search(r"\{.*\}", raw, re.DOTALL)
+    if match:
+        try:
+            data = json.loads(match.group(0))
+        except json.JSONDecodeError:
+            data = {}
+    return Summary(
+        recording_id=recording_id,
+        model=model,
+        overview=str(data.get("overview") or raw.strip()[:1000]),
+        key_points=[str(x) for x in (data.get("key_points") or [])],
+        action_items=[str(x) for x in (data.get("action_items") or [])],
+    )
+
+
+class Transcriber(Protocol):
+    name: str
+
+    def transcribe(self, audio_path: str, language: str | None = None) -> Transcript: ...
+
+
+class Summariser(Protocol):
+    name: str
+
+    def summarise(self, recording_id: str, transcript_text: str) -> Summary: ...

server/app/providers/factory.py

@@ -0,0 +1,40 @@
+# SPDX-License-Identifier: GPL-3.0-only
+"""Build the configured providers from settings, applying sensible per-provider defaults."""
+from __future__ import annotations
+
+from ..config import settings
+from .base import Summariser, Transcriber
+from .summary import AnthropicSummariser, OpenAICompatibleSummariser
+from .transcription import LocalWhisperTranscriber, OpenAICompatibleTranscriber
+
+
+def build_summariser() -> Summariser:
+    provider = settings.llm_provider
+    model = settings.llm_model
+
+    if provider == "anthropic":
+        return AnthropicSummariser(settings.llm_api_key, model or "claude-opus-4-8")
+
+    if provider == "openai_compatible":
+        return OpenAICompatibleSummariser(
+            settings.llm_base_url, settings.llm_api_key, model or "gpt-4o-mini"
+        )
+
+    # Default: Ollama via its OpenAI-compatible /v1 endpoint (fully self-hosted).
+    base = settings.ollama_url.rstrip("/") + "/v1"
+    return OpenAICompatibleSummariser(
+        base, settings.llm_api_key or "ollama", model or settings.ollama_model or "llama3.1"
+    )
+
+
+def build_transcriber() -> Transcriber:
+    if settings.transcription_provider == "openai_compatible":
+        return OpenAICompatibleTranscriber(
+            settings.transcription_base_url,
+            settings.transcription_api_key,
+            settings.transcription_model or "whisper-1",
+        )
+    # Default: local faster-whisper (self-hosted).
+    return LocalWhisperTranscriber(
+        settings.whisper_model, settings.whisper_device, settings.whisper_compute_type
+    )

server/app/providers/summary.py

@@ -0,0 +1,66 @@
+# SPDX-License-Identifier: GPL-3.0-only
+"""Summarisation providers.
+
+- OpenAICompatibleSummariser: any endpoint speaking the OpenAI /chat/completions API -
+  OpenAI, Groq, Together, OpenRouter, LocalAI, vLLM, LM Studio, and Ollama's /v1 endpoint.
+- AnthropicSummariser: Claude via the official Anthropic SDK (Messages API). Anthropic does
+  not expose an OpenAI-compatible endpoint, so it needs its own provider.
+"""
+from __future__ import annotations
+
+import httpx
+
+from ..models import Summary
+from .base import SUMMARY_SYSTEM, parse_summary, summary_user_prompt
+
+
+class OpenAICompatibleSummariser:
+    """Talks the OpenAI Chat Completions API. Works with any compatible base_url."""
+
+    def __init__(self, base_url: str, api_key: str, model: str):
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.model = model
+        self.name = f"openai_compatible:{model}"
+
+    def summarise(self, recording_id: str, transcript_text: str) -> Summary:
+        headers = {"Authorization": f"Bearer {self.api_key}"} if self.api_key else {}
+        payload = {
+            "model": self.model,
+            "messages": [
+                {"role": "system", "content": SUMMARY_SYSTEM},
+                {"role": "user", "content": summary_user_prompt(transcript_text)},
+            ],
+            "temperature": 0.2,
+            # Honoured by OpenAI/Groq/vLLM/etc.; ignored by servers that don't support it.
+            "response_format": {"type": "json_object"},
+        }
+        resp = httpx.post(
+            f"{self.base_url}/chat/completions", headers=headers, json=payload, timeout=120
+        )
+        resp.raise_for_status()
+        content = resp.json()["choices"][0]["message"]["content"]
+        return parse_summary(recording_id, self.name, content)
+
+
+class AnthropicSummariser:
+    """Claude via the official Anthropic SDK. Default model: claude-opus-4-8."""
+
+    def __init__(self, api_key: str, model: str):
+        import anthropic  # imported lazily so the dep is only needed for this provider
+
+        self._client = (
+            anthropic.Anthropic(api_key=api_key) if api_key else anthropic.Anthropic()
+        )
+        self.model = model
+        self.name = f"anthropic:{model}"
+
+    def summarise(self, recording_id: str, transcript_text: str) -> Summary:
+        resp = self._client.messages.create(
+            model=self.model,
+            max_tokens=2000,
+            system=SUMMARY_SYSTEM,
+            messages=[{"role": "user", "content": summary_user_prompt(transcript_text)}],
+        )
+        text = next((b.text for b in resp.content if b.type == "text"), "")
+        return parse_summary(recording_id, self.name, text)

server/app/providers/transcription.py

@@ -0,0 +1,65 @@
+# SPDX-License-Identifier: GPL-3.0-only
+"""Transcription providers.
+
+- OpenAICompatibleTranscriber: any endpoint speaking the OpenAI /audio/transcriptions API -
+  OpenAI Whisper, Groq (whisper-large-v3), or a self-hosted whisper.cpp/faster-whisper
+  server exposing that route.
+- LocalWhisperTranscriber: in-process faster-whisper. Wired up in M5 (needs the model
+  download); the interface and config exist now so it is selectable.
+"""
+from __future__ import annotations
+
+import os
+
+import httpx
+
+from ..models import Transcript, TranscriptSegment
+
+
+class OpenAICompatibleTranscriber:
+    def __init__(self, base_url: str, api_key: str, model: str):
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.model = model
+        self.name = f"openai_compatible:{model}"
+
+    def transcribe(self, audio_path: str, language: str | None = None) -> Transcript:
+        headers = {"Authorization": f"Bearer {self.api_key}"} if self.api_key else {}
+        data = {"model": self.model, "response_format": "verbose_json"}
+        if language:
+            data["language"] = language
+        with open(audio_path, "rb") as f:
+            files = {"file": (os.path.basename(audio_path), f, "audio/wav")}
+            resp = httpx.post(
+                f"{self.base_url}/audio/transcriptions",
+                headers=headers,
+                data=data,
+                files=files,
+                timeout=600,
+            )
+        resp.raise_for_status()
+        body = resp.json()
+        segments = [
+            TranscriptSegment(start=s.get("start", 0.0), end=s.get("end", 0.0),
+                              text=s.get("text", ""))
+            for s in body.get("segments", [])
+        ]
+        return Transcript(
+            recording_id="",
+            language=body.get("language") or language or "en",
+            model=self.name,
+            text=body.get("text", ""),
+            segments=segments,
+        )
+
+
+class LocalWhisperTranscriber:
+    def __init__(self, model: str, device: str, compute_type: str):
+        self.model = model
+        self.device = device
+        self.compute_type = compute_type
+        self.name = f"faster-whisper:{model}"
+
+    def transcribe(self, audio_path: str, language: str | None = None) -> Transcript:
+        # M5: load faster_whisper.WhisperModel(self.model, device, compute_type) and run it.
+        raise NotImplementedError("Local faster-whisper transcription lands in M5")