feat(logic): dostawcy LLM i pisanie horoskopu (LOG-31)

Domyslnie model LOKALNY — prompt niesie oryginalne opisy z baz, wiec
domyslnie NIC nie opuszcza sieci. Chmura wlaczana swiadomie (LOG-32).

- app/llm/: LLMProvider (jak EphemerisEngine z LOG-24) + dwie implementacje.
  Lokalny serwer modelu (Ollama/vLLM/llama.cpp) i OpenAI mowia TYM SAMYM
  protokolem /chat/completions, wiec obsluguje je jedna klasa; Anthropic ma
  wlasny /v1/messages. Napisane na samym httpx — bez SDK openai/anthropic:
  mniej zaleznosci i pelna kontrola nad tym, co wychodzi z sieci.
- Kazdy dostawca deklaruje `leaves_lan` — interfejs MUSI jawnie mowic, czy
  tresc baz opuszcza siec; UI na tej podstawie ostrzega.
- Ponawianie z backoffem (429/5xx), timeouty, czytelne bledy zamiast stacktrace.
- Klucz wylacznie z LLM_API_KEY (sekret), nigdy w repo ani w UI.
- POST /chart/horoscope + GET /llm/health.

WAZNE: prompt jest zwracany ZAWSZE — takze gdy model padnie lub brakuje
klucza. Dzieki temu awaria dostawcy nie blokuje pracy: prompt mozna
skopiowac i uzyc recznie.

Prezentacja: wybor modelu (lokalny/Anthropic/OpenAI), przycisk „Napisz
horoskop (AI)", wynik z informacja kto go napisal, czy dane opuscily siec,
ile wskazan weszlo, oraz zastrzezenie ze to nie porada medyczna (PRE-15).

Testy: 13 nowych (transport podstawiony — zaden prawdziwy model nie wolany),
calosc 131 passed / 1 skipped. Zweryfikowane e2e na atrapie serwera modelu:
horoskop napisany, leaves_lan=false, tokeny zliczone; a przy padnietym
modelu / braku klucza / zlym dostawcy — czytelny blad i zachowany prompt.

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

services/logic/app/llm/__init__.py

@@ -0,0 +1 @@
+"""Warstwa dostawców modeli językowych (LOG-31)."""

services/logic/app/llm/base.py

