feat: alias LoaderPipeline to LoaderOrchestrator

docker/pyproject.deps.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mcp-plex"
-version = "0.26.71"
+version = "0.26.72"
 requires-python = ">=3.11,<3.13"
 dependencies = [
   "fastmcp>=2.11.2",

mcp_plex/loader/__init__.py

@@ -1,4 +1,11 @@
-"""Utilities for loading Plex metadata with IMDb and TMDb details."""
+"""Loader orchestration utilities and legacy pipeline helpers.
+
+This package now centres its public API on :class:`LoaderOrchestrator`,
+the coordination layer for the ingestion, enrichment, and persistence
+stages. The historical pipeline implementation remains available as
+``LegacyLoaderPipeline`` for the CLI while the original ``LoaderPipeline``
+name resolves to the orchestrator with a deprecation warning.
+"""
 from __future__ import annotations
 
 import asyncio
@@ -38,6 +45,7 @@
     chunk_sequence,
     require_positive,
 )
+from .pipeline.orchestrator import LoaderOrchestrator
 from .pipeline.persistence import PersistenceStage as _PersistenceStage
 from ..common.types import (
     AggregatedItem,
@@ -1335,6 +1343,29 @@ def _handle_upsert_batch(
             self._upsert_start,
             queue_size,
         )
+
+
+# Preserve the legacy pipeline implementation for the CLI while exposing the
+# orchestrator as the public API moving forward.
+LegacyLoaderPipeline = LoaderPipeline
+del LoaderPipeline
+
+
+def __getattr__(name: str) -> Any:
+    """Provide deprecated access to :class:`LoaderOrchestrator`."""
+
+    if name == "LoaderPipeline":
+        warnings.warn(
+            "LoaderPipeline has been renamed to LoaderOrchestrator; import "
+            "mcp_plex.loader.LoaderOrchestrator instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        globals()[name] = LoaderOrchestrator
+        return LoaderOrchestrator
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
 async def run(
     plex_url: Optional[str],
     plex_token: Optional[str],
@@ -1415,7 +1446,7 @@ async def run(
     if sample_dir is not None:
         logger.info("Loading sample data from %s", sample_dir)
         sample_items = _load_from_sample(sample_dir)
-        pipeline = LoaderPipeline(
+        pipeline = LegacyLoaderPipeline(
             client=client,
             collection_name=collection_name,
             dense_model_name=dense_model_name,
@@ -1438,7 +1469,7 @@ async def run(
             raise RuntimeError("TMDB_API_KEY must be provided")
         logger.info("Loading data from Plex server %s", plex_url)
         server = PlexServer(plex_url, plex_token)
-        pipeline = LoaderPipeline(
+        pipeline = LegacyLoaderPipeline(
             client=client,
             collection_name=collection_name,
             dense_model_name=dense_model_name,

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mcp-plex"
-version = "0.26.71"
+version = "0.26.72"
 
 description = "Plex-Oriented Model Context Protocol Server"
 requires-python = ">=3.11,<3.13"

tests/test_loader_alias.py

@@ -0,0 +1,17 @@
+"""Compatibility tests for loader public API aliases."""
+
+import importlib
+import warnings
+
+
+def test_loader_pipeline_alias_emits_deprecation_warning() -> None:
+    """The legacy LoaderPipeline export should point at the orchestrator."""
+
+    module = importlib.import_module("mcp_plex.loader")
+    module = importlib.reload(module)
+    with warnings.catch_warnings(record=True) as caught:
+        warnings.simplefilter("always", DeprecationWarning)
+        alias = getattr(module, "LoaderPipeline")
+
+    assert alias is module.LoaderOrchestrator
+    assert any(issubclass(w.category, DeprecationWarning) for w in caught)

tests/test_loader_logging.py

@@ -128,17 +128,17 @@ async def fake_ensure(*args, **kwargs):
 
     monkeypatch.setattr(loader, "_ensure_collection", fake_ensure)
     sample_dir = Path(__file__).resolve().parents[1] / "sample-data"
-    original_execute = loader.LoaderPipeline.execute
+    original_execute = loader.LegacyLoaderPipeline.execute
 
     async def fake_execute(self):
         order.append("execute")
         self._items = []
 
-    monkeypatch.setattr(loader.LoaderPipeline, "execute", fake_execute)
+    monkeypatch.setattr(loader.LegacyLoaderPipeline, "execute", fake_execute)
 
     asyncio.run(loader.run(None, None, None, sample_dir, None, None))
 
     assert order and order[0] == "ensure"
     assert "execute" in order
 
-    monkeypatch.setattr(loader.LoaderPipeline, "execute", original_execute)
+    monkeypatch.setattr(loader.LegacyLoaderPipeline, "execute", original_execute)

tests/test_loader_unit.py

@@ -13,7 +13,7 @@
 from mcp_plex import loader
 from mcp_plex.loader.imdb_cache import IMDbCache
 from mcp_plex.loader import (
-    LoaderPipeline,
+    LegacyLoaderPipeline as LoaderPipeline,
     _build_plex_item,
     _extract_external_ids,
     _fetch_imdb,