added seerr beginning tools

skills/__init__.py

@@ -3,13 +3,41 @@ Skill system — each skill is a piece of domain knowledge or a capability
 that can be attached to an agent to shape its behavior and system prompt.
 
 A Skill is a lightweight object with:
-- name        : short identifier (e.g. "media_info")
-- description : human-readable summary
+- name            : short identifier (e.g. "media_info")
+- description     : human-readable summary
 - prompt_fragment : extra text injected into the agent's system prompt
+- tools           : OpenAI function-calling tool definitions (list of dicts)
+- execute         : async callable to run a tool → ToolResult
 """
 
 from dataclasses import dataclass, field
-from typing import Dict
+from typing import Any, Awaitable, Callable, Dict, List, Optional
+from core.config import get_config  # re-export so every skill can use it
+
+
+# ---------------------------------------------------------------------------
+# ToolResult — every skill executor must return this
+# ---------------------------------------------------------------------------
+@dataclass
+class ToolResult:
+    """Result of executing a tool.
+    - success: True if the API returned 2xx and the action completed.
+    - content: The message to feed back to the LLM (will be shown to the user).
+    """
+    content: str
+    success: bool = True
+
+    @classmethod
+    def ok(cls, content: str) -> "ToolResult":
+        return cls(content=content, success=True)
+
+    @classmethod
+    def fail(cls, content: str) -> "ToolResult":
+        return cls(content=content, success=False)
+
+
+# Type alias for a tool executor
+ToolExecutor = Callable[[str, dict], Awaitable[ToolResult]]
 
 
 @dataclass
@@ -17,6 +45,8 @@ class Skill:
     name: str
     description: str
     prompt_fragment: str = ""
+    tools: List[Dict[str, Any]] = field(default_factory=list)
+    execute: Optional[ToolExecutor] = None
 
 
 # ---------------------------------------------------------------------------
@@ -48,3 +78,52 @@ def get_combined_prompt(skill_names: list[str], base_prompt: str = "") -> str:
         if s and s.prompt_fragment:
             parts.append(s.prompt_fragment)
     return "\n\n".join(parts)
+
+
+def get_all_tools(skill_names: list[str]) -> List[Dict[str, Any]]:
+    """Collect all OpenAI tool definitions across the requested skills."""
+    tools: List[Dict[str, Any]] = []
+    seen: set[str] = set()
+    for name in skill_names:
+        s = get(name)
+        if s:
+            for t in s.tools:
+                fn_name = t.get("function", {}).get("name", "")
+                if fn_name and fn_name not in seen:
+                    seen.add(fn_name)
+                    tools.append(t)
+    return tools
+
+
+async def execute_tool(
+    skill_names: list[str], tool_name: str, args: dict
+) -> ToolResult | None:
+    """Find the skill that owns *tool_name* and run its executor.
+    Only logs failures to the console — successful calls are silent.
+    """
+    import logging
+    logger = logging.getLogger("skills")
+
+    for name in skill_names:
+        s = get(name)
+        if s and s.execute:
+            for t in s.tools:
+                if t.get("function", {}).get("name") == tool_name:
+                    try:
+                        result = await s.execute(tool_name, args)
+                        if not result.success:
+                            logger.warning(
+                                "⚠️  TOOL FAILED: %s | args=%s → %s",
+                                tool_name, args, result.content[:300],
+                            )
+                        return result
+                    except Exception as exc:
+                        logger.exception(
+                            "💥 TOOL CRASH: %s | args=%s", tool_name, args
+                        )
+                        return ToolResult.fail(
+                            f"Tool '{tool_name}' crashed unexpectedly: {exc}"
+                        )
+
+    logger.warning("⚠️  TOOL NOT FOUND: %s (skills=%s)", tool_name, skill_names)
+    return None

skills/media_info.py

@@ -1,45 +1,31 @@
 """
 Demo skill: media_info
 
