synop 0.1.0__py3-none-any.whl

synop/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

synop/ai_client.py

@@ -0,0 +1,214 @@
+from __future__ import annotations
+
+import base64
+import json
+import re
+from dataclasses import dataclass
+from urllib.parse import urljoin
+
+import httpx
+
+OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1"
+DEFAULT_MODEL = "x-ai/grok-4.20-beta"
+
+
+@dataclass(slots=True)
+class DescriptionResult:
+    title: str
+    short_summary: str
+    generated_description: str
+
+
+class OpenRouterError(RuntimeError):
+    pass
+
+
+class OpenRouterClient:
+    def __init__(
+        self,
+        api_key: str,
+        model: str = DEFAULT_MODEL,
+        timeout: float = 120.0,
+        api_base_url: str = OPENROUTER_BASE_URL,
+    ):
+        self.api_key = api_key
+        self.model = model
+        self.timeout = timeout
+        self.api_base_url = api_base_url.rstrip("/")
+
+    @property
+    def chat_completions_url(self) -> str:
+        if self.api_base_url.lower().endswith("/chat/completions"):
+            return self.api_base_url
+        return urljoin(f"{self.api_base_url}/", "chat/completions")
+
+    @property
+    def is_openrouter(self) -> bool:
+        return "openrouter.ai" in self.api_base_url.lower()
+
+    async def generate_description(self, frame_jpegs: list[bytes]) -> DescriptionResult:
+        if not frame_jpegs:
+            raise ValueError("No frame images were provided to the AI client")
+
+        content: list[dict[str, object]] = [
+            {
+                "type": "text",
+                "text": (
+                    "You are an expert film archiver. Analyze these sequential frames "
+                    "from a video and respond with valid JSON only. You are allowed to use explicit/adult language in case of NSFW context. "
+                    'Schema: {"title":"...", "short_summary":"...", "generated_description":"..."}. '
+                    "Requirements: title should be catchy and concise, short_summary must be exactly 2 sentences, "
+                    "generated_description must be 3 paragraphs with rich plot/detail context."
+                ),
+            }
+        ]
+
+        for frame in frame_jpegs:
+            encoded = base64.b64encode(frame).decode("ascii")
+            content.append(
+                {
+                    "type": "image_url",
+                    "image_url": {"url": f"data:image/jpeg;base64,{encoded}"},
+                }
+            )
+
+        payload = {
+            "model": self.model,
+            "messages": [{"role": "user", "content": content}],
+            "temperature": 0.4,
+        }
+
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        }
+        if self.is_openrouter:
+            headers["HTTP-Referer"] = "https://github.com/h4nz4/synop"
+            headers["X-Title"] = "synop"
+
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            response = await client.post(
+                self.chat_completions_url,
+                headers=headers,
+                json=payload,
+            )
+
+        if response.status_code >= 400:
+            self._raise_http_error(response)
+
+        data = response.json()
+        raw_content = _extract_assistant_content(data)
+        return _parse_description(raw_content)
+
+    def _raise_http_error(self, response: httpx.Response) -> None:
+        body_text = response.text
+        status = response.status_code
+        lowered = body_text.lower()
+
+        if status == 401:
+            provider = "OpenRouter" if self.is_openrouter else "API"
+            raise OpenRouterError(
+                f"{provider} authentication failed. Check SYNOP_API_KEY or saved key."
+            )
+        if status == 429:
+            provider = "OpenRouter" if self.is_openrouter else "API"
+            raise OpenRouterError(
+                f"{provider} rate limit reached. Retry later or use another model."
+            )
+        if (
+            status == 400
+            and "image" in lowered
+            and ("unsupported" in lowered or "not support" in lowered)
+        ):
+            raise OpenRouterError(
+                f"Model '{self.model}' does not appear to support vision input."
+            )
+
+        raise OpenRouterError(f"OpenRouter request failed ({status}): {body_text}")
+
+
+def _extract_assistant_content(payload: dict[str, object]) -> str:
+    choices = payload.get("choices")
+    if not isinstance(choices, list) or not choices:
+        raise OpenRouterError("OpenRouter response is missing choices")
+
+    first_choice = choices[0]
+    if not isinstance(first_choice, dict):
+        raise OpenRouterError("OpenRouter response has invalid choice format")
+
+    message = first_choice.get("message")
+    if not isinstance(message, dict):
+        raise OpenRouterError("OpenRouter response is missing message payload")
+
+    content = message.get("content")
+    if isinstance(content, str):
+        return content.strip()
+
+    if isinstance(content, list):
+        parts: list[str] = []
+        for item in content:
+            if isinstance(item, dict):
+                text = item.get("text")
+                if isinstance(text, str):
+                    parts.append(text)
+        if parts:
+            return "\n".join(parts).strip()
+
+    raise OpenRouterError("OpenRouter response did not include text content")
+
+
+def _parse_description(content: str) -> DescriptionResult:
+    data = _parse_json_maybe(content)
+    if data is not None:
+        title = str(data.get("title") or "Untitled")
+        short_summary = str(data.get("short_summary") or "No short summary provided.")
+        generated_description = str(
+            data.get("generated_description") or "No detailed description provided."
+        )
+        return DescriptionResult(
+            title=title.strip(),
+            short_summary=short_summary.strip(),
+            generated_description=generated_description.strip(),
+        )
+
+    plain = content.strip()
+    short_summary = plain[:220].strip()
+    if short_summary and not short_summary.endswith("."):
+        short_summary += "."
+    return DescriptionResult(
+        title="Generated Video Description",
+        short_summary=short_summary or "No short summary provided.",
+        generated_description=plain or "No detailed description provided.",
+    )
+
+
+def _parse_json_maybe(content: str) -> dict[str, object] | None:
+    stripped = content.strip()
+    try:
+        loaded = json.loads(stripped)
+        if isinstance(loaded, dict):
+            return loaded
+    except json.JSONDecodeError:
+        pass
+
+    fenced_match = re.search(r"```(?:json)?\s*(\{.*?\})\s*```", stripped, re.DOTALL)
+    if fenced_match:
+        candidate = fenced_match.group(1)
+        try:
+            loaded = json.loads(candidate)
+            if isinstance(loaded, dict):
+                return loaded
+        except json.JSONDecodeError:
+            pass
+
+    bracket_match = re.search(r"\{.*\}", stripped, re.DOTALL)
+    if bracket_match:
+        candidate = bracket_match.group(0)
+        try:
+            loaded = json.loads(candidate)
+            if isinstance(loaded, dict):
+                return loaded
+        except json.JSONDecodeError:
+            return None
+
+    return None