tse-agent 0.1.0__py3-none-any.whl

agent_client/__init__.py

@@ -0,0 +1,8 @@
+"""Agent Client di The Social Experiment.
+
+Gira sul computer dell'utente. Ospita l'LLM locale (Ollama / LM Studio), carica la
+personalita' dall'AGENT.md e traduce le decisioni del modello in azioni del protocollo
+verso il World Server. Il server non vede mai il modello ne' il prompt: solo le azioni.
+"""
+
+__version__ = "0.1.0"

agent_client/calibrate.py

@@ -0,0 +1,221 @@
+"""Calibrazione vera: l'LLM dell'utente risponde alle sonde (roadmap-next 1a + 1b).
+
+Il server genera le prove (probe/start), il client le fa risolvere al modello e rimanda
+le risposte (probe/submit); il grading resta tutto sul server (il client non vede mai le
+risposte attese della batteria di potenza). Questo rende VERI i numeri su cui poggiano i
+requisiti delle stanze, la regola di fascia del master e il trigger a divergenza.
+
+Scelte (concept-agent-power, concept-agent-capabilities):
+  - il system prompt NON e' l'AGENT.md: si misura il MODELLO, non la personalita'
+    (una personalita' laconica o teatrale falserebbe la misura);
+  - un modello lento/offline a meta' batteria: le prove non risposte valgono 0 (una
+    misura bassa e' comunque una misura valida), ma lo si dice all'utente;
+  - sonda 'image': l'immagine (data URL) va al modello via complete_with_image; se
+    l'adapter/modello non la supporta la sonda resta senza risposta (non verificata);
+  - sonde 'tools'/'tools_multi': il client fa da HARNESS. Il risultato dello strumento
+    viene rivelato SOLO se il modello emette la chiamata JSON corretta (e per la catena
+    get_key -> unlock(key) solo con la chiave giusta), poi il modello risponde col codice.
+    Limite onesto (come da wiki): il segreto viaggia nella sfida per l'harness, la sonda
+    verifica il comportamento di function-calling, non e' una prova crittografica.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import re
+
+import httpx
+
+from .llm.base import LLMAdapter
+
+# Neutro e severo: solo la risposta, nessuna personalita', nessuna spiegazione.
+NEUTRAL_SYSTEM = (
+    "You are taking a technical capability test. Answer with the exact answer only: "
+    "no explanations, no reasoning out loud, no punctuation around it, no extra words."
+)
+
+# Tempo massimo per singola prova: un modello lento non deve bloccare la batteria per ore.
+PER_CHALLENGE_TIMEOUT_S = 120.0
+
+
+async def _answer_power_battery(
+    adapter: LLMAdapter, challenges: list[dict], on_progress=None
+) -> tuple[dict[str, str], list[str]]:
+    """Fa risolvere le prove al modello. Ritorna (risposte, id delle prove saltate)."""
+    answers: dict[str, str] = {}
+    skipped: list[str] = []
+    for i, ch in enumerate(challenges, start=1):
+        qid = ch["id"]
+        try:
+            text = await asyncio.wait_for(
+                adapter.complete(NEUTRAL_SYSTEM, ch["prompt"]), timeout=PER_CHALLENGE_TIMEOUT_S
+            )
+            answers[qid] = (text or "").strip()
+        except Exception:  # noqa: BLE001 - modello lento/offline: la prova vale 0
+            skipped.append(qid)
+        if on_progress:
+            on_progress(i, len(challenges), qid)
+    return answers, skipped
+
+
+# --- Harness delle sonde di capacita' (1b) ---
+
+_JSON_RE = re.compile(r"\{.*\}", re.DOTALL)
+
+
+def _parse_tool_call(text: str) -> tuple[str, dict] | None:
+    """Estrae {"tool_call": <nome>, "args": {...}} dalla risposta del modello."""
+    m = _JSON_RE.search(text or "")
+    if not m:
+        return None
+    try:
+        obj = json.loads(m.group(0))
+    except (json.JSONDecodeError, ValueError):
+        return None
+    if not isinstance(obj, dict) or "tool_call" not in obj:
+        return None
+    args = obj.get("args")
+    return str(obj["tool_call"]), args if isinstance(args, dict) else {}
+
+
+async def _run_tools_challenge(adapter: LLMAdapter, ch: dict) -> str | None:
+    """Esegue una sonda tools/tools_multi facendo da harness. Ritorna la risposta finale.
+
+    Il modello vede il prompt della sfida; ogni sua chiamata JSON corretta viene
+    'eseguita' rivelando il risultato dal blocco harness; alla fine deve rispondere con
+    il codice. Massimo 3 passi di strumento (la catena vera ne richiede 2).
+    """
+    harness = ch.get("harness") or {}
+    results: dict = dict(harness.get("results") or {})
+    unlock_spec = harness.get("unlock") or None
+
+    transcript = ch["prompt"]
+    for _step in range(3):
+        reply = await asyncio.wait_for(
+            adapter.complete(NEUTRAL_SYSTEM, transcript), timeout=PER_CHALLENGE_TIMEOUT_S
+        )
+        call = _parse_tool_call(reply)
+        if call is None:
+            # Nessuna chiamata: e' la risposta finale (giusta o sbagliata che sia).
+            return (reply or "").strip()
+        name, args = call
+        if name in results:
+            tool_result = results[name]
+        elif unlock_spec is not None and name == "unlock":
+            # La catena: unlock rivela il codice SOLO con la chiave giusta.
+            if str(args.get("key", "")) == str(unlock_spec.get("expects")):
+                tool_result = unlock_spec.get("result")
+            else:
+                tool_result = "ERROR: wrong key"
+        else:
+            tool_result = "ERROR: unknown tool"
+        transcript += (
+            f"\n\nAssistant called: {json.dumps({'tool_call': name, 'args': args})}"
+            f"\nTool result: {tool_result}"
+            "\nContinue: call the next tool if needed, otherwise answer with the code only."
+        )
+    return None  # non e' arrivato a una risposta finale
+
+
+async def _answer_capabilities(
+    adapter: LLMAdapter, challenges: list[dict], on_progress=None
+) -> tuple[dict[str, str], list[str]]:
+    """Risponde alle sonde di capacita'. Chiavi risposta: cap_<modality> (come il server).
+
+    Le sonde che l'adapter/modello non supporta restano senza risposta: la capacita'
+    risulta non verificata (e costa la penalita' lieve solo se era stata dichiarata).
+    """
+    answers: dict[str, str] = {}
+    skipped: list[str] = []
+    for i, ch in enumerate(challenges, start=1):
+        modality = ch.get("modality", "")
+        key = f"cap_{modality}"
+        try:
+            if modality == "image" and ch.get("image"):
+                text = await asyncio.wait_for(
+                    adapter.complete_with_image(NEUTRAL_SYSTEM, ch["prompt"], ch["image"]),
+                    timeout=PER_CHALLENGE_TIMEOUT_S,
+                )
+                answers[key] = (text or "").strip()
+            elif modality in ("tools", "tools_multi"):
+                final = await _run_tools_challenge(adapter, ch)
+                if final is None:
+                    skipped.append(key)
+                else:
+                    answers[key] = final
+            else:
+                skipped.append(key)  # es. audio: nessuna sonda reale lato client
+        except Exception:  # noqa: BLE001 - non supportata/offline: resta non verificata
+            skipped.append(key)
+        if on_progress:
+            on_progress(i, len(challenges), key)
+    return answers, skipped
+
+
+async def run_calibration(
+    server_url: str,
+    agent_id: str,
+    token: str,
+    adapter: LLMAdapter | None,
+    on_progress=None,
+    transport=None,  # per i test: un httpx.MockTransport al posto della rete
+) -> dict:
+    """Esegue la calibrazione end-to-end contro il server. Ritorna l'esito arricchito.
+
+    Con adapter None (modalita' test, nessun LLM) le risposte sono vuote: la potenza
+    risulta 0, comunque MISURATA (non null), quindi l'onboarding puo' proseguire.
+    """
+    headers = {"X-Agent-Token": token}
+    async with httpx.AsyncClient(
+        base_url=server_url.rstrip("/"), timeout=60, transport=transport
+    ) as c:
+        started = await c.post(f"/api/agents/{agent_id}/probe/start", headers=headers)
+        started.raise_for_status()
+        battery = started.json()
+
+        power_challenges = battery.get("power", [])
+        capability_challenges = battery.get("capabilities", [])
+        if adapter is None:
+            answers, skipped = {}, [ch["id"] for ch in power_challenges]
+        else:
+            answers, skipped = await _answer_power_battery(
+                adapter, power_challenges, on_progress
+            )
+            cap_answers, cap_skipped = await _answer_capabilities(
+                adapter, capability_challenges, on_progress
+            )
+            answers.update(cap_answers)
+            skipped.extend(cap_skipped)
+
+        submitted = await c.post(
+            f"/api/agents/{agent_id}/probe/submit", json={"answers": answers}, headers=headers
+        )
+        submitted.raise_for_status()
+        result = submitted.json()
+
+    result["challenges_total"] = len(power_challenges) + (
+        len(capability_challenges) if adapter is not None else 0
+    )
+    result["challenges_answered"] = len(answers)
+    result["challenges_skipped"] = skipped
+    return result
+
+
+def print_calibration_result(result: dict) -> None:
+    """Stampa leggibile dell'esito per la CLI."""
+    print("\n--- Calibrazione completata ---")
+    print("power score:  ", result.get("power_score"))
+    print("power level:  ", result.get("power_level"))
+    print("battery ver.: ", result.get("battery_version"))
+    est = result.get("model_estimate") or {}
+    print("stima modello:", est.get("guess", "?"))
+    caps = result.get("verified_capabilities") or []
+    print("capacita' verificate:", ", ".join(caps) if caps else "-")
+    skipped = result.get("challenges_skipped") or []
+    if skipped:
+        print(
+            f"\nATTENZIONE: {len(skipped)} prove su {result.get('challenges_total')} non hanno "
+            "avuto risposta (modello lento o non raggiungibile): valgono 0."
+        )
+        print("Prove saltate:", ", ".join(skipped))

agent_client/config.py

@@ -0,0 +1,62 @@
+"""Configurazione dell'Agent Client.
+
+Legge i parametri da riga di comando e da variabili d'ambiente. Il `token` e l'`agent_id`
+si ottengono registrando l'agente (dal frontend o dal sottocomando `register`).
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+
+@dataclass
+class Config:
+    server_url: str = "http://localhost:8099"  # base HTTP del World Server (porta di dev)
+    token: str = ""            # token dell'agente (auth della connessione WS)
+    agent_id: str = ""
+    room_id: str = ""          # stanza in cui entrare e collaborare
+    runtime: str = "test"      # ollama | lmstudio | anthropic | openai | google | test
+    base_url: str = ""         # endpoint locale dell'LLM (per ollama/lmstudio)
+    model: str = "TestModel"   # modello dichiarato al server (auto-dichiarato)
+    api_key: str = ""          # chiave dell'utente per i runtime via API (Claude/GPT/Gemini)
+    inference_interval_s: int = 5  # tetto anti-spreco: intervallo minimo tra inferenze
+    agent_md_path: str = "AGENT.md"
+    # La personalita' gia' risolta. `tse-agent start` la prende dal server (e' li' che vive,
+    # approvata dal gate): se e' valorizzata vince sul file, cosi' l'utente non deve avere
+    # alcun AGENT.md sul disco. Vuota = si legge `agent_md_path` (comandi espliciti).
+    agent_md_text: str = ""
+    # Ragionamento (runtime anthropic): adaptive thinking per le decisioni piu' complesse.
+    # Spento di default per parsimonia; 'effort' regola profondita'/spesa (low..max).
+    thinking: bool = False
+    effort: str = ""           # "" = default dell'API; low | medium | high | xhigh | max
+
+    def ws_url(self) -> str:
+        base = self.server_url.replace("http://", "ws://").replace("https://", "wss://").rstrip("/")
+        return f"{base}/ws?token={self.token}"
+
+    def llm_base_url(self) -> str:
+        if self.base_url:
+            return self.base_url
+        if self.runtime == "ollama":
+            return "http://localhost:11434"
+        if self.runtime == "lmstudio":
+            return "http://localhost:1234/v1"
+        return ""
+
+
+def from_env() -> Config:
+    return Config(
+        server_url=os.environ.get("TSE_SERVER_URL", "http://localhost:8099"),
+        token=os.environ.get("TSE_TOKEN", ""),
+        agent_id=os.environ.get("TSE_AGENT_ID", ""),
+        room_id=os.environ.get("TSE_ROOM_ID", ""),
+        runtime=os.environ.get("TSE_RUNTIME", "test"),
+        base_url=os.environ.get("TSE_LLM_BASE_URL", ""),
+        model=os.environ.get("TSE_MODEL", "TestModel"),
+        api_key=os.environ.get("TSE_API_KEY", ""),
+        inference_interval_s=int(os.environ.get("TSE_INFERENCE_INTERVAL", "5")),
+        agent_md_path=os.environ.get("TSE_AGENT_MD", "AGENT.md"),
+        thinking=os.environ.get("TSE_THINKING", "").lower() in ("1", "true", "yes", "on"),
+        effort=os.environ.get("TSE_EFFORT", ""),
+    )

agent_client/llm/__init__.py

@@ -0,0 +1,10 @@
+"""Adapter verso l'LLM locale (Ollama / LM Studio).
+
+Astraggono il runtime dietro un'unica interfaccia, cosi' il resto del client non dipende
+dal runtime specifico (integration-ollama). In modalita' 'test' non c'e' LLM: il loop usa
+un'euristica, utile per far girare il mondo senza un modello locale.
+"""
+
+from .base import LLMAdapter, build_adapter
+
+__all__ = ["LLMAdapter", "build_adapter"]

agent_client/llm/anthropic.py

@@ -0,0 +1,65 @@
+"""Adapter per Claude (Anthropic API), via l'SDK ufficiale `anthropic`.
+
+L'utente porta la propria chiave API (variabile TSE_API_KEY / ANTHROPIC_API_KEY o --api-key):
+il costo dei token resta a carico suo, quindi la decentralizzazione della spesa e' preservata
+(adr-user-hosted-llms). Il World Server non vede mai la chiave ne' il prompt.
+"""
+
+from __future__ import annotations
+
+from .base import LLMAdapter
+
+
+class AnthropicAdapter(LLMAdapter):
+    def __init__(self, api_key: str, model: str, thinking: bool = False, effort: str = "") -> None:
+        try:
+            import anthropic
+        except ImportError as exc:  # noqa: BLE001
+            raise RuntimeError(
+                "Manca il pacchetto 'anthropic'. Installa con: pip install \".[api]\""
+            ) from exc
+        # api_key vuota -> l'SDK usa ANTHROPIC_API_KEY dall'ambiente.
+        self.client = anthropic.AsyncAnthropic(api_key=api_key) if api_key else anthropic.AsyncAnthropic()
+        self.model = model or "claude-opus-4-8"
+        # Adaptive thinking (opzionale, --thinking): il modello decide da solo quando e quanto
+        # ragionare; 'effort' (low..max) regola profondita' e spesa di token. Spento di default
+        # per parsimonia: le decisioni della stanza sono brevi e strutturate.
+        self.thinking = thinking
+        self.effort = effort
+
+    def _request_kwargs(self, system: str, user: str) -> dict:
+        """Costruisce i parametri della richiesta (separato per testabilita' senza rete)."""
+        kwargs: dict = {
+            "model": self.model,
+            # Col thinking attivo il ragionamento consuma output token: serve piu' spazio.
+            "max_tokens": 8192 if self.thinking else 1024,
+            "system": system,
+            "messages": [{"role": "user", "content": user}],
+        }
+        if self.thinking:
+            kwargs["thinking"] = {"type": "adaptive"}
+        if self.effort:
+            kwargs["output_config"] = {"effort": self.effort}
+        return kwargs
+
+    async def complete(self, system: str, user: str) -> str:
+        resp = await self.client.messages.create(**self._request_kwargs(system, user))
+        # Solo i blocchi di testo: gli eventuali blocchi 'thinking' non entrano nella risposta.
+        return "".join(b.text for b in resp.content if getattr(b, "type", None) == "text")
+
+    async def complete_with_image(self, system: str, user: str, image_data_url: str) -> str:
+        from .base import parse_data_url
+
+        media, b64 = parse_data_url(image_data_url)
+        kwargs = self._request_kwargs(system, user)
+        kwargs["messages"] = [
+            {
+                "role": "user",
+                "content": [
+                    {"type": "image", "source": {"type": "base64", "media_type": media, "data": b64}},
+                    {"type": "text", "text": user},
+                ],
+            }
+        ]
+        resp = await self.client.messages.create(**kwargs)
+        return "".join(b.text for b in resp.content if getattr(b, "type", None) == "text")

agent_client/llm/base.py

@@ -0,0 +1,61 @@
+"""Interfaccia comune degli adapter LLM e factory per runtime."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+
+class LLMAdapter(ABC):
+    @abstractmethod
+    async def complete(self, system: str, user: str) -> str:
+        """Restituisce il testo generato dal modello dato system+user prompt."""
+
+    async def complete_with_image(self, system: str, user: str, image_data_url: str) -> str:
+        """Come complete, ma con un'immagine (data URL) allegata al messaggio utente.
+
+        Serve alla sonda 'image' (roadmap-next 1b). Default: non supportato; gli adapter
+        multimodali fanno override. Chi chiama tratta l'eccezione come 'capacita' non
+        disponibile' (la sonda resta senza risposta, mai un crash).
+        """
+        raise NotImplementedError("image input not supported by this adapter")
+
+
+def parse_data_url(data_url: str) -> tuple[str, str]:
+    """Scompone un data URL 'data:<media>;base64,<dati>' in (media_type, base64)."""
+    head, _, b64 = data_url.partition(",")
+    media = head.removeprefix("data:").removesuffix(";base64") or "image/png"
+    return media, b64
+
+
+def build_adapter(config) -> LLMAdapter | None:
+    """Crea l'adapter per il runtime scelto. `None` = modalita' test (nessun LLM).
+
+    Runtime locali: ollama, lmstudio. Runtime via API (l'utente porta la propria chiave):
+    anthropic (Claude), openai (GPT), google (Gemini).
+    """
+    if config.runtime == "ollama":
+        from .ollama import OllamaAdapter
+
+        return OllamaAdapter(config.llm_base_url(), config.model)
+    if config.runtime == "lmstudio":
+        from .lmstudio import LMStudioAdapter
+
+        return LMStudioAdapter(config.llm_base_url(), config.model)
+    if config.runtime == "anthropic":
+        from .anthropic import AnthropicAdapter
+
+        return AnthropicAdapter(
+            config.api_key,
+            config.model,
+            thinking=getattr(config, "thinking", False),
+            effort=getattr(config, "effort", ""),
+        )
+    if config.runtime == "openai":
+        from .openai import OpenAIAdapter
+
+        return OpenAIAdapter(config.api_key, config.model)
+    if config.runtime == "google":
+        from .gemini import GoogleAdapter
+
+        return GoogleAdapter(config.api_key, config.model)
+    return None

agent_client/llm/gemini.py

@@ -0,0 +1,47 @@
+"""Adapter per Gemini (Google AI), via l'SDK ufficiale `google-genai`.
+
+L'utente porta la propria chiave (TSE_API_KEY / GOOGLE_API_KEY o --api-key). Il costo resta suo.
+"""
+
+from __future__ import annotations
+
+from .base import LLMAdapter
+
+
+class GoogleAdapter(LLMAdapter):
+    def __init__(self, api_key: str, model: str) -> None:
+        try:
+            from google import genai
+        except ImportError as exc:  # noqa: BLE001
+            raise RuntimeError(
+                "Manca il pacchetto 'google-genai'. Installa con: pip install \".[api]\""
+            ) from exc
+        self._genai = genai
+        self.client = genai.Client(api_key=api_key) if api_key else genai.Client()
+        self.model = model or "gemini-2.0-flash"
+
+    async def complete(self, system: str, user: str) -> str:
+        from google.genai import types
+
+        resp = await self.client.aio.models.generate_content(
+            model=self.model,
+            contents=user,
+            config=types.GenerateContentConfig(system_instruction=system),
+        )
+        return resp.text or ""
+
+    async def complete_with_image(self, system: str, user: str, image_data_url: str) -> str:
+        import base64
+
+        from google.genai import types
+
+        from .base import parse_data_url
+
+        media, b64 = parse_data_url(image_data_url)
+        part = types.Part.from_bytes(data=base64.b64decode(b64), mime_type=media)
+        resp = await self.client.aio.models.generate_content(
+            model=self.model,
+            contents=[part, user],
+            config=types.GenerateContentConfig(system_instruction=system),
+        )
+        return resp.text or ""

agent_client/llm/lmstudio.py

@@ -0,0 +1,54 @@
+"""Adapter per LM Studio (server locale OpenAI-compatibile, default http://localhost:1234/v1)."""
+
+from __future__ import annotations
+
+import httpx
+
+from .base import LLMAdapter
+
+
+class LMStudioAdapter(LLMAdapter):
+    def __init__(self, base_url: str, model: str) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.model = model
+
+    async def complete(self, system: str, user: str) -> str:
+        payload = {
+            "model": self.model,
+            "messages": [
+                {"role": "system", "content": system},
+                {"role": "user", "content": user},
+            ],
+            "temperature": 0.7,
+            "stream": False,
+        }
+        async with httpx.AsyncClient(timeout=120) as http:
+            resp = await http.post(f"{self.base_url}/chat/completions", json=payload)
+            resp.raise_for_status()
+            data = resp.json()
+        choices = data.get("choices") or [{}]
+        return (choices[0].get("message") or {}).get("content", "")
+
+    async def complete_with_image(self, system: str, user: str, image_data_url: str) -> str:
+        # Formato OpenAI-compatibile (funziona solo con modelli multimodali caricati).
+        payload = {
+            "model": self.model,
+            "messages": [
+                {"role": "system", "content": system},
+                {
+                    "role": "user",
+                    "content": [
+                        {"type": "text", "text": user},
+                        {"type": "image_url", "image_url": {"url": image_data_url}},
+                    ],
+                },
+            ],
+            "temperature": 0.7,
+            "stream": False,
+        }
+        async with httpx.AsyncClient(timeout=120) as http:
+            resp = await http.post(f"{self.base_url}/chat/completions", json=payload)
+            resp.raise_for_status()
+            data = resp.json()
+        choices = data.get("choices") or [{}]
+        return (choices[0].get("message") or {}).get("content", "")

agent_client/llm/ollama.py

@@ -0,0 +1,47 @@
+"""Adapter per Ollama (API HTTP locale, default http://localhost:11434)."""
+
+from __future__ import annotations
+
+import httpx
+
+from .base import LLMAdapter
+
+
+class OllamaAdapter(LLMAdapter):
+    def __init__(self, base_url: str, model: str) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.model = model
+
+    async def complete(self, system: str, user: str) -> str:
+        payload = {
+            "model": self.model,
+            "messages": [
+                {"role": "system", "content": system},
+                {"role": "user", "content": user},
+            ],
+            "stream": False,
+        }
+        async with httpx.AsyncClient(timeout=120) as http:
+            resp = await http.post(f"{self.base_url}/api/chat", json=payload)
+            resp.raise_for_status()
+            data = resp.json()
+        return (data.get("message") or {}).get("content", "")
+
+    async def complete_with_image(self, system: str, user: str, image_data_url: str) -> str:
+        # Ollama accetta immagini base64 nel messaggio (solo modelli multimodali).
+        from .base import parse_data_url
+
+        _media, b64 = parse_data_url(image_data_url)
+        payload = {
+            "model": self.model,
+            "messages": [
+                {"role": "system", "content": system},
+                {"role": "user", "content": user, "images": [b64]},
+            ],
+            "stream": False,
+        }
+        async with httpx.AsyncClient(timeout=120) as http:
+            resp = await http.post(f"{self.base_url}/api/chat", json=payload)
+            resp.raise_for_status()
+            data = resp.json()
+        return (data.get("message") or {}).get("content", "")

agent_client/llm/openai.py

@@ -0,0 +1,46 @@
+"""Adapter per GPT (OpenAI API), via l'SDK ufficiale `openai`.
+
+L'utente porta la propria chiave (TSE_API_KEY / OPENAI_API_KEY o --api-key). Il costo resta suo.
+"""
+
+from __future__ import annotations
+
+from .base import LLMAdapter
+
+
+class OpenAIAdapter(LLMAdapter):
+    def __init__(self, api_key: str, model: str) -> None:
+        try:
+            from openai import AsyncOpenAI
+        except ImportError as exc:  # noqa: BLE001
+            raise RuntimeError(
+                "Manca il pacchetto 'openai'. Installa con: pip install \".[api]\""
+            ) from exc
+        self.client = AsyncOpenAI(api_key=api_key) if api_key else AsyncOpenAI()
+        self.model = model or "gpt-4o"
+
+    async def complete(self, system: str, user: str) -> str:
+        resp = await self.client.chat.completions.create(
+            model=self.model,
+            messages=[
+                {"role": "system", "content": system},
+                {"role": "user", "content": user},
+            ],
+        )
+        return resp.choices[0].message.content or ""
+
+    async def complete_with_image(self, system: str, user: str, image_data_url: str) -> str:
+        resp = await self.client.chat.completions.create(
+            model=self.model,
+            messages=[
+                {"role": "system", "content": system},
+                {
+                    "role": "user",
+                    "content": [
+                        {"type": "text", "text": user},
+                        {"type": "image_url", "image_url": {"url": image_data_url}},
+                    ],
+                },
+            ],
+        )
+        return resp.choices[0].message.content or ""