updated playback aware

Media/playback_aware_lidarr_discovery.sh

@@ -1,3 +1,115 @@
+#currently a consecpt
+
+#!/bin/bash
+# ==============================================================================================
+# ================================== DECISION ENGINE ===========================================
+# ==============================================================================================
+# Central behavioral decision engine for the media ecosystem.
+#
+# This engine transforms recent user activity into weighted decision output used by
+# downstream automation systems such as Lidarr, Sonarr, Radarr, and future services.
+#
+# The engine is:
+#   Time-aware         — recent activity matters more than historical ownership
+#   Behavior-driven    — decisions are based on actual usage patterns
+#   Family-aware       — balances influence across active users dynamically
+#   Domain-agnostic    — policies can adapt behavior per media type
+#   Constraint-based   — no single user can dominate system-wide discovery
+#
+# ── CORE PHILOSOPHY ────────────────────────────────────────────────────────────────────────────
+#
+# This is NOT:
+#   • a recommendation engine
+#   • a media AI
+#   • a centralized content manager
+#
+# This IS:
+#   • a decision layer
+#   • a weighting system
+#   • a behavioral context engine
+#
+# Recent activity defines current context.
+#
+# Discovery influence is earned through participation, not ownership.
+# Users who actively engage with media contribute more strongly to discovery weighting,
+# while configurable caps prevent any single user from overwhelming the ecosystem.
+#
+# The result is a continuously adapting media environment that reflects the current
+# behavioral state of the household rather than static long-term bias.
+#
+# ── RESPONSIBILITIES ───────────────────────────────────────────────────────────────────────────
+#
+#   • Ingest recent activity from media systems and APIs
+#   • Normalize activity across users and domains
+#   • Apply time-decay and recency weighting
+#   • Enforce per-user influence caps
+#   • Generate ranked discovery candidates
+#   • Return structured decision output to consumer scripts
+#
+# ── NON-RESPONSIBILITIES ───────────────────────────────────────────────────────────────────────
+#
+# The decision engine NEVER:
+#   • Executes downloads
+#   • Calls arr APIs directly
+#   • Starts/stops containers
+#   • Performs filesystem operations
+#   • Handles infrastructure orchestration
+#
+# Infrastructure execution belongs to:
+#   • adapter scripts
+#   • orchestrators
+#   • common.sh shared runtime functions
+#
+# ── ARCHITECTURE ROLE ─────────────────────────────────────────────────────────────────────────
+#
+# Ecosystem Layers:
+#
+#   Config Layer
+#     master.conf + host configs
+#       ↓
+#   Runtime Layer
+#     common.sh
+#       ↓
+#   Decision Layer
+#     decision_engine.sh   ← THIS FILE
+#       ↓
+#   Domain Adapters
+#     lidarr_discovery.sh
+#     sonarr_discovery.sh
+#     radarr_discovery.sh
+#     transcoding_manager.sh
+#
+# This separation keeps decision logic centralized while allowing execution systems
+# to evolve independently.
+#
+# ── FUTURE EXPANSION ──────────────────────────────────────────────────────────────────────────
+#
+# Planned consumers:
+#   • Lidarr music discovery
+#   • Sonarr TV discovery balancing
+#   • Radarr movie discovery weighting
+#   • Transcoding priority orchestration
+#   • Queue scheduling systems
+#   • Resource-aware automation policies
+#
+# Shared decision primitives may eventually include:
+#   • Recency decay models
+#   • User weighting models
+#   • Fairness constraints
+#   • Diversity scoring
+#   • Load-sensitive prioritization
+#
+# ── DESIGN RULES ──────────────────────────────────────────────────────────────────────────────
+#
+#   • Engines decide — adapters execute
+#   • Policies tune behavior — engines apply logic
+#   • Shared infrastructure belongs in common.sh
+#   • Domain logic belongs in policy modules
+#   • No infrastructure execution inside the engine
+#
+# ── VERSION ───────────────────────────────────────────────────────────────────────────────────
+#   v1.0 — Initial decision engine architecture
+# ==============================================================================================
 import requests
 from collections import defaultdict
 from dataclasses import dataclass