Step 4: LLM client — DeepSeek wrapper with retry and LLMUnavailable

Implements specs/02_llm_client.md. chat_json uses response_format=json_object
and retries on 5xx/connection errors with exponential backoff; chat_vision
base64-encodes images for multimodal calls. Raises LLMUnavailable on missing
key, auth failure, or exhausted retries.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

core/llm_client.py

@@ -1,5 +1,12 @@
+import base64
+import json
+import time
 from pathlib import Path
 
+import openai
+
+from core.config import DEEPSEEK_API_KEY, DEEPSEEK_BASE_URL, MODEL_NAME
+
 
 class LLMUnavailable(Exception):
     pass
@@ -7,10 +14,47 @@ class LLMUnavailable(Exception):
 
 class LLM:
     def __init__(self, api_key: str | None = None):
-        pass
+        resolved = api_key if api_key is not None else DEEPSEEK_API_KEY
+        self._api_key = resolved
+        self._client = openai.OpenAI(
+            api_key=resolved or "no-key",
+            base_url=DEEPSEEK_BASE_URL,
+        )
+
+    def _check_key(self) -> None:
+        if not self._api_key:
+            raise LLMUnavailable("No API key configured")
 
     def chat_json(self, system: str, user: str, max_retries: int = 2) -> dict:
-        raise NotImplementedError
+        self._check_key()
+        last_exc: Exception | None = None
+        for attempt in range(max_retries + 1):
+            try:
+                resp = self._client.chat.completions.create(
+                    model=MODEL_NAME,
+                    messages=[
+                        {"role": "system", "content": system},
+                        {"role": "user", "content": user},
+                    ],
+                    temperature=0,
+                    response_format={"type": "json_object"},
+                )
+                content = resp.choices[0].message.content or ""
+                try:
+                    return json.loads(content)
+                except json.JSONDecodeError:
+                    if attempt < max_retries:
+                        system = system + " Respond ONLY with valid JSON, no prose."
+                        continue
+                    raise LLMUnavailable("Malformed JSON after retries")
+            except openai.AuthenticationError as e:
+                raise LLMUnavailable("Invalid API key") from e
+            except (openai.APIStatusError, openai.APIConnectionError) as e:
+                last_exc = e
+                if attempt < max_retries:
+                    time.sleep(2 ** attempt)
+                    continue
+        raise LLMUnavailable(f"API error after retries: {last_exc}") from last_exc
 
     def chat_vision(
         self,
@@ -19,4 +63,34 @@ class LLM:
         image: bytes | str | Path,
         max_retries: int = 2,
     ) -> str:
-        raise NotImplementedError
+        self._check_key()
+        if isinstance(image, (str, Path)):
+            raw = Path(image).read_bytes()
+        else:
+            raw = image
+        b64 = base64.b64encode(raw).decode()
+        data_uri = f"data:image/png;base64,{b64}"
+
+        last_exc: Exception | None = None
+        for attempt in range(max_retries + 1):
+            try:
+                resp = self._client.chat.completions.create(
+                    model=MODEL_NAME,
+                    messages=[
+                        {"role": "system", "content": system},
+                        {"role": "user", "content": [
+                            {"type": "text", "text": user_text},
+                            {"type": "image_url", "image_url": {"url": data_uri}},
+                        ]},
+                    ],
+                    temperature=0,
+                )
+                return resp.choices[0].message.content or ""
+            except openai.AuthenticationError as e:
+                raise LLMUnavailable("Invalid API key") from e
+            except (openai.APIStatusError, openai.APIConnectionError) as e:
+                last_exc = e
+                if attempt < max_retries:
+                    time.sleep(2 ** attempt)
+                    continue
+        raise LLMUnavailable(f"API error after retries: {last_exc}") from last_exc

specs/02_llm_client.md

