pybotchi 3.2.0__tar.gz → 3.4.0__tar.gz

{pybotchi-3.2.0 → pybotchi-3.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pybotchi
-Version: 3.2.0
+Version: 3.4.0
 Summary: A deterministic, intent-based AI agent builder.
 License-File: LICENSE
 Author: Alexie (Boyong) Madolid

{pybotchi-3.2.0 → pybotchi-3.4.0}/pybotchi/action.py

@@ -6,7 +6,6 @@ from asyncio import TaskGroup
 from collections import deque
 from collections.abc import Generator
 from inspect import getmembers
-from itertools import islice
 from os import getenv
 from typing import Any, Generic, TYPE_CHECKING, TypeVar
 
@@ -19,7 +18,6 @@ from .common import (
     Graph,
     Groups,
     ToolCall,
-    UNSPECIFIED,
     UsageData,
 )
 from .utils import apply_placeholders, unwrap_exceptions, uuid
@@ -49,6 +47,29 @@ ${system}
 ${addons}
 """.strip(),
 )
+DEFAULT_MAX_ITERATION_PROMPT = getenv(
+    "DEFAULT_MAX_ITERATION_PROMPT",
+    """
+You are an AI assistant responsible for delivering the final response to the user.
+Your primary responsibility is to synthesize all prior tool calls and results from the conversation history into a clear, coherent, and complete response.
+
+# Finalization Guidelines:
+- Review the full conversation history, including all function calls made, their inputs, and their returned results.
+- Synthesize all gathered information into a single, well-structured final response.
+- Do NOT invoke any additional functions or tools — this is a finalization step only.
+- If the task was fully completed through prior iterations, summarize and present the results clearly.
+- If the task was only partially completed, clearly communicate:
+  - What was successfully accomplished.
+  - What could not be completed and why (e.g., iteration limit reached before all steps finished).
+  - Any actionable next steps the user can take.
+- If conflicting or incomplete data exists across iterations, use your best judgment to reconcile it and flag any uncertainty to the user.
+- Maintain the tone and context established in the original task.
+- Never expose raw function names, parameters, or internal tool output directly — always translate them into natural, user-friendly language.
+
+# Initial Task:
+${system}
+""".strip(),
+)
 
 TAction = TypeVar("TAction", bound="Action")
 TContext = TypeVar("TContext", bound="Context")
@@ -67,6 +88,7 @@ class Action(BaseModel, Generic[TContext]):
     __enabled__: bool = True
     __system_prompt__: str | None = None
     __tool_call_prompt__: str | None = None
+    __max_iteration_prompt__: str | None = None
     __temperature__: float | None = None
     __max_tool_prompts__: int | None = None
     __default_tool__ = DEFAULT_ACTION
@@ -75,6 +97,7 @@ class Action(BaseModel, Generic[TContext]):
 
     __has_pre__: bool
     __has_fallback__: bool
+    __has_on_child_init_error__: bool
     __has_on_error__: bool
     __has_post__: bool
     __has_as_tool__: bool
@@ -115,6 +138,7 @@ class Action(BaseModel, Generic[TContext]):
         cls.__display_name__ = src.get("__display_name__", cls.__name__)
         cls.__has_pre__ = cls.pre is not Action.pre
         cls.__has_fallback__ = cls.fallback is not Action.fallback
+        cls.__has_on_child_init_error__ = cls.on_child_init_error is not Action.on_child_init_error
         cls.__has_on_error__ = cls.on_error is not Action.on_error
         cls.__has_post__ = cls.post is not Action.post
         cls.__has_as_tool__ = cls._as_tool is not Action._as_tool
@@ -156,6 +180,16 @@ class Action(BaseModel, Generic[TContext]):
         """Execute fallback process."""
         return ActionReturn.GO
 
+    async def on_child_init_error(
+        self,
+        context: TContext,
+        next_actions: list["Action"],
+        child_cls: type[Action],
+        child_args: dict[str, Any],
+        exception: Exception,
+    ) -> str | None:
+        """Execute on child init error process."""
+
     async def on_error(
         self,
         context: TContext,
@@ -165,6 +199,49 @@ class Action(BaseModel, Generic[TContext]):
         """Execute on error process."""
         return ActionReturn.GO
 
+    async def on_max_iteration(self, context: TContext) -> ActionReturn:
+        """Execute on max iteration process."""
+        await context.notify(
+            {
+                "event": "tool",
+                "type": "finalize",
+                "status": "started",
+                "data": self.__display_name__,
+            }
+        )
+        llm = context.llm
+        if self.__temperature__ is not None:
+            llm = llm.with_config(configurable={"llm_temperature": self.__temperature__})
+
+        message = await llm.ainvoke(
+            [
+                {
+                    "content": self.max_iteration_prompt(context),
+                    "role": "system",
+                },
+                *context.shifted_prompts(self.__max_tool_prompts__),
+            ]
+        )
+
+        await context.add_usage(
+            self,
+            context.llm_model,
+            message.usage_metadata,
+            "$finalize",
+        )
+
+        await context.notify(
+            {
+                "event": "tool",
+                "type": "finalize",
+                "status": "completed",
+                "data": self.__display_name__,
+            }
+        )
+        await context.add_response(self, message.text)
+
+        return ActionReturn.GO
+
     async def post(self, context: TContext) -> ActionReturn:
         """Execute post process."""
         return ActionReturn.GO
@@ -183,6 +260,13 @@ class Action(BaseModel, Generic[TContext]):
             system=self.__system_prompt__ or context.prompts[0]["content"] or "Not defined",
         )
 
+    def max_iteration_prompt(self, context: TContext) -> str:
+        """Get max iteration prompt."""
+        return apply_placeholders(
+            self.__max_iteration_prompt__ or DEFAULT_MAX_ITERATION_PROMPT,
+            system=self.__system_prompt__ or context.prompts[0]["content"] or "Not defined",
+        )
+
     async def get_child_actions(self, context: TContext) -> ChildActions:
         """Retrieve child Actions."""
         return {
@@ -204,35 +288,46 @@ class Action(BaseModel, Generic[TContext]):
         llm = context.llm.bind_tools(
             [await child._as_tool(context) if child.__has_as_tool__ else child for child in child_actions.values()],
             tool_choice=tool_choice,
+            parallel_tool_calls=not self.__first_tool_only__,
         )
         if self.__temperature__ is not None:
             llm = llm.with_config(configurable={"llm_temperature": self.__temperature__})
 
-        max = len(context.prompts)
-        if self.__max_tool_prompts__:
-            min = max - self.__max_tool_prompts__
-            min = 1 if min < 1 else min
-        else:
-            min = 1
-
         message = await llm.ainvoke(
             [
                 {
                     "content": self.child_selection_prompt(context, tool_choice),
                     "role": "system",
                 },
-                *islice(context.prompts, min, max),
+                *context.shifted_prompts(self.__max_tool_prompts__),
             ]
         )
         await context.add_usage(
             self,
-            context.llm.model_name,
+            context.llm_model,
             message.usage_metadata,
             "$tool",
         )
 
-        next_actions = [child_actions[call["name"]](**call["args"]) for call in message.tool_calls]
-
+        next_actions: list[Action] = []
+        for call in message.tool_calls:
+            child_action = child_actions[call["name"]]
+            try:
+                next_actions.append(child_action(**call["args"]))
+            except Exception as error:
+                if self.__has_on_child_init_error__:
+                    if (
+                        error_message := await self.on_child_init_error(
+                            context,
+                            next_actions,
+                            child_action,
+                            call["args"],
+                            error,
+                        )
+                    ) is not None:
+                        return [], error_message
+                else:
+                    raise error
         return next_actions, message.text
 
     async def execute(self, context: TContext, parent: Action | None = None, append: bool = True) -> ActionReturn:
@@ -254,11 +349,14 @@ class Action(BaseModel, Generic[TContext]):
 
             if self.__max_child_iteration__:
                 iteration = 0
-                while iteration <= self.__max_child_iteration__:
+                while iteration < self.__max_child_iteration__:
                     if (result := await self.execution(context)).is_break:
                         break
                     iteration += 1
-                if result.is_end:
+                if result.is_end or (
+                    iteration >= self.__max_child_iteration__
+                    and (result := await self.on_max_iteration(context)).is_break
+                ):
                     return result
             elif (result := await self.execution(context)).is_break:
                 return result
@@ -355,15 +453,7 @@ class Action(BaseModel, Generic[TContext]):
 
             await context.add_usage(
                 self,
-                getattr(
-                    context.llm,
-                    "model_name",
-                    getattr(
-                        context.llm,
-                        "deployment_name",
-                        UNSPECIFIED,
-                    ),
-                ),
+                context.llm_model,
                 message.usage_metadata,
                 "$fallback",
             )
@@ -501,7 +591,7 @@ async def graph(action: type[Action], allowed_actions: dict[str, bool] | None =
     """Retrieve Graph."""
     origin = f"{action.__module__}.{action.__qualname__}"
     await traverse(
-        graph := Graph(origin=origin, nodes={origin}),
+        graph := Graph(origin=origin, nodes={origin}, edges=set()),
         action,
         allowed_actions,
     )

{pybotchi-3.2.0 → pybotchi-3.4.0}/pybotchi/action.pyi

@@ -1,4 +1,4 @@
-from .common import ActionEntry as ActionEntry, ActionReturn as ActionReturn, ConcurrentBreakPoint as ConcurrentBreakPoint, Graph as Graph, Groups as Groups, ToolCall as ToolCall, UNSPECIFIED as UNSPECIFIED, UsageData as UsageData
+from .common import ActionEntry as ActionEntry, ActionReturn as ActionReturn, ConcurrentBreakPoint as ConcurrentBreakPoint, Graph as Graph, Groups as Groups, ToolCall as ToolCall, UsageData as UsageData
 from .context import Context as Context
 from .utils import apply_placeholders as apply_placeholders, unwrap_exceptions as unwrap_exceptions, uuid as uuid
 from _typeshed import Incomplete
@@ -8,6 +8,7 @@ from typing import Any, Generic, TypeVar
 
 DEFAULT_ACTION: Incomplete
 DEFAULT_TOOL_CALL_PROMPT: Incomplete
+DEFAULT_MAX_ITERATION_PROMPT: Incomplete
 TAction = TypeVar('TAction', bound='Action')
 TContext = TypeVar('TContext', bound='Context')
 T = TypeVar('T')
@@ -17,6 +18,7 @@ class Action(BaseModel, Generic[TContext]):
     __enabled__: bool
     __system_prompt__: str | None
     __tool_call_prompt__: str | None
+    __max_iteration_prompt__: str | None
     __temperature__: float | None
     __max_tool_prompts__: int | None
     __default_tool__ = DEFAULT_ACTION
@@ -24,6 +26,7 @@ class Action(BaseModel, Generic[TContext]):
     __concurrent__: bool
     __has_pre__: bool
     __has_fallback__: bool
+    __has_on_child_init_error__: bool
     __has_on_error__: bool
     __has_post__: bool
     __has_as_tool__: bool
@@ -41,10 +44,13 @@ class Action(BaseModel, Generic[TContext]):
     def __init_child_actions__(cls) -> None: ...
     async def pre(self, context: TContext) -> ActionReturn: ...
     async def fallback(self, context: TContext, content: str) -> ActionReturn: ...
+    async def on_child_init_error(self, context: TContext, next_actions: list['Action'], child_cls: type[Action], child_args: dict[str, Any], exception: Exception) -> str | None: ...
     async def on_error(self, context: TContext, exception: Exception, unwrapped_exceptions: Generator[Exception, None, None]) -> ActionReturn: ...
+    async def on_max_iteration(self, context: TContext) -> ActionReturn: ...
     async def post(self, context: TContext) -> ActionReturn: ...
     async def commit_context(self, parent: TContext, child: TContext) -> None: ...
     def child_selection_prompt(self, context: TContext, tool_choice: str) -> str: ...
+    def max_iteration_prompt(self, context: TContext) -> str: ...
     async def get_child_actions(self, context: TContext) -> ChildActions: ...
     async def child_selection(self, context: TContext, child_actions: ChildActions | None = None) -> tuple[list['Action'], str]: ...
     async def execute(self, context: TContext, parent: Action | None = None, append: bool = True) -> ActionReturn: ...

{pybotchi-3.2.0 → pybotchi-3.4.0}/pybotchi/context.py

@@ -1,7 +1,7 @@
 """Pybotchi Context."""
 
 from asyncio import Future, get_event_loop, new_event_loop
-from collections.abc import Callable, Coroutine, Iterable
+from collections.abc import Callable, Coroutine, Iterable, Iterator
 from concurrent.futures import Executor
 from copy import deepcopy
 from functools import cached_property, partial
@@ -41,6 +41,30 @@ class Context(BaseModel, Generic[TLLM]):
         """Get base LLM."""
         return LLM.base()
 
+    @cached_property
+    def llm_model(self) -> str:
+        """Get base LLM Model."""
+        return getattr(
+            self.llm,
+            "model_name",
+            getattr(
+                self.llm,
+                "deployment_name",
+                UNSPECIFIED,
+            ),
+        )
+
+    def shifted_prompts(self, offset: int | None) -> Iterator[dict[str, Any]]:
+        """Get shifted prompts."""
+        max = len(self.prompts)
+        if offset:
+            min = max - offset
+            min = 1 if min < 1 else min
+        else:
+            min = 1
+
+        return islice(self.prompts, min, max)
+
     async def start(self, action: type[TAction], /, **kwargs: Any) -> tuple[TAction, ActionReturn]:
         """Start Action."""
         if not self.prompts or self.prompts[0]["role"] != ChatRole.SYSTEM:

{pybotchi-3.2.0 → pybotchi-3.4.0}/pybotchi/context.pyi

@@ -2,7 +2,7 @@ from .action import Action as Action, ActionReturn as ActionReturn, T as T, TAct
 from .common import ChatRole as ChatRole, ToolCall as ToolCall, UNSPECIFIED as UNSPECIFIED, UsageMetadata as UsageMetadata
 from .llm import LLM as LLM
 from asyncio import Future
-from collections.abc import Callable as Callable, Coroutine
+from collections.abc import Callable as Callable, Coroutine, Iterator
 from concurrent.futures import Executor
 from functools import cached_property as cached_property
 from langchain_core.language_models.chat_models import BaseChatModel
@@ -24,6 +24,9 @@ class Context(BaseModel, Generic[TLLM]):
     parent: Self | None
     @cached_property
     def llm(self) -> TLLM: ...
+    @cached_property
+    def llm_model(self) -> str: ...
+    def shifted_prompts(self, offset: int | None) -> Iterator[dict[str, Any]]: ...
     async def start(self, action: type[TAction], /, **kwargs: Any) -> tuple[TAction, ActionReturn]: ...
     def check_self_recursion(self, action: Action) -> bool: ...
     async def merge_to_usages(self, model: str, usage: UsageMetadata) -> None: ...

{pybotchi-3.2.0 → pybotchi-3.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "pybotchi"
-version = "3.2.0"
+version = "3.4.0"
 description = "A deterministic, intent-based AI agent builder."
 authors = ["Alexie (Boyong) Madolid <madolid.alexie@gmail.com>"]
 readme = "README.md"
@@ -31,13 +31,13 @@ grpcio-tools = { version = ">=1.76.0", optional = true }
 aiofiles = { version = ">=25.1.0", optional = true }
 
 [tool.poetry.group.dev.dependencies]
-python-dotenv = "1.1.1"
-mypy = "1.19.1"
-ruff = "0.14.10"
-pre-commit = "4.5.1"
-types-protobuf = "6.32.1.20251105"
-types-aiofiles = "25.1.0.20251011"
-mypy-protobuf = "4.0.0"
+python-dotenv = "1.2.2"
+mypy = "2.1.0"
+ruff = "0.15.13"
+pre-commit = "4.6.0"
+types-protobuf = "7.34.1.20260518"
+types-aiofiles = "25.1.0.20260518"
+mypy-protobuf = "5.1.0"
 
 # for examples
 langchain-openai = ">=0.3.15"