phase 4

core/detect/providers/__init__.py

@@ -0,0 +1,58 @@
+"""
+Cloud LLM provider registry.
+
+Select provider via CLOUD_LLM_PROVIDER env var.
+Each provider reads its own env vars for auth/config.
+
+    CLOUD_LLM_PROVIDER=groq   → GROQ_API_KEY, GROQ_MODEL, GROQ_BASE_URL
+    CLOUD_LLM_PROVIDER=gemini → GEMINI_API_KEY, GEMINI_MODEL
+    CLOUD_LLM_PROVIDER=openai → OPENAI_API_KEY, OPENAI_MODEL, OPENAI_BASE_URL
+    CLOUD_LLM_PROVIDER=claude → ANTHROPIC_API_KEY, CLAUDE_MODEL
+"""
+
+from __future__ import annotations
+
+import os
+
+from .base import CloudProvider, ProviderResponse
+from .groq import GroqProvider
+from .gemini import GeminiProvider
+from .openai_compat import OpenAICompatProvider
+from .claude import ClaudeProvider
+
+PROVIDERS: dict[str, type] = {
+    "groq": GroqProvider,
+    "gemini": GeminiProvider,
+    "openai": OpenAICompatProvider,
+    "claude": ClaudeProvider,
+}
+
+_cached: CloudProvider | None = None
+
+
+def get_provider() -> CloudProvider:
+    """Get the configured cloud provider (cached after first call)."""
+    global _cached
+    if _cached is not None:
+        return _cached
+
+    name = os.environ.get("CLOUD_LLM_PROVIDER", "groq")
+    cls = PROVIDERS.get(name)
+    if cls is None:
+        raise ValueError(f"Unknown provider: {name!r}. Options: {list(PROVIDERS)}")
+
+    _cached = cls()
+    return _cached
+
+
+def has_api_key() -> bool:
+    """Check if the configured provider has an API key set."""
+    name = os.environ.get("CLOUD_LLM_PROVIDER", "groq")
+    key_map = {
+        "groq": "GROQ_API_KEY",
+        "gemini": "GEMINI_API_KEY",
+        "openai": "OPENAI_API_KEY",
+        "claude": "ANTHROPIC_API_KEY",
+    }
+    env_var = key_map.get(name, "")
+    return bool(os.environ.get(env_var, ""))

core/detect/providers/base.py