@@ -0,0 +1,101 @@
+# Spec 02 — LLM Client
+
+**Step:** 4 of 15  
+**Time budget:** ~25 min  
+**Checkpoint:** `LLM().chat_json(system, user)` returns a dict when the API key is valid; raises `LLMUnavailable` when the key is missing.
+
+---
+
+## Goal
+
+Implement `core/llm_client.py` — a thin wrapper around the OpenAI Python SDK pointed at the DeepSeek API. Provides `chat_json` (JSON-mode responses) and `chat_vision` (multimodal image input). Both methods retry on transient failures and raise `LLMUnavailable` after `max_retries`.
+
+---
+
+## Dependencies
+
+- `openai` Python SDK (OpenAI-compatible, pointed at DeepSeek base URL)
+- `core.config` for `DEEPSEEK_API_KEY`, `DEEPSEEK_BASE_URL`, `MODEL_NAME`, `MODEL_VERSION`
+- `core.prompts` for prompt constants (used by callers, not by this module directly)
+
+---
+
+## Class: `LLMUnavailable`
+
+```python
+class LLMUnavailable(Exception):
+    pass
+```
+
+Raised whenever the LLM call cannot be completed after all retries. Callers should catch this and route to `fallback.py`.
+
+---
+
+## Class: `LLM`
+
+### `__init__(self, api_key: str | None = None)`
+
+- If `api_key` is `None`, use `config.DEEPSEEK_API_KEY`.
+- If the resolved key is `None` or empty: do NOT raise immediately — defer to call time so the app can start without a key (precomputed mode).
+- Create an `openai.OpenAI(api_key=key, base_url=DEEPSEEK_BASE_URL)` client and store as `self._client`.
+
+### `chat_json(self, system: str, user: str, max_retries: int = 2) -> dict`
+
+Calls the chat completions API with `response_format={"type": "json_object"}`, `temperature=0`.
+
+Messages: `[{"role": "system", "content": system}, {"role": "user", "content": user}]`
+
+Retry logic:
+1. Try the API call.
+2. On success: parse `response.choices[0].message.content` as JSON. If `json.loads` fails, retry once with a stricter system postscript `" Respond ONLY with valid JSON, no prose."`. If it fails again, raise `LLMUnavailable("Malformed JSON after retries")`.
+3. On `openai.APIStatusError` (5xx) or `openai.APIConnectionError`: exponential backoff (`2 ** attempt` seconds, max 2 attempts), then raise `LLMUnavailable`.
+4. On `openai.AuthenticationError` (401): raise `LLMUnavailable("Invalid API key")` immediately (no retry).
+5. If `api_key` is None/empty at call time: raise `LLMUnavailable("No API key configured")`.
+
+Returns `dict`.
+
+### `chat_vision(self, system: str, user_text: str, image: bytes | str | Path, max_retries: int = 2) -> str`
+
+Sends a multimodal message using the OpenAI vision format.
+
+Image encoding:
+- If `image` is `bytes`: base64-encode directly.
+- If `image` is `Path` or `str`: read the file as bytes, then base64-encode.
+- Build data URI: `f"data:image/png;base64,{b64_str}"`.
+
+Message format:
+```python
+[
+  {"role": "system", "content": system},
+  {"role": "user", "content": [
+    {"type": "text", "text": user_text},
+    {"type": "image_url", "image_url": {"url": data_uri}},
+  ]},
+]
+```
+
+Call at `temperature=0`, no `response_format` (vision endpoint returns plain text).
+
+Retry logic: same as `chat_json` but on content errors: just retry with same prompt. Returns `response.choices[0].message.content` as string.
+
+On any failure after retries: raise `LLMUnavailable`.
+
+---
+
+## Error handling summary
+
+| Condition | Behaviour |
+|---|---|
+| Missing/empty API key | `LLMUnavailable("No API key configured")` |
+| 401 AuthenticationError | `LLMUnavailable("Invalid API key")` |
+| 5xx / ConnectionError | Retry with backoff, then `LLMUnavailable` |
+| Malformed JSON (chat_json) | Retry once with stricter prompt, then `LLMUnavailable` |
+
+---
+
+## Acceptance Criteria
+
+1. `from core.llm_client import LLM, LLMUnavailable` imports cleanly.
+2. `LLM(api_key=None)` with no `.env` → calling `chat_json(...)` raises `LLMUnavailable` (not an unhandled exception).
+3. With a valid key: `LLM().chat_json("respond with valid json", '{"ok": true}')` returns `{"ok": True}` (or similar).
+4. `LLMUnavailable` is a subclass of `Exception`.