zrb 1.9.5__py3-none-any.whl → 1.9.7__py3-none-any.whl

zrb/builtin/llm/llm_ask.py

@@ -7,10 +7,10 @@ from zrb.builtin.llm.tool.cli import run_shell_command
 from zrb.builtin.llm.tool.code import analyze_repo
 from zrb.builtin.llm.tool.file import (
     analyze_file,
-    apply_diff,
     list_files,
     read_from_file,
     read_many_files,
+    replace_in_file,
     search_files,
     write_many_files,
     write_to_file,
@@ -135,7 +135,7 @@ if CFG.LLM_ALLOW_ACCESS_LOCAL_FILE:
         list_files,
         read_from_file,
         read_many_files,
-        apply_diff,
+        replace_in_file,
         write_to_file,
         write_many_files,
     )

zrb/builtin/llm/tool/api.py

@@ -3,11 +3,16 @@ from typing import Literal
 
 
 def get_current_location() -> str:
-    """Get current location (latitude, longitude) based on IP address.
+    """
+    Fetches the user's current geographical location (latitude and longitude) based on their IP address.
+
+    Use this tool when the user asks "Where am I?", "What is my current location?", or has a query that requires knowing their location to be answered.
+
     Returns:
-        str: JSON string representing latitude and longitude.
+        str: A JSON string containing the 'lat' and 'lon' of the current location.
+             Example: '{"lat": 48.8584, "lon": 2.2945}'
     Raises:
-        requests.RequestException: If the API request fails.
+        requests.RequestException: If the API request to the location service fails.
     """
     import requests
 
@@ -24,15 +29,20 @@ def get_current_weather(
     longitude: float,
     temperature_unit: Literal["celsius", "fahrenheit"],
 ) -> str:
-    """Get current weather for a specific location.
+    """
+    Retrieves the current weather conditions for a given geographical location.
+
+    Use this tool when the user asks about the weather. If the user does not provide a location, first use the `get_current_location` tool to determine their location.
+
     Args:
-        latitude (float): Latitude coordinate.
-        longitude (float): Longitude coordinate.
-        temperature_unit (Literal["celsius", "fahrenheit"]): Temperature unit.
+        latitude (float): The latitude of the location.
+        longitude (float): The longitude of the location.
+        temperature_unit (Literal["celsius", "fahrenheit"]): The desired unit for the temperature reading.
+
     Returns:
-        str: JSON string with weather data.
+        str: A JSON string containing detailed weather data, including temperature, wind speed, and weather code.
     Raises:
-        requests.RequestException: If the API request fails.
+        requests.RequestException: If the API request to the weather service fails.
     """
     import requests
 

zrb/builtin/llm/tool/cli.py

@@ -2,14 +2,20 @@ import subprocess
 
 
 def run_shell_command(command: str) -> str:
-    """Execute a shell command and return its combined stdout and stderr.
+    """
+    Executes a shell command on the user's local machine and returns the output.
+
+    This tool is powerful and should be used for tasks that require interacting with the command line, such as running scripts, managing system processes, or using command-line tools.
+
+    **Security Warning:** This tool executes commands with the same permissions as the user running the assistant. Before executing any command that could modify files or system state (e.g., `git`, `npm`, `pip`, `docker`), you MUST explain what the command does and ask the user for confirmation.
+
     Args:
-        command (str): Shell command to execute on the user's system.
+        command (str): The exact shell command to execute.
+
     Returns:
-        str: The command's output (stdout and stderr combined).
+        str: The combined standard output (stdout) and standard error (stderr) from the command. If the command fails, this will contain the error message.
     Raises:
-        subprocess.CalledProcessError: If the command returns a non-zero exit code.
-        subprocess.SubprocessError: If there's an issue with subprocess execution.
+        subprocess.CalledProcessError: If the command returns a non-zero exit code, indicating an error.
     """
     try:
         output = subprocess.check_output(

zrb/builtin/llm/tool/code.py

@@ -86,29 +86,29 @@ async def analyze_repo(
     summarization_token_limit: int = 40000,
 ) -> str:
     """
