model-compose 0.4.95__tar.gz → 0.4.97__tar.gz

model_compose-0.4.97/PKG-INFO

@@ -0,0 +1,327 @@
+Metadata-Version: 2.4
+Name: model-compose
+Version: 0.4.97
+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<2.0,>=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.97/pyproject.toml

@@ -0,0 +1,54 @@
+[project]
+name = "model-compose"
+version = "0.4.97"
+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,<2.0",
+    "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.bootstrap" = ["requirements.txt"]
+"mindor.core.component.runtime.container.assets" = ["Dockerfile.*", "*.stub.txt", "*.stub.sh"]
+"mindor.core.controller.runtime.container.assets" = ["Dockerfile.*", "*.stub.txt", "*.stub.sh", "bootstrap.sh"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

model_compose-0.4.97/src/mindor/core/component/base.py

@@ -0,0 +1,263 @@
+from typing import Type, Union, Literal, Optional, Dict, List, Tuple, Set, Annotated, Awaitable, Callable, Any
+from typing_extensions import Self
+from abc import ABC, abstractmethod
+from pydantic import BaseModel, Field
+from mindor.dsl.schema.component import ComponentConfig, ComponentType
+from mindor.dsl.schema.action import ActionConfig
+from mindor.dsl.schema.listener import ListenerConfig
+from mindor.dsl.schema.gateway import GatewayConfig
+from mindor.dsl.schema.workflow import WorkflowConfig
+from mindor.dsl.schema.runtime import RuntimeType
+from mindor.core.foundation import AsyncService
+from mindor.core.foundation.streaming.iterators import StreamIterator
+from mindor.core.utils.work_queue import WorkQueue
+from mindor.core.utils.active_counter import ActiveCounter
+from mindor.core.utils.time import TimeTracker
+from mindor.core.logger import logging
+from collections.abc import AsyncIterator
+from .context import ComponentActionContext
+from .streaming import ComponentOutputStreamIterator, StreamTerminatedEvent
+import asyncio
+
+class ActionResolver:
+    def __init__(self, actions: List[ActionConfig]):
+        self.actions: List[ActionConfig] = actions
+
+    def resolve(self, action_id: str, raise_on_error: bool = True) -> Union[Tuple[str, ActionConfig], Tuple[None, None]]:
+        if action_id == "__default__":
+            action = self.actions[0] if len(self.actions) == 1 else None
+            action = action or next((action for action in self.actions if action.default), None)
+        else:
+            action = next((action for action in self.actions if action.id == action_id), None)
+
+        if action is None:
+            if raise_on_error:
+                raise LookupError(f"Action not found: {action_id}")
+            else:
+                return (None, None)
+
+        return action.id, action
+
+class ComponentGlobalConfigs(BaseModel):
+    components: List[ComponentConfig] = Field(default_factory=list)
+    listeners:  List[ListenerConfig]  = Field(default_factory=list)
+    gateways:   List[GatewayConfig]   = Field(default_factory=list)
+    workflows:  List[WorkflowConfig]  = Field(default_factory=list)
+
+    @classmethod
+    def create(cls,
+        components: List[ComponentConfig],
+        listeners:  List[ListenerConfig],
+        gateways:   List[GatewayConfig],
+        workflows:  List[WorkflowConfig],
+    ) -> Self:
+        return cls(
+            components=components,
+            listeners=listeners,
+            gateways=gateways,
+            workflows=workflows,
+        )
+
+class ComponentService(AsyncService):
+    def __init__(
+        self,
+        id: str,
+        config: ComponentConfig,
+        global_configs: ComponentGlobalConfigs,
+        daemon: bool
+    ):
+        super().__init__(daemon)
+
+        self.id: str = id
+        self.config: ComponentConfig = config
+        self.global_configs: ComponentGlobalConfigs = global_configs
+        self.work_queue: Optional[WorkQueue] = None
+
+        self._runtime_manager = None
+        self._active_counter: ActiveCounter = ActiveCounter()
+
+        if self.config.max_concurrent_count > 0:
+            self.work_queue = WorkQueue(self.config.max_concurrent_count, self._run)
+
+    async def setup(self) -> None:
+        # Only in-process runtimes install dependencies on the host. Isolated runtimes
+        # (process / virtualenv / docker / apple-container) install their dependencies
+        # inside their own environment (worker venv / container build), so we skip
+        # the host-side install to avoid leaking them into the parent interpreter.
+        if self.config.runtime.type in (RuntimeType.NATIVE, RuntimeType.EMBEDDED):
+            await super().setup()
+
+    async def start(self, background: bool = False) -> None:
+        self._runtime_manager = self._create_runtime_manager(self.config.runtime.type)
+        if self._runtime_manager is not None:
+            await self._runtime_manager.start()
+            logging.info(f"Component '{self.id}' started with {self.config.runtime.type.value} runtime")
+            self.started = True
+            return
+
+        await super().start(background)
+        await self.wait_until_ready()
+
+    async def stop(self) -> None:
+        if self._runtime_manager is not None:
+            await self._runtime_manager.stop()
+            logging.info(f"Component '{self.id}' {self.config.runtime.type.value} runtime stopped")
+            self._runtime_manager = None
+            self.started = False
+            return
+
+        await super().stop()
+
+    async def run(
+        self,
+        action_id: str,
+        run_id: str,
+        input: Dict[str, Any],
+        workflow=None,
+        job_id: Optional[str] = None,
+        on_event: Optional[Callable[[Dict[str, Any]], Awaitable[None]]] = None,
+    ) -> Dict[str, Any]:
+        if self._runtime_manager is not None:
+            # Bridge parent-side workflow event notifier into the worker via IPC.
+            # In-worker `ComponentService.run` receives these events through its own
+            # `on_event` param and re-emits them locally via the context notifier.
+            return await self._runtime_manager.run(
+                action_id,
+                run_id,
+                input,
+                on_event=self._build_runtime_event_forwarder(workflow, job_id, run_id)
+            )
+
+        _, action = ActionResolver(self.config.actions).resolve(action_id)
+        context = ComponentActionContext(
+            run_id,
+            input,
+            workflow=workflow,
+            component_id=self.id,
+            component_type=self.config.type.value,
+            job_id=job_id,
+            on_event=on_event,
+        )
+
+        time_tracker = TimeTracker()
+        await context.event_notifier.notify("started", input=input)
+
+        try:
+            if self.work_queue:
+                output = await (await self.work_queue.schedule(action, context))
+            else:
+                self._active_counter.acquire()
+                try:
+                    output = await self._run(action, context)
+                finally:
+                    self._active_counter.release()
+        except asyncio.CancelledError:
+            await context.event_notifier.notify("cancelled", elapsed=time_tracker.elapsed())
+            raise
+        except Exception as e:
+            await context.event_notifier.notify("failed", elapsed=time_tracker.elapsed(), error=str(e))
+            raise
+
+        if isinstance(output, (StreamIterator, AsyncIterator)):
+            async def _on_terminated(event: StreamTerminatedEvent, error: Optional[str]) -> None:
+                if event == "completed":
+                    await context.event_notifier.notify("completed", elapsed=time_tracker.elapsed(), output=None)
+                elif event == "cancelled":
+                    await context.event_notifier.notify("cancelled", elapsed=time_tracker.elapsed())
+                else:
+                    await context.event_notifier.notify("failed", elapsed=time_tracker.elapsed(), error=error)
+
+            return ComponentOutputStreamIterator(output, _on_terminated)
+
+        await context.event_notifier.notify("completed", elapsed=time_tracker.elapsed(), output=output)
+
+        return output
+
+    async def _start(self) -> None:
+        if self.work_queue:
+            await self.work_queue.start()
+
+        await super()._start()
+
+    async def _stop(self) -> None:
+        if self.work_queue:
+            await self.work_queue.stop()
+
+        await self._active_counter.wait_for_zero()
+
+        await super()._stop()
+
+    async def _is_ready(self) -> bool:
+        return True
+
+    async def _install_package(self, package_spec: str, repository: Optional[str]) -> None:
+        logging.info(f"Installing required module: {package_spec}")
+        await super()._install_package(package_spec, repository)
+
+    @abstractmethod
+    async def _run(self, action: ActionConfig, context: ComponentActionContext) -> Any:
+        pass
+
+    def _create_component(self, component_id: str) -> "ComponentService":
+        from .component import ComponentResolver, create_component
+
+        resolved_id, resolved_config = ComponentResolver(self.global_configs.components).resolve(component_id)
+        return create_component(resolved_id, resolved_config, self.global_configs, daemon=False)
+
+    def _create_runtime_manager(self, runtime_type: RuntimeType):
+        if runtime_type == RuntimeType.PROCESS:
+            from .runtime.process import ComponentProcessRuntimeManager
+
+            return ComponentProcessRuntimeManager(self.id, self.config, self.global_configs)
+
+        if runtime_type == RuntimeType.VIRTUALENV:
+            from .runtime.virtualenv import ComponentVirtualEnvRuntimeManager
+
+            return ComponentVirtualEnvRuntimeManager(self.id, self.config, self.global_configs)
+
+        if runtime_type == RuntimeType.DOCKER:
+            from .runtime.docker import ComponentDockerRuntimeManager
+
+            return ComponentDockerRuntimeManager(self.id, self.config, self.global_configs)
+
+        if runtime_type == RuntimeType.APPLE_CONTAINER:
+            from .runtime.apple_container import ComponentAppleContainerRuntimeManager
+
+            return ComponentAppleContainerRuntimeManager(self.id, self.config, self.global_configs)
+
+        return None
+
+    def _build_runtime_event_forwarder(
+        self,
+        workflow,
+        job_id: Optional[str],
+        run_id: str,
+    ) -> Optional[Callable[[Dict[str, Any]], Awaitable[None]]]:
+        notifier = workflow.component_event_notifier if workflow is not None else None
+
+        if notifier is None:
+            return None
+
+        async def _forward(payload: Dict[str, Any]) -> None:
+            await notifier.notify(
+                event=payload["event"],
+                job_id=job_id,
+                component_id=self.id,
+                component_type=self.config.type.value,
+                run_id=run_id,
+                kind=payload.get("kind"),
+                elapsed=payload.get("elapsed"),
+                input=payload.get("input"),
+                output=payload.get("output"),
+                error=payload.get("error"),
+            )
+
+        return _forward
+
+def register_component(type: ComponentType):
+    def decorator(cls: Type[ComponentService]) -> Type[ComponentService]:
+        ComponentRegistry[type] = cls
+        return cls
+    return decorator
+
+ComponentRegistry: Dict[ComponentType, Type[ComponentService]] = {}