-Gives the agent knowledge about how to respond to media-related queries
-(movie / TV / subtitle requests). This is intentionally simple — in the future
-you would add real API-calling skills here (Sonarr / Jellyfin / Seerr / etc.).
+A lightweight base skill that teaches the agent it is a media assistant.
+Real API capabilities come from other skills (seerr, triage, etc.).
 """
 
 from skills import Skill, register
 
 media_info_skill = Skill(
     name="media_info",
-    description="Respond to media queries with a structured format "
-    "(movie / TV show requests, subtitles, tickets).",
-    prompt_fragment="""## Media Agent Instructions
+    description="Base media assistant persona — movie, TV, subtitle, and media requests.",
+    prompt_fragment="""## Media Assistant Persona
 
-You are a media assistant. When users ask about movies, TV shows, subtitles,
-or media library requests, follow these rules:
+You are a friendly media assistant connected to a media back-end (Seerr,
+Jellyfin, Sonarr, etc.). Your job is to help users discover, request, and
+troubleshoot their media library.
 
-- If a user wants to **request** a movie or show, respond with a clear
-  confirmation using this format:
+When responding:
+- Be concise and helpful.
+- Use the tools available to you for real actions.
+- If a user asks about **subtitles**, explain that Bazarr handles those and
+  suggest submitting a ticket if there's a problem.
+- Always confirm successful actions and warn about failures.
 
-  ```
-  [MEDIA REQUEST]
-  Title: <title>
-  Type: <movie | show>
-  Status: PENDING — this would be submitted to Seerr
-  ```
-
-- If a user asks about **subtitles**, acknowledge the request and respond with:
-
-  ```
-  [SUBTITLE REQUEST]
-  Media: <title>
-  Language: <language>
-  Status: PENDING — Bazarr would process this
-  ```
-
-- Otherwise, answer normally but always remind the user that media-backend
-  integrations (Seerr, Sonarr, Jellyfin) are not yet connected.
-
-This is a **demo** skill. Real API calls will be added later.""",
+This is the base media assistant persona. Real API capabilities come from the
+attached skills (seerr, triage, etc.).""",
 )
 
 register(media_info_skill)
+

skills/seerr.py

@@ -0,0 +1,470 @@
+"""
+Seerr skill — connects to Overseerr / Jellyseerr API for media discovery,
+requests, and issue submission.
+
+.env variables:
+    SEERR_URL      – base URL (e.g. https://seerr.example.com)
+    SEERR_API_KEY  – API key from Seerr settings
+    SEERR_TIMEOUT  – optional request timeout in seconds (default 30)
+"""
+
+from __future__ import annotations
+
+import json
+from urllib.parse import quote
+
+import httpx
+
+from skills import Skill, register, ToolResult, get_config
+
+# ---------------------------------------------------------------------------
+# Config
+# ---------------------------------------------------------------------------
+SEERR_URL = (get_config("SEERR_URL") or "").rstrip("/")
+SEERR_API_KEY = get_config("SEERR_API_KEY") or ""
+SEERR_TIMEOUT = int(get_config("SEERR_TIMEOUT", "30"))
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+def _client() -> httpx.AsyncClient:
+    return httpx.AsyncClient(
+        base_url=SEERR_URL,
+        headers={"X-Api-Key": SEERR_API_KEY},
+        timeout=SEERR_TIMEOUT,
+    )
+
+
+def _fmt_items(items: list[dict], kind: str) -> str:
+    """Format a list of media items for the LLM to present."""
+    lines = []
+    for i, item in enumerate(items[:10], 1):
+        title = item.get("title") or item.get("name") or "Unknown"
+        year = (
+            item.get("releaseDate", "")[:4]
+            or item.get("firstAirDate", "")[:4]
+            or "?"
+        )
+        overview = (item.get("overview") or "")[:120]
+        lines.append(f"{i}. **{title}** ({year}) — {overview}…")
+    return f"Found {len(items)} {kind}. Top results:\n\n" + "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Tool definitions (OpenAI function-calling schema)
+# ---------------------------------------------------------------------------
+TOOLS = [
+    {
+        "type": "function",
+        "function": {
+            "name": "seerr_trending",
+            "description": "Get trending movies and TV shows from Seerr using "
+            "the /discover/trending endpoint. Call this when a user asks what "
+            "is popular, trending, or new.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "kind": {
+                        "type": "string",
+                        "enum": ["movie", "tv", "all"],
+                        "description": "What kind of media to fetch. "
+                        "Use 'all' when the user doesn't specify.",
+                    },
+                    "language": {
+                        "type": "string",
+                        "description": "Language filter (e.g. 'en', 'nl'). "
+                        "Omit for all languages.",
+                    },
+                },
+                "required": ["kind"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "seerr_discover",
+            "description": "Discover movies or TV shows by genre, studio, "
+            "keyword, or language in Seerr. Uses /discover/{movies|tv}/genre/{id} "
+            "for genre queries, /discover/{movies|tv}/studio/{id} for studios, "
+            "and /discover/{movies|tv}?query= for keyword search. "
+            "Call when a user asks 'what movies in category X do you recommend?' "
+            "or 'show me horror movies' or 'find Studio Ghibli movies'.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "kind": {
+                        "type": "string",
+                        "enum": ["movie", "tv"],
+                        "description": "Media type to search.",
+                    },
+                    "genre": {
+                        "type": "string",
+                        "description": "Genre name, e.g. 'horror', 'comedy', "
+                        "'animation', 'action', 'science fiction'. "
+                        "Use this for genre-based discovery.",
+                    },
+                    "studio": {
+                        "type": "string",
+                        "description": "Studio name to filter by, e.g. "
+                        "'Studio Ghibli', 'Pixar', 'Marvel'. "
+                        "Use this for studio-based discovery.",
+                    },
+                    "keyword": {
+                        "type": "string",
+                        "description": "Free-text keyword search, e.g. "
+                        "'space', 'superhero', 'dinosaur'. "
+                        "Use this for topic-based discovery.",
+                    },
+                    "language": {
+                        "type": "string",
+                        "description": "Language filter (e.g. 'en', 'ja'). "
+                        "Omit for all languages.",
+                    },
+                    "page": {
+                        "type": "integer",
+                        "description": "Page number (default 1).",
+                    },
+                },
+                "required": ["kind"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "seerr_request_media",
+            "description": "Request a movie or TV show to be added to the media "
+            "library via Seerr. Call when a user asks 'can you request movie X?' "
+            "or 'please add show Y'.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "kind": {
+                        "type": "string",
+                        "enum": ["movie", "tv"],
+                        "description": "Whether this is a movie or TV show.",
+                    },
+                    "title": {
+                        "type": "string",
+                        "description": "The title of the movie or TV show to request.",
+                    },
+                    "tmdb_id": {
+                        "type": "integer",
+                        "description": "The TMDb ID if known (optional — Seerr will "
+                        "search by title if not provided).",
+                    },
+                },
+                "required": ["kind", "title"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "seerr_submit_issue",
+            "description": "Submit a ticket/issue for a specific media item. "
+            "Call when a user wants to report a problem (bad quality, wrong "
+            "language, missing episodes, corrupt file, etc.) or when they want "
+            "an action that only a human operator can perform. "
+            "IMPORTANT: always include the media_title so the system can "
+            "look up the correct mediaId.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "subject": {
+                        "type": "string",
+                        "description": "Short summary of the issue.",
+                    },
+                    "description": {
+                        "type": "string",
+                        "description": "Detailed description of the problem.",
+                    },
+                    "media_title": {
+                        "type": "string",
+                        "description": "The movie or TV show title this issue "
+                        "relates to. Always provide this — the system will "
+                        "search for the matching mediaId.",
+                    },
+                    "issue_type": {
+                        "type": "integer",
+                        "enum": [1, 2, 3, 4],
+                        "description": "Issue category code: "
+                        "1 = Video (playback, codec, quality), "
+                        "2 = Audio (sync, missing), "
+                        "3 = Subtitle (missing, wrong, timing), "
+                        "4 = Other (operator-only actions like delete/cancel).",
+                    },
+                },
+                "required": ["subject", "description", "media_title", "issue_type"],
+            },
+        },
+    },
+]
+
+
+# ---------------------------------------------------------------------------
+# Tool executor
+# ---------------------------------------------------------------------------
+async def _execute(tool_name: str, args: dict) -> ToolResult:
+    """Route tool calls to the right handler. Returns ToolResult with success
+    based on HTTP status code (2xx = ok, everything else = fail)."""
+    import logging
+    logger = logging.getLogger("skills.seerr")
+
+    handlers = {
+        "seerr_trending": _trending,
+        "seerr_discover": _discover,
+        "seerr_request_media": _request_media,
+        "seerr_submit_issue": _submit_issue,
+    }
+    handler = handlers.get(tool_name)
+    if not handler:
+        return ToolResult.fail(f"Unknown tool: {tool_name}")
+    try:
+        result = await handler(args)
+        return result
+    except httpx.HTTPStatusError as exc:
+        status = exc.response.status_code
+        body = exc.response.text[:500]
+        logger.error("Seerr API HTTP %s on %s: %s", status, tool_name, body)
+        return ToolResult.fail(
+            f"Seerr API returned HTTP {status} for '{tool_name}'. "
+            f"Response: {body}"
+        )
+    except httpx.HTTPError as exc:
+        logger.error("Seerr API network error on %s: %s", tool_name, exc)
+        return ToolResult.fail(
+            f"Seerr API is unreachable for '{tool_name}': {exc}"
+        )
+    except Exception as exc:
+        logger.exception("Unexpected error in %s", tool_name)
+        return ToolResult.fail(f"Unexpected error in '{tool_name}': {exc}")
+
+
+# ---------------------------------------------------------------------------
+# API handlers
+# ---------------------------------------------------------------------------
+
+async def _trending(args: dict) -> ToolResult:
+    """Use Jellyseerr's /api/v1/discover/trending endpoint.
+    Query params: language (optional), mediaType (movie | tv, default all).
+    """
+    media_type = args.get("kind", "all")
+    language = args.get("language", "").strip() or None
+
+    params: dict = {}
+    if media_type in ("movie", "tv"):
+        params["mediaType"] = media_type
+    if language:
+        params["language"] = language
+
+    async with _client() as c:
+        r = await c.get("/api/v1/discover/trending", params=params)
+        r.raise_for_status()
+        data = r.json()
+        results = data.get("results", [])
+
+    label = f"trending {media_type}" if media_type != "all" else "trending items"
+    if language:
+        label += f" ({language})"
+    if not results:
+        return ToolResult.ok(f"No {label} found right now.")
+    return ToolResult.ok(_fmt_items(results, label))
+
+
+async def _discover(args: dict) -> ToolResult:
+    """Jellyseerr discover endpoints:
+    Genre:  /api/v1/discover/{movies|tv}/genre/{genreId}
+    Studio: /api/v1/discover/{movies|tv}/studio/{studioId}
+    Keyword: /api/v1/discover/{movies|tv}?query=keyword
+    Language falls back to the base discover endpoint.
+    """
+    kind = args["kind"]
+    genre = args.get("genre", "").strip()
+    studio = args.get("studio", "").strip()
+    keyword = args.get("keyword", "").strip()
+    language = args.get("language", "").strip() or None
+    page = args.get("page", 1)
+
+    # Map common genre names to TMDb genre IDs
+    genre_map = {
+        "action": 28, "adventure": 12, "animation": 16, "comedy": 35,
+        "crime": 80, "documentary": 99, "drama": 18, "family": 10751,
+        "fantasy": 14, "history": 36, "horror": 27, "music": 10402,
+        "mystery": 9648, "romance": 10749, "science fiction": 878,
+        "sci-fi": 878, "scifi": 878, "tv movie": 10770, "thriller": 53,
+        "war": 10752, "western": 37,
+    }
+
+    base = f"/api/v1/discover/{'movies' if kind == 'movie' else 'tv'}"
+    params: dict = {"page": page}
+    endpoint = base
+
+    if genre:
+        genre_id = genre_map.get(genre.lower())
+        if not genre_id:
+            return ToolResult.fail(
+                f"I don't recognise the genre '{genre}'. "
+                f"Try one of: {', '.join(sorted(genre_map.keys()))}."
+            )
+        endpoint = f"{base}/genre/{genre_id}"
+    elif studio:
+        endpoint = f"{base}/studio/{studio}"
+    elif keyword:
+        params["query"] = keyword
+        endpoint = base
+
+    if language:
+        params["language"] = language
+
+    async with _client() as c:
+        r = await c.get(endpoint, params=params)
+        r.raise_for_status()
+        results = r.json().get("results", [])
+
+    desc = genre or studio or keyword or kind
+    if not results:
+        return ToolResult.ok(f"No {desc} {kind}s found.")
+    return ToolResult.ok(_fmt_items(results, f"{desc} {kind}s"))
+
+
+async def _request_media(args: dict) -> ToolResult:
+    kind = args["kind"]
+    title = args["title"]
+    tmdb_id = args.get("tmdb_id")
+
+    # Step 1: Search for the media
+    async with _client() as c:
+        r = await c.get("/api/v1/search/", params={"query": quote(title), "page": 1})
+        r.raise_for_status()
+        results = r.json().get("results", [])
+
+        # Filter by mediaType if we have results from unified search
+        filtered = [item for item in results if item.get("mediaType") == kind] if results else []
+        if not filtered:
+            filtered = results  # fallback if mediaType not set
+
+        if not filtered:
+            return ToolResult.fail(
+                f"I couldn't find '{title}' on Seerr. "
+                f"Please double-check the title or provide a TMDb ID."
+            )
+
+        # If tmdb_id provided, match it; otherwise use the first result
+        match = None
+        if tmdb_id:
+            match = next(
+                (item for item in filtered if item.get("id") == tmdb_id),
+                None,
+            )
+        if not match:
+            match = filtered[0]
+
+        # Seerr's request endpoint expects the local mediaInfo.id
+        media_info = match.get("mediaInfo", {})
+        media_id = media_info.get("id") or match.get("id")
+        media_title = match.get("title") or match.get("name") or title
+        media_year = (
+            (match.get("releaseDate") or match.get("firstAirDate") or "?")[:4]
+        )
+
+        # Step 2: Submit the request
+        request_body = {
+            "mediaType": kind,
+            "mediaId": media_id,
+        }
+        if kind == "tv":
+            request_body["seasons"] = "all"
+
+        req_r = await c.post("/api/v1/request", json=request_body)
+
+        if req_r.status_code == 201:
+            return ToolResult.ok(
+                f"✅ Successfully requested **{media_title}** ({media_year}). "
+                f"It has been submitted to Seerr and will be processed soon."
+            )
+        elif req_r.status_code == 409:
+            return ToolResult.fail(
+                f"⚠️ **{media_title}** ({media_year}) has already been requested "
+                f"or is already available."
+            )
+        else:
+            detail = req_r.text
+            return ToolResult.fail(
+                f"❌ Failed to request **{media_title}** ({media_year}). "
+                f"Seerr responded with status {req_r.status_code}: {detail}"
+            )
+
+
+async def _submit_issue(args: dict) -> ToolResult:
+    subject = args["subject"]
+    description = args["description"]
+    media_title = args.get("media_title", "")
+    issue_type = args.get("issue_type", 4)  # numeric code: 1=video, 2=audio, 3=sub, 4=other
+    media_id = args.get("media_id")
+
+    body: dict = {
+        "issueType": int(issue_type),
+        "subject": subject,
+        "message": description,
+    }
+    if media_title:
+        body["message"] = f"[Media: {media_title}]\n\n{description}"
+
+    async with _client() as c:
+        # --- Resolve mediaId (Seerr's internal ID, not TMDb) ---
+        if not media_id and media_title:
+            search_r = await c.get("/api/v1/search/", params={"query": quote(media_title), "page": 1})
+            if search_r.status_code == 200:
+                results = search_r.json().get("results", [])
+                if results:
+                    # Seerr's /api/v1/issue expects the local mediaInfo.id,
+                    # not the TMDb id at the top level.
+                    media_info = results[0].get("mediaInfo", {})
+                    media_id = media_info.get("id") or results[0].get("id")
+
+        if media_id:
+            body["mediaId"] = int(media_id)
+
+        r = await c.post("/api/v1/issue", json=body)
+
+        resp_json = r.json() if r.text else {}
+        if r.status_code in (200, 201):
+            ticket_id = resp_json.get("id", "N/A")
+            return ToolResult.ok(
+                f"✅ Issue submitted successfully (ticket #{ticket_id}). "
+                f"A human operator will review: **{subject}**"
+            )
+        else:
+            return ToolResult.fail(
+                f"❌ Failed to submit issue. Seerr responded with "
+                f"status {r.status_code}: {r.text[:500]}"
+            )
+
+
+# ---------------------------------------------------------------------------
+# Register the skill
+# ---------------------------------------------------------------------------
+seerr_skill = Skill(
+    name="seerr",
+    description="Seerr integration — trending, discover, request media, submit issues",
+    prompt_fragment="""## Seerr Media Tools
+
+You have access to the Seerr media management system. Use the provided tools
+to help users with media-related tasks:
+
+- **seerr_trending** — when a user asks what is trending/popular/new
+- **seerr_discover** — when a user asks for recommendations by genre/category
+- **seerr_request_media** — when a user wants to request a movie or TV show
+- **seerr_submit_issue** — when a user needs to report a problem or needs an
+  operator-only action (like deleting media or cancelling a request)
+
+Always confirm successful actions to the user. If a tool fails, tell the user
+what went wrong and suggest alternatives.""",
+    tools=TOOLS,
+    execute=_execute,
+)
+
+register(seerr_skill)

skills/triage.py

@@ -0,0 +1,51 @@
+"""
+Triage skill — fallback for actions that aren't covered by any registered skill.
+
+When a user asks for something that the agent cannot do (either because the
+skill doesn't exist or is intentionally unavailable — e.g. deleting media,
+cancelling requests, banning users), this skill teaches the LLM to:
+
+1. Politely explain that the action requires a human operator.
+2. Offer to submit a ticket instead.
+3. Use the seerr_submit_issue tool (if available) to create the ticket.
+"""
+
+from skills import Skill, register
+
+# This skill has no tools of its own — it guides the LLM's behavior.
+# The actual ticket submission is handled by seerr_submit_issue.
+
+triage_skill = Skill(
+    name="triage",
+    description="Fallback for unsupported actions — explains limitations "
+    "and offers to create a ticket instead.",
+    prompt_fragment="""## Triage & Fallback Rules
+
+You are a helpful media assistant, but you have limited capabilities. Follow these
+rules when a user asks for something you **cannot** do:
+
+### Actions you CANNOT perform (human-operator-only):
+- Deleting media, requests, or users
+- Cancelling existing requests
+- Modifying library settings
+- Changing user permissions
+- Any destructive or administrative action
+
+### When the user asks for an unsupported action:
+1. **Politely explain** that this action requires a human operator.
+2. **Offer to submit a ticket** via the seerr_submit_issue tool with a clear
+   description of what the user wants.
+3. Never say "I don't know how to do that" without also offering the ticket
+   alternative.
+
+### Example response template:
+"I can't perform [action] directly — that requires a human operator for safety.
+But I'd be happy to **submit a ticket** for you with all the details. Would you
+like me to do that?"
+
+Always lean toward being helpful rather than just saying no.""",
+    tools=[],  # no tools — this is a prompt-only skill
+    execute=None,
+)
+
+register(triage_skill)