@@ -0,0 +1,36 @@
+"""Cloud LLM provider protocol and model metadata."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+
+@dataclass
+class ModelInfo:
+    """Metadata for a cloud LLM model."""
+    id: str
+    vision: bool = True
+    cost_per_input_token: float = 0.0
+    cost_per_output_token: float = 0.0
+    max_output_tokens: int = 4096
+    notes: str = ""
+
+
+@dataclass
+class ProviderResponse:
+    answer: str
+    total_tokens: int = 0
+
+
+class CloudProvider(Protocol):
+    """
+    Interface for cloud LLM providers.
+
+    Each provider handles its own auth, payload format, and response parsing.
+    The pipeline only calls call() and reads the response.
+    """
+    name: str
+    models: dict[str, ModelInfo]
+
+    def call(self, image_b64: str, prompt: str) -> ProviderResponse: ...

core/detect/providers/claude.py

@@ -0,0 +1,73 @@
+"""Anthropic Claude provider — uses the official SDK."""
+
+from __future__ import annotations
+
+import logging
+import os
+
+from .base import ModelInfo, ProviderResponse
+
+logger = logging.getLogger(__name__)
+
+# Claude-specific env vars
+# ANTHROPIC_API_KEY is read by the SDK automatically
+CLAUDE_MODEL = os.environ.get("CLAUDE_MODEL", "claude-sonnet-4-20250514")
+
+MODELS = {
+    "claude-sonnet-4-20250514": ModelInfo(
+        id="claude-sonnet-4-20250514",
+        vision=True,
+        cost_per_input_token=0.000003,
+        cost_per_output_token=0.000015,
+        notes="Best balance of quality/cost with vision",
+    ),
+    "claude-haiku-4-5-20251001": ModelInfo(
+        id="claude-haiku-4-5-20251001",
+        vision=True,
+        cost_per_input_token=0.0000008,
+        cost_per_output_token=0.000004,
+        notes="Fastest, cheapest, good for simple brand ID",
+    ),
+    "claude-opus-4-6": ModelInfo(
+        id="claude-opus-4-6",
+        vision=True,
+        cost_per_input_token=0.000015,
+        cost_per_output_token=0.000075,
+        notes="Highest quality, use for ambiguous cases",
+    ),
+}
+
+
+class ClaudeProvider:
+    name = "claude"
+    models = MODELS
+
+    def __init__(self):
+        from anthropic import Anthropic
+        self.client = Anthropic()
+        self.model = CLAUDE_MODEL
+
+    def call(self, image_b64: str, prompt: str) -> ProviderResponse:
+        message = self.client.messages.create(
+            model=self.model,
+            max_tokens=150,
+            messages=[{
+                "role": "user",
+                "content": [
+                    {
+                        "type": "image",
+                        "source": {
+                            "type": "base64",
+                            "media_type": "image/jpeg",
+                            "data": image_b64,
+                        },
+                    },
+                    {"type": "text", "text": prompt},
+                ],
+            }],
+        )
+
+        answer = message.content[0].text.strip()
+        total_tokens = message.usage.input_tokens + message.usage.output_tokens
+
+        return ProviderResponse(answer=answer, total_tokens=total_tokens)

core/detect/providers/gemini.py

@@ -0,0 +1,75 @@
+"""Google Gemini provider — native REST API, not OpenAI-compatible."""
+
+from __future__ import annotations
+
+import logging
+import os
+
+import requests
+
+from .base import ModelInfo, ProviderResponse
+
+logger = logging.getLogger(__name__)
+
+# Gemini-specific env vars
+GEMINI_API_KEY = os.environ.get("GEMINI_API_KEY", "")
+GEMINI_MODEL = os.environ.get("GEMINI_MODEL", "gemini-2.0-flash")
+
+MODELS = {
+    "gemini-2.0-flash": ModelInfo(
+        id="gemini-2.0-flash",
+        vision=True,
+        cost_per_input_token=0.0000001,
+        cost_per_output_token=0.0000004,
+        notes="Fast, cheap, good vision",
+    ),
+    "gemini-2.0-pro": ModelInfo(
+        id="gemini-2.0-pro",
+        vision=True,
+        cost_per_input_token=0.00000125,
+        cost_per_output_token=0.000005,
+        notes="Higher quality, slower",
+    ),
+    "gemini-1.5-flash": ModelInfo(
+        id="gemini-1.5-flash",
+        vision=True,
+        cost_per_input_token=0.000000075,
+        cost_per_output_token=0.0000003,
+        notes="Cheapest option",
+    ),
+}
+
+
+class GeminiProvider:
+    name = "gemini"
+    models = MODELS
+
+    def __init__(self):
+        self.api_key = GEMINI_API_KEY
+        self.model = GEMINI_MODEL
+        self.endpoint = (
+            f"https://generativelanguage.googleapis.com/v1beta/models/"
+            f"{self.model}:generateContent"
+        )
+
+    def call(self, image_b64: str, prompt: str) -> ProviderResponse:
+        payload = {
+            "contents": [{
+                "parts": [
+                    {"text": prompt},
+                    {"inline_data": {"mime_type": "image/jpeg", "data": image_b64}},
+                ],
+            }],
+            "generationConfig": {"maxOutputTokens": 150},
+        }
+
+        url = f"{self.endpoint}?key={self.api_key}"
+        resp = requests.post(url, json=payload, timeout=30)
+        resp.raise_for_status()
+        data = resp.json()
+
+        answer = data["candidates"][0]["content"]["parts"][0]["text"].strip()
+        usage = data.get("usageMetadata", {})
+        total_tokens = usage.get("totalTokenCount", 0)
+
+        return ProviderResponse(answer=answer, total_tokens=total_tokens)

core/detect/providers/groq.py

@@ -0,0 +1,66 @@
+"""Groq cloud provider — OpenAI-compatible API with vision."""
+
+from __future__ import annotations
+
+import logging
+import os
+
+import requests
+
+from .base import ModelInfo, ProviderResponse
+
+logger = logging.getLogger(__name__)
+
+# Groq-specific env vars
+GROQ_API_KEY = os.environ.get("GROQ_API_KEY", "")
+GROQ_BASE_URL = os.environ.get("GROQ_BASE_URL", "https://api.groq.com/openai/v1")
+GROQ_MODEL = os.environ.get("GROQ_MODEL", "meta-llama/llama-4-scout-17b-16e-instruct")
+
+MODELS = {
+    "meta-llama/llama-4-scout-17b-16e-instruct": ModelInfo(
+        id="meta-llama/llama-4-scout-17b-16e-instruct",
+        vision=True,
+        cost_per_input_token=0.0,
+        cost_per_output_token=0.0,
+        notes="Llama 4 Scout, only vision model on Groq free tier",
+    ),
+}
+
+
+class GroqProvider:
+    name = "groq"
+    models = MODELS
+
+    def __init__(self):
+        self.api_key = GROQ_API_KEY
+        self.base_url = GROQ_BASE_URL
+        self.model = GROQ_MODEL
+        self.endpoint = f"{self.base_url.rstrip('/')}/chat/completions"
+        self.headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        }
+
+    def call(self, image_b64: str, prompt: str) -> ProviderResponse:
+        payload = {
+            "model": self.model,
+            "messages": [{
+                "role": "user",
+                "content": [
+                    {"type": "text", "text": prompt},
+                    {"type": "image_url", "image_url": {
+                        "url": f"data:image/jpeg;base64,{image_b64}",
+                    }},
+                ],
+            }],
+            "max_tokens": 150,
+        }
+
+        resp = requests.post(self.endpoint, headers=self.headers, json=payload, timeout=30)
+        resp.raise_for_status()
+        data = resp.json()
+
+        answer = data["choices"][0]["message"]["content"].strip()
+        total_tokens = data.get("usage", {}).get("total_tokens", 0)
+
+        return ProviderResponse(answer=answer, total_tokens=total_tokens)

core/detect/providers/openai_compat.py

@@ -0,0 +1,73 @@
+"""Generic OpenAI-compatible provider (OpenAI, Together, etc.)."""
+
+from __future__ import annotations
+
+import logging
+import os
+
+import requests
+
+from .base import ModelInfo, ProviderResponse
+
+logger = logging.getLogger(__name__)
+
+# OpenAI-compat specific env vars
+OPENAI_API_KEY = os.environ.get("OPENAI_API_KEY", "")
+OPENAI_BASE_URL = os.environ.get("OPENAI_BASE_URL", "https://api.openai.com/v1")
+OPENAI_MODEL = os.environ.get("OPENAI_MODEL", "gpt-4o-mini")
+
+MODELS = {
+    "gpt-4o-mini": ModelInfo(
+        id="gpt-4o-mini",
+        vision=True,
+        cost_per_input_token=0.00000015,
+        cost_per_output_token=0.0000006,
+        notes="Cheap, fast, decent vision",
+    ),
+    "gpt-4o": ModelInfo(
+        id="gpt-4o",
+        vision=True,
+        cost_per_input_token=0.0000025,
+        cost_per_output_token=0.00001,
+        notes="Best OpenAI vision model",
+    ),
+}
+
+
+class OpenAICompatProvider:
+    name = "openai"
+    models = MODELS
+
+    def __init__(self):
+        self.api_key = OPENAI_API_KEY
+        self.base_url = OPENAI_BASE_URL
+        self.model = OPENAI_MODEL
+        self.endpoint = f"{self.base_url.rstrip('/')}/chat/completions"
+        self.headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        }
+
+    def call(self, image_b64: str, prompt: str) -> ProviderResponse:
+        payload = {
+            "model": self.model,
+            "messages": [{
+                "role": "user",
+                "content": [
+                    {"type": "text", "text": prompt},
+                    {"type": "image_url", "image_url": {
+                        "url": f"data:image/jpeg;base64,{image_b64}",
+                    }},
+                ],
+            }],
+            "max_tokens": 150,
+        }
+
+        resp = requests.post(self.endpoint, headers=self.headers, json=payload, timeout=30)
+        resp.raise_for_status()
+        data = resp.json()
+
+        answer = data["choices"][0]["message"]["content"].strip()
+        total_tokens = data.get("usage", {}).get("total_tokens", 0)
+
+        return ProviderResponse(answer=answer, total_tokens=total_tokens)