feat: Add drop-in Python plugin system (#188)

CHANGELOG.md

@@ -2,6 +2,35 @@
 
 All notable changes to Library Manager will be documented in this file.
 
+## [0.9.0-beta.142] - 2026-03-21
+
+### Added
+
+- **Issue #188: Drop-in Python plugin system** - New plugin loader that discovers and loads
+  Python plugins from a configurable directory (`/data/plugins` for Docker). Plugins extend
+  a simple `BasePlugin` class with `setup()`, `can_process()`, `process()`, and `teardown()`
+  methods. The loader handles manifest validation, dynamic module importing via `importlib`,
+  exception isolation (bad plugins never crash the app), timeout enforcement via
+  `ThreadPoolExecutor`, and deep-copying book data before passing to plugins. Each plugin is
+  wrapped in a `PluginAdapter` that implements the `LayerAdapter` interface, making plugins
+  fully compatible with the modular pipeline orchestrator. Plugins are registered in the
+  `LayerRegistry` and tracked by the existing health dashboard with auto-disable circuit
+  breaker support.
+
+- **Plugin manifest system** - Each plugin requires a `manifest.json` with metadata (id,
+  name, version, description), entry point configuration, ordering, and dependency
+  declarations (required config keys and secrets). Manifests are strictly validated on
+  discovery -- invalid plugins are logged as warnings and skipped.
+
+- **Plugin configuration** - New `plugin_dir` config key (default: `/data/plugins`) and
+  `plugin_configs` dict for per-plugin configuration overrides. Plugin-specific secrets are
+  read from `secrets.json`.
+
+- **Example plugin** - Template plugin at `test-env/example-plugin/` demonstrating the
+  `BasePlugin` interface with manifest.json and a simple logging implementation.
+
+---
+
 ## [0.9.0-beta.141] - 2026-03-21
 
 ### Added

README.md

@@ -4,7 +4,7 @@
 
 **Smart Audiobook Library Organizer with Multi-Source Metadata & AI Verification**
 
-[![Version](https://img.shields.io/badge/version-0.9.0--beta.141-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-0.9.0--beta.142-blue.svg)](CHANGELOG.md)
 [![Docker](https://img.shields.io/badge/docker-ghcr.io-blue.svg)](https://ghcr.io/deucebucket/library-manager)
 [![License](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](LICENSE)
 

app.py

@@ -11,7 +11,7 @@
 - Multi-provider AI (Gemini, OpenRouter, Ollama)
 """
 
-APP_VERSION = "0.9.0-beta.141"
+APP_VERSION = "0.9.0-beta.142"
 GITHUB_REPO = "deucebucket/library-manager"  # Your GitHub repo
 
 # Versioning Guide:
@@ -122,6 +122,7 @@
 from library_manager.hints import get_all_hints
 from library_manager.hooks import hooks_bp, run_hooks, build_hook_context
 from library_manager.plugins import plugins_bp
+from library_manager.plugin_loader import register_plugins, teardown_plugins
 
 # Try to import P2P cache (optional - gracefully degrades if not available)
 try:
@@ -736,7 +737,7 @@
             try:
                 with open(ERROR_REPORTS_PATH, 'r') as f:
                     reports = json.load(f)
             except:
                 reports = []
 
         # Add new report (keep last 100 reports to avoid file bloat)
@@ -760,7 +761,7 @@
         try:
             with open(ERROR_REPORTS_PATH, 'r') as f:
                 return json.load(f)
         except:
             return []
     return []
 
@@ -1715,7 +1716,7 @@
                     continue
                 result = call_gemini(prompt, merged_config)
                 if result:
                     logger.info(f"[PROVIDER CHAIN] Success with gemini")
                     return result
 
             elif provider == 'openrouter':
@@ -1724,13 +1725,13 @@
                     continue
                 result = call_openrouter(prompt, merged_config)
                 if result:
                     logger.info(f"[PROVIDER CHAIN] Success with openrouter")
                     return result
 
             elif provider == 'ollama':
                 result = call_ollama(prompt, merged_config)
                 if result:
                     logger.info(f"[PROVIDER CHAIN] Success with ollama")
                     return result
 
             else:
@@ -1832,7 +1833,7 @@
                         return result
                     elif result and result.get('transcript'):
                         # Got transcript but no match - still useful, return for potential AI fallback
                         logger.info(f"[AUDIO CHAIN] BookDB returned transcript only")
                         return result
                     elif result is None and attempt < max_retries - 1:
                         # Connection might be down, wait and retry
@@ -2164,11 +2165,11 @@
                 device = "cuda"
                 # int8 works on all CUDA devices including GTX 1080 (compute 6.1)
                 # float16 only works on newer GPUs (compute 7.0+)
                 logger.info(f"[WHISPER] Using CUDA GPU acceleration (10x faster)")
             else:
                 logger.info(f"[WHISPER] Using CPU (no CUDA GPU detected)")
         except ImportError:
             logger.info(f"[WHISPER] Using CPU (ctranslate2 not available)")
 
         _whisper_model = WhisperModel(model_name, device=device, compute_type=compute_type)
         _whisper_model_name = model_name
@@ -2375,7 +2376,7 @@
         if sample_path and os.path.exists(sample_path):
             try:
                 os.unlink(sample_path)
             except:
                 pass
 
     return result
@@ -12142,6 +12143,18 @@
     init_db()
     cleanup_garbage_entries()  # Remove @eaDir, #recycle, etc. from database (Issue #88)
     cleanup_duplicate_history_entries()  # Remove duplicate history entries (Issue #79)
+
+    # Issue #188: Load drop-in Python plugins
+    try:
+        from library_manager.pipeline.registry import default_registry
+        _startup_config = load_config()
+        _loaded_plugins = register_plugins(default_registry, _startup_config, get_db)
+        if _loaded_plugins:
+            logger.info(f"[PLUGIN] {len(_loaded_plugins)} plugin(s) loaded and registered")
+    except Exception as e:
+        logger.error(f"[PLUGIN] Failed to load plugins: {e}")
+        _loaded_plugins = []
+
     start_worker()
     port = int(os.environ.get('PORT', 5757))
     app.run(host='0.0.0.0', port=port, debug=False)

library_manager/config.py

@@ -142,6 +142,9 @@ def _detect_data_dir():
     "post_processing_hooks": [],
     # Custom HTTP API layers - user-defined external API processing layers (Issue #185)
     "custom_layers": [],
+    # Drop-in Python plugins (Issue #188)
+    "plugin_dir": "/data/plugins",             # Directory to scan for drop-in plugins (Docker: /data/plugins)
+    "plugin_configs": {},                      # Per-plugin config overrides: {"plugin-id": {"key": "value"}}
     # Issue #110: File validation - check audio files before processing
     "enable_file_validation": True,            # Validate audio files with ffprobe before queueing
     "min_audio_duration_seconds": 600,         # Minimum duration (seconds) to consider a valid audiobook (default: 10 min)