Refactor/plugin management (Pipelex#129)

### 📝 Description
- handle external plugins for LLMs

### 🔄 Type of Change
- [ ] 🐛 Bug fix
- [X] ✨ New feature
- [ ] 💥 Breaking change
- [ ] 📚 Documentation update
- [X] 🧹 Code refactor
- [ ] ⚡ Performance improvement
- [X] ✅ Test update

### 🧪 Tests
- test_external_plugin.py

Author: lchoquel

docs/pages/advanced-customization/index.md

@@ -16,7 +16,6 @@ from pipelex import Pipelex
 pipelex = Pipelex(
     template_provider=MyTemplateProvider(),
     llm_model_provider=MyLLMProvider(),
-    plugin_manager=MyPluginManager(),
     inference_manager=MyInferenceManager(),
     pipeline_tracker=MyPipelineTracker(),
     activity_manager=MyActivityManager(),
@@ -38,7 +37,6 @@ from pipelex.hub import PipelexHub
 hub = PipelexHub()
 hub.set_template_provider(MyTemplateProvider())
 hub.set_llm_models_provider(MyLLMProvider())
-hub.set_plugin_manager(MyPluginManager())
 # ... and so on for other components
 ```
 
@@ -88,54 +86,45 @@ Pipelex supports injection of the following components:
     - Default: `LLMModelLibrary`
     - [Details](llm-model-provider-injection.md)
 
-3. **Plugin Manager** (`PluginManager`)
-
-    - Protocol: `PluginManagerProtocol`
-    - Default: `PluginManager`
-    - [Details](plugin-manager-injection.md)
-
-4. **Inference Manager** (`InferenceManager`)
+3. **Inference Manager** (`InferenceManager`)
 
     - Protocol: `InferenceManagerProtocol`
     - Default: `InferenceManager`
     - [Details](inference-manager-injection.md)
 
-5. **Reporting Delegate** (`ReportingManager`)
+4. **Reporting Delegate** (`ReportingManager`)
 
     - Protocol: `ReportingProtocol`
     - Default: `ReportingManager` or `ReportingNoOp` if disabled
     - [Details](reporting-delegate-injection.md)
 
-6. **Pipeline Tracker** (`PipelineTracker`)
+5. **Pipeline Tracker** (`PipelineTracker`)
 
     - Protocol: `PipelineTrackerProtocol`
     - Default: `PipelineTracker` or `PipelineTrackerNoOp` if disabled
     - [Details](pipeline-tracker-injection.md)
 
-7. **Activity Manager** (`ActivityManager`)
+6. **Activity Manager** (`ActivityManager`)
 
     - Protocol: `ActivityManagerProtocol`
     - Default: `ActivityManager` or `ActivityManagerNoOp` if disabled
     - [Details](activity-manager-injection.md)
 
-8. **Secrets Provider** (`EnvSecretsProvider`)
+7. **Secrets Provider** (`EnvSecretsProvider`)
 
     - Protocol: `SecretsProviderProtocol`
     - Default: `EnvSecretsProvider`
     - [Details](secrets-provider-injection.md)
 
-9. **Content Generator** (`ContentGenerator`)
+8. **Content Generator** (`ContentGenerator`)
 
     - Protocol: `ContentGeneratorProtocol`
     - Default: `ContentGenerator`
     - [Details](content-generator-injection.md)
 
-10. **Pipe Router** (`PipeRouter`)
+9. **Pipe Router** (`PipeRouter`)
 
     - Protocol: `PipeRouterProtocol`
     - Default: `PipeRouter`
     - [Details](pipe-router-injection.md)
 
-## Best Practices
-
-⚠️ Under construction

pipelex/cogt/exceptions.py

@@ -23,6 +23,10 @@ class SdkTypeError(CogtError):
     pass
 
 
+class SdkRegistryError(CogtError):
+    pass
+
+
 class LLMWorkerError(CogtError):
     pass
 
@@ -128,5 +132,9 @@ def __init__(self, dependency_name: str, extra_name: str, message: Optional[str]
         super().__init__(error_msg)
 
 
+class MissingPluginError(CogtError):
+    pass
+
+
 class OcrCapabilityError(CogtError):
     pass

pipelex/cogt/imgg/imgg_worker_factory.py

@@ -5,9 +5,9 @@
 from pipelex.cogt.imgg.imgg_platform import ImggPlatform
 from pipelex.cogt.imgg.imgg_worker_abstract import ImggWorkerAbstract
 from pipelex.cogt.llm.llm_models.llm_platform import LLMPlatform
-from pipelex.cogt.plugin_manager import PluginHandle
 from pipelex.hub import get_plugin_manager, get_secret
 from pipelex.plugins.openai.openai_imgg_worker import OpenAIImggWorker
+from pipelex.plugins.plugin_sdk_registry import PluginSdkHandle
 from pipelex.reporting.reporting_protocol import ReportingProtocol
 from pipelex.tools.secrets.secrets_errors import SecretNotFoundError
 
@@ -22,8 +22,8 @@ def make_imgg_worker(
         imgg_engine: ImggEngine,
         reporting_delegate: Optional[ReportingProtocol] = None,
     ) -> ImggWorkerAbstract:
-        imgg_sdk_handle = PluginHandle.get_for_imgg_engine(imgg_platform=imgg_engine.imgg_platform)
-        plugin_manager = get_plugin_manager()
+        imgg_sdk_handle = PluginSdkHandle.get_for_imgg_engine(imgg_platform=imgg_engine.imgg_platform)
+        plugin_sdk_registry = get_plugin_manager().plugin_sdk_registry
         imgg_worker: ImggWorkerAbstract
         match imgg_engine.imgg_platform:
             case ImggPlatform.FAL_AI:
@@ -41,7 +41,9 @@ def make_imgg_worker(
 
                 from pipelex.plugins.fal.fal_imgg_worker import FalImggWorker
 
-                imgg_sdk_instance = plugin_manager.get_imgg_sdk_instance(imgg_sdk_handle=imgg_sdk_handle) or plugin_manager.set_imgg_sdk_instance(
+                imgg_sdk_instance = plugin_sdk_registry.get_imgg_sdk_instance(
+                    imgg_sdk_handle=imgg_sdk_handle
+                ) or plugin_sdk_registry.set_imgg_sdk_instance(
                     imgg_sdk_handle=imgg_sdk_handle,
                     imgg_sdk_instance=FalAsyncClient(key=fal_api_key),
                 )
@@ -54,7 +56,9 @@ def make_imgg_worker(
             case ImggPlatform.OPENAI:
                 from pipelex.plugins.openai.openai_factory import OpenAIFactory
 
-                imgg_sdk_instance = plugin_manager.get_llm_sdk_instance(llm_sdk_handle=imgg_sdk_handle) or plugin_manager.set_llm_sdk_instance(
+                imgg_sdk_instance = plugin_sdk_registry.get_llm_sdk_instance(
+                    llm_sdk_handle=imgg_sdk_handle
+                ) or plugin_sdk_registry.set_llm_sdk_instance(
                     llm_sdk_handle=imgg_sdk_handle,
                     llm_sdk_instance=OpenAIFactory.make_openai_client(llm_platform=LLMPlatform.OPENAI),
                 )

pipelex/cogt/inference/inference_manager.py

@@ -1,4 +1,4 @@
-from typing import Dict, Optional
+from typing import Dict, Type
 
 from typing_extensions import override
 
@@ -12,6 +12,7 @@
 from pipelex.cogt.llm.llm_models.llm_engine_factory import LLMEngineFactory
 from pipelex.cogt.llm.llm_worker_abstract import LLMWorkerAbstract
 from pipelex.cogt.llm.llm_worker_factory import LLMWorkerFactory
+from pipelex.cogt.llm.llm_worker_internal_abstract import LLMWorkerInternalAbstract
 from pipelex.cogt.ocr.ocr_engine_factory import OcrEngineFactory
 from pipelex.cogt.ocr.ocr_worker_abstract import OcrWorkerAbstract
 from pipelex.cogt.ocr.ocr_worker_factory import OcrWorkerFactory
@@ -31,10 +32,16 @@ def __init__(self):
     def teardown(self):
         self.imgg_worker_factory = ImggWorkerFactory()
         self.ocr_worker_factory = OcrWorkerFactory()
-        self.llm_workers.clear()
-        self.imgg_workers.clear()
-        self.ocr_workers.clear()
-        log.verbose("InferenceManagerAsync reset")
+        for llm_worker in self.llm_workers.values():
+            llm_worker.teardown()
+        self.llm_workers = {}
+        for imgg_worker in self.imgg_workers.values():
+            imgg_worker.teardown()
+        self.imgg_workers = {}
+        for ocr_worker in self.ocr_workers.values():
+            ocr_worker.teardown()
+        self.ocr_workers = {}
+        log.verbose("InferenceManager teardown done")
 
     def print_workers(self):
         log.debug("LLM Workers:")
@@ -60,15 +67,15 @@ def setup_llm_workers(self):
         llm_handle_to_llm_engine_blueprint = get_llm_deck().llm_handles
         log.verbose(f"{len(llm_handle_to_llm_engine_blueprint)} LLM engine_cards found")
         for llm_handle, llm_engine_blueprint in llm_handle_to_llm_engine_blueprint.items():
-            self._setup_one_llm_worker(llm_engine_blueprint=llm_engine_blueprint, llm_handle=llm_handle)
+            self._setup_one_internal_llm_worker(llm_engine_blueprint=llm_engine_blueprint, llm_handle=llm_handle)
             log.verbose(f"Setup LLM worker for '{llm_handle}' on {llm_engine_blueprint.llm_platform_choice}")
         log.debug("Done setting up LLM Workers (async)")
 
-    def _setup_one_llm_worker(
+    def _setup_one_internal_llm_worker(
         self,
         llm_engine_blueprint: LLMEngineBlueprint,
         llm_handle: str,
-    ) -> LLMWorkerAbstract:
+    ) -> LLMWorkerInternalAbstract:
         llm_engine = LLMEngineFactory.make_llm_engine(llm_engine_blueprint=llm_engine_blueprint)
         llm_worker = LLMWorkerFactory.make_llm_worker(
             llm_engine=llm_engine,
@@ -78,27 +85,34 @@ def _setup_one_llm_worker(
         return llm_worker
 
     @override
-    def get_llm_worker(
-        self,
-        llm_handle: str,
-        specific_llm_engine_blueprint: Optional[LLMEngineBlueprint] = None,
-    ) -> LLMWorkerAbstract:
+    def get_llm_worker(self, llm_handle: str) -> LLMWorkerAbstract:
         if llm_worker := self.llm_workers.get(llm_handle):
             return llm_worker
         if not get_config().cogt.inference_manager_config.is_auto_setup_preset_llm:
             raise InferenceManagerWorkerSetupError(
                 f"No LLM worker for '{llm_handle}', set it up or enable cogt.inference_manager_config.is_auto_setup_preset_llm"
             )
 
-        if not specific_llm_engine_blueprint:
-            specific_llm_engine_blueprint = get_llm_deck().get_llm_engine_blueprint(llm_handle=llm_handle)
-        llm_worker = self._setup_one_llm_worker(
-            llm_engine_blueprint=specific_llm_engine_blueprint,
+        llm_engine_blueprint = get_llm_deck().get_llm_engine_blueprint(llm_handle=llm_handle)
+        llm_worker = self._setup_one_internal_llm_worker(
+            llm_engine_blueprint=llm_engine_blueprint,
             llm_handle=llm_handle,
         )
 
         return llm_worker
 
+    @override
+    def set_llm_worker_from_external_plugin(
+        self,
+        llm_handle: str,
+        llm_worker_class: Type[LLMWorkerAbstract],
+        should_warn_if_already_registered: bool = True,
+    ):
+        if llm_handle in self.llm_workers:
+            if should_warn_if_already_registered:
+                log.warning(f"LLM worker for '{llm_handle}' already registered, skipping")
+        self.llm_workers[llm_handle] = llm_worker_class(reporting_delegate=get_report_delegate())
+
     ####################################################################################################
     # Manage IMGG Workers
     ####################################################################################################

pipelex/cogt/inference/inference_manager_protocol.py

@@ -1,7 +1,6 @@
-from typing import Optional, Protocol
+from typing import Protocol, Type
 
 from pipelex.cogt.imgg.imgg_worker_abstract import ImggWorkerAbstract
-from pipelex.cogt.llm.llm_models.llm_engine_blueprint import LLMEngineBlueprint
 from pipelex.cogt.llm.llm_worker_abstract import LLMWorkerAbstract
 from pipelex.cogt.ocr.ocr_worker_abstract import OcrWorkerAbstract
 
@@ -20,11 +19,14 @@ def teardown(self): ...
 
     def setup_llm_workers(self): ...
 
-    def get_llm_worker(
+    def get_llm_worker(self, llm_handle: str) -> LLMWorkerAbstract: ...
+
+    def set_llm_worker_from_external_plugin(
         self,
         llm_handle: str,
-        specific_llm_engine_blueprint: Optional[LLMEngineBlueprint] = None,
-    ) -> LLMWorkerAbstract: ...
+        llm_worker_class: Type[LLMWorkerAbstract],
+        should_warn_if_already_registered: bool = True,
+    ): ...
 
     ####################################################################################################
     # IMG Generation Workers

pipelex/cogt/inference/inference_worker_abstract.py

@@ -11,6 +11,12 @@ def __init__(
     ):
         self.reporting_delegate = reporting_delegate
 
+    def setup(self):
+        pass
+
+    def teardown(self):
+        pass
+
     @property
     @abstractmethod
     def desc(self) -> str:

pipelex/cogt/llm/llm_models/llm_deck.py

@@ -42,17 +42,14 @@ def get_llm_engine_blueprint(self, llm_handle: str) -> LLMEngineBlueprint:
 
     @override
     def get_llm_setting(self, llm_setting_or_preset_id: LLMSettingOrPresetId) -> LLMSetting:
-        the_llm_setting: LLMSetting
-        if isinstance(llm_setting_or_preset_id, str):
+        if isinstance(llm_setting_or_preset_id, LLMSetting):
+            return llm_setting_or_preset_id
+        else:
             # it's a preset id
             the_llm_preset = self.llm_presets.get(llm_setting_or_preset_id)
             if not the_llm_preset:
                 raise LLMPresetNotFoundError(f"LLM preset '{llm_setting_or_preset_id}' not found in deck")
-            the_llm_setting = the_llm_preset
-        else:
-            # it's an explict setting
-            the_llm_setting = llm_setting_or_preset_id
-        return the_llm_setting
+            return the_llm_preset
 
     @override
     def get_llm_setting_for_text(self, override: Optional[LLMSettingChoices] = None) -> LLMSetting:
@@ -139,6 +136,19 @@ def find_llm_model(self, llm_handle: str) -> LLMModel:
         )
         return llm_model
 
+    @override
+    def find_optional_llm_model(self, llm_handle: str) -> Optional[LLMModel]:
+        llm_models_provider = get_llm_models_provider()
+        llm_engine_blueprint = self.llm_handles.get(llm_handle)
+        if not llm_engine_blueprint:
+            return None
+        llm_model = llm_models_provider.get_optional_llm_model(
+            llm_name=llm_engine_blueprint.llm_name,
+            llm_version=llm_engine_blueprint.llm_version,
+            llm_platform_choice=llm_engine_blueprint.llm_platform_choice,
+        )
+        return llm_model
+
     @override
     @classmethod
     def final_validate(cls, deck: Self):
@@ -215,11 +225,11 @@ def validate_llm_choice_overrides(cls, value: LLMSettingChoices) -> LLMSettingCh
             value.for_object_list_direct = None
         return value
 
-    def add_llm_handle_to_llm_engine_blueprint(self, llm_handle: str, llm_engine_default: str):
-        if llm_handle in self.llm_handles:
-            raise ConfigValidationError(f"LLM engine blueprint for '{llm_handle}' is already defined in llm_handle_to_llm_engine_blueprint")
+    def add_llm_name_as_handle_with_defaults(self, llm_name: str):
+        if llm_name in self.llm_handles:
+            raise ConfigValidationError(f"LLM engine blueprint for '{llm_name}' is already defined in llm deck's llm_handles")
         # TODO: sort the defaults by llm family
-        self.llm_handles[llm_handle] = LLMEngineBlueprint(llm_name=llm_engine_default)
+        self.llm_handles[llm_name] = LLMEngineBlueprint(llm_name=llm_name)
 
     def validate_llm_presets(self) -> Self:
         for llm_preset_id, llm_setting in self.llm_presets.items():

pipelex/cogt/llm/llm_models/llm_deck_abstract.py

@@ -1,5 +1,5 @@
 from abc import ABC, abstractmethod
-from typing import Dict, Optional
+from typing import Dict, List, Optional
 
 from pydantic import Field
 from typing_extensions import Self
@@ -11,6 +11,7 @@
 
 class LLMDeckAbstract(ABC):
     llm_handles: Dict[str, LLMEngineBlueprint] = Field(default_factory=dict)
+    llm_external_handles: List[str] = Field(default_factory=list)
     llm_presets: Dict[str, LLMSetting] = Field(default_factory=dict)
     llm_choice_defaults: LLMSettingChoices
     llm_choice_overrides: LLMSettingChoices = LLMSettingChoices(
@@ -57,6 +58,10 @@ def get_llm_setting_for_object_list_direct(self, override: Optional[LLMSettingCh
     def find_llm_model(self, llm_handle: str) -> LLMModel:
         pass
 
+    @abstractmethod
+    def find_optional_llm_model(self, llm_handle: str) -> Optional[LLMModel]:
+        pass
+
     @classmethod
     @abstractmethod
     def final_validate(cls, deck: Self):

pipelex/cogt/llm/llm_models/llm_engine.py

@@ -31,7 +31,7 @@ def desc(self) -> str:
 
     @property
     def tag(self) -> str:
-        return f"{self.llm_platform} - {self.llm_model.llm_name} - {self.llm_model.version}"
+        return f"{self.llm_platform}:{self.llm_model.llm_name}:{self.llm_model.version}:id-[{self.llm_id}]"
 
     @property
     def is_gen_object_supported(self) -> bool:

pipelex/cogt/llm/llm_models/llm_engine_factory.py

@@ -15,7 +15,7 @@ def make_llm_engine(
         Create an instance of LLMEngine based on the parameters provided through the LLMEngineCard.
 
         Args:
-            llm_engine_blueprint: LLMEngineCard
+            llm_engine_blueprint: LLMEngineBlueprint
 
         """
         llm_platform_choice = llm_engine_blueprint.llm_platform_choice