zrb 1.5.2__tar.gz → 1.5.4__tar.gz

{zrb-1.5.2 → zrb-1.5.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: zrb
-Version: 1.5.2
+Version: 1.5.4
 Summary: Your Automation Powerhouse
 Home-page: https://github.com/state-alchemists/zrb
 License: AGPL-3.0-or-later
@@ -26,7 +26,7 @@ Requires-Dist: openai (>=1.70.0,<2.0.0) ; extra == "rag" or extra == "all"
 Requires-Dist: pdfplumber (>=0.11.6,<0.12.0) ; extra == "rag" or extra == "all"
 Requires-Dist: playwright (>=1.51.0,<2.0.0) ; extra == "playwright" or extra == "all"
 Requires-Dist: psutil (>=7.0.0,<8.0.0)
-Requires-Dist: pydantic-ai (>=0.0.49,<0.0.50)
+Requires-Dist: pydantic-ai (>=0.0.52,<0.0.53)
 Requires-Dist: python-dotenv (>=1.1.0,<2.0.0)
 Requires-Dist: python-jose[cryptography] (>=3.4.0,<4.0.0)
 Requires-Dist: requests (>=2.32.3,<3.0.0)

{zrb-1.5.2 → zrb-1.5.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "zrb"
-version = "1.5.2"
+version = "1.5.4"
 description = "Your Automation Powerhouse"
 authors = ["Go Frendi Gunawan <gofrendiasgard@gmail.com>"]
 license = "AGPL-3.0-or-later"
@@ -49,7 +49,7 @@ beautifulsoup4 = "^4.13.3"
 fastapi = {extras = ["standard"], version = "^0.115.12"}
 python-jose = {extras = ["cryptography"], version = "^3.4.0"}
 ulid-py = "^1.1.0"
-pydantic-ai = "^0.0.49"
+pydantic-ai = "^0.0.52"
 openai = {version = "^1.70.0", optional = true}
 playwright = {version = "^1.51.0", optional = true}
 psutil = "^7.0.0"

zrb-1.5.4/src/zrb/builtin/project/add/fastapp/fastapp_template/my_app_name/README.md

@@ -0,0 +1,129 @@
+# My App Name
+
+Welcome to My App Name! This application is designed to help you start your project with a flexible architecture that can scale as your needs grow. My App Name supports both monolithic and microservices architectures, allowing you to start small and expand without rewriting your codebase.
+
+## Key Features
+
+- **Modular-Monolith Architecture**: My App Name is built with a modular-monolith architecture, providing a clean interface for inter-module communication. This allows you to run My App Name as a monolith or as microservices without altering your code.
+
+- **Low Coupling, High Cohesion**: The architecture ensures low coupling and high cohesion, making it easy to split your code into microservices when needed.
+
+## How It Works
+
+### Inter-Module Communication
+
+Each module in My App Name is independent and communicates with others through a `Client` object. The `Client` is an interface with two implementations: `ApiClient` and `DirectClient`.
+
+- **ApiClient**: Used when running My App Name as microservices. It communicates over HTTP using a base URL.
+- **DirectClient**: Used when running My App Name as a monolith. It allows direct method calls between modules.
+
+### Code Examples
+
+Here's how you can use the `as_api_client` and `as_direct_client` methods:
+
+```python
+# Using as_api_client
+from my_app_name.config import APP_AUTH_BASE_URL
+from my_app_name.module.auth.service.permission.permission_service_factory import permission_service
+
+# Create an API client for the permission service
+permission_api_client = permission_service.as_api_client(base_url=APP_AUTH_BASE_URL)
+
+# Using as_direct_client
+from my_app_name.module.auth.service.role.role_service_factory import role_service
+
+# Create a direct client for the role service
+role_direct_client = role_service.as_direct_client()
+```
+## Application Architecture
+
+My App Name follows a modular-monolith architecture. Each module (e.g., Auth, Library) encapsulates a specific business capability. The Gateway module acts as the entry point for user interactions (e.g., web UI).
+
+**Communication Modes:**
+
+1.  **Monolith (Direct Communication):**
+    ```
+    +---------+       +---------+
+    | Gateway | ----> |  Auth   |  (e.g., for login, permission checks)
+    | (UI)    |       | Service |
+    +---------+       +---------+
+        |                 ^
+        |                 | (Library might call Auth for specific checks)
+        |                 |
+        v                 |
+    +---------+ -----------+
+    | Library |
+    | Service |
+    +---------+
+     (Gateway also calls Library directly)
+     (DirectClient calls between services if needed)
+    ```
+    Modules communicate directly via `DirectClient` implementations. The Gateway calls necessary services, and services can call each other directly if required.
+
+2.  **Microservices (API Communication):**
+    ```
+    +---------+       +---------+
+    | Gateway | ----> |  Auth   |  (e.g., via Auth API)
+    | (UI)    |       | Service |
+    |         |       | (API)   |
+    +---------+       +---------+
+        |                 ^
+        |                 | (Library Service might call Auth API)
+        |                 |
+        v                 |
+    +---------+ -----------+
+    | Library |
+    | Service |
+    | (API)   |
+    +---------+
+     (Gateway also calls Library API)
+     (ApiClient calls via HTTP between services if needed)
+    ```
+    Modules communicate via `ApiClient` implementations over HTTP/API calls. The Gateway calls necessary service APIs, and services can call each other's APIs if required.
+
+## Factory Pattern
+
+The application utilizes the Factory pattern extensively, particularly for creating client, service, and repository instances. This allows the application to switch between different implementations based on configuration settings.
+
+**Example (`my_app_name/module/auth/client/auth_client_factory.py`):**
+
+```python
+from my_app_name.config import APP_COMMUNICATION
+from my_app_name.module.auth.client.auth_api_client import AuthAPIClient
+from my_app_name.module.auth.client.auth_client import AuthClient
+from my_app_name.module.auth.client.auth_direct_client import AuthDirectClient
+
+# Selects the client based on the configuration
+if APP_COMMUNICATION == "direct":
+    auth_client: AuthClient = AuthDirectClient()  # Used in Monolith mode
+elif APP_COMMUNICATION == "api":
+    auth_client: AuthClient = AuthAPIClient()      # Used in Microservices mode
+```
+
+By changing the `APP_COMMUNICATION` variable in `my_app_name/config.py`, you can switch how modules communicate without changing the core module logic. Similar factories exist for services and repositories (e.g., switching between database and in-memory implementations based on `APP_REPOSITORY_TYPE`).
+
+## Key Folders and Files
+
+-   `my_app_name/config.py`: Central configuration file (database connections, communication mode, etc.).
+-   `my_app_name/main.py`: Main application entry point.
+-   `my_app_name/common/`: Shared utilities, base classes (e.g., `app_factory.py`, `base_service.py`).
+-   `my_app_name/module/`: Contains the application modules (e.g., `auth`, `library`, `gateway`).
+    -   `my_app_name/module/<module_name>/`: Each module directory typically contains:
+        -   `client/`: Client interfaces (`*_client.py`, `*_api_client.py`, `*_direct_client.py`) and factories (`*_client_factory.py`).
+        -   `service/`: Business logic implementation (`*_service.py`) and factories (`*_service_factory.py`).
+        -   `repository/`: Data access logic (`*_repository.py`, `*_db_repository.py`) and factories (`*_repository_factory.py`).
+        -   `route.py`: API or UI routes for the module.
+        -   `schema/`: Data transfer objects or database models (if applicable).
+        -   `migration/`: Database migration scripts (if using Alembic).
+-   `my_app_name/schema/`: Shared data schemas used across modules.
+-   `my_app_name/test/`: Unit and integration tests.
+-   `my_app_name/_zrb/`: Tooling scripts (likely for code generation or automation).
+
+
+## Principles
+
+- Developers should be able to override everything with a reasonable amount of code.
+- Simple tasks should only require a small amount of code.
+- A bit of magic is okay as long as it's transparent and documented.
+
+For more details, refer to the client implementations in `module/auth/client/auth_api_client.py` and `module/auth/client/auth_direct_client.py`.

{zrb-1.5.2 → zrb-1.5.4}/src/zrb/llm_config.py

@@ -38,27 +38,27 @@ class LLMConfig:
         default_persona: str | None = None,
         default_system_prompt: str | None = None,
     ):
-        self._model_name = (
+        self._default_model_name = (
             default_model_name
             if default_model_name is not None
             else os.getenv("ZRB_LLM_MODEL", None)
         )
-        self._model_base_url = (
+        self._default_model_base_url = (
             default_base_url
             if default_base_url is not None
             else os.getenv("ZRB_LLM_BASE_URL", None)
         )
-        self._model_api_key = (
+        self._default_model_api_key = (
             default_api_key
             if default_api_key is not None
             else os.getenv("ZRB_LLM_API_KEY", None)
         )
-        self._system_prompt = (
+        self._default_system_prompt = (
             default_system_prompt
             if default_system_prompt is not None
             else os.getenv("ZRB_LLM_SYSTEM_PROMPT", None)
         )
-        self._persona = (
+        self._default_persona = (
             default_persona
             if default_persona is not None
             else os.getenv("ZRB_LLM_PERSONA", None)
@@ -67,24 +67,28 @@ class LLMConfig:
         self._default_model = None
 
     def _get_model_name(self) -> str | None:
-        return self._model_name if self._model_name is not None else None
+        return (
+            self._default_model_name if self._default_model_name is not None else None
+        )
 
     def get_default_model_provider(self) -> Provider | str:
         if self._default_provider is not None:
             return self._default_provider
-        if self._model_base_url is None and self._model_api_key is None:
+        if self._default_model_base_url is None and self._default_model_api_key is None:
             return "openai"
         return OpenAIProvider(
-            base_url=self._model_base_url, api_key=self._model_api_key
+            base_url=self._default_model_base_url, api_key=self._default_model_api_key
         )
 
     def get_default_system_prompt(self) -> str:
         system_prompt = (
             DEFAULT_SYSTEM_PROMPT
-            if self._system_prompt is None
-            else self._system_prompt
+            if self._default_system_prompt is None
+            else self._default_system_prompt
+        )
+        persona = (
+            DEFAULT_PERSONA if self._default_persona is None else self._default_persona
         )
-        persona = DEFAULT_PERSONA if self._persona is None else self._persona
         if persona is not None:
             return f"{persona}\n{system_prompt}"
         return system_prompt
@@ -100,17 +104,20 @@ class LLMConfig:
             provider=self.get_default_model_provider(),
         )
 
+    def set_default_persona(self, persona: str):
+        self._default_persona = persona
+
     def set_default_system_prompt(self, system_prompt: str):
-        self._system_prompt = system_prompt
+        self._default_system_prompt = system_prompt
 
     def set_default_model_name(self, model_name: str):
-        self._model_name = model_name
+        self._default_model_name = model_name
 
     def set_default_model_api_key(self, model_api_key: str):
-        self._model_api_key = model_api_key
+        self._default_model_api_key = model_api_key
 
     def set_default_model_base_url(self, model_base_url: str):
-        self._model_base_url = model_base_url
+        self._default_model_base_url = model_base_url
 
     def set_default_provider(self, provider: Provider | str):
         self._default_provider = provider

{zrb-1.5.2 → zrb-1.5.4}/src/zrb/task/base_task.py

@@ -1,6 +1,6 @@
 import asyncio
 import os
-from collections.abc import Callable
+from collections.abc import Callable, Coroutine
 from typing import Any
 
 from zrb.attr.type import BoolAttr, fstring
@@ -64,7 +64,7 @@ class BaseTask(AnyTask):
     def __repr__(self):
         return f"<{self.__class__.__name__} name={self._name}>"
 
-    def __rshift__(self, other: AnyTask | list[AnyTask]) -> AnyTask:
+    def __rshift__(self, other: AnyTask | list[AnyTask]) -> AnyTask | list[AnyTask]:
         try:
             if isinstance(other, AnyTask):
                 other.append_upstream(self)
@@ -123,7 +123,9 @@ class BaseTask(AnyTask):
         return [task_input for task_input in inputs if task_input is not None]
 
     def __combine_inputs(
-        self, inputs: list[AnyInput], other_inputs: list[AnyInput] | AnyInput
+        self,
+        inputs: list[AnyInput],
+        other_inputs: list[AnyInput | None] | AnyInput | None,
     ):
         input_names = [task_input.name for task_input in inputs]
         if isinstance(other_inputs, AnyInput):
@@ -429,7 +431,7 @@ class BaseTask(AnyTask):
             session.get_task_status(self).reset()
             # defer this action
             ctx.log_info("Running")
-            action_coro = asyncio.create_task(
+            action_coro: Coroutine = asyncio.create_task(
                 run_async(self.__exec_action_and_retry(session))
             )
             session.defer_action(self, action_coro)

{zrb-1.5.2 → zrb-1.5.4}/src/zrb/task/llm_task.py

@@ -1,4 +1,3 @@
-import copy
 import functools
 import inspect
 import json
@@ -9,6 +8,7 @@ from typing import Any
 
 from openai import APIError
 from pydantic_ai import Agent, Tool
+from pydantic_ai.mcp import MCPServer
 from pydantic_ai.messages import (
     FinalResultEvent,
     FunctionToolCallEvent,
@@ -54,9 +54,9 @@ class LLMTask(BaseTask):
             Callable[[AnySharedContext], Model | str | fstring] | Model | None
         ) = None,
         render_model: bool = True,
-        model_base_url: StrAttr = None,
+        model_base_url: StrAttr | None = None,
         render_model_base_url: bool = True,
-        model_api_key: StrAttr = None,
+        model_api_key: StrAttr | None = None,
         render_model_api_key: bool = True,
         model_settings: (
             ModelSettings | Callable[[AnySharedContext], ModelSettings] | None
@@ -68,6 +68,9 @@ class LLMTask(BaseTask):
         tools: (
             list[ToolOrCallable] | Callable[[AnySharedContext], list[ToolOrCallable]]
         ) = [],
+        mcp_servers: (
+            list[MCPServer] | Callable[[AnySharedContext], list[MCPServer]]
+        ) = [],
         conversation_history: (
             ListOfDict | Callable[[AnySharedContext], ListOfDict]
         ) = [],
@@ -127,6 +130,8 @@ class LLMTask(BaseTask):
         self._message = message
         self._tools = tools
         self._additional_tools: list[ToolOrCallable] = []
+        self._mcp_servers = mcp_servers
+        self._additional_mcp_servers: list[MCPServer] = []
         self._conversation_history = conversation_history
         self._conversation_history_reader = conversation_history_reader
         self._conversation_history_writer = conversation_history_writer
@@ -137,32 +142,36 @@ class LLMTask(BaseTask):
     def add_tool(self, tool: ToolOrCallable):
         self._additional_tools.append(tool)
 
+    def add_mcp_server(self, mcp_server: MCPServer):
+        self._additional_mcp_servers.append(mcp_server)
+
     async def _exec_action(self, ctx: AnyContext) -> Any:
         history = await self._read_conversation_history(ctx)
         user_prompt = self._get_message(ctx)
         agent = self._get_agent(ctx)
         try:
-            async with agent.iter(
-                user_prompt=user_prompt,
-                message_history=ModelMessagesTypeAdapter.validate_python(history),
-            ) as agent_run:
-                async for node in agent_run:
-                    # Each node represents a step in the agent's execution
-                    # Reference: https://ai.pydantic.dev/agents/#streaming
-                    try:
-                        await self._print_node(ctx, agent_run, node)
-                    except APIError as e:
-                        # Extract detailed error information from the response
-                        error_details = _extract_api_error_details(e)
-                        ctx.log_error(f"API Error: {error_details}")
-                        raise
-                    except Exception as e:
-                        ctx.log_error(f"Error processing node: {str(e)}")
-                        ctx.log_error(f"Error type: {type(e).__name__}")
-                        raise
-                new_history = json.loads(agent_run.result.all_messages_json())
-                await self._write_conversation_history(ctx, new_history)
-                return agent_run.result.data
+            async with agent.run_mcp_servers():
+                async with agent.iter(
+                    user_prompt=user_prompt,
+                    message_history=ModelMessagesTypeAdapter.validate_python(history),
+                ) as agent_run:
+                    async for node in agent_run:
+                        # Each node represents a step in the agent's execution
+                        # Reference: https://ai.pydantic.dev/agents/#streaming
+                        try:
+                            await self._print_node(ctx, agent_run, node)
+                        except APIError as e:
+                            # Extract detailed error information from the response
+                            error_details = _extract_api_error_details(e)
+                            ctx.log_error(f"API Error: {error_details}")
+                            raise
+                        except Exception as e:
+                            ctx.log_error(f"Error processing node: {str(e)}")
+                            ctx.log_error(f"Error type: {type(e).__name__}")
+                            raise
+                    new_history = json.loads(agent_run.result.all_messages_json())
+                    await self._write_conversation_history(ctx, new_history)
+                    return agent_run.result.data
         except Exception as e:
             ctx.log_error(f"Error in agent execution: {str(e)}")
             raise
@@ -277,10 +286,15 @@ class LLMTask(BaseTask):
             tool if isinstance(tool, Tool) else Tool(_wrap_tool(tool), takes_ctx=False)
             for tool in tools_or_callables
         ]
+        mcp_servers = list(
+            self._mcp_servers(ctx) if callable(self._mcp_servers) else self._mcp_servers
+        )
+        mcp_servers.extend(self._additional_mcp_servers)
         return Agent(
             self._get_model(ctx),
             system_prompt=self._get_system_prompt(ctx),
             tools=tools,
+            mcp_servers=mcp_servers,
             model_settings=self._get_model_settings(ctx),
             retries=3,
         )

zrb-1.5.2/src/zrb/builtin/project/add/fastapp/fastapp_template/my_app_name/README.md

@@ -1,7 +0,0 @@
-# App Name
-
-# Principle
-
-- Developer should be able to override everything with sane amount of code.
-- Simple tasks should only require small amount of code.
-- A bit of magic is okay as long as transparent and documented.