model-compose 0.1.0__tar.gz → 0.1.1__tar.gz

{model_compose-0.1.0 → model_compose-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: model-compose
-Version: 0.1.0
+Version: 0.1.1
 Summary: model-compose: Declarative AI Model and Workflow Orchestrator (part of the Mindor project)
 Author-email: Hanyeol Cho <hanyeol.cho@gmail.com>
 License-Expression: MIT
@@ -21,41 +21,28 @@ Requires-Dist: gradio
 Requires-Dist: Pillow
 Dynamic: license-file
 
-# model-compose: Declarative AI Model and Workflow Orchestrator (_part of the Mindor project_)
+# model-compose: Declarative AI Model and Workflow Orchestrator
 
 [![Python Version](https://img.shields.io/badge/python-3.9+-blue.svg)](https://python.org)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](http://makeapullrequest.com)
 
+![Screenshots](docs/images/screenshots.png)
+
 **model-compose** is an open-source, declarative workflow orchestrator inspired by `docker-compose`. It lets you define and run AI model pipelines using simple YAML files — no custom code required. Effortlessly connect external AI services or run local AI models, all within powerful, composable workflows.
 
 ---
 
 ## ✨ Features
 
-#### 🔧 Declarative by Design
-Define complete AI workflows using simple YAML files — no complex scripting required.
-
-#### 🔗 Compose Anything
-Combine multiple AI models, APIs, and tools into a single, unified pipeline.
-
-#### 🧠 Built for Orchestration
-Orchestrate multi-step model interactions with ease. Turn individual API calls into maintainable, end-to-end systems using **model-compose**.
-
-#### 🛠️ Multi-Workflow Support
-Define multiple named workflows in one project. Run them by name or set a default for quick execution.
-
-#### 🧩 Modular Components
-Break down logic into reusable components and jobs. Easily plug, swap, and extend them across workflows.
-
-#### ⚙️ Flexible I/O Routing
-Connect inputs and outputs between jobs using clean, scoped variables - no glue code needed.
-
-#### 🧪 Run Locally, Serve Remotely
-Execute workflows from the CLI or expose them as HTTP or MCP endpoints with an optional Web UI.
-
-#### 📦 Works with Environment Variables
-Easily inject secrets and configuration via `.env` files or environment variables to keep your YAML clean and secure.
+- **Declarative by Design:** Define complete AI workflows using simple YAML files—no complex scripting required.
+- **Compose Anything:** Combine multiple AI models, APIs, and tools into a single, unified pipeline.
+- **Built for Orchestration:**  Orchestrate multi-step model interactions with ease. Transform individual API calls into maintainable, end-to-end systems.
+- **Multi-Workflow Support:** Define multiple named workflows in one project. Run them by name or set a default for quick execution.
+- **Modular Components:** Break down logic into reusable components and jobs. Easily plug, swap, and extend them across workflows.
+- **Flexible I/O Routing:** Connect inputs and outputs between jobs using clean, scoped variables—no glue code needed.
+- **Run Locally, Serve Remotely:** Execute workflows from the CLI or expose them as HTTP or MCP endpoints with an optional Web UI.
+- **Environment Variable Support:** Easily inject secrets and configuration via `.env` files or environment variables to keep your YAML clean and secure.
 
 ---
 
@@ -214,14 +201,14 @@ listener:
   port: 8090
   base_path: /callbacks
   callbacks:
-    - path: /chatgpt
+    - path: /chat-ai
       method: POST
       item: ${body.data}
       identify_by: ${item.task_id}
       result: ${item.choices[0].message.content}
 ```
 
-This listener sets up an HTTP callback endpoint at `http://localhost:8090/callbacks/chatgpt` to receive asynchronous responses from a remote ChatGPT-compatible service. It extracts the incoming data from the request body, identifies the task using `task_id`, and stores the final message content from the first choice in the response.
+This listener sets up an HTTP callback endpoint at http://localhost:8090/callbacks/chat-ai to handle asynchronous responses from an external service that behaves like ChatGPT but supports delayed or push-based results. This is useful when integrating with services that notify results via webhook-style callbacks.
 
 #### 🌐 Gateway Example
 
@@ -234,7 +221,12 @@ gateway:
 
 This gateway configuration exposes the local listener defined above to the public internet using an HTTP tunnel powered by ngrok. It forwards incoming traffic from a secure, public URL (e.g., https://abc123.ngrok.io) directly to your local callback endpoint at http://localhost:8090. This is essential when integrating with third-party services that need to push data back to your workflow via webhooks or asynchronous callbacks.
 
-> 📁 For more example model-compose.yml configurations, check the samples directory in the source code.
+> 📁 For more example model-compose.yml configurations, check the [examples directory](examples) in the source code.
+
+---
+## 🏗 Architecture
+
+![Archtecture Diagram](docs/images/architecture-diagram.png)
 
 ---
 

{model_compose-0.1.0 → model_compose-0.1.1}/README.md

@@ -1,38 +1,25 @@
-# model-compose: Declarative AI Model and Workflow Orchestrator (_part of the Mindor project_)
+# model-compose: Declarative AI Model and Workflow Orchestrator
 
 [![Python Version](https://img.shields.io/badge/python-3.9+-blue.svg)](https://python.org)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](http://makeapullrequest.com)
 
+![Screenshots](docs/images/screenshots.png)
+
 **model-compose** is an open-source, declarative workflow orchestrator inspired by `docker-compose`. It lets you define and run AI model pipelines using simple YAML files — no custom code required. Effortlessly connect external AI services or run local AI models, all within powerful, composable workflows.
 
 ---
 
 ## ✨ Features
 
-#### 🔧 Declarative by Design
-Define complete AI workflows using simple YAML files — no complex scripting required.
-
-#### 🔗 Compose Anything
-Combine multiple AI models, APIs, and tools into a single, unified pipeline.
-
-#### 🧠 Built for Orchestration
-Orchestrate multi-step model interactions with ease. Turn individual API calls into maintainable, end-to-end systems using **model-compose**.
-
-#### 🛠️ Multi-Workflow Support
-Define multiple named workflows in one project. Run them by name or set a default for quick execution.
-
-#### 🧩 Modular Components
-Break down logic into reusable components and jobs. Easily plug, swap, and extend them across workflows.
-
-#### ⚙️ Flexible I/O Routing
-Connect inputs and outputs between jobs using clean, scoped variables - no glue code needed.
-
-#### 🧪 Run Locally, Serve Remotely
-Execute workflows from the CLI or expose them as HTTP or MCP endpoints with an optional Web UI.
-
-#### 📦 Works with Environment Variables
-Easily inject secrets and configuration via `.env` files or environment variables to keep your YAML clean and secure.
+- **Declarative by Design:** Define complete AI workflows using simple YAML files—no complex scripting required.
+- **Compose Anything:** Combine multiple AI models, APIs, and tools into a single, unified pipeline.
+- **Built for Orchestration:**  Orchestrate multi-step model interactions with ease. Transform individual API calls into maintainable, end-to-end systems.
+- **Multi-Workflow Support:** Define multiple named workflows in one project. Run them by name or set a default for quick execution.
+- **Modular Components:** Break down logic into reusable components and jobs. Easily plug, swap, and extend them across workflows.
+- **Flexible I/O Routing:** Connect inputs and outputs between jobs using clean, scoped variables—no glue code needed.
+- **Run Locally, Serve Remotely:** Execute workflows from the CLI or expose them as HTTP or MCP endpoints with an optional Web UI.
+- **Environment Variable Support:** Easily inject secrets and configuration via `.env` files or environment variables to keep your YAML clean and secure.
 
 ---
 
@@ -191,14 +178,14 @@ listener:
   port: 8090
   base_path: /callbacks
   callbacks:
-    - path: /chatgpt
+    - path: /chat-ai
       method: POST
       item: ${body.data}
       identify_by: ${item.task_id}
       result: ${item.choices[0].message.content}
 ```
 
-This listener sets up an HTTP callback endpoint at `http://localhost:8090/callbacks/chatgpt` to receive asynchronous responses from a remote ChatGPT-compatible service. It extracts the incoming data from the request body, identifies the task using `task_id`, and stores the final message content from the first choice in the response.
+This listener sets up an HTTP callback endpoint at http://localhost:8090/callbacks/chat-ai to handle asynchronous responses from an external service that behaves like ChatGPT but supports delayed or push-based results. This is useful when integrating with services that notify results via webhook-style callbacks.
 
 #### 🌐 Gateway Example
 
@@ -211,7 +198,12 @@ gateway:
 
 This gateway configuration exposes the local listener defined above to the public internet using an HTTP tunnel powered by ngrok. It forwards incoming traffic from a secure, public URL (e.g., https://abc123.ngrok.io) directly to your local callback endpoint at http://localhost:8090. This is essential when integrating with third-party services that need to push data back to your workflow via webhooks or asynchronous callbacks.
 
-> 📁 For more example model-compose.yml configurations, check the samples directory in the source code.
+> 📁 For more example model-compose.yml configurations, check the [examples directory](examples) in the source code.
+
+---
+## 🏗 Architecture
+
+![Archtecture Diagram](docs/images/architecture-diagram.png)
 
 ---
 

{model_compose-0.1.0 → model_compose-0.1.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "model-compose"
-version = "0.1.0"
+version = "0.1.1"
 description = "model-compose: Declarative AI Model and Workflow Orchestrator (part of the Mindor project)"
 authors = [
     { name = "Hanyeol Cho", email = "hanyeol.cho@gmail.com" }

{model_compose-0.1.0 → model_compose-0.1.1}/src/mindor/core/component/engine/http_client.py

@@ -10,8 +10,9 @@ from datetime import datetime, timezone
 import asyncio
 
 class HttpClientPollingCompletion:
-    def __init__(self, base_url: Optional[str], config: HttpClientCompletionConfig):
+    def __init__(self, base_url: Optional[str], headers: Optional[Dict[str, str]], config: HttpClientCompletionConfig):
         self.base_url: Optional[str] = base_url
+        self.headers: Optional[Dict[str, str]] = headers
         self.config: HttpClientCompletionConfig = config
         self.client: HttpClient = HttpClient()
 
@@ -20,7 +21,7 @@ class HttpClientPollingCompletion:
         method  = await context.render_template(self.config.method)
         params  = await context.render_template(self.config.params)
         body    = await context.render_template(self.config.body)
-        headers = await context.render_template(self.config.headers)
+        headers = await context.render_template({ **self.headers, **self.config.headers })
 
         interval = parse_duration(self.config.interval) if self.config.interval else 5.0
         timeout  = parse_duration(self.config.timeout) if self.config.timeout else 300
@@ -67,8 +68,9 @@ class HttpClientCallbackCompletion:
         return await future
 
 class HttpClientAction:
-    def __init__(self, base_url: Optional[str], config: HttpClientActionConfig):
+    def __init__(self, base_url: Optional[str], headers: Optional[Dict[str, str]], config: HttpClientActionConfig):
         self.base_url: Optional[str] = base_url
+        self.headers: Optional[Dict[str, str]] = headers
         self.config: HttpClientActionConfig = config
         self.client: HttpClient = HttpClient()
 
@@ -77,7 +79,7 @@ class HttpClientAction:
         method  = await context.render_template(self.config.method)
         params  = await context.render_template(self.config.params)
         body    = await context.render_template(self.config.body)
-        headers = await context.render_template(self.config.headers)
+        headers = await context.render_template({ **self.headers, **self.config.headers })
 
         response, result = await self.client.request(url, method, params, body, headers), None
 
@@ -100,7 +102,7 @@ class HttpClientAction:
 
     async def _handle_completion(self, completion: HttpClientCompletionConfig, context: ComponentContext) -> Any:
         if completion.type == "polling":
-            return await HttpClientPollingCompletion(self.base_url, completion).run(context)
+            return await HttpClientPollingCompletion(self.base_url, self.headers, completion).run(context)
         
         if completion.type == "callback":
             return await HttpClientCallbackCompletion(completion).run(context)
@@ -118,6 +120,6 @@ class HttpClientComponent(ComponentEngine):
         pass
 
     async def _run(self, action: ActionConfig, context: ComponentContext) -> Any:
-        return await HttpClientAction(self.config.base_url, action).run(context)
+        return await HttpClientAction(self.config.base_url, self.config.headers, action).run(context)
 
 ComponentEngineMap[ComponentType.HTTP_CLIENT] = HttpClientComponent

{model_compose-0.1.0 → model_compose-0.1.1}/src/mindor/core/controller/engine/http_server.py

@@ -109,7 +109,8 @@ class HttpServerController(ControllerEngine):
         await self.server.serve()
  
     async def _shutdown(self) -> None:
-        self.server.should_exit = True
+        if self.server:
+            self.server.should_exit = True
 
     async def _parse_workflow_body(self, request: Request) -> WorkflowTaskRequestBody:
         content_type, _ = parse_options_header(request.headers, "Content-Type")

{model_compose-0.1.0 → model_compose-0.1.1}/src/mindor/core/controller/webui/gradio.py

@@ -5,6 +5,7 @@ from mindor.core.utils.image import load_image_from_stream
 from mindor.core.utils.streaming import Base64StreamResource, save_stream_to_temporary_file
 from .schema import WorkflowSchema
 import gradio as gr
+import json
 
 class GradioWebUIBuilder:
     def build(self, schema: Dict[str, WorkflowSchema], runner: Callable[[Optional[str], Any], Awaitable[Any]]) -> gr.Blocks:
@@ -44,8 +45,11 @@ class GradioWebUIBuilder:
 
                 if workflow.output:
                     if isinstance(output, dict):
-                        output = [ await self._convert_type(output[variable.name], variable.type, variable.subtype, variable.format) for variable in workflow.output ]
-                        output = output[0] if len(output) == 1 else output
+                        outputs = []
+                        for variable in workflow.output:
+                            value = output[variable.name] if variable.name else output
+                            outputs.append(await self._convert_type(value, variable.type, variable.subtype, variable.format))
+                        output = outputs[0] if len(outputs) == 1 else outputs
                     else:
                         variable = workflow.output[0]
                         output = await self._convert_type(output, variable.type, variable.subtype, variable.format)
@@ -115,4 +119,9 @@ class GradioWebUIBuilder:
                 return await save_stream_to_temporary_file(value, subtype)
             return None
 
+        if type == "string":
+            if isinstance(value, (dict, list)):
+                return json.dumps(value)
+            return str(value)
+
         return value

{model_compose-0.1.0 → model_compose-0.1.1}/src/mindor/core/controller/webui/schema.py

@@ -26,7 +26,7 @@ class WorkflowVariableResolver:
                 key, path, type, subtype, format, default = match.group(1, 2, 3, 4, 5, 6)
 
                 if type and default:
-                    default = self._convert_type(default, type, subtype, format)
+                    default = self._parse_as_type(default, type)
 
                 if key == wanted_key:
                     variables.append((path, type or "string", subtype, format, default))
@@ -52,7 +52,7 @@ class WorkflowVariableResolver:
                 type, subtype, format, default = match.group(3, 4, 5, 6)
 
                 if type and default:
-                    default = self._convert_type(default, type, subtype, format)
+                    default = self._parse_as_type(default, type)
 
                 variables.append((key, type or "string", subtype, format, default))
             
@@ -67,12 +67,12 @@ class WorkflowVariableResolver:
         if isinstance(value, list):
             return sum([ self._enumerate_output_variables(f"{key}[{i}]" if key else f"[{i}]", v) for i, v in enumerate(value) ], [])
         
-        return []        
+        return []
 
-    def _convert_type(self, value: Any, type: str, subtype: str, format: Optional[str]) -> Any:
+    def _parse_as_type(self, value: Any, type: str) -> Any:
         if type == "number":
             return float(value)
-        
+
         if type == "integer":
             return int(value)
         

{model_compose-0.1.0 → model_compose-0.1.1}/src/mindor/core/controller/webui/webui.py

@@ -54,7 +54,8 @@ class ControllerWebUI(AsyncService):
         await self.server.serve()
     
     async def _shutdown(self) -> None:
-        self.server.should_exit = True
+        if self.server:
+            self.server.should_exit = True
     
     async def _run_workflow(self, workflow_id: Optional[str], input: Any) -> Any:
         return await self.runner.run_workflow(workflow_id, input)

{model_compose-0.1.0 → model_compose-0.1.1}/src/mindor/core/listener/engine/http_callback.py

@@ -109,7 +109,8 @@ class HttpCallbackListener(ListenerEngine):
         await self.server.serve()
  
     async def _shutdown(self) -> None:
-        self.server.should_exit = True
+        if self.server:
+            self.server.should_exit = True
 
     def _get_pending_future(self, id: str) -> Optional[asyncio.Future]:
         with _pending_futures_lock:

{model_compose-0.1.0 → model_compose-0.1.1}/src/mindor/core/utils/template.py

@@ -46,7 +46,7 @@ class TemplateRenderer:
             except Exception:
                 value = None
 
-            value = default if not value else value
+            value = default if value is None else value
 
             if type and value:
                 value = await self._convert_type(value, type, subtype, format)

{model_compose-0.1.0 → model_compose-0.1.1}/src/mindor/core/workflow/job.py

@@ -6,10 +6,10 @@ from .context import WorkflowContext
 import ulid
 
 class Job:
-    def __init__(self, id: str, config: JobConfig, component_provider: Callable[[Union[ComponentConfig, str]], ComponentEngine]):
+    def __init__(self, id: str, config: JobConfig, component_provider: Callable[[str, Union[ComponentConfig, str]], ComponentEngine]):
         self.id: str = id
         self.config: JobConfig = config
-        self.component_provider: Callable[[Union[ComponentConfig, str]], ComponentEngine] = component_provider
+        self.component_provider: Callable[[str, Union[ComponentConfig, str]], ComponentEngine] = component_provider
 
     async def run(self, context: WorkflowContext) -> Any:
         component: ComponentEngine = self.component_provider(self.id, self.config.component)
@@ -17,9 +17,17 @@ class Job:
         if not component.started:
             await component.start()
 
-        call_id = ulid.ulid()
         input = (await context.render_template(self.config.input)) if self.config.input else context.input
-        output = await component.run(self.config.action, call_id, input)
+        outputs = []
+
+        for _ in range(self.config.repeats):
+            call_id = ulid.ulid()
+            output = await component.run(self.config.action, call_id, input)
+            
+            if output:
+                outputs.append(output)
+
+        output = outputs[0] if len(outputs) == 1 else outputs or None
 
         if output:
             context.register_source("output", output)

{model_compose-0.1.0 → model_compose-0.1.1}/src/mindor/core/workflow/workflow.py

@@ -74,9 +74,9 @@ class WorkflowResolver:
         return default_ids[0] if default_ids else "__default__"
 
 class WorkflowRunner:
-    def __init__(self, jobs: Dict[str, JobConfig], component_provider: Callable[[Union[str, ComponentConfig, str]], ComponentEngine]):
+    def __init__(self, jobs: Dict[str, JobConfig], component_provider: Callable[[str, Union[ComponentConfig, str]], ComponentEngine]):
         self.jobs: Dict[str, JobConfig] = jobs
-        self.component_provider: Callable[[Union[str, ComponentConfig, str]], ComponentEngine] = component_provider
+        self.component_provider: Callable[[str, Union[ComponentConfig, str]], ComponentEngine] = component_provider
 
     async def run(self, context: WorkflowContext) -> Any:
         pending_jobs: Dict[str, Job] = { job_id: Job(job_id, job, self.component_provider) for job_id, job in self.jobs.items() }

{model_compose-0.1.0 → model_compose-0.1.1}/src/mindor/dsl/schema/workflow.py

@@ -5,11 +5,12 @@ from pydantic import model_validator
 from .component import ComponentConfig
 
 class JobConfig(BaseModel):
-    component: Optional[Union[ str, ComponentConfig ]] = "__default__"
-    action: Optional[str] = "__default__"
-    input: Optional[Any] = None
-    output: Optional[Any] = None
-    depends_on: Optional[List[str]] = Field(default_factory=list)
+    component: Optional[Union[str, 'ComponentConfig']] = Field(default="__default__", description="The component to execute. Can be a string identifier or a ComponentConfig object.")
+    action: Optional[str] = Field(default="__default__", description="The action to invoke within the component. Defaults to '__default__'.")
+    repeats: Optional[int] = Field(default=1, ge=1, description="Number of times to repeat the component execution. Must be at least 1.")
+    input: Optional[Any] = Field(default=None, description="The input data passed to the component. Can be of any type.")
+    output: Optional[Any] = Field(default=None, description="The expected output data from the component. Can be of any type.")
+    depends_on: Optional[List[str]] = Field(default_factory=list, description="List of job names that this job depends on. Ensures execution order.")
 
 class WorkflowVariableType(str, Enum):
     # Primitive data types

{model_compose-0.1.0 → model_compose-0.1.1}/src/model_compose.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: model-compose
-Version: 0.1.0
+Version: 0.1.1
 Summary: model-compose: Declarative AI Model and Workflow Orchestrator (part of the Mindor project)
 Author-email: Hanyeol Cho <hanyeol.cho@gmail.com>
 License-Expression: MIT
@@ -21,41 +21,28 @@ Requires-Dist: gradio
 Requires-Dist: Pillow
 Dynamic: license-file
 
-# model-compose: Declarative AI Model and Workflow Orchestrator (_part of the Mindor project_)
+# model-compose: Declarative AI Model and Workflow Orchestrator
 
 [![Python Version](https://img.shields.io/badge/python-3.9+-blue.svg)](https://python.org)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](http://makeapullrequest.com)
 
+![Screenshots](docs/images/screenshots.png)
+
 **model-compose** is an open-source, declarative workflow orchestrator inspired by `docker-compose`. It lets you define and run AI model pipelines using simple YAML files — no custom code required. Effortlessly connect external AI services or run local AI models, all within powerful, composable workflows.
 
 ---
 
 ## ✨ Features
 
-#### 🔧 Declarative by Design
-Define complete AI workflows using simple YAML files — no complex scripting required.
-
-#### 🔗 Compose Anything
-Combine multiple AI models, APIs, and tools into a single, unified pipeline.
-
-#### 🧠 Built for Orchestration
-Orchestrate multi-step model interactions with ease. Turn individual API calls into maintainable, end-to-end systems using **model-compose**.
-
-#### 🛠️ Multi-Workflow Support
-Define multiple named workflows in one project. Run them by name or set a default for quick execution.
-
-#### 🧩 Modular Components
-Break down logic into reusable components and jobs. Easily plug, swap, and extend them across workflows.
-
-#### ⚙️ Flexible I/O Routing
-Connect inputs and outputs between jobs using clean, scoped variables - no glue code needed.
-
-#### 🧪 Run Locally, Serve Remotely
-Execute workflows from the CLI or expose them as HTTP or MCP endpoints with an optional Web UI.
-
-#### 📦 Works with Environment Variables
-Easily inject secrets and configuration via `.env` files or environment variables to keep your YAML clean and secure.
+- **Declarative by Design:** Define complete AI workflows using simple YAML files—no complex scripting required.
+- **Compose Anything:** Combine multiple AI models, APIs, and tools into a single, unified pipeline.
+- **Built for Orchestration:**  Orchestrate multi-step model interactions with ease. Transform individual API calls into maintainable, end-to-end systems.
+- **Multi-Workflow Support:** Define multiple named workflows in one project. Run them by name or set a default for quick execution.
+- **Modular Components:** Break down logic into reusable components and jobs. Easily plug, swap, and extend them across workflows.
+- **Flexible I/O Routing:** Connect inputs and outputs between jobs using clean, scoped variables—no glue code needed.
+- **Run Locally, Serve Remotely:** Execute workflows from the CLI or expose them as HTTP or MCP endpoints with an optional Web UI.
+- **Environment Variable Support:** Easily inject secrets and configuration via `.env` files or environment variables to keep your YAML clean and secure.
 
 ---
 
@@ -214,14 +201,14 @@ listener:
   port: 8090
   base_path: /callbacks
   callbacks:
-    - path: /chatgpt
+    - path: /chat-ai
       method: POST
       item: ${body.data}
       identify_by: ${item.task_id}
       result: ${item.choices[0].message.content}
 ```
 
-This listener sets up an HTTP callback endpoint at `http://localhost:8090/callbacks/chatgpt` to receive asynchronous responses from a remote ChatGPT-compatible service. It extracts the incoming data from the request body, identifies the task using `task_id`, and stores the final message content from the first choice in the response.
+This listener sets up an HTTP callback endpoint at http://localhost:8090/callbacks/chat-ai to handle asynchronous responses from an external service that behaves like ChatGPT but supports delayed or push-based results. This is useful when integrating with services that notify results via webhook-style callbacks.
 
 #### 🌐 Gateway Example
 
@@ -234,7 +221,12 @@ gateway:
 
 This gateway configuration exposes the local listener defined above to the public internet using an HTTP tunnel powered by ngrok. It forwards incoming traffic from a secure, public URL (e.g., https://abc123.ngrok.io) directly to your local callback endpoint at http://localhost:8090. This is essential when integrating with third-party services that need to push data back to your workflow via webhooks or asynchronous callbacks.
 
-> 📁 For more example model-compose.yml configurations, check the samples directory in the source code.
+> 📁 For more example model-compose.yml configurations, check the [examples directory](examples) in the source code.
+
+---
+## 🏗 Architecture
+
+![Archtecture Diagram](docs/images/architecture-diagram.png)
 
 ---