-    Extract and summarize information from any directory.
-    You should state the goal specifically so that the tool can return relevant informations.
+    Performs a deep, goal-oriented analysis of a code repository or directory.
+
+    This powerful tool recursively reads all relevant files in a directory, extracts key information, and then summarizes that information in relation to a specific goal. It uses intelligent sub-agents for extraction and summarization, making it ideal for complex tasks that require a holistic understanding of a codebase.
+
     Use this tool for:
-    - summarization
-    - outline/structure extraction
-    - code review
-    - create diagram as code
-    - other tasks
+    - Understanding a large or unfamiliar codebase.
+    - Generating high-level summaries of a project's architecture.
+    - Performing a preliminary code review.
+    - Creating documentation or diagrams (e.g., "Generate a Mermaid C4 diagram for this service").
+    - Answering broad questions like "How does the authentication in this project work?".
+
     Args:
-        path (str): File path to be analyze. Pass exactly as provided, including '~'.
-        goal(str): Goal of extracting information (for example creating C4 diagram)
-        extensions(Optional[list[str]]): List of extension to be included
-            while reading resources. Defaults to common programming languages and config files.
-        exclude_patterns(Optional[list[str]]): List of patterns to exclude from analysis.
-            Common patterns like '.venv', 'node_modules' should be excluded by default.
-        extraction_token_limit(Optional[int]): Max resource content char length
-            the extraction assistant able to handle. Defaults to 150000
-        summarization_token_limit(Optional[int]): Max resource content char length
-            the summarization assistant able to handle. Defaults to 150000
+        path (str): The path to the directory or repository to analyze.
+        goal (str): A clear and specific description of what you want to achieve. A good goal is critical for getting a useful result. For example: "Understand the database schema by analyzing all the .sql files" or "Create a summary of all the API endpoints defined in the 'api' directory".
+        extensions (list[str], optional): A list of file extensions to include in the analysis. Defaults to a comprehensive list of common code and configuration files.
+        exclude_patterns (list[str], optional): A list of glob patterns for files and directories to exclude from the analysis. Defaults to common patterns like '.git', 'node_modules', and '.venv'.
+        extraction_token_limit (int, optional): The maximum token limit for the extraction sub-agent.
+        summarization_token_limit (int, optional): The maximum token limit for the summarization sub-agent.
+
     Returns:
-        str: The analysis result
+        str: A detailed, markdown-formatted analysis and summary of the repository, tailored to the specified goal.
     Raises:
-        Exception: If an error occurs.
+        Exception: If an error occurs during the analysis.
     """
     abs_path = os.path.abspath(os.path.expanduser(path))
     file_metadatas = _get_file_metadatas(abs_path, extensions, exclude_patterns)

zrb/builtin/llm/tool/file.py

@@ -106,17 +106,22 @@ def list_files(
     include_hidden: bool = False,
     excluded_patterns: Optional[list[str]] = None,
 ) -> str:
-    """List files/directories in a path, excluding specified patterns.
+    """
+    Lists the files and directories within a specified path.
+
+    This is a fundamental tool for exploring the file system. Use it to discover the structure of a directory, find specific files, or get a general overview of the project layout before performing other operations.
+
     Args:
-        path (str): Path to list. Pass exactly as provided, including '~'. Defaults to ".".
-        recursive (bool): List recursively. Defaults to True.
-        include_hidden (bool): Include hidden files/dirs. Defaults to False.
-        excluded_patterns (Optional[List[str]]): List of glob patterns to exclude.
-            Defaults to a comprehensive list of common temporary/artifact patterns.
+        path (str, optional): The directory path to list. Defaults to the current directory (".").
+        recursive (bool, optional): If True, lists files and directories recursively. If False, lists only the top-level contents. Defaults to True.
+        include_hidden (bool, optional): If True, includes hidden files and directories (those starting with a dot). Defaults to False.
+        excluded_patterns (list[str], optional): A list of glob patterns to exclude from the listing. This is useful for ignoring irrelevant files like build artifacts or virtual environments. Defaults to a standard list of common exclusion patterns.
+
     Returns:
-        str: JSON string: {"files": ["file1.txt", ...]} or {"error": "..."}
+        str: A JSON string containing a list of file and directory paths relative to the input path.
+             Example: '{"files": ["src/main.py", "README.md"]}'
     Raises:
-        Exception: If an error occurs.
+        FileNotFoundError: If the specified path does not exist.
     """
     all_files: list[str] = []
     abs_path = os.path.abspath(os.path.expanduser(path))
