From 607168815b4315ea5c7fb565a2284f78b558e1d3 Mon Sep 17 00:00:00 2001 From: Eric Jungbauer Date: Mon, 20 Apr 2026 23:02:44 +0000 Subject: [PATCH] The Pirate Phase 1.b extension: Plex tools MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds 4 read-only Plex tools using a new plex_get helper that sends X-Plex-Token as a query param and Accept: application/json: - plex_library_sections: per-section item counts - plex_on_deck: in-progress items across all libraries - plex_watch_history: recent watches with user-name resolution via /accounts - plex_recently_added: latest additions across sections Token sourced from Plex registry on Darrow (HKU per-user hive). Stored in service_configs.plex. Plex paginated counts require BOTH X-Plex-Container-Start and X-Plex-Container-Size in query string to return totalSize — dropping Start makes Plex return the full library. Pirate catalog: 20 → 24 tools. --- agents/pirate/tools/__init__.py | 4 +- agents/pirate/tools/_common.py | 16 ++++ agents/pirate/tools/plex.py | 152 ++++++++++++++++++++++++++++++++ 3 files changed, 170 insertions(+), 2 deletions(-) create mode 100644 agents/pirate/tools/plex.py diff --git a/agents/pirate/tools/__init__.py b/agents/pirate/tools/__init__.py index 6850d11..60391df 100644 --- a/agents/pirate/tools/__init__.py +++ b/agents/pirate/tools/__init__.py @@ -7,13 +7,13 @@ The runtime loads all modules here and builds a combined catalog. The LLM picks which tool to call; the runtime executes it and returns the result as a tool message. """ -from . import sonarr, radarr, lidarr, whisparr, qbittorrent, storage, overseerr +from . import sonarr, radarr, lidarr, whisparr, qbittorrent, storage, overseerr, plex def build_catalog(): """Return a list of all available tools across all modules.""" catalog = [] - for mod in (sonarr, radarr, lidarr, whisparr, qbittorrent, storage, overseerr): + for mod in (sonarr, radarr, lidarr, whisparr, qbittorrent, storage, overseerr, plex): catalog.extend(getattr(mod, "TOOLS", [])) return catalog diff --git a/agents/pirate/tools/_common.py b/agents/pirate/tools/_common.py index ef2db92..92f295c 100644 --- a/agents/pirate/tools/_common.py +++ b/agents/pirate/tools/_common.py @@ -33,6 +33,22 @@ def arr_get(service_name, path, params=None): return json.loads(resp.read().decode()) +def plex_get(path, params=None): + """GET from the Plex API. Auth is via X-Plex-Token query param; returns JSON.""" + cfg = get_service_config("plex") + base = cfg["base_url"].rstrip("/") + key = cfg["api_key"] + if not base or not key: + raise RuntimeError("plex not configured (base_url + api_key required)") + merged = {"X-Plex-Token": key} + if params: + merged.update(params) + url = f"{base}{path}?" + urlparse.urlencode(merged, quote_via=urlparse.quote) + req = urlreq.Request(url, headers={"Accept": "application/json"}) + with urlreq.urlopen(req, timeout=15) as resp: + return json.loads(resp.read().decode()) + + def qbit_request(path, method="GET", params=None, data=None, cookies=None): """qBittorrent Web API helper. Login (if password set) returns SID cookie string.""" cfg = get_service_config("qbittorrent") diff --git a/agents/pirate/tools/plex.py b/agents/pirate/tools/plex.py new file mode 100644 index 0000000..73bede9 --- /dev/null +++ b/agents/pirate/tools/plex.py @@ -0,0 +1,152 @@ +"""Plex tools — watch history, on deck, recently added, library stats (read-only).""" + +from ._common import plex_get + + +def _resolve_accounts(): + """Build an accountID -> display-name map. Plex's history endpoint uses numeric IDs.""" + try: + data = plex_get("/accounts") + return { + a.get("id"): (a.get("name") or "").strip() or f"account_{a.get('id')}" + for a in data.get("MediaContainer", {}).get("Account", []) + } + except Exception: + return {} + + +def _title(m): + """Human-readable title for a metadata item (handles episodes, movies, tracks).""" + grand = m.get("grandparentTitle") or "" + parent = m.get("parentTitle") or "" + title = m.get("title") or "" + if grand and m.get("type") == "episode": + season = m.get("parentIndex") + ep = m.get("index") + if season is not None and ep is not None: + return f"{grand} S{season:02d}E{ep:02d} — {title}" + return f"{grand} — {title}" + if grand and m.get("type") == "track": + return f"{grand} — {title}" + return title + + +def plex_library_sections(): + """List Plex library sections with per-section item counts.""" + data = plex_get("/library/sections") + sections = [] + for s in data.get("MediaContainer", {}).get("Directory", []): + sid = s.get("key") + try: + count_data = plex_get(f"/library/sections/{sid}/all", {"X-Plex-Container-Start": 0, "X-Plex-Container-Size": 1}) + total = count_data.get("MediaContainer", {}).get("totalSize", 0) + except Exception: + total = None + sections.append({ + "id": sid, + "title": s.get("title"), + "type": s.get("type"), + "item_count": total, + }) + return {"sections": sections} + + +def plex_on_deck(limit=10): + """What's ready to resume — partially watched items across all libraries.""" + data = plex_get("/library/onDeck", {"X-Plex-Container-Size": limit}) + items = [] + for m in data.get("MediaContainer", {}).get("Metadata", [])[:limit]: + duration_ms = m.get("duration") or 0 + offset_ms = m.get("viewOffset") or 0 + pct = round(100 * offset_ms / duration_ms, 1) if duration_ms else None + items.append({ + "type": m.get("type"), + "title": _title(m), + "library": m.get("librarySectionTitle"), + "progress_pct": pct, + "duration_min": round(duration_ms / 60000, 1) if duration_ms else None, + "last_viewed_epoch": m.get("lastViewedAt"), + }) + return {"count": len(items), "items": items} + + +def plex_watch_history(limit=20, user=None): + """Recent Plex watch history. Optionally filter by user display name (case-insensitive).""" + accounts = _resolve_accounts() + params = {"X-Plex-Container-Size": limit, "sort": "viewedAt:desc"} + if user: + # Find matching account id(s) + wanted = user.strip().lower() + matching_ids = [aid for aid, name in accounts.items() if name.lower() == wanted] + if matching_ids: + params["accountID"] = matching_ids[0] + data = plex_get("/status/sessions/history/all", params) + items = [] + for m in data.get("MediaContainer", {}).get("Metadata", [])[:limit]: + items.append({ + "type": m.get("type"), + "title": _title(m), + "library": m.get("librarySectionTitle"), + "watched_epoch": m.get("viewedAt"), + "user": accounts.get(m.get("accountID"), f"account_{m.get('accountID')}"), + }) + return {"count": len(items), "filter_user": user, "items": items} + + +def plex_recently_added(limit=15): + """What was added to the Plex library most recently.""" + data = plex_get("/library/recentlyAdded", {"X-Plex-Container-Size": limit}) + items = [] + for m in data.get("MediaContainer", {}).get("Metadata", [])[:limit]: + items.append({ + "type": m.get("type"), + "title": _title(m), + "library": m.get("librarySectionTitle"), + "added_epoch": m.get("addedAt"), + "year": m.get("year"), + }) + return {"count": len(items), "items": items} + + +TOOLS = [ + { + "name": "plex_library_sections", + "description": "List Plex library sections (Movies, TV Shows, Music, etc.) with item counts per section. Use when the user asks 'how big is the Plex library', 'what libraries do we have', or 'how many movies are on Plex'.", + "input_schema": {"type": "object", "properties": {}}, + "read_only": True, + "fn": plex_library_sections, + }, + { + "name": "plex_on_deck", + "description": "List what the user (and household) is in the middle of — partially watched episodes and movies across all libraries. Use when the user asks 'what was I watching', 'what's on deck', 'where did I leave off'.", + "input_schema": { + "type": "object", + "properties": {"limit": {"type": "integer", "default": 10}}, + }, + "read_only": True, + "fn": plex_on_deck, + }, + { + "name": "plex_watch_history", + "description": "Recent Plex watch history with user attribution. Optionally filter by user display name (Eric, Angela, Jaclyn, etc.). Use when the user asks 'what did we watch last night', 'what has Angela been watching', 'show me recent views'.", + "input_schema": { + "type": "object", + "properties": { + "limit": {"type": "integer", "default": 20}, + "user": {"type": "string", "description": "Optional Plex user display name to filter by"}, + }, + }, + "read_only": True, + "fn": plex_watch_history, + }, + { + "name": "plex_recently_added", + "description": "Latest items added to the Plex library across all sections. Use when the user asks 'what's new on Plex', 'what got added this week', 'what arrived recently'.", + "input_schema": { + "type": "object", + "properties": {"limit": {"type": "integer", "default": 15}}, + }, + "read_only": True, + "fn": plex_recently_added, + }, +]