@@ -0,0 +1,42 @@
+"""Kontrakt dostawcy modelu językowego (LOG-31).
+
+Analogicznie do `EphemerisEngine` (LOG-24): prezentacja i reszta logiki nie wiedzą,
+kto pisze tekst — lokalny model na naszym sprzęcie czy dostawca w chmurze.
+
+Kluczowa własność dla bezpieczeństwa baz (LOG-32): każdy dostawca deklaruje
+`leaves_lan`. Prompt niesie ORYGINALNE opisy z baz, więc interfejs musi jawnie
+mówić, czy ta treść opuszcza naszą sieć — UI ma na tej podstawie ostrzegać.
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Completion:
+    """Wynik generowania — tekst + metryki do rozliczenia i podglądu."""
+
+    text: str
+    model: str
+    provider: str
+    leaves_lan: bool
+    usage: dict = field(default_factory=dict)   # prompt_tokens / completion_tokens
+
+
+class LLMError(RuntimeError):
+    """Błąd wołania modelu — z komunikatem nadającym się do pokazania użytkownikowi."""
+
+
+class LLMProvider(ABC):
+    name: str = "?"
+    #: czy treść promptu (a więc opisy z baz) opuszcza naszą sieć
+    leaves_lan: bool = True
+
+    @abstractmethod
+    def generate(self, prompt: str, max_tokens: int) -> Completion:
+        """Zwraca gotowy tekst. Rzuca LLMError przy niepowodzeniu."""
+
+    @abstractmethod
+    def health(self) -> dict:
+        """Czy dostawca jest osiągalny i skonfigurowany."""

services/logic/app/llm/factory.py

@@ -0,0 +1,70 @@
+"""Wybór dostawcy LLM (LOG-31) — jedyne miejsce znające konkretne implementacje.
+
+Domyślny jest **model lokalny**: prompt niesie oryginalne opisy z baz, więc
+domyślnie nic nie opuszcza naszej sieci (LOG-32). Chmurę włącza się świadomie —
+przez konfigurację albo pojedyncze żądanie.
+
+Zmienne środowiskowe:
+  LLM_PROVIDER   local (domyślnie) | openai | anthropic
+  LLM_MODEL      nazwa modelu (domyślna zależy od dostawcy)
+  LLM_BASE_URL   adres API (domyślnie: lokalny serwer zgodny z OpenAI)
+  LLM_API_KEY    klucz — WYŁĄCZNIE z sekretu; niepotrzebny dla modelu lokalnego
+  LLM_TIMEOUT    sekundy (domyślnie 120)
+  LLM_MAX_TOKENS limit długości odpowiedzi (domyślnie 2000)
+"""
+from __future__ import annotations
+
+import os
+
+from app.llm.base import LLMError, LLMProvider
+from app.llm.providers import AnthropicProvider, ChatCompletionsProvider
+
+LOCAL = "local"
+OPENAI = "openai"
+ANTHROPIC = "anthropic"
+PROVIDERS = (LOCAL, OPENAI, ANTHROPIC)
+
+_DEFAULT_MODEL = {
+    LOCAL: "llama3.1:8b",
+    OPENAI: "gpt-4o-mini",
+    ANTHROPIC: "claude-sonnet-5",
+}
+_DEFAULT_URL = {
+    # Ollama i vLLM wystawiają zgodne API pod /v1
+    LOCAL: "http://localhost:11434/v1",
+    OPENAI: "https://api.openai.com/v1",
+    ANTHROPIC: "https://api.anthropic.com",
+}
+
+
+def default_provider_name() -> str:
+    return os.getenv("LLM_PROVIDER", LOCAL).lower()
+
+
+def max_tokens() -> int:
+    return int(os.getenv("LLM_MAX_TOKENS", "2000"))
+
+
+def timeout() -> float:
+    return float(os.getenv("LLM_TIMEOUT", "120"))
+
+
+def build_provider(name: str | None = None) -> LLMProvider:
+    name = (name or default_provider_name()).lower()
+    if name not in PROVIDERS:
+        raise LLMError(f"Nieznany dostawca LLM: {name!r} (dostępne: {', '.join(PROVIDERS)})")
+
+    model = os.getenv("LLM_MODEL") or _DEFAULT_MODEL[name]
+    base_url = os.getenv("LLM_BASE_URL") or _DEFAULT_URL[name]
+    api_key = os.getenv("LLM_API_KEY", "")
+
+    if name == ANTHROPIC:
+        return AnthropicProvider(base_url, model, api_key, timeout())
+    if name == OPENAI:
+        if not api_key:
+            raise LLMError("Brak LLM_API_KEY — dostawca openai wymaga klucza.")
+        return ChatCompletionsProvider(OPENAI, base_url, model, api_key, timeout(),
+                                       leaves_lan=True)
+    # lokalny — klucz zwykle zbędny; treść NIE opuszcza sieci
+    return ChatCompletionsProvider(LOCAL, base_url, model, api_key, timeout(),
+                                   leaves_lan=False)

services/logic/app/llm/providers.py

@@ -0,0 +1,143 @@
+"""Implementacje dostawców LLM (LOG-31) — na samym httpx, bez SDK.
+
+Świadomie bez bibliotek `openai` / `anthropic`: lokalny serwer modelu (Ollama,
+vLLM, llama.cpp) i OpenAI mówią **tym samym** protokołem `/chat/completions`,
+więc jedna implementacja obsługuje oba — różni je tylko adres i klucz. Anthropic
+ma własny kształt `/v1/messages`, stąd druga klasa. Mniej zależności, mniej
+powierzchni ataku, pełna kontrola nad tym, co wychodzi z sieci.
+"""
+from __future__ import annotations
+
+import time
+
+import httpx
+
+from app.llm.base import Completion, LLMError, LLMProvider
+
+RETRY_STATUSES = {429, 500, 502, 503, 504}
+MAX_ATTEMPTS = 3
+
+
+def _post_with_retry(url: str, headers: dict, payload: dict, timeout: float) -> dict:
+    """POST z ponawianiem i backoffem — chroni przed chwilowym 429/5xx."""
+    last: Exception | None = None
+    for attempt in range(MAX_ATTEMPTS):
+        try:
+            with httpx.Client(timeout=timeout) as client:
+                r = client.post(url, json=payload, headers=headers)
+            if r.status_code in RETRY_STATUSES and attempt < MAX_ATTEMPTS - 1:
+                time.sleep(2 ** attempt)
+                continue
+            if r.status_code >= 400:
+                raise LLMError(f"Model odpowiedział błędem {r.status_code}: {r.text[:300]}")
+            return r.json()
+        except httpx.TimeoutException as e:
+            last = e
+            if attempt < MAX_ATTEMPTS - 1:
+                time.sleep(2 ** attempt)
+                continue
+            raise LLMError(
+                f"Model nie odpowiedział w czasie {timeout:.0f}s. Dłuższe horoskopy "
+                f"wymagają większego LLM_TIMEOUT albo mniejszego budżetu promptu."
+            ) from e
+        except httpx.HTTPError as e:
+            last = e
+            if attempt < MAX_ATTEMPTS - 1:
+                time.sleep(2 ** attempt)
+                continue
+            raise LLMError(f"Nie udało się połączyć z modelem: {e}") from e
+    raise LLMError(f"Nie udało się wywołać modelu: {last}")
+
+
+class ChatCompletionsProvider(LLMProvider):
+    """Protokół OpenAI `/chat/completions` — lokalny serwer modelu ORAZ OpenAI."""
+
+    def __init__(self, name: str, base_url: str, model: str, api_key: str = "",
+                 timeout: float = 120.0, leaves_lan: bool = True) -> None:
+        self.name = name
+        self.base_url = base_url.rstrip("/")
+        self.model = model
+        self.api_key = api_key
+        self.timeout = timeout
+        self.leaves_lan = leaves_lan
+
+    def _headers(self) -> dict:
+        h = {"Content-Type": "application/json"}
+        if self.api_key:
+            h["Authorization"] = f"Bearer {self.api_key}"
+        return h
+
+    def generate(self, prompt: str, max_tokens: int) -> Completion:
+        data = _post_with_retry(
+            f"{self.base_url}/chat/completions", self._headers(),
+            {
+                "model": self.model,
+                "max_tokens": max_tokens,
+                "messages": [{"role": "user", "content": prompt}],
+            },
+            self.timeout,
+        )
+        try:
+            text = data["choices"][0]["message"]["content"]
+        except (KeyError, IndexError, TypeError) as e:
+            raise LLMError(f"Nieoczekiwany kształt odpowiedzi modelu: {str(data)[:300]}") from e
+        return Completion(
+            text=text, model=data.get("model", self.model), provider=self.name,
+            leaves_lan=self.leaves_lan, usage=data.get("usage") or {},
+        )
+
+    def health(self) -> dict:
+        info = {"provider": self.name, "model": self.model, "leaves_lan": self.leaves_lan}
+        try:
+            with httpx.Client(timeout=min(self.timeout, 10.0)) as client:
+                r = client.get(f"{self.base_url}/models", headers=self._headers())
+            info["status"] = "ok" if r.status_code < 400 else f"http {r.status_code}"
+        except httpx.HTTPError as e:
+            info["status"] = f"down: {e}"
+        return info
+
+
+class AnthropicProvider(LLMProvider):
+    """Protokół Anthropic `/v1/messages`."""
+
+    leaves_lan = True
+
+    def __init__(self, base_url: str, model: str, api_key: str = "",
+                 timeout: float = 120.0) -> None:
+        self.name = "anthropic"
+        self.base_url = base_url.rstrip("/")
+        self.model = model
+        self.api_key = api_key
+        self.timeout = timeout
+
+    def generate(self, prompt: str, max_tokens: int) -> Completion:
+        if not self.api_key:
+            raise LLMError("Brak LLM_API_KEY — dostawca anthropic wymaga klucza.")
+        data = _post_with_retry(
+            f"{self.base_url}/v1/messages",
+            {
+                "Content-Type": "application/json",
+                "x-api-key": self.api_key,
+                "anthropic-version": "2023-06-01",
+            },
+            {
+                "model": self.model,
+                "max_tokens": max_tokens,
+                "messages": [{"role": "user", "content": prompt}],
+            },
+            self.timeout,
+        )
+        try:
+            text = "".join(b.get("text", "") for b in data["content"] if b.get("type") == "text")
+        except (KeyError, TypeError) as e:
+            raise LLMError(f"Nieoczekiwany kształt odpowiedzi modelu: {str(data)[:300]}") from e
+        return Completion(
+            text=text, model=data.get("model", self.model), provider=self.name,
+            leaves_lan=True, usage=data.get("usage") or {},
+        )
+
+    def health(self) -> dict:
+        return {
+            "provider": self.name, "model": self.model, "leaves_lan": True,
+            "status": "ok (klucz ustawiony)" if self.api_key else "brak LLM_API_KEY",
+        }

services/logic/app/main.py

@@ -203,6 +203,54 @@ def chart_prompt(req: PromptRequest) -> dict:
     return out
 
 
+class HoroscopeRequest(PromptRequest):
+    """Jak PromptRequest + wybór dostawcy modelu (LOG-31)."""
+    provider: str | None = None        # local (dom.) | openai | anthropic
+    max_tokens: int | None = None
+
+
+@app.post("/chart/horoscope")
+def chart_horoscope(req: HoroscopeRequest) -> dict:
+    """Napisany horoskop (LOG-31): prompt z LOG-29/30 → model → gotowy tekst.
+
+    Zwraca TAKŻE użyty prompt — również gdy wywołanie modelu padnie — żeby dało się
+    go obejrzeć i użyć ręcznie. `leaves_lan` mówi, czy treść baz opuściła naszą sieć
+    (LOG-32); prezentacja ma na tej podstawie ostrzegać.
+    """
+    from app.llm.base import LLMError
+    from app.llm.factory import build_provider, max_tokens
+
+    out = chart_prompt(req)            # ten sam prompt co w podglądzie
+    try:
+        provider = build_provider(req.provider)
+        result = provider.generate(out["prompt"], req.max_tokens or max_tokens())
+    except LLMError as e:
+        # prompt zostaje — użytkownik moze go skopiowac i uzyc recznie
+        out["llm_error"] = str(e)
+        return out
+
+    out.update(
+        horoscope=result.text,
+        provider=result.provider,
+        model=result.model,
+        leaves_lan=result.leaves_lan,
+        usage=result.usage,
+    )
+    return out
+
+
+@app.get("/llm/health")
+def llm_health(provider: str | None = None) -> dict:
+    """Czy model jest osiągalny i skonfigurowany (bez generowania czegokolwiek)."""
+    from app.llm.base import LLMError
+    from app.llm.factory import build_provider
+
+    try:
+        return build_provider(provider).health()
+    except LLMError as e:
+        return {"status": f"blad konfiguracji: {e}"}
+
+
 class ProfectionsRequest(BaseModel):
     when_utc: datetime           # moment urodzenia (UTC)
     lat: float = 0.0