@@ -214,19 +219,26 @@ def read_from_file(
     start_line: Optional[int] = None,
     end_line: Optional[int] = None,
 ) -> str:
-    """Read file content (or specific lines) at a path, including line numbers.
-    This tool can read both, text and pdf file.
+    """
+    Reads the content of a file, optionally from a specific start line to an end line.
+
+    This tool is essential for inspecting file contents. It can read both text and PDF files. The returned content is prefixed with line numbers, which is crucial for providing context when you need to modify the file later with the `apply_diff` tool.
+
+    Use this tool to:
+    - Examine the source code of a file.
+    - Read configuration files.
+    - Check the contents of a document.
+
     Args:
-        path (str): Path to read. Pass exactly as provided, including '~'.
-        start_line (Optional[int]): Starting line number (1-based).
-            Defaults to None (start of file).
-        end_line (Optional[int]): Ending line number (1-based, inclusive).
-            Defaults to None (end of file).
+        path (str): The path to the file to read.
+        start_line (int, optional): The 1-based line number to start reading from. If omitted, reading starts from the beginning of the file.
+        end_line (int, optional): The 1-based line number to stop reading at (inclusive). If omitted, reads to the end of the file.
+
     Returns:
-        str: JSON: {"path": "...", "content": "...", "start_line": N, ...} or {"error": "..."}
-        The content includes line numbers.
+        str: A JSON object containing the file path, the requested content with line numbers, the start and end lines, and the total number of lines in the file.
+             Example: '{"path": "src/main.py", "content": "1: import os\n2: \n3: print(\"Hello, World!\")", "start_line": 1, "end_line": 3, "total_lines": 3}'
     Raises:
-        Exception: If an error occurs.
+        FileNotFoundError: If the specified file does not exist.
     """
     abs_path = os.path.abspath(os.path.expanduser(path))
     # Check if file exists
@@ -267,26 +279,20 @@ def read_from_file(
 def write_to_file(
     path: str,
     content: str,
-    line_count: int,
 ) -> str:
-    """Write full content to a file. Creates/overwrites file.
+    """
+    Writes content to a file, completely overwriting it if it exists or creating it if it doesn't.
+
+    Use this tool to create new files or to replace the entire content of existing files. This is a destructive operation, so be certain of your actions. Always read the file first to understand its contents before overwriting it, unless you are creating a new file.
+
     Args:
-        path (str): Path to write. Pass exactly as provided, including '~'.
-        content (str): Full file content.
-            MUST be complete, no truncation/omissions. Exclude line numbers.
-        line_count (int): Number of lines in the provided content.
+        path (str): The path to the file to write to.
+        content (str): The full, complete content to be written to the file. Do not use partial content or omit any lines.
+
     Returns:
-        str: JSON: {"success": true, "path": "f.txt", "warning": "..."} or {"error": "..."}
-    Raises:
-        Exception: If an error occurs.
+        str: A JSON object indicating success or failure.
+             Example: '{"success": true, "path": "new_file.txt"}'
     """
-    actual_lines = len(content.splitlines())
-    warning = None
-    if actual_lines != line_count:
-        warning = (
-            f"Provided line_count ({line_count}) does not match actual "
-            f"content lines ({actual_lines}) for file {path}"
-        )
     try:
         abs_path = os.path.abspath(os.path.expanduser(path))
         # Ensure directory exists
@@ -295,8 +301,6 @@ def write_to_file(
             os.makedirs(directory, exist_ok=True)
         write_file(abs_path, content)
         result_data = {"success": True, "path": path}
-        if warning:
-            result_data["warning"] = warning
         return json.dumps(result_data)
     except (OSError, IOError) as e:
         raise OSError(f"Error writing file {path}: {e}")
@@ -310,17 +314,21 @@ def search_files(
     file_pattern: Optional[str] = None,
     include_hidden: bool = True,
 ) -> str:
-    """Search files in a directory using regex, showing context.
+    """
+    Searches for a regular expression (regex) pattern within files in a specified directory.
+
+    This tool is invaluable for finding specific code, configuration, or text across multiple files. Use it to locate function definitions, variable assignments, error messages, or any other text pattern.
+
     Args:
-        path (str): Path to search. Pass exactly as provided, including '~'.
-        regex (str): Python regex pattern to search for.
-        file_pattern (Optional[str]): Glob pattern to filter files
-            (e.g., '*.py'). Defaults to None.
-        include_hidden (bool): Include hidden files/dirs. Defaults to True.
+        path (str): The directory path to start the search from.
+        regex (str): The Python-compatible regular expression pattern to search for.
+        file_pattern (str, optional): A glob pattern to filter which files get searched (e.g., "*.py", "*.md"). If omitted, all files are searched.
+        include_hidden (bool, optional): If True, the search will include hidden files and directories. Defaults to True.
+
     Returns:
-        str: JSON: {"summary": "...", "results": [{"file":"f.py", ...}]} or {"error": "..."}
+        str: A JSON object containing a summary of the search and a list of results. Each result includes the file path and a list of matches, with each match showing the line number, line content, and a few lines of context from before and after the match.
     Raises:
-        Exception: If error occurs or regex is invalid.
+        ValueError: If the provided `regex` pattern is invalid.
     """
     try:
         pattern = re.compile(regex)
@@ -407,83 +415,70 @@ def _get_file_matches(
         raise RuntimeError(f"Unexpected error processing {file_path}: {e}")
 
 
-def apply_diff(
+def replace_in_file(
     path: str,
-    start_line: int,
-    end_line: int,
-    search_content: str,
-    replace_content: str,
+    old_string: str,
+    new_string: str,
 ) -> str:
-    """Apply a precise search/replace to a file based on line numbers and content.
-    This tool enables you to update certain part of the file efficiently.
+    """
+    Replaces the first occurrence of a string in a file.
+
+    This tool is for making targeted modifications to a file. It is a single-step operation that is generally safer and more ergonomic than `write_to_file` for small changes.
+
+    To ensure the replacement is applied correctly and to avoid ambiguity, the `old_string` parameter should be a unique, multi-line string that includes context from before and after the code you want to change.
+
     Args:
-        path (str): Path to modify. Pass exactly as provided, including '~'.
-        start_line (int): The 1-based starting line number of the content to replace.
-        end_line (int): The 1-based ending line number (inclusive) of the content to replace.
-        search_content (str): The exact content expected to be found in the specified
-            line range. Must exactly match file content including whitespace/indentation,
-            excluding line numbers.
-        replace_content (str): The new content to replace the search_content with.
-            Excluding line numbers.
+        path (str): The path of the file to modify.
+        old_string (str): The exact, verbatim string to search for and replace. This should be a unique, multi-line block of text.
+        new_string (str): The new string that will replace the `old_string`.
+
     Returns:
-        str: JSON: {"success": true, "path": "f.py"} or {"success": false, "error": "..."}
+        str: A JSON object indicating the success or failure of the operation.
     Raises:
-        Exception: If an error occurs.
+        FileNotFoundError: If the specified file does not exist.
+        ValueError: If the `old_string` is not found in the file.
     """
     abs_path = os.path.abspath(os.path.expanduser(path))
     if not os.path.exists(abs_path):
         raise FileNotFoundError(f"File not found: {path}")
     try:
         content = read_file(abs_path)
-        lines = content.splitlines()
-        if start_line < 1 or end_line > len(lines) or start_line > end_line:
-            raise ValueError(
-                f"Invalid line range {start_line}-{end_line} for file with {len(lines)} lines"
-            )
-        original_content = "\n".join(lines[start_line - 1 : end_line])
-        if original_content != search_content:
-            error_message = (
-                f"Search content does not match file content at "
-                f"lines {start_line}-{end_line}.\n"
-                f"Expected ({len(search_content.splitlines())} lines):\n"
-                f"---\n{search_content}\n---\n"
-                f"Actual ({len(lines[start_line-1:end_line])} lines):\n"
-                f"---\n{original_content}\n---"
-            )
-            return json.dumps({"success": False, "path": path, "error": error_message})
-        new_lines = (
-            lines[: start_line - 1] + replace_content.splitlines() + lines[end_line:]
-        )
-        new_content = "\n".join(new_lines)
-        if content.endswith("\n"):
-            new_content += "\n"
+        if old_string not in content:
+            raise ValueError(f"old_string not found in file: {path}")
+        new_content = content.replace(old_string, new_string, 1)
         write_file(abs_path, new_content)
         return json.dumps({"success": True, "path": path})
     except ValueError as e:
-        raise ValueError(f"Error parsing diff: {e}")
+        raise e
     except (OSError, IOError) as e:
-        raise OSError(f"Error applying diff to {path}: {e}")
+        raise OSError(f"Error applying replacement to {path}: {e}")
     except Exception as e:
-        raise RuntimeError(f"Unexpected error applying diff to {path}: {e}")
+        raise RuntimeError(f"Unexpected error applying replacement to {path}: {e}")
 
 
 async def analyze_file(
     ctx: AnyContext, path: str, query: str, token_limit: int = 40000
 ) -> str:
-    """Analyze file using LLM capability to reduce context usage.
-    Use this tool for:
-    - summarization
-    - outline/structure extraction
-    - code review
-    - other tasks
+    """
+    Performs a deep, goal-oriented analysis of a single file using a sub-agent.
+
+    This tool is ideal for complex questions about a single file that go beyond simple reading or searching. It uses a specialized sub-agent to analyze the file's content in relation to a specific query.
+
+    Use this tool to:
+    - Summarize the purpose and functionality of a script or configuration file.
+    - Extract the structure of a file (e.g., "List all the function names in this Python file").
+    - Perform a detailed code review of a specific file.
+    - Answer complex questions like, "How is the 'User' class used in this file?".
+
     Args:
-        path (str): File path to be analyze. Pass exactly as provided, including '~'.
-        query(str): Instruction to analyze the file
-        token_limit(Optional[int]): Max token length to be taken from file
+        path (str): The path to the file to be analyzed.
+        query (str): A clear and specific question or instruction about what to analyze in the file.
+        token_limit (int, optional): The maximum token length of the file content to be passed to the analysis sub-agent.
+
     Returns:
-        str: The analysis result
+        str: A detailed, markdown-formatted analysis of the file, tailored to the specified query.
     Raises:
-        Exception: If an error occurs.
+        FileNotFoundError: If the specified file does not exist.
     """
     abs_path = os.path.abspath(os.path.expanduser(path))
     if not os.path.exists(abs_path):
@@ -504,38 +499,16 @@ async def analyze_file(
 
 def read_many_files(paths: List[str]) -> str:
     """
-    Read and return the content of multiple files.
+    Reads and returns the full content of multiple files at once.
 
-    This function is ideal for when you need to inspect the contents of
-    several files at once. For each file path provided in the input list,
-    it reads the entire file content. The result is a JSON string
-    containing a dictionary where keys are the file paths and values are
-    the corresponding file contents.
-
-    Use this tool when you need a comprehensive view of multiple files,
-    for example, to understand how different parts of a module interact,
-    to check configurations across various files, or to gather context
-    before making widespread changes.
+    This tool is highly efficient for gathering context from several files simultaneously. Use it when you need to understand how different files in a project relate to each other, or when you need to inspect a set of related configuration or source code files.
 
     Args:
-        paths (List[str]): A list of absolute or relative paths to the
-                           files you want to read. It is crucial to
-                           provide accurate paths. Use the `list_files`
-                           tool if you are unsure about the exact file
-                           locations.
+        paths (List[str]): A list of paths to the files you want to read. It is crucial to provide accurate paths. Use the `list_files` tool first if you are unsure about the exact file locations.
 
     Returns:
-        str: A JSON string representing a dictionary where each key is a
-             file path and the corresponding value is the content of that
-             file. If a file cannot be read, its entry in the dictionary
-             will contain an error message.
-             Example:
-             {
-                 "results": {
-                     "path/to/file1.py": "...",
-                     "path/to/file2.txt": "..."
-                 }
-             }
+        str: A JSON object where keys are the file paths and values are their corresponding contents, prefixed with line numbers. If a file cannot be read, its value will be an error message.
+             Example: '{"results": {"src/api.py": "1: import ...", "config.yaml": "1: key: value"}}'
     """
     results = {}
     for path in paths:
@@ -552,42 +525,18 @@ def read_many_files(paths: List[str]) -> str:
 
 def write_many_files(files: Dict[str, str]) -> str:
     """
-    Write content to multiple files simultaneously.
-
-    This function allows you to create, overwrite, or update multiple
-    files in a single operation. You provide a dictionary where each
-    key is a file path and the corresponding value is the content to be
-    written to that file. This is particularly useful for applying
-    changes across a project, such as refactoring code, updating
-    configuration files, or creating a set of new files from a template.
+    Writes content to multiple files in a single, atomic operation.
 
-    Each file is handled as a complete replacement of its content. If the
-    file does not exist, it will be created. If it already exists, its
+    This tool is for applying widespread changes to a project, such as creating a set of new files from a template, updating multiple configuration files, or performing a large-scale refactoring.
 
-    entire content will be overwritten with the new content you provide.
-    Therefore, it is essential to provide the full, intended content for
-    each file.
+    Each file's content is completely replaced. If a file does not exist, it will be created. If it exists, its current content will be entirely overwritten. Therefore, you must provide the full, intended content for each file.
 
     Args:
-        files (Dict[str, str]): A dictionary where keys are the file paths
-                                (absolute or relative) and values are the
-                                complete contents to be written to those
-                                files.
+        files (Dict[str, str]): A dictionary where keys are the file paths and values are the complete contents to be written to those files.
 
     Returns:
-        str: A JSON string summarizing the operation. It includes a list
-             of successfully written files and a list of files that
-             failed, along with the corresponding error messages.
-             Example:
-             {
-                 "success": [
-                     "path/to/file1.py",
-                     "path/to/file2.txt"
-                 ],
-                 "errors": {
-                     "path/to/problematic/file.py": "Error message"
-                 }
-             }
+        str: A JSON object summarizing the operation, listing successfully written files and any files that failed, along with corresponding error messages.
+             Example: '{"success": ["file1.py", "file2.txt"], "errors": {}}'
     """
     success = []
     errors = {}
@@ -602,3 +551,6 @@ def write_many_files(files: Dict[str, str]) -> str:
         except Exception as e:
             errors[path] = f"Error writing file: {e}"
     return json.dumps({"success": success, "errors": errors})
+
+
+apply_diff = replace_in_file

zrb/builtin/llm/tool/rag.py

@@ -43,10 +43,33 @@ def create_rag_from_directory(
     openai_base_url: str | None = None,
     openai_embedding_model: str | None = None,
 ):
-    """Create a RAG retrieval tool function for LLM use.
-    This factory configures and returns an async function that takes a query,
-    updates a vector database if needed, performs a similarity search,
-    and returns relevant document chunks.
+    """
+    Creates a powerful Retrieval-Augmented Generation (RAG) tool for querying a local knowledge base.
+
+    This factory function generates a tool that can perform semantic searches over a directory of documents. It automatically indexes the documents into a vector database, keeping it updated as files change. The generated tool is ideal for answering questions based on a specific set of documents, such as project documentation, research papers, or internal wikis.
+
+    The created tool will:
+    1.  Monitor a specified directory for file changes.
+    2.  Automatically update a vector database (ChromaDB) with the latest content.
+    3.  Accept a user query, embed it, and perform a similarity search against the document vectors.
+    4.  Return the most relevant document chunks that match the query.
+
+    Args:
+        tool_name (str): The name for the generated RAG tool (e.g., "search_project_docs").
+        tool_description (str): A clear description of what the generated tool does and when to use it (e.g., "Searches the project's technical documentation to answer questions.").
+        document_dir_path (str, optional): The path to the directory containing the documents to be indexed.
+        vector_db_path (str, optional): The path to store the ChromaDB vector database.
+        vector_db_collection (str, optional): The name of the collection within the vector database.
+        chunk_size (int, optional): The size of text chunks for embedding.
+        overlap (int, optional): The overlap between text chunks.
+        max_result_count (int, optional): The maximum number of search results to return.
+        file_reader (list[RAGFileReader], optional): Custom file readers for specific file types.
+        openai_api_key (str, optional): OpenAI API key for embeddings.
+        openai_base_url (str, optional): OpenAI base URL for embeddings.
+        openai_embedding_model (str, optional): The embedding model to use.
+
+    Returns:
+        Callable: An asynchronous function that serves as the RAG tool.
     """
 
     async def retrieve(query: str) -> str:

zrb/builtin/llm/tool/sub_agent.py

@@ -29,25 +29,23 @@ def create_sub_agent_tool(
     mcp_servers: list["MCPServer"] = [],
 ) -> Callable[[AnyContext, str], Coroutine[Any, Any, str]]:
     """
-    Create an LLM "sub-agent" tool function for use by a main LLM agent.
+    Creates a "tool that is another AI agent," capable of handling complex, multi-step sub-tasks.
 
-    This factory configures and returns an async function that, when called
-    by the main agent, instantiates and runs a sub-agent (the sub-agent)
-    with a given query and returns the sub-agent's final response.
+    This powerful factory function generates a tool that, when used, spins up a temporary, specialized AI agent. This "sub-agent" has its own system prompt, tools, and context, allowing it to focus exclusively on accomplishing the task it's given without being distracted by the main conversation.
+
+    This is ideal for delegating complex tasks like analyzing a file or a repository.
 
     Args:
-        tool_name: The name of the tool for the main agent.
-        tool_description: The description of the tool for the main agent.
-        sub_agent_system_prompt: The system prompt for the sub-agent.
-        sub_agent_model: The model for the sub-agent (optional).
-        sub_agent_model_settings: Model settings for the sub-agent (optional).
-        sub_agent_tools: A list of tools (Tool instances or callables) for the
-            sub-agent (optional).
-        sub_agent_mcp_servers: A list of MCP servers for the sub-agent (optional).
+        tool_name (str): The name for the generated sub-agent tool.
+        tool_description (str): A clear description of the sub-agent's purpose and when to use it.
+        system_prompt (str, optional): The system prompt that will guide the sub-agent's behavior.
+        model (str | Model, optional): The language model the sub-agent will use.
+        model_settings (ModelSettings, optional): Specific settings for the sub-agent's model.
+        tools (list, optional): A list of tools that will be exclusively available to the sub-agent.
+        mcp_servers (list, optional): A list of MCP servers for the sub-agent.
 
     Returns:
-        An async callable function that takes a context and a query string,
-        runs the sub-agent, and returns the sub-agent's final message content.
+        Callable: An asynchronous function that serves as the sub-agent tool. When called, it runs the sub-agent with a given query and returns its final result.
     """
 
     async def run_sub_agent(ctx: AnyContext, query: str) -> str: