model-compose 0.4.82__tar.gz → 0.4.83__tar.gz

model_compose-0.4.83/PKG-INFO

@@ -0,0 +1,327 @@
+Metadata-Version: 2.4
+Name: model-compose
+Version: 0.4.83
+Summary: model-compose: Declarative AI Workflow Orchestrator
+Author-email: Hanyeol Cho <hanyeol.cho@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/hanyeol/model-compose
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click
+Requires-Dist: pyyaml
+Requires-Dist: pydantic
+Requires-Dist: python-dotenv
+Requires-Dist: packaging
+Requires-Dist: docker
+Requires-Dist: aiohttp
+Requires-Dist: aiofiles
+Requires-Dist: brotlicffi
+Requires-Dist: requests
+Requires-Dist: fastapi
+Requires-Dist: websockets
+Requires-Dist: uvicorn
+Requires-Dist: mcp>=1.10.1
+Requires-Dist: ulid
+Requires-Dist: Pillow
+Requires-Dist: async_timeout>=4.0; python_version < "3.11"
+Dynamic: license-file
+
+<div align="center">
+
+![model-compose - Compose Any AI, Deploy Anywhere](docs/images/main-banner.png)
+
+[![Python Version](https://img.shields.io/badge/python-3.10+-blue.svg)](https://python.org)
+[![PyPI version](https://img.shields.io/pypi/v/model-compose.svg)](https://pypi.org/project/model-compose/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Downloads](https://pepy.tech/badge/model-compose)](https://pepy.tech/project/model-compose)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](http://makeapullrequest.com)
+
+[한국어](README.ko.md) | [中文](README.zh-cn.md)
+
+</div>
+
+---
+
+# model-compose
+
+**Deploy production-ready AI services in minutes.**
+
+One YAML file. Any model. Any protocol. Any runtime. Build chat APIs, RAG pipelines, autonomous agents, and MCP servers without writing application code — then deploy the same file anywhere, like `docker-compose`.
+
+AI systems should not be locked into a single provider, runtime, or cloud. model-compose is built on four principles:
+
+- **Composable** — Models, agents, workflows, tools, memory, and protocols are interchangeable building blocks.
+- **Portable** — Define your AI system once, deploy anywhere without re-engineering.
+- **Hybrid-First** — Bridge cloud APIs and local models on your own terms.
+- **Stream-Native** — Data flows through workflows as it arrives — tokens, audio, frames, and events as first-class values.
+
+<div align="center">
+
+[Quick Start](#quick-start) · [What You Can Build](#what-you-can-build) · [Documentation](docs/user-guide/README.md) · [Examples](examples/README.md)
+
+</div>
+
+---
+
+## Quick Start
+
+Install with pip:
+
+```bash
+pip install model-compose
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv pip install model-compose
+```
+
+Create `model-compose.yml`:
+
+```yaml
+controller:
+  adapter:
+    type: http-server
+    port: 8080
+  webui:
+    port: 8081
+
+workflow:
+  job:
+    component: chatgpt
+    input:
+      prompt: ${input.prompt}
+
+component:
+  id: chatgpt
+  type: http-client
+  base_url: https://api.openai.com/v1
+  action:
+    path: /chat/completions
+    method: POST
+    headers:
+      Authorization: Bearer ${env.OPENAI_API_KEY}
+    body:
+      model: gpt-4o
+      messages:
+        - role: user
+          content: ${input.prompt}
+```
+
+Run it:
+
+```bash
+export OPENAI_API_KEY=your-key
+model-compose up
+```
+
+**That's it.** You're serving GPT-4o at `http://localhost:8080` with a web UI at `http://localhost:8081`. No application code. No framework boilerplate. Same file runs locally, in Docker, or in production.
+
+---
+
+## What You Can Build
+
+Here's what a single YAML file can serve today — just a few examples.
+
+### 🤖 Autonomous Agents
+
+Build a ReAct agent that plans, uses tools, and completes multi-step tasks — declaratively.
+
+```yaml
+component:
+  id: research-agent
+  type: agent
+  tools: [search-web, fetch-page]
+  max_iteration_count: 10
+  action:
+    model:
+      component: chatgpt
+    system_prompt: You are a web research assistant.
+    user_prompt: ${input.question}
+```
+
+See simple agents like a code reviewer, a RAG assistant, and a web researcher in [agents/](examples/agents/).
+
+### 🔍 RAG Pipelines
+
+Compose embedding, vector search, and generation into a single workflow — no glue code.
+
+```yaml
+workflow:
+  jobs:
+    - id: embed
+      component: embedder
+      input: { text: ${input.query} }
+
+    - id: retrieve
+      component: knowledge
+      action: search
+      input: { vector: ${jobs.embed.output} }
+
+    - id: answer
+      component: chatgpt
+      input:
+        context: ${jobs.retrieve.output}
+        question: ${input.query}
+```
+
+Native drivers ship for Chroma, Milvus, Qdrant, FAISS, Neo4j, ArangoDB, and Redis.
+
+### 🌐 MCP Servers
+
+Turn any workflow into an MCP server that Claude, ChatGPT, or Cursor can use — one line change.
+
+```yaml
+controller:
+  adapter:
+    type: mcp-server   # ← was: http-server
+    port: 8080
+```
+
+Full examples live in [mcp-servers/](examples/mcp-servers/), including a Slack bot MCP.
+
+### ⚡ Streaming Multi-Modal Workflows
+
+Stream tokens, audio chunks, and video frames end-to-end — first-class across every stage.
+
+```yaml
+workflow:
+  job:
+    component: chatgpt
+    output: ${output as sse-text}
+
+component:
+  id: chatgpt
+  type: http-client
+  action:
+    body: { stream: true, ... }
+    stream_format: json
+    output: ${response[].choices[0].delta.content}
+```
+
+Real-time TTS, video-to-frames, and live chat examples live under [data-streaming/](examples/data-streaming/) and [showcase/](examples/showcase/).
+
+---
+
+## From Development to Production
+
+The same YAML that runs on your laptop scales without a rewrite.
+
+### 1. Develop locally
+
+```bash
+model-compose up
+```
+
+Runs on your machine with a Gradio web UI at `:8081` — perfect for iteration.
+
+### 2. Deploy as a container
+
+Add a `runtime:` block. Same file, same behavior:
+
+```yaml
+controller:
+  runtime:
+    type: docker
+    image: my-ai-service:latest
+    ports: [ "8080:8080" ]
+```
+
+### 3. Scale horizontally
+
+Add a queue. Dispatchers accept jobs, subscribers process them across N machines:
+
+```yaml
+controller:
+  adapter: { type: http-server, port: 8080 }
+  queue:
+    driver: redis
+    host: redis.internal
+    name: my-queue
+```
+
+No shared filesystem. No code changes. Just add more subscribers to scale.
+
+---
+
+## Why model-compose?
+
+| | **model-compose** | Managed APIs (OpenAI, etc.) | Code Frameworks (LangChain, etc.) |
+|---|---|---|---|
+| **Time to first API** | **Minutes** (one YAML) | Hours (SDK + server code) | Days (framework + integration) |
+| **Provider Coupling** | **Multi-provider via config** | Single provider per SDK | Multi-provider via abstractions |
+| **Code Coupling** | **Declarative YAML — no application code** | Application code required | Framework-specific code required |
+| **Infrastructure Control** | **Full Sovereignty** | Provider-controlled | Heavy Abstraction |
+| **Runtime Flexibility** | **Hybrid-First (Local + Cloud)** | Cloud Only | Complex to customize |
+| **Protocol Support** | **HTTP / WebSocket / MCP** | Provider-specific | Limited |
+| **Data Streaming** | **First-class across all stages** | Response-only (SSE tokens) | Framework-wrapped generators |
+| **Deployment** | **Docker / Native / Virtualenv / Process** | Provider-managed | Manual integration |
+
+---
+
+## Highlights
+
+- **Any model, anywhere** — HuggingFace, vLLM, llama.cpp locally, or OpenAI/Anthropic/Google/xAI via HTTP
+- **Agents in YAML** — ReAct loops, tool use, multi-step reasoning — no code
+- **Human-in-the-loop** — pause workflows for approval, resume from CLI/UI/API
+- **20+ components** — models, agents, HTTP/WebSocket clients, vector/graph stores, shell, browsers, and more
+- **Any protocol** — HTTP REST, WebSocket, or MCP with one line
+- **Any runtime** — Docker, native, virtualenv, process, embedded — switch in one line
+- **Distributed** — Redis queue dispatch for horizontal scaling
+- **Instant Web UI** — Gradio-powered UI in 2 lines of YAML
+- **Streaming everywhere** — SSE, WebSocket, and inter-job streams as first-class values
+
+---
+
+## Examples
+
+Browse examples by category:
+
+| Category | What's inside |
+|---|---|
+| [`agents/`](examples/agents/) | Code reviewer, RAG assistant, Web researcher, Web page analyzer, ... |
+| [`showcase/`](examples/showcase/) | End-to-end pipelines: disk analysis, face-based scene search, real-time TTS |
+| [`model-providers/`](examples/model-providers/) | OpenAI, Anthropic, xAI, Google, ElevenLabs, vLLM |
+| [`model-tasks/`](examples/model-tasks/) | Local chat, embedding, TTS, VLM, face embedding, ... |
+| [`mcp-servers/`](examples/mcp-servers/) | Build MCP servers exposed to Claude, Cursor, ChatGPT |
+| [`workflow-queue/`](examples/workflow-queue/) | Redis-backed distributed dispatch (streaming + non-streaming) |
+| [`data-streaming/`](examples/data-streaming/) | Video-to-frames, YouTube live chat, streaming inputs |
+| [`integrations/`](examples/integrations/) | Vector/graph/KV stores, search engines, channels, tunnels |
+
+Browse the full catalog in [examples/README.md](examples/README.md).
+
+---
+
+## Architecture
+
+Protocol adapters → Composition engine → Runtime executors
+
+![Architecture Diagram](docs/images/architecture-diagram.png)
+
+---
+
+## Contributing
+
+We welcome all contributions — bug fixes, docs improvements, new examples.
+
+```bash
+git clone https://github.com/hanyeol/model-compose.git
+cd model-compose
+pip install -e .
+```
+
+See [CONTRIBUTING](CONTRIBUTING.md) if available, or open a PR directly.
+
+---
+
+## License
+
+MIT License © 2025-2026 Hanyeol Cho.
+
+---
+
+## Contact
+
+Have questions, ideas, or feedback? [Open an issue](https://github.com/hanyeol/model-compose/issues) or start a discussion on [GitHub Discussions](https://github.com/hanyeol/model-compose/discussions).

model_compose-0.4.83/pyproject.toml

@@ -0,0 +1,53 @@
+[project]
+name = "model-compose"
+version = "0.4.83"
+description = "model-compose: Declarative AI Workflow Orchestrator"
+authors = [
+    { name = "Hanyeol Cho", email = "hanyeol.cho@gmail.com" }
+]
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+dependencies = [
+    "click",
+    "pyyaml",
+    "pydantic",
+    "python-dotenv",
+    "packaging",
+    "docker",
+    "aiohttp",
+    "aiofiles",
+    "brotlicffi",
+    "requests",
+    "fastapi",
+    "websockets",
+    "uvicorn",
+    "mcp>=1.10.1",
+    "ulid",
+    "Pillow",
+    "async_timeout>=4.0; python_version < '3.11'"
+]
+
+[project.scripts]
+model-compose = "mindor.cli.compose:compose_command"
+
+[project.urls]
+"Homepage" = "https://github.com/hanyeol/model-compose"
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"mindor.core.runtime.base.bootstrap" = ["requirements.txt"]
+"mindor.core.runtime.base.container" = ["Dockerfile"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

model_compose-0.4.83/src/mindor/core/component/action/base.py

@@ -0,0 +1,6 @@
+from typing import Any, Callable
+import asyncio, functools
+
+class ComponentAction:
+    async def _run_in_executor(self, fn: Callable[..., Any], *args: Any, **kwargs: Any) -> Any:
+        return await asyncio.get_running_loop().run_in_executor(None, functools.partial(fn, *args, **kwargs))

model_compose-0.4.83/src/mindor/core/component/action/media.py

@@ -0,0 +1,53 @@
+from mindor.dsl.schema.action import VideoAudioEncodingConfig, VideoEncoderConfig, AudioEncoderConfig
+from mindor.core.foundation.media.encoding import VideoEncoderParams, AudioEncoderParams, VideoAudioEncodingParams
+from mindor.core.foundation.variable.bitrate import parse_bitrate
+from ..context import ComponentActionContext
+from .base import ComponentAction
+
+class MediaComponentAction(ComponentAction):
+    """Base for actions that emit/consume video+audio with encoding configuration.
+
+    Provides shared helpers to resolve DSL encoding configs into the normalized
+    `VideoAudioEncodingParams` shape the driver/session/recorder layer expects.
+    """
+
+    async def _resolve_encoding_params(
+        self, context: ComponentActionContext, config: VideoAudioEncodingConfig,
+    ) -> VideoAudioEncodingParams:
+        format = await context.render_variable(config.format) if config.format else None
+
+        return VideoAudioEncodingParams(
+            format=format,
+            video=await self._resolve_video_encoder(context, config.video) if config.video else None,
+            audio=await self._resolve_audio_encoder(context, config.audio) if config.audio else None,
+        )
+
+    async def _resolve_video_encoder(
+        self, context: ComponentActionContext, config: VideoEncoderConfig,
+    ) -> VideoEncoderParams:
+        codec      = await context.render_variable(config.codec)      if config.codec      else None
+        bitrate    = await context.render_variable(config.bitrate)    if config.bitrate    else None
+        resolution = await context.render_variable(config.resolution) if config.resolution else None
+        fps        = await context.render_variable(config.fps)        if config.fps        else None
+
+        return VideoEncoderParams(
+            codec=codec,
+            bitrate=parse_bitrate(bitrate) if bitrate is not None else None,
+            resolution=resolution,
+            fps=float(fps) if fps is not None else None,
+        )
+
+    async def _resolve_audio_encoder(
+        self, context: ComponentActionContext, config: AudioEncoderConfig,
+    ) -> AudioEncoderParams:
+        codec       = await context.render_variable(config.codec)       if config.codec       else None
+        bitrate     = await context.render_variable(config.bitrate)     if config.bitrate     else None
+        sample_rate = await context.render_variable(config.sample_rate) if config.sample_rate is not None else None
+        channels    = await context.render_variable(config.channels)    if config.channels    is not None else None
+
+        return AudioEncoderParams(
+            codec=codec,
+            bitrate=parse_bitrate(bitrate) if bitrate is not None else None,
+            sample_rate=int(sample_rate) if sample_rate is not None else None,
+            channels=int(channels) if channels is not None else None,
+        )

model_compose-0.4.83/src/mindor/core/component/context.py

@@ -0,0 +1,163 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+from typing import Type, Union, Literal, Optional, Dict, List, Tuple, Set, Annotated, Any
+from collections.abc import AsyncIterator
+from mindor.core.foundation.variable.renderer import VariableRenderer
+from mindor.core.foundation.variable.image import ImageValueRenderer, ImageArrayValue
+from mindor.core.foundation.variable.audio import AudioValueRenderer, AudioBufferValueRenderer, AudioBufferArrayValue
+from mindor.core.utils.audio import AudioBuffer
+from mindor.core.foundation.variable.video import VideoValueRenderer
+from mindor.core.foundation.variable.media import MediaValueRenderer
+from mindor.core.foundation.variable.file import FileValueRenderer
+from mindor.core.foundation.variable.text import TextValueRenderer
+from mindor.core.foundation.variable.size import SizeValueRenderer
+from mindor.core.foundation.variable.color import ColorValueRenderer, Color
+from mindor.core.foundation.variable.array import ArrayValueRenderer, ArrayValue
+from mindor.core.foundation.variable.vector import VectorValueRenderer, VectorValue, VectorArrayValue
+from mindor.core.foundation.streaming.media import MediaSource
+from mindor.core.foundation.cancellation import CancellationToken
+from mindor.core.gateway import find_gateway_by_port
+from PIL import Image as PILImage
+
+if TYPE_CHECKING:
+    from mindor.core.workflow.context import WorkflowContext
+    from mindor.core.workflow.notifiers import ComponentEventNotifier
+
+class ComponentActionEventNotifier:
+    def __init__(self, notifier: Optional[ComponentEventNotifier], component_id: Optional[str], component_type: Optional[str], job_id: Optional[str], run_id: Optional[str]):
+        self.notifier: Optional[ComponentEventNotifier] = notifier
+        self.component_id: Optional[str] = component_id
+        self.component_type: Optional[str] = component_type
+        self.job_id: Optional[str] = job_id
+        self.run_id: Optional[str] = run_id
+
+    async def notify(
+        self,
+        event: Literal[ "started", "completed", "failed", "internal" ],
+        kind: Optional[str] = None,
+        input: Optional[Any] = None,
+        output: Optional[Any] = None,
+        error: Optional[str] = None,
+    ) -> None:
+        if self.notifier is None:
+            return
+        await self.notifier.notify(
+            event=event,
+            job_id=self.job_id,
+            component_id=self.component_id,
+            component_type=self.component_type,
+            run_id=self.run_id,
+            kind=kind,
+            input=input,
+            output=output,
+            error=error,
+        )
+
+class ComponentActionContext:
+    def __init__(
+        self,
+        run_id: str,
+        input: Dict[str, Any],
+        workflow: Optional[WorkflowContext] = None,
+        component_id: Optional[str] = None,
+        component_type: Optional[str] = None,
+        job_id: Optional[str] = None,
+    ):
+        self.run_id: str = run_id
+        self.input: Dict[str, Any] = input
+        self.workflow: Optional[WorkflowContext] = workflow
+        self.component_id: Optional[str] = component_id
+        self.component_type: Optional[str] = component_type
+        self.job_id: Optional[str] = job_id
+        self.context: Dict[str, Any] = { "run_id": run_id }
+        self.sources: Dict[str, Dict[str, Any]] = { "__global__": {} }
+        self.renderer: VariableRenderer = VariableRenderer(self.resolve_source)
+        self.event_notifier: ComponentActionEventNotifier = self._build_event_notifier()
+
+    @property
+    def cancellation_token(self) -> Optional[CancellationToken]:
+        return self.workflow.cancellation_token if self.workflow else None
+
+    def register_source(self, key: str, source: Any, scope: Optional[str] = None) -> None:
+        self.sources.setdefault(scope or "__global__", {})[key] = source
+
+    async def render_variable(self, value: Any, scope: Optional[str] = None, skip_decode: bool = False) -> Any:
+        return await self.renderer.render(value, scope, skip_decode=skip_decode)
+
+    async def render_text(self, value: Any) -> Optional[Union[str, List[Optional[str]], AsyncIterator[Optional[str]]]]:
+        return await TextValueRenderer().render(await self.render_variable(value))
+
+    async def render_image(self, value: Any) -> Union[PILImage.Image, List[PILImage.Image], AsyncIterator[PILImage.Image]]:
+        return await ImageValueRenderer().render(await self.render_variable(value))
+
+    async def render_image_array(self, value: Any) -> Union[ImageArrayValue, List[ImageArrayValue], AsyncIterator[ImageArrayValue]]:
+        return await ImageValueRenderer().render_array(await self.render_variable(value))
+
+    async def render_audio(self, value: Any) -> Union[MediaSource, List[MediaSource]]:
+        return await AudioValueRenderer().render(await self.render_variable(value))
+
+    async def render_audio_buffer(self, value: Any) -> Union[AudioBuffer, List[AudioBuffer], AsyncIterator[AudioBuffer]]:
+        return await AudioBufferValueRenderer().render(await self.render_variable(value))
+
+    async def render_audio_buffer_array(self, value: Any) -> Union[AudioBufferArrayValue, List[AudioBufferArrayValue], AsyncIterator[AudioBufferArrayValue]]:
+        return await AudioBufferValueRenderer().render_array(await self.render_variable(value))
+
+    async def render_video(self, value: Any) -> Union[MediaSource, List[MediaSource]]:
+        return await VideoValueRenderer().render(await self.render_variable(value))
+
+    async def render_media(self, value: Any) -> Union[MediaSource, List[MediaSource]]:
+        return await MediaValueRenderer().render(await self.render_variable(value))
+
+    async def render_file(self, value: Any) -> Any:
+        return await FileValueRenderer().render(await self.render_variable(value))
+
+    async def render_vector(self, value: Any) -> Union[VectorValue, List[VectorValue], AsyncIterator[VectorValue]]:
+        return await VectorValueRenderer().render(await self.render_variable(value))
+
+    async def render_vector_array(self, value: Any) -> Union[VectorArrayValue, List[VectorArrayValue], AsyncIterator[VectorArrayValue]]:
+        return await VectorValueRenderer().render_array(await self.render_variable(value))
+
+    async def render_array(self, value: Any) -> Union[ArrayValue, List[ArrayValue], AsyncIterator[ArrayValue]]:
+        return await ArrayValueRenderer().render(await self.render_variable(value))
+
+    async def render_size(self, value: Any, default: Optional[int] = None) -> Optional[int]:
+        return await SizeValueRenderer().render(await self.render_variable(value), default)
+
+    async def render_color(self, value: Any, default: Optional[Color] = None) -> Optional[Color]:
+        return await ColorValueRenderer().render(await self.render_variable(value), default)
+
+    async def resolve_source(self, key: str, index: Optional[int], scope: Optional[str]) -> Any:
+        sources = self.sources.get(scope or "__global__", {})
+
+        if key in sources:
+            return sources[key][index] if index is not None else sources[key]
+
+        if key == "input":
+            return self.input
+
+        if key == "context":
+            return self.context
+
+        if key.startswith("gateway:"):
+            return self._resolve_gateway(key)
+
+        raise KeyError(f"Unknown source: {key}")
+
+    def _resolve_gateway(self, key: str) -> Any:
+        _, port = key.split(":")
+        gateway = find_gateway_by_port(int(port)) if port else None
+
+        if gateway:
+            return gateway.get_context(int(port))
+
+        return None
+
+    def _build_event_notifier(self) -> ComponentActionEventNotifier:
+        return ComponentActionEventNotifier(
+            self.workflow.component_event_notifier if self.workflow else None,
+            self.component_id,
+            self.component_type,
+            self.job_id,
+            self.run_id
+        )

model_compose-0.4.83/src/mindor/core/component/services/audio_converter/audio_converter.py

@@ -0,0 +1,60 @@
+from typing import Optional, List, Any
+from mindor.dsl.schema.component import AudioConverterComponentConfig, AudioConverterDriver
+from mindor.dsl.schema.action import ActionConfig
+from ...base import ComponentService, ComponentType, ComponentGlobalConfigs, register_component
+from ...context import ComponentActionContext
+from .base import AudioConverterService, AudioConverterServiceRegistry
+import importlib
+
+@register_component(ComponentType.AUDIO_CONVERTER)
+class AudioConverterComponent(ComponentService):
+    def __init__(
+        self,
+        id: str,
+        config: AudioConverterComponentConfig,
+        global_configs: ComponentGlobalConfigs,
+        daemon: bool
+    ):
+        super().__init__(id, config, global_configs, daemon)
+
+        self.service: AudioConverterService = self._create_service(self.config.driver)
+
+    def _create_service(self, driver: AudioConverterDriver) -> AudioConverterService:
+        try:
+            if driver not in AudioConverterServiceRegistry:
+                self._load_driver_module(driver)
+            return AudioConverterServiceRegistry[driver](self.id, self.config, self.daemon)
+        except KeyError:
+            raise ValueError(f"Unsupported audio converter driver: {driver}")
+
+    def _load_driver_module(self, driver: AudioConverterDriver) -> None:
+        """Import the module that registers the given audio converter driver.
+
+        Convention: a driver "foo-bar" (AudioConverterDriver.value) maps to
+        mindor.core.component.services.audio_converter.drivers.foo_bar — either
+        a single-file module (foo_bar.py) or a package (foo_bar/__init__.py).
+        Importing the module triggers its @register_audio_converter_service
+        decorator, populating AudioConverterServiceRegistry.
+        """
+        driver_module = driver.value.replace("-", "_")
+
+        try:
+            importlib.import_module(f"mindor.core.component.services.audio_converter.drivers.{driver_module}")
+        except ImportError as e:
+            raise ValueError(f"Unsupported audio converter driver: {driver}") from e
+
+    def _get_setup_requirements(self) -> Optional[List[str]]:
+        return self.service.get_setup_requirements()
+
+    async def _start(self) -> None:
+        await self.service.start()
+
+        await super()._start()
+
+    async def _stop(self) -> None:
+        await super()._stop()
+
+        await self.service.stop()
+
+    async def _run(self, action: ActionConfig, context: ComponentActionContext) -> Any:
+        return await self.service.run(action, context)