first commit

backend/app/model_adapters/base.py

@@ -0,0 +1,93 @@
+"""Abstract base class for model adapters."""
+
+from abc import ABC, abstractmethod
+import asyncio
+import time
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+
+import httpx
+
+
+@dataclass
+class ChatResponse:
+    text: str
+    token_usage: Dict[str, int]
+    latency_ms: float
+
+
+class ModelAdapter(ABC):
+    """Unified interface for LLM vendors.
+
+    Subclasses only need to provide base_url, api_key, model name and any
+    vendor-specific headers. Concurrency and retry logic are inherited.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        model: str,
+        base_url: str,
+        concurrency: int = 5,
+        max_retries: int = 3,
+        timeout: float = 120.0,
+    ):
+        self.api_key = api_key
+        self.model = model
+        self.base_url = base_url.rstrip("/")
+        self.semaphore = asyncio.Semaphore(concurrency)
+        self.max_retries = max_retries
+        self.timeout = timeout
+
+    @abstractmethod
+    def _build_payload(self, prompt: str, params: Dict[str, Any]) -> Dict[str, Any]:
+        ...
+
+    @abstractmethod
+    def _extract_text(self, data: Dict[str, Any]) -> str:
+        ...
+
+    def _extract_token_usage(self, data: Dict[str, Any]) -> Dict[str, int]:
+        usage = data.get("usage", {})
+        return {
+            "prompt_tokens": usage.get("prompt_tokens", 0),
+            "completion_tokens": usage.get("completion_tokens", 0),
+            "total_tokens": usage.get("total_tokens", 0),
+        }
+
+    def _headers(self) -> Dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        }
+
+    async def chat(self, prompt: str, params: Optional[Dict[str, Any]] = None) -> ChatResponse:
+        params = params or {}
+        payload = self._build_payload(prompt, params)
+        async with self.semaphore:
+            last_exception: Optional[Exception] = None
+            for attempt in range(self.max_retries + 1):
+                start = time.perf_counter()
+                try:
+                    async with httpx.AsyncClient(timeout=self.timeout) as client:
+                        response = await client.post(
+                            f"{self.base_url}/chat/completions",
+                            headers=self._headers(),
+                            json=payload,
+                        )
+                        response.raise_for_status()
+                        data = response.json()
+                        latency_ms = (time.perf_counter() - start) * 1000
+                        return ChatResponse(
+                            text=self._extract_text(data),
+                            token_usage=self._extract_token_usage(data),
+                            latency_ms=latency_ms,
+                        )
+                except Exception as e:
+                    last_exception = e
+                    if attempt < self.max_retries:
+                        wait = 2**attempt
+                        await asyncio.sleep(wait)
+            raise RuntimeError(
+                f"Model {self.model} failed after {self.max_retries} retries: {last_exception}"
+            )

backend/app/model_adapters/factory.py

@@ -0,0 +1,48 @@
+"""Factory for creating model adapters from configuration."""
+
+from app.config import get_settings
+from app.model_adapters.base import ModelAdapter
+from app.model_adapters.providers import DeepSeekAdapter, KimiAdapter, QwenAdapter
+
+
+_ADAPTER_MAP = {
+    "deepseek": DeepSeekAdapter,
+    "kimi": KimiAdapter,
+    "qwen": QwenAdapter,
+}
+
+
+def create_adapter(model_id: str, concurrency: int = 5, max_retries: int = 3) -> ModelAdapter:
+    settings = get_settings()
+    model_id = model_id.lower()
+    adapter_cls = _ADAPTER_MAP.get(model_id)
+    if not adapter_cls:
+        raise ValueError(f"Unknown model_id: {model_id}. Available: {list(_ADAPTER_MAP.keys())}")
+
+    if model_id == "deepseek":
+        return adapter_cls(
+            api_key=settings.deepseek_api_key or "",
+            model=settings.deepseek_model,
+            base_url=settings.deepseek_base_url,
+            concurrency=concurrency,
+            max_retries=max_retries,
+        )
+    if model_id == "kimi":
+        return adapter_cls(
+            api_key=settings.kimi_api_key or "",
+            model=settings.kimi_model,
+            base_url=settings.kimi_base_url,
+            concurrency=concurrency,
+            max_retries=max_retries,
+        )
+    return adapter_cls(
+        api_key=settings.qwen_api_key or "",
+        model=settings.qwen_model,
+        base_url=settings.qwen_base_url,
+        concurrency=concurrency,
+        max_retries=max_retries,
+    )
+
+
+def list_models() -> list[str]:
+    return list(_ADAPTER_MAP.keys())

backend/app/model_adapters/providers.py

@@ -0,0 +1,57 @@
+"""Concrete model adapters for DeepSeek, Kimi, and Qwen."""
+
+from typing import Any, Dict
+
+from app.model_adapters.base import ModelAdapter
+
+
+class DeepSeekAdapter(ModelAdapter):
+    def _build_payload(self, prompt: str, params: Dict[str, Any]) -> Dict[str, Any]:
+        return {
+            "model": self.model,
+            "messages": [{"role": "user", "content": prompt}],
+            "temperature": params.get("temperature", 0.7),
+            "max_tokens": params.get("max_tokens", 8192),
+            # Disable vendor reasoning mode: thinking tokens would otherwise
+            # exhaust max_tokens and leave `content` empty, and reasoning
+            # behavior is an uncontrolled variable in the prompt-strategy
+            # experiment.
+            "thinking": {"type": "disabled"},
+        }
+
+    def _extract_text(self, data: Dict[str, Any]) -> str:
+        return data["choices"][0]["message"]["content"]
+
+
+class KimiAdapter(ModelAdapter):
+    def _build_payload(self, prompt: str, params: Dict[str, Any]) -> Dict[str, Any]:
+        return {
+            "model": self.model,
+            "messages": [{"role": "user", "content": prompt}],
+            # kimi-k2.x rejects any temperature other than 0.6.
+            "temperature": params.get("temperature", 0.6),
+            "max_tokens": params.get("max_tokens", 8192),
+            # No `thinking` switch: kimi-k2.x rejects it, and its built-in
+            # reasoning is short enough to leave room for the answer.
+        }
+
+    def _extract_text(self, data: Dict[str, Any]) -> str:
+        return data["choices"][0]["message"]["content"]
+
+
+class QwenAdapter(ModelAdapter):
+    def _build_payload(self, prompt: str, params: Dict[str, Any]) -> Dict[str, Any]:
+        return {
+            "model": self.model,
+            "messages": [{"role": "user", "content": prompt}],
+            "temperature": params.get("temperature", 0.7),
+            "max_tokens": params.get("max_tokens", 8192),
+            # Disable vendor reasoning mode: thinking tokens would otherwise
+            # exhaust max_tokens and leave `content` empty, and reasoning
+            # behavior is an uncontrolled variable in the prompt-strategy
+            # experiment.
+            "thinking": {"type": "disabled"},
+        }
+
+    def _extract_text(self, data: Dict[str, Any]) -> str:
+        return data["choices"][0]["message"]["content"]