fabricatio 0.2.7.dev4__cp312-cp312-win_amd64.whl → 0.2.8__cp312-cp312-win_amd64.whl

fabricatio/models/kwargs_types.py

@@ -1,7 +1,7 @@
 """This module contains the types for the keyword arguments of the methods in the models module."""
 
 from importlib.util import find_spec
-from typing import Any, Dict, Required, TypedDict
+from typing import Any, Dict, List, Optional, Required, TypedDict
 
 from litellm.caching.caching import CacheMode
 from litellm.types.caching import CachingSupportedCallTypes
@@ -95,11 +95,30 @@ class ValidateKwargs[T](GenerateKwargs, total=False):
     such as limiting the number of validation attempts.
     """
 
-    default: T
+    default: Optional[T]
     max_validations: int
     co_extractor: GenerateKwargs
 
 
+class CompositeScoreKwargs(ValidateKwargs[List[Dict[str, float]]], total=False):
+    """Arguments for composite score generation operations.
+
+    Extends GenerateKwargs with parameters for generating composite scores
+    based on specific criteria and weights.
+    """
+
+    topic: str
+    criteria: set[str]
+    weights: Dict[str, float]
+    manual: Dict[str, str]
+
+
+class BestKwargs(CompositeScoreKwargs, total=False):
+    """Arguments for choose top-k operations."""
+
+    k: int
+
+
 class ReviewInnerKwargs[T](ValidateKwargs[T], total=False):
     """Arguments for content review operations."""
 
@@ -118,22 +137,9 @@ class ReviewKwargs[T](ReviewInnerKwargs[T], total=False):
     topic: Required[str]
 
 
-class CorrectKwargs[T](ReviewKwargs[T], total=False):
-    """Arguments for content correction operations.
-
-    Extends GenerateKwargs with parameters for correcting content based on
-    specific criteria and templates.
-    """
-
-    reference: str
-    supervisor_check: bool
-
-
-class CensoredCorrectKwargs[T](ReviewInnerKwargs[T], total=False):
-    """Arguments for content censorship operations."""
-
+class ReferencedKwargs[T](ValidateKwargs[T], total=False):
+    """Arguments for content review operations."""
     reference: str
-    supervisor_check: bool
 
 
 # noinspection PyTypedDict

fabricatio/models/role.py

@@ -8,11 +8,12 @@ from fabricatio.core import env
 from fabricatio.journal import logger
 from fabricatio.models.action import WorkFlow
 from fabricatio.models.events import Event
+from fabricatio.models.generic import WithBriefing
 from fabricatio.models.tool import ToolBox
 from pydantic import Field
 
 
-class Role(ProposeTask, HandleTask, Correct):
+class Role(WithBriefing, ProposeTask, HandleTask, Correct):
     """Class that represents a role with a registry of events and workflows.
 
     A Role serves as a container for workflows, managing their registration to events
@@ -22,6 +23,8 @@ class Role(ProposeTask, HandleTask, Correct):
         registry: Mapping of events to workflows that handle them
         toolboxes: Set of toolboxes available to this role and its workflows
     """
+    description:str =""
+    """A brief description of the role's responsibilities and capabilities."""
 
     registry: dict[Event | str, WorkFlow] = Field(default_factory=dict)
     """The registry of events and workflows."""

fabricatio/models/task.py

@@ -6,13 +6,13 @@ It includes methods to manage the task's lifecycle, such as starting, finishing,
 from asyncio import Queue
 from typing import Any, List, Optional, Self
 
-from fabricatio._rust_instances import TEMPLATE_MANAGER
 from fabricatio.config import configs
 from fabricatio.core import env
 from fabricatio.journal import logger
 from fabricatio.models.events import Event, EventLike
 from fabricatio.models.generic import ProposedAble, WithBriefing, WithDependency
 from fabricatio.models.utils import TaskStatus
+from fabricatio.rust_instances import TEMPLATE_MANAGER
 from pydantic import Field, PrivateAttr
 
 

fabricatio/models/tool.py

@@ -1,4 +1,8 @@
-"""A module for defining tools and toolboxes."""
+"""A module for defining tools and toolboxes.
+
+This module provides classes for defining tools and toolboxes, which can be used to manage and execute callable functions
+with additional functionalities such as logging, execution info, and briefing.
+"""
 
 from importlib.machinery import ModuleSpec
 from importlib.util import module_from_spec
@@ -14,7 +18,16 @@ from pydantic import BaseModel, ConfigDict, Field
 
 
 class Tool[**P, R](WithBriefing):
-    """A class representing a tool with a callable source function."""
+    """A class representing a tool with a callable source function.
+
+    This class encapsulates a callable function (source) and provides methods to invoke it, log its execution, and generate
+    a brief description (briefing) of the tool.
+
+    Attributes:
+        name (str): The name of the tool.
+        description (str): The description of the tool.
+        source (Callable[P, R]): The source function of the tool.
+    """
 
     name: str = Field(default="")
     """The name of the tool."""
@@ -26,7 +39,16 @@ class Tool[**P, R](WithBriefing):
     """The source function of the tool."""
 
     def model_post_init(self, __context: Any) -> None:
-        """Initialize the tool with a name and a source function."""
+        """Initialize the tool with a name and a source function.
+
+        This method sets the tool's name and description based on the source function's name and docstring.
+
+        Args:
+            __context (Any): Context passed during model initialization.
+
+        Raises:
+            RuntimeError: If the tool does not have a source function.
+        """
         self.name = self.name or self.source.__name__
 
         if not self.name:
@@ -36,7 +58,17 @@ class Tool[**P, R](WithBriefing):
         self.description = self.description.strip()
 
     def invoke(self, *args: P.args, **kwargs: P.kwargs) -> R:
-        """Invoke the tool's source function with the provided arguments."""
+        """Invoke the tool's source function with the provided arguments.
+
+        This method logs the invocation of the tool and then calls the source function with the given arguments.
+
+        Args:
+            *args (P.args): Positional arguments to be passed to the source function.
+            **kwargs (P.kwargs): Keyword arguments to be passed to the source function.
+
+        Returns:
+            R: The result of the source function.
+        """
         logger.info(f"Invoking tool: {self.name}")
         return self.source(*args, **kwargs)
 
@@ -44,6 +76,8 @@ class Tool[**P, R](WithBriefing):
     def briefing(self) -> str:
         """Return a brief description of the tool.
 
+        This method generates a brief description of the tool, including its name, signature, and description.
+
         Returns:
             str: A brief description of the tool.
         """
@@ -59,7 +93,18 @@ def _desc_wrapper(desc: str) -> str:
 
 
 class ToolBox(WithBriefing):
-    """A class representing a collection of tools."""
+    """A class representing a collection of tools.
+
+    This class manages a list of tools and provides methods to add tools, retrieve tools by name, and generate a brief
+    description (briefing) of the toolbox.
+
+    Attributes:
+        description (str): The description of the toolbox.
+        tools (List[Tool]): A list of tools in the toolbox.
+    """
+
+    description: str = ""
+    """The description of the toolbox."""
 
     tools: List[Tool] = Field(default_factory=list, frozen=True)
     """A list of tools in the toolbox."""
@@ -67,6 +112,8 @@ class ToolBox(WithBriefing):
     def collect_tool[**P, R](self, func: Callable[P, R]) -> Callable[P, R]:
         """Add a callable function to the toolbox as a tool.
 
+        This method wraps the function with logging execution info and adds it to the toolbox.
+
         Args:
             func (Callable[P, R]): The function to be added as a tool.
 
@@ -79,6 +126,8 @@ class ToolBox(WithBriefing):
     def add_tool[**P, R](self, func: Callable[P, R]) -> Self:
         """Add a callable function to the toolbox as a tool.
 
+        This method wraps the function with logging execution info and adds it to the toolbox.
+
         Args:
             func (Callable): The function to be added as a tool.
 
@@ -92,6 +141,8 @@ class ToolBox(WithBriefing):
     def briefing(self) -> str:
         """Return a brief description of the toolbox.
 
+        This method generates a brief description of the toolbox, including its name, description, and a list of tools.
+
         Returns:
             str: A brief description of the toolbox.
         """
@@ -102,6 +153,8 @@ class ToolBox(WithBriefing):
     def get[**P, R](self, name: str) -> Tool[P, R]:
         """Invoke a tool by name with the provided arguments.
 
+        This method retrieves a tool by its name from the toolbox.
+
         Args:
             name (str): The name of the tool to invoke.
 
@@ -120,13 +173,24 @@ class ToolBox(WithBriefing):
         return tool
 
     def __hash__(self) -> int:
-        """Return a hash of the toolbox based on its briefing."""
+        """Return a hash of the toolbox based on its briefing.
+
+        Returns:
+            int: A hash value based on the toolbox's briefing.
+        """
         return hash(self.briefing)
 
 
 class ToolExecutor(BaseModel):
-    """A class representing a tool executor with a sequence of tools to execute."""
+    """A class representing a tool executor with a sequence of tools to execute.
+
+    This class manages a sequence of tools and provides methods to inject tools and data into a module, execute the tools,
+    and retrieve specific outputs.
 
+    Attributes:
+        candidates (List[Tool]): The sequence of tools to execute.
+        data (Dict[str, Any]): The data that could be used when invoking the tools.
+    """
     model_config = ConfigDict(use_attribute_docstrings=True)
     candidates: List[Tool] = Field(default_factory=list, frozen=True)
     """The sequence of tools to execute."""
@@ -135,7 +199,16 @@ class ToolExecutor(BaseModel):
     """The data that could be used when invoking the tools."""
 
     def inject_tools[M: ModuleType](self, module: Optional[M] = None) -> M:
-        """Inject the tools into the provided module or default."""
+        """Inject the tools into the provided module or default.
+
+        This method injects the tools into the provided module or creates a new module if none is provided.
+
+        Args:
+            module (Optional[M]): The module to inject tools into. If None, a new module is created.
+
+        Returns:
+            M: The module with injected tools.
+        """
         module = module or cast(
             "M", module_from_spec(spec=ModuleSpec(name=configs.toolbox.tool_module_name, loader=None))
         )
@@ -145,7 +218,16 @@ class ToolExecutor(BaseModel):
         return module
 
     def inject_data[M: ModuleType](self, module: Optional[M] = None) -> M:
-        """Inject the data into the provided module or default."""
+        """Inject the data into the provided module or default.
+
+        This method injects the data into the provided module or creates a new module if none is provided.
+
+        Args:
+            module (Optional[M]): The module to inject data into. If None, a new module is created.
+
+        Returns:
+            M: The module with injected data.
+        """
         module = module or cast(
             'M', module_from_spec(spec=ModuleSpec(name=configs.toolbox.data_module_name, loader=None))
         )
@@ -155,7 +237,17 @@ class ToolExecutor(BaseModel):
         return module
 
     def execute[C: Dict[str, Any]](self, source: CodeType, cxt: Optional[C] = None) -> C:
-        """Execute the sequence of tools with the provided context."""
+        """Execute the sequence of tools with the provided context.
+
+        This method executes the tools in the sequence with the provided context.
+
+        Args:
+            source (CodeType): The source code to execute.
+            cxt (Optional[C]): The context to execute the tools with. If None, an empty dictionary is used.
+
+        Returns:
+            C: The context after executing the tools.
+        """
         cxt = cxt or {}
 
         @use_temp_module([self.inject_data(), self.inject_tools()])
@@ -167,16 +259,49 @@ class ToolExecutor(BaseModel):
 
     @overload
     def take[C: Dict[str, Any]](self, keys: List[str], source: CodeType, cxt: Optional[C] = None) -> C:
-        """Check the output of the tools with the provided context."""
+        """Check the output of the tools with the provided context.
+
+        This method executes the tools and retrieves specific keys from the context.
+
+        Args:
+            keys (List[str]): The keys to retrieve from the context.
+            source (CodeType): The source code to execute.
+            cxt (Optional[C]): The context to execute the tools with. If None, an empty dictionary is used.
+
+        Returns:
+            C: A dictionary containing the retrieved keys and their values.
+        """
         ...
 
     @overload
     def take[C: Dict[str, Any]](self, keys: str, source: CodeType, cxt: Optional[C] = None) -> Any:
-        """Check the output of the tools with the provided context."""
+        """Check the output of the tools with the provided context.
+
+        This method executes the tools and retrieves a specific key from the context.
+
+        Args:
+            keys (str): The key to retrieve from the context.
+            source (CodeType): The source code to execute.
+            cxt (Optional[C]): The context to execute the tools with. If None, an empty dictionary is used.
+
+        Returns:
+            Any: The value of the retrieved key.
+        """
         ...
 
     def take[C: Dict[str, Any]](self, keys: List[str] | str, source: CodeType, cxt: Optional[C] = None) -> C | Any:
-        """Check the output of the tools with the provided context."""
+        """Check the output of the tools with the provided context.
+
+        This method executes the tools and retrieves specific keys or a specific key from the context.
+
+        Args:
+            keys (List[str] | str): The keys to retrieve from the context. Can be a single key or a list of keys.
+            source (CodeType): The source code to execute.
+            cxt (Optional[C]): The context to execute the tools with. If None, an empty dictionary is used.
+
+        Returns:
+            C | Any: A dictionary containing the retrieved keys and their values, or the value of the retrieved key.
+        """
         cxt = self.execute(source, cxt)
         if isinstance(keys, str):
             return cxt[keys]
@@ -184,7 +309,17 @@ class ToolExecutor(BaseModel):
 
     @classmethod
     def from_recipe(cls, recipe: List[str], toolboxes: List[ToolBox]) -> Self:
-        """Create a tool executor from a recipe and a list of toolboxes."""
+        """Create a tool executor from a recipe and a list of toolboxes.
+
+        This method creates a tool executor by retrieving tools from the provided toolboxes based on the recipe.
+
+        Args:
+            recipe (List[str]): The recipe specifying the names of the tools to be added.
+            toolboxes (List[ToolBox]): The list of toolboxes to retrieve tools from.
+
+        Returns:
+            Self: A new instance of the tool executor with the specified tools.
+        """
         tools = []
         while tool_name := recipe.pop(0):
             for toolbox in toolboxes:

fabricatio/models/usages.py

@@ -1,11 +1,11 @@
 """This module contains classes that manage the usage of language models and tools in tasks."""
 
+import traceback
 from asyncio import gather
-from typing import Callable, Dict, Iterable, List, Optional, Self, Sequence, Set, Type, Union, Unpack, overload
+from typing import Callable, Dict, Iterable, List, Optional, Self, Sequence, Set, Union, Unpack, overload
 
 import asyncstdlib
 import litellm
-from fabricatio._rust_instances import TEMPLATE_MANAGER
 from fabricatio.config import configs
 from fabricatio.decorators import logging_exec_time
 from fabricatio.journal import logger
@@ -13,8 +13,10 @@ from fabricatio.models.generic import ScopedConfig, WithBriefing
 from fabricatio.models.kwargs_types import ChooseKwargs, EmbeddingKwargs, GenerateKwargs, LLMKwargs, ValidateKwargs
 from fabricatio.models.task import Task
 from fabricatio.models.tool import Tool, ToolBox
-from fabricatio.models.utils import Messages, ok
+from fabricatio.models.utils import Messages
 from fabricatio.parser import GenericCapture, JsonCapture
+from fabricatio.rust_instances import TEMPLATE_MANAGER
+from fabricatio.utils import ok
 from litellm import RateLimitError, Router, stream_chunk_builder  # pyright: ignore [reportPrivateImportUsage]
 from litellm.types.router import Deployment, LiteLLM_Params, ModelInfo
 from litellm.types.utils import (
@@ -38,21 +40,30 @@ ROUTER = Router(
     allowed_fails=configs.routing.allowed_fails,
     retry_after=configs.routing.retry_after,
     cooldown_time=configs.routing.cooldown_time,
+    cache_responses=configs.cache.enabled,
+    cache_kwargs=configs.cache.params,
 )
 
 
 class LLMUsage(ScopedConfig):
-    """Class that manages LLM (Large Language Model) usage parameters and methods."""
+    """Class that manages LLM (Large Language Model) usage parameters and methods.
+
+    This class provides methods to deploy LLMs, query them for responses, and handle various configurations
+    related to LLM usage such as API keys, endpoints, and rate limits.
+    """
 
     def _deploy(self, deployment: Deployment) -> Router:
-        """Add a deployment to the router."""
+        """Add a deployment to the router.
+
+        Args:
+            deployment (Deployment): The deployment to be added to the router.
+
+        Returns:
+            Router: The updated router with the added deployment.
+        """
         self._added_deployment = ROUTER.upsert_deployment(deployment)
         return ROUTER
 
-    @classmethod
-    def _scoped_model(cls) -> Type["LLMUsage"]:
-        return LLMUsage
-
     # noinspection PyTypeChecker,PydanticTypeChecker
     async def aquery(
         self,
@@ -132,10 +143,10 @@ class LLMUsage(ScopedConfig):
             **kwargs (Unpack[LLMKwargs]): Additional keyword arguments for the LLM usage.
 
         Returns:
-            List[Choices | StreamingChoices]: A list of choices or streaming choices from the model response.
+            Sequence[TextChoices | Choices | StreamingChoices]: A sequence of choices or streaming choices from the model response.
         """
         resp = await self.aquery(
-            messages=Messages().add_system_message(system_message).add_user_message(question),
+            messages=Messages().add_system_message(system_message).add_user_message(question).as_list(),
             n=n,
             **kwargs,
         )
@@ -277,34 +288,32 @@ class LLMUsage(ScopedConfig):
         question: str | List[str],
         validator: Callable[[str], T | None],
         default: Optional[T] = None,
-        max_validations: PositiveInt = 2,
+        max_validations: PositiveInt = 3,
         co_extractor: Optional[GenerateKwargs] = None,
         **kwargs: Unpack[GenerateKwargs],
     ) -> Optional[T] | List[Optional[T]] | List[T] | T:
         """Asynchronously asks a question and validates the response using a given validator.
 
         Args:
-            question (str): The question to ask.
+            question (str | List[str]): The question to ask.
             validator (Callable[[str], T | None]): A function to validate the response.
             default (T | None): Default value to return if validation fails. Defaults to None.
-            max_validations (PositiveInt): Maximum number of validation attempts. Defaults to 2.
+            max_validations (PositiveInt): Maximum number of validation attempts. Defaults to 3.
             co_extractor (Optional[GenerateKwargs]): Keyword arguments for the co-extractor, if provided will enable co-extraction.
-            **kwargs (Unpack[LLMKwargs]): Additional keyword arguments for the LLM usage.
+            **kwargs (Unpack[GenerateKwargs]): Additional keyword arguments for the LLM usage.
 
         Returns:
-            T: The validated response.
-
+            Optional[T] | List[Optional[T]] | List[T] | T: The validated response.
         """
 
         async def _inner(q: str) -> Optional[T]:
             for lap in range(max_validations):
                 try:
-                    if (
-                        (response := await self.aask(question=q, **kwargs))
-                        or (
-                            co_extractor
-                            and (
-                                response := await self.aask(
+                    if ((validated := validator(response := await self.aask(question=q, **kwargs))) is not None) or (
+                        co_extractor
+                        and (
+                            validated := validator(
+                                await self.aask(
                                     question=(
                                         TEMPLATE_MANAGER.render_template(
                                             configs.templates.co_validation_template,
@@ -315,7 +324,8 @@ class LLMUsage(ScopedConfig):
                                 )
                             )
                         )
-                    ) and (validated := validator(response)):
+                        is not None
+                    ):
                         logger.debug(f"Successfully validated the response at {lap}th attempt.")
                         return validated
 
@@ -324,6 +334,7 @@ class LLMUsage(ScopedConfig):
                     continue
                 except Exception as e:  # noqa: BLE001
                     logger.error(f"Error during validation: \n{e}")
+                    logger.debug(traceback.format_exc())
                     break
                 if not kwargs.get("no_cache"):
                     kwargs["no_cache"] = True
@@ -334,7 +345,7 @@ class LLMUsage(ScopedConfig):
 
         return await (gather(*[_inner(q) for q in question]) if isinstance(question, list) else _inner(question))
 
-    async def aliststr(
+    async def alist_str(
         self, requirement: str, k: NonNegativeInt = 0, **kwargs: Unpack[ValidateKwargs[List[str]]]
     ) -> Optional[List[str]]:
         """Asynchronously generates a list of strings based on a given requirement.
@@ -345,7 +356,7 @@ class LLMUsage(ScopedConfig):
             **kwargs (Unpack[ValidateKwargs]): Additional keyword arguments for the LLM usage.
 
         Returns:
-            List[str]: The validated response as a list of strings.
+            Optional[List[str]]: The validated response as a list of strings.
         """
         return await self.aask_validate(
             TEMPLATE_MANAGER.render_template(
@@ -364,9 +375,9 @@ class LLMUsage(ScopedConfig):
             **kwargs (Unpack[ChooseKwargs]): Additional keyword arguments for the LLM usage.
 
         Returns:
-            List[str]: The validated response as a list of strings.
+            Optional[List[str]]: The validated response as a list of strings.
         """
-        return await self.aliststr(
+        return await self.alist_str(
             TEMPLATE_MANAGER.render_template(
                 configs.templates.pathstr_template,
                 {"requirement": requirement},
@@ -382,7 +393,7 @@ class LLMUsage(ScopedConfig):
             **kwargs (Unpack[ValidateKwargs]): Additional keyword arguments for the LLM usage.
 
         Returns:
-            str: The validated response as a single string.
+            Optional[str]: The validated response as a single string.
         """
         if paths := await self.apathstr(
             requirement,
@@ -401,7 +412,7 @@ class LLMUsage(ScopedConfig):
             **kwargs (Unpack[GenerateKwargs]): Additional keyword arguments for the LLM usage.
 
         Returns:
-            str: The generated string.
+            Optional[str]: The generated string.
         """
         return await self.aask_validate(  # pyright: ignore [reportReturnType]
             TEMPLATE_MANAGER.render_template(
@@ -428,12 +439,7 @@ class LLMUsage(ScopedConfig):
             **kwargs (Unpack[ValidateKwargs]): Additional keyword arguments for the LLM usage.
 
         Returns:
-            List[T]: The final validated selection result list, with element types matching the input `choices`.
-
-        Important:
-            - Uses a template engine to generate structured prompts.
-            - Ensures response compliance through JSON parsing and format validation.
-            - Relies on `aask_validate` to implement retry mechanisms with validation.
+            Optional[List[T]]: The final validated selection result list, with element types matching the input `choices`.
         """
         if dup := duplicates_everseen(choices, key=lambda x: x.name):
             logger.error(err := f"Redundant choices: {dup}")
@@ -521,7 +527,10 @@ class LLMUsage(ScopedConfig):
 
 
 class EmbeddingUsage(LLMUsage):
-    """A class representing the embedding model."""
+    """A class representing the embedding model.
+
+    This class extends LLMUsage and provides methods to generate embeddings for input text using various models.
+    """
 
     async def aembedding(
         self,
@@ -540,14 +549,13 @@ class EmbeddingUsage(LLMUsage):
             timeout (Optional[PositiveInt]): The timeout for the embedding request. Defaults to the instance's `llm_timeout` or the global configuration.
             caching (Optional[bool]): Whether to cache the embedding result. Defaults to False.
 
-
         Returns:
             EmbeddingResponse: The response containing the embeddings.
         """
         # check seq length
         max_len = self.embedding_max_sequence_length or configs.embedding.max_sequence_length
-        if max_len and any(len(t) > max_len for t in input_text):
-            logger.error(err := f"Input text exceeds maximum sequence length {max_len}.")
+        if max_len and any(length := (token_counter(text=t)) > max_len for t in input_text):
+            logger.error(err := f"Input text exceeds maximum sequence length {max_len}, got {length}.")
             raise ValueError(err)
 
         return await litellm.aembedding(
@@ -598,14 +606,21 @@ class EmbeddingUsage(LLMUsage):
 
 
 class ToolBoxUsage(LLMUsage):
-    """A class representing the usage of tools in a task."""
+    """A class representing the usage of tools in a task.
+
+    This class extends LLMUsage and provides methods to manage and use toolboxes and tools within tasks.
+    """
 
     toolboxes: Set[ToolBox] = Field(default_factory=set)
     """A set of toolboxes used by the instance."""
 
     @property
     def available_toolbox_names(self) -> List[str]:
-        """Return a list of available toolbox names."""
+        """Return a list of available toolbox names.
+
+        Returns:
+            List[str]: A list of names of the available toolboxes.
+        """
         return [toolbox.name for toolbox in self.toolboxes]
 
     async def choose_toolboxes(
@@ -617,11 +632,10 @@ class ToolBoxUsage(LLMUsage):
 
         Args:
             task (Task): The task for which to choose toolboxes.
-            system_message (str): Custom system-level prompt, defaults to an empty string.
             **kwargs (Unpack[LLMKwargs]): Additional keyword arguments for the LLM usage.
 
         Returns:
-            List[ToolBox]: The selected toolboxes.
+            Optional[List[ToolBox]]: The selected toolboxes.
         """
         if not self.toolboxes:
             logger.warning("No toolboxes available.")
@@ -646,7 +660,7 @@ class ToolBoxUsage(LLMUsage):
             **kwargs (Unpack[LLMKwargs]): Additional keyword arguments for the LLM usage.
 
         Returns:
-            List[Tool]: The selected tools.
+            Optional[List[Tool]]: The selected tools.
         """
         if not toolbox.tools:
             logger.warning(f"No tools available in toolbox {toolbox.name}.")
@@ -708,7 +722,7 @@ class ToolBoxUsage(LLMUsage):
         """
         if isinstance(others, ToolBoxUsage):
             others = [others]
-        for other in others:
+        for other in (x for x in others if isinstance(x, ToolBoxUsage)):
             self.toolboxes.update(other.toolboxes)
         return self
 
@@ -724,6 +738,6 @@ class ToolBoxUsage(LLMUsage):
         """
         if isinstance(others, ToolBoxUsage):
             others = [others]
-        for other in others:
+        for other in (x for x in others if isinstance(x, ToolBoxUsage)):
             other.toolboxes.update(self.toolboxes